MQTT

MQTT — протокол обмена данными, использующийся в программном обеспечении Wiren Board. Базовая информация по MQTT на Википедии.

Драйверы, которые отвечают за аппаратную часть контроллера (цифровые и транзисторные входы, АЦП и т.п.) и функции внешних подключенных устройств публикуют их состояние по MQTT в виде сообщений. Веб-интерфейс читает эти сообщения и на их основе отображает состояние устройств.

Действия пользователя в веб-интерфейсе также публикуются по MQTT, где их получает драйвер и передает команду пользователя устройству.

Примеры работы через MQTT

Получение значения от датчика температуры и вывод его в веб-интерфейс

Показания датчика и его уникальный идентификатор на странице Devices веб-интерфейса

К Wiren Board подключён датчик температуры по шине 1-Wire. Проследим, как данные с него через MQTT попадают в веб-интерфейс:

1. Драйвер, отвечающий за данную аппаратную функцию (wb-homa-w1) опрашивает подключённые к контролеру датчики 1-Wire.
2. При получении значения драйвер публикует по MQTT сообщение вида:

   /devices/wb-w1/controls/28-0115a48fcfff 23.25

   Оно значит, что от устройства 1-Wire с идентификатором 28-0115a48fcfff получено значение 23.25 °C.
3. Веб-интерфейс, который подписан на все сообщения из MQTT, получает это сообщение и выводит значение датчика на страницу.

Нажатие кнопки в веб-интерфейсе и переключение реле на внешнем модуле

Веб-интерфейс после нажатия кнопки включения Реле 1 на подключённом по RS-485 релейном модуле WB-MRM2

К контроллеру по шине RS-485 подключён релейный модуль WB-MRM2. Пользователь в веб-интерфейсе нажимает кнопку включения реле. Проследим, как команда из веб-интерфейса попадает на внешний модуль:

1. После нажатия кнопки веб-интерфейс публикует по MQTT сообщение вида:

   /devices/wb-mrm2_130/controls/Relay 1/on 1

   Оно значит, что устройство WB-MRM2 с адресом 130 должно перевести Реле 1 в состояние логической единицы — «включено».
2. Драйвер wb-mqtt-serial, отвечающий за данную аппаратную функцию, получает это сообщение (он подписан на все сообщения, относящиеся к подключённым по RS-485 устройствам) и посылает по шине RS-485 релейному модулю команду на включение первого реле.
3. Релейный модуль WB-MRM2 получает команду от контроллера, переключает реле и посылает обратно уведомление «Реле 1 включено».
4. Драйвер wb-mqtt-serial получает это уведомление по RS-485 и публикует по MQTT сообщение:

   /devices/wb-mrm2_130/controls/Relay 1 1

   Оно значит, что первое реле на устройстве WB-MRM2 с адресом 130 находится (уже переведено) в состоянии логической единицы — «включено».

Принцип работы MQTT

Через MQTT работают драйверы внутренних функций, внешних устройств, веб-интерфейс, система правил

Система сообщений MQTT построена по следующему принципу:

• есть иерархическая система «топиков» (как на обычных форумах в интернете).
• в эти топики клиенты (в случае Wiren Board это драйверы устройств и веб-интерфейс) могут писать сообщения и читать оттуда.
• чтобы следить за изменениями нужного топика (например, температуры на датчике), клиент может на него «подписаться» — тогда он получит все сообщения в этом топике.

Читать полное описание системы топиков и подписок.

Отображение устройств в структуре сообщений

Логика организации топиков, соответствующих разным устройствам и их параметрам, в Wiren Board следует определённым правилам — так называемым соглашениям (Wiren Board MQTT Conventions).

Полный список MQTT-топиков можно увидеть на странице Settings веб-интерфейса в разделе MQTT Channels (появилось в последних версиях прошивки).

Клиенты MQTT

• драйверы внутренних аппаратных функций,
• драйверы внешних подключённых устройств,
• веб-интерфейс,
• движок правил,
• (если есть) собственные программы пользователя.

Структура сообщения о состоянии устройства

Вот сообщение от драйвера температурного датчика 1-Wire из примера выше:

/devices/wb-w1/controls/28-0115a48fcfff 23.25

Часть до пробела — название топика, после — само сообщение.

Название топика состоит из вложенных друг в друга «подтопиков»:

• /devices — коренной топик для всех «устройств» — как встроенных функций Wiren Board (цифровые, АЦП, ...), так и подключённых внешних (например, модулей реле).
• /wb-w1 — подтопик, который наполняется драйвером 1-Wire.
• /controls — подтопик, который есть у всех устройств — именно в него записываются все их параметры, которые меняются («включено-выключено», значение датчика, ...).
• /28-0115a48fcfff — непосредственно сам «канал» («контрол») — топик, куда записывается значение с датчика. Его название совпадает с адресом 1-Wire датчика на шине.

Содержание сообщения:

• 23.25 — значение температуры

Если вы хотите самостоятельно написать драйвер устройства, и хотите, что оно отображалось на вкладке Devices и его можно было использовать в правилах, вам необходимо придерживаться такой же структуры топиков.

Структура сообщения об ошибке опроса устройства

Каждый «канал» («контрол») имеет «подтопик» /meta/error, в котором содержится информация о наличии ошибок взаимодействия с устройством. Ошибки получения данных (чтения) обозначаются символом r, ошибки записи — w.

Пример ошибки получения данных:

/devices/wb-w1/controls/28-0115a48fcfff/meta/error r

Это означает, что не удалось получить температуру термометра с адресом 28-0115a48fcfff.

Драйвер wb-mqtt-serial устанавливает признак r, если не удалось запросить значение параметра устройства, признак w — не удалось передать значение устройству.

Драйвер wb-mqtt-adc устанавливает признак r, если не удалось получить значение соотвествующего канала АЦП.

Пример подписки

Клиенты, которые хотят следить за значением температуры, «подписываются» на этот топик, и им приходят все новые сообщения — меняющиеся значения температуры. Один из таких клиентов — веб-интерфейс.

Подписаться на сообщения можно и из консоли Linux при помощи утилиты mosquitto_sub:

root@wirenboard:~# mosquitto_sub -t '/devices/wb-w1/controls/28-0115a48fcfff' -v //получить сообщения из топика устройства 1-Wire с идентификатором 28-0115a48fcfff
/devices/wb-w1/controls/28-0115a48fcfff 22.75 //в этой строке и ниже - вывод утилиты, полученные сообщения
/devices/wb-w1/controls/28-0115a48fcfff 22.75
/devices/wb-w1/controls/28-0115a48fcfff 22.75

Полное описание работы с MQTT из командной строки смотрите ниже.

Структура сообщения — команды на изменение состояния

Подпишемся на сообщения о состоянии первого реле подключённого по RS-485 релейного модуля WB-MRM2:

root@wirenboard:~# mosquitto_sub -t "/devices/wb-mrm2_130/controls/Relay 1/#" -v
/devices/wb-mrm2_130/controls/Relay 1/meta/type switch
/devices/wb-mrm2_130/controls/Relay 1/meta/order 1
/devices/wb-mrm2_130/controls/Relay 1 0

Тут стоит отметить, что MQTT сохраняет часть сообщений (а именно те, которые при отправке были помечены флагом retained) вечно, поэтому после подписки вы получите даже те сообщения, которые были отправлены раньше, чем вы подписались.

Релейный модуль управляется драйвером Драйвер wb-mqtt-serial. У него есть соответствующий топик-«канал» («контрол») Relay 1. У него самого есть значение — 0 (реле выключено), и есть два подтопика. Один из них — служебный: в /meta/type записан тип «контрола». Здесь он switch — выключатель. Второй подтопик /on — интереснее: в него клиенты пишут то состояние, в которое они хотят установить реле. Заметим, что оно может не совпадать некоторое время (затрачиваемое на процесс переключения) с тем состоянием, в котором реле находится. Драйвер при этом ведёт себя следующим образом: при получении сообщения в топик /devices/wb-mrm2_130/controls/Relay 1/on он физически включает реле на релейном модуле, а лишь затем записывает новое состояние реле в топик /devices/wb-mrm2_130/controls/Relay.

Например, если мы сейчас нажмём на кнопку реле в веб-интерфейсе (переключим его состояние), то получим новые сообщения:

/devices/wb-mrm2_130/controls/Relay 1/on 1
/devices/wb-mrm2_130/controls/Relay 1 1

- веб-интерфейс сначала «даёт указание» включить реле, потом драйвер его включает и записывает актуальное состояние в «канал» («контрол»).

Работа с сообщениями MQTT

Программа (демон), отвечающая за рассылку сообщений от одних клиентов другим, называется брокером сообщений. В Wiren Board используется брокер сообщений Mosquitto. Фактически, все драйверы и веб-интерфейс передают свои сообщения именно демону-брокеру Mosquitto.

Работа из командной строки

Управление устройствами из командной строки

Для управления устройством (изменения значения канала), необходимо отправить сообщение в топик /devices/<device-id>/controls/<control-id>/on (обратите внимание на /on в конце). Это делается с помощью консольной команды mosquitto_pub. Пример:

root@wirenboard:~# mosquitto_pub -t "/devices/wb-mrm2_130/controls/Relay 1/on" -m "1"

команда отправляет сообщение «1» (логическую единицу, «включить») в топик, соответствующий подключённому по RS-485 релейном модуле WM-MRM2 с адресом 130.

Слежение за состоянием устройства / подписка на топик

Клиенты, которые хотят следить за значением температуры, «подписываются» на этот топик, и им приходят все новые сообщения - меняющиеся значения температуры. Один из таких клиентов - веб-интерфейс.

Подписаться на сообщения можно и из консоли Linux при помощи утилиты mosquitto_sub (полное описание утилиты смотрите на http://mosquitto.org/man/mosquitto_sub-1.html):

root@wirenboard:~# mosquitto_sub -t '/devices/wb-w1/controls/28-0115a48fcfff' -v //получить сообщения из топика устройства 1-Wire с идентификатором 28-0115a48fcfff
/devices/wb-w1/controls/28-0115a48fcfff 22.75 //в этой строке и ниже — вывод утилиты, полученные сообщения
/devices/wb-w1/controls/28-0115a48fcfff 22.75
/devices/wb-w1/controls/28-0115a48fcfff 22.75

Метасимволы

Подписаться можно не только на один топик, но и на группу топиков по метасиволу. В MQTT применяется два метасимвола: # и +. Метасимвол # означает любое количество уровней вложенных топиков. Выполним команду

root@wirenboard:~# mosquitto_sub -t '/devices/wb-w1/#' -v
/devices/wb-w1/meta/name 1-wire Thermometers
/devices/wb-w1/controls/28-0115a48fcfff 22.812
/devices/wb-w1/controls/28-0115a48fcfff/meta/type temperature
/devices/wb-w1/controls/28-0115a48fcfff 22.75

В результате мы получили не только значения с «контрола» устройства, но и топики с метаданными — название драйвера устройства и тип «контрола» - temperature. Существует так же метасимвол +, который обозначает один уровень, а не произвольное количество,как #:

mosquitto_sub -v -t "/config/widgets/+/name"

В этом случае мы получим имена всех виджетов.

Полное описание системы топиков и подписок.

Очистка очереди сообщений

Ненужные retained-сообщения могут остаться в системе MQTT после удаления неиспользуемых драйверов или отключения каких-либо устройств. Это приводит к тому, что несуществующие больше устройства могут отображаться в разделе Devices веб-интерфейса.

Для удаления топиков можно воспользоваться командой mqtt-delete-retained.

Например, удалим все топики, начинающиеся на /devices/noolite_tx_1234/

root@wirenboard:~# mqtt-delete-retained '/devices/noolite_tx_1234/#'

Для удаления топиков «по маске», можно циклично вызывать runShellCommand из правил. Таким образом, задача сводится к задаче работы со строками в js.

var deviceName = ['name1',.., 'nameN'];
var controlName = 'Temperature';

for (var i = 0; i<deviceName.length; i++) {
  runShellCommand ('mqtt-delete-retained /devices/'+ deviceName[i]  + '/controls/controlName/#'); 
}

Работа с MQTT из внешних программ

Если вы разрабатываете собственное ПО для Wiren Board, взаимодействовать с его аппаратными ресурсами лучше всего через протокол MQTT — ваша программа передаёт сообщение по MQTT, драйвер управляет устройством и вашей программе не нужно напрямую взаимодействовать с устройством на низком уровне.

Для того, чтобы отправлять сообщения MQTT, для многих языков программирования есть библиотеки:

• Python - [1]
• C - [2]

Просмотр MQTT-каналов в web-интерфейсе

MQTT-названия устройств, их элементов управления и последние значения можно найти в разделе Settings web-интерфейса:

Информация об MQTT-названиях устройств

Настройка MQTT моста (bridge)

Настройки брокера Cloud MQTT

MQTT мост (bridge) — это функция MQTT-брокера, позволяющая пересылать все или часть сообщений на другой MQTT-брокер, и получать сообщения с другого брокера обратно. На контроллере эта функция настраивается в конфигурационных файлах mosquitto. Самый простой вариант конфигурации приведён ниже.

Задача: настроить пересылку всех сообщений MQTT на популярный дешёвый облачный MQTT брокер http://cloudmqtt.com/ и обратно.

Решение:

1. Зарегистрируйтесь на http://cloudmqtt.com/
2. Зайдите в свой аккаунт на http://cloudmqtt.com/ и посмотрите настройки: сервер, порт, логин, пароль.
3. Зайдите на контроллер и добавьте в конец файла /etc/mosquitto/mosquitto.conf следующие строки:

   connection cloudmqtt
   address m21.cloudmqtt.com:10858
   remote_username fs_user_kp
   remote_password 5dn_pass_pm
   clientid pavel_test
   try_private false
   start_type automatic
   topic # both
   

   (последняя строка говорит, что нужно пересылать все сообщения (метасимвол #, смотрите описание выше) в обе (both) стороны (с брокера контроллера на облачный брокер и обратно)

   Более подробное описание всех опций смотрите на https://mosquitto.org/man/mosquitto-conf-5.html.

4. Перезапустите mosquitto, выполнив в консоли:

   service mosquitto restart
   

Другие облачные брокеры

Список облачных брокеров, в том числе бесплатных: https://github.com/mqtt/mqtt.github.io/wiki/public_brokers

Задача: настроить пересылку топика MQTT на другой контроллер. Есть два контроллера в одной сети^

1. DestinationController с адресом 10.0.0.40, на этот контроллер получать топик.
2. SourceController с адресом 10.0.0.70, с этого контроллера будем забирать топик.

На SourceController есть /client/temp1, но его нужно видеть на DestinationController в /devices/temp1.

Решается двумя способами, можно с SourceController публиковать на DestinationController или с DestinationController подписаться на топик SourceController и забирать изменения. От выбора стратегии зависит на каком контроллере будем проводить настройки.

Мы будем настраивать DestinationController.

Решение: На контроллере DestinationController добавьте в конфиг:

mcedit /etc/mosquitto/conf.d/bridge.conf

Строки:

connection wb_40
address 10.0.0.70
notifications true
notification_topic /client/wb_40/bridge_status
keepalive_interval 20
restart_timeout 20

topic /temp1/# in 2 /devices /client

Перезапустите mosquitto на DestinationController:

systemctl restart mosquitto; systemctl status mosquitto

ВАЖНО: перед перезапуском желательно остановить watchdog. В случае ошибки в конфигурационных файлах брокер не запустится и watchdog вызовет перезапуск контроллера.

Рассмотрим подробнее строчку topic /temp1/# in 2 /devices /client где:

• /temp1/# это топик от «корня». На брокере-источнике /client/temp1.
• in — только забираем, изменения на контроллере не передадутся на сервер.
• /devices — «корень» куда располагаем локально. На контроллере DestinationController это /devices и полный путь будет выгляджеть как /devices/temp1.
• /client — «корень» откуда забираем на удаленном. На контроллере SourceController это /client и полный путь будет выгляджеть как /client/temp1.

Проверка: Дожидаемся статуса бриджа «1» в топике /client/wb_40/bridge_status на контроллере SourceController. На нем же публикуем:

for i in {1..25}
do
mosquitto_pub  -t "/client/temp1/temp" -m "$i" -r
done

Подписавшись на контроллере DestinationController на целевой топик можно видеть:

mosquitto_sub -v -t /devices/temp1/# 
/devices/temp1/temp
/devices/temp1/temp 1
/devices/temp1/temp 2
/devices/temp1/temp 3
/devices/temp1/temp 4
/devices/temp1/temp 5
/devices/temp1/temp 6
/devices/temp1/temp 7
/devices/temp1/temp 8
/devices/temp1/temp 9
/devices/temp1/temp 10
/devices/temp1/temp 11
/devices/temp1/temp 12
/devices/temp1/temp 13
/devices/temp1/temp 14
/devices/temp1/temp 15
/devices/temp1/temp 16
/devices/temp1/temp 17
/devices/temp1/temp 18
/devices/temp1/temp 19
/devices/temp1/temp 20
/devices/temp1/temp 21
/devices/temp1/temp 22
/devices/temp1/temp 23
/devices/temp1/temp 24
/devices/temp1/temp 25

Настройка своего брокера MQTT

Установка

Установите mosquitto:

apt update && apt install mosquitto -y

Отредактируйте файл конфигурации, отключив возможность анонимного входа:

cat << EOF >>/etc/mosquitto/mosquitto.conf

#Disable anonomous login:
allow_anonymous false
#Password file:
password_file /etc/mosquitto/mosquitto.pwd

EOF

Создайте пароль для пользователя, в примере использован пользователь test с паролем test11test:

mosquitto_passwd -c /etc/mosquitto/mosquitto.pwd test

Введите дважды пароль и запомните его, он вам пригодится ниже.

Перезапустите mosquitto и проверьте его состояние:

systemctl restart mosquitto && systemctl status mosquitto

Подключитесь к брокеру для проверки, в примере адрес брокера 10.0.26.1:

mosquitto_sub -v -h 10.0.26.1 -u test -P test11test -t "/#"

Запустите в другой консоли команду ниже и убедитесь, что топик меняется:

for i in {1..25}; do mosquitto_pub -h 10.0.26.1 -u test -P test11test -t "/client/temp1/temp" -m "$i" -r; done

Брокер установлен, доступ к нему разрешен только с логином и паролем, с контроллера брокер доступен.