MQTT: различия между версиями

'''MQTT''' — протокол обмена данными, использующийся в [[Программное обеспечение Wiren Board|программном обеспечении Wiren Board]]. [http://en.wikipedia.org/wiki/MQTT Базовая информация по MQTT на Википедии].

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

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

Через MQTT работают: веб-интерфейс, движок правил и встроенные драйверы. Если вы разрабатываете собственное ПО в дополнение к предустановленному — мы рекомендуем использовать MQTT.

[[File:Web-devices-1-wire.png|400px|thumb|Показания датчика и его уникальный идентификатор на странице ''Devices'' веб-интерфейса]]

#При получении значения драйвер публикует MQTT сообщение вида: <pre>/devices/wb-w1/controls/28-0115a48fcfff 23.25</pre>Оно значит, что от устройства 1-Wire с идентификатором ''28-0115a48fcfff'' получено значение 23.25 °C.

#Веб-интерфейс, который подписан на все сообщения из MQTT, получает это сообщение и выводит значение датчика на страницу.

[[File:Web-devices-serial.png|400px|thumb|Веб-интерфейс после нажатия кнопки включения Реле 1 на подключённом по RS-485 релейном модуле [[WB-MRM2]]]]

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

#Драйвер wb-mqtt-serial получает это уведомление по RS-485 и публикует по MQTT сообщение:<pre>/devices/wb-mrm2_130/controls/Relay 1 1</pre>Оно значит, что первое реле на устройстве WB-MRM2 с адресом ''130'' находится (уже переведено) в состоянии логической единицы — «включено».

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

*есть иерархическая система «топиков» (как на обычных форумах в интернете).

[http://mosquitto.org/man/mqtt-7.html Читать полное описание системы топиков и подписок].

Логика организации топиков, соответствующих разным устройствам и их параметрам, в Wiren Board следует определённым правилам — так называемым соглашениям ([https://github.com/wirenboard/conventions/blob/main/README.md Wiren Board MQTT Conventions]).

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

*драйверы внешних подключённых устройств,

*веб-интерфейс,

*(если есть) собственные программы пользователя.

<pre>

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

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

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

* <code>/devices</code> — коренной топик для всех «устройств» — как встроенных функций Wiren Board (цифровые, АЦП, ...), так и подключённых внешних (например, модулей реле).

* <code>23.25</code> — значение температуры

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

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

<pre>

</pre>

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

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

[https://github.com/wirenboard/wb-homa-adc Драйвер wb-mqtt-adc] устанавливает признак '''r''', если не удалось получить значение соотвествующего канала АЦП.

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

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

<syntaxhighlight lang="bash">

</syntaxhighlight>

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

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

<syntaxhighlight lang="bash">

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

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

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

<pre>

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

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

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

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

Это делается с помощью консольной команды '''mosquitto_pub'''. Пример:

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

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

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

</syntaxhighlight>

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

<syntaxhighlight lang="bash">

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

[http://mosquitto.org/man/mqtt-7.html Полное описание системы топиков и подписок].

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

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

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

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

<syntaxhighlight lang="bash">

</syntaxhighlight>

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

<syntaxhighlight lang="bash">

var controlName = 'Temperature';

for (var i = 0; i<deviceName.length; i++) {

   runShellCommand ('mqtt-delete-retained /devices/'+ deviceName[i]  + '/controls/controlName/#');  

</syntaxhighlight>

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

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

* Python - [https://github.com/contactless/mqtt-tools]

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

[[Файл:Wb_settings.png|900px|thumb|center|Информация об MQTT-названиях устройств]]

Установленный на контроллер брокер mosquitto по умолчанию принимает подключения внешних клиентов по порту 1883 без пароля.

Например, если контроллер имеет адрес 192.168.0.67, его топики можно прочитать с другого компьютера с Linux, находящегося в той же сети:

<syntaxhighlight lang="bash">

</syntaxhighlight>

Альтернативный вариант — использовать [[MQTT Explorer]].

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

Эту функцию удобно применять в следующей ситуации: хотя на самом контроллере уже есть MQTT-брокер, к нему часто неудобно подключаться, так как контроллер может не иметь белого IP-адреса, а иногда может быть выключен или не в сети. В таком случае удобно иметь отдельный брокер в облаке с фиксированным адресом, который будет всегда онлайн, и на который будут пересылаться сообщения с брокера контроллера.

На контроллере эта функция настраивается в конфигурационных файлах ''mosquitto''. Самый простой вариант конфигурации приведён ниже.

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

'''Решение:'''

# Зарегистрируйтесь на http://cloudmqtt.com/

[[File:Clusterfly3.png | thumb | 400px | Настройки брокера CLUSTERFLY]]

'''Задача:''' настроить пересылку всех сообщений MQTT на бесплатный облачный MQTT брокер https://clusterfly.ru/ и обратно.

'''Решение:'''

# Зарегистрируйтесь на https://clusterfly.ru/

# Зайдите в свой аккаунт на https://clusterfly.ru/ и выберите "Профиль" посмотрите настройки: сервер, порт, логин и сгенерируйте пароль. Для пересылки используйте сервер <code>srv1.clusterfly.ru</code>.

</syntaxhighlight>

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

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

Есть два контроллера в одной сети:

# ''SourceController'' с адресом <code>10.0.0.70</code>, с этого контроллера будем забирать топик.

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

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

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

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

<syntaxhighlight lang="bash">

restart_timeout 20

topic /temp1/# in 2 /devices /client

</syntaxhighlight>

Перезапустите <code>mosquitto</code> на ''DestinationController'':

<syntaxhighlight lang="bash">

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

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

где:

* <code>/client</code> — «корень» откуда забираем на удаленном. На контроллере ''SourceController'' это <code>/client</code> и полный путь будет выгляджеть как '''/client'''/temp1.

'''Проверка:'''

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

</syntaxhighlight>

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

<syntaxhighlight lang="bash">

</syntaxhighlight>

Вы можете создать отдельный брокер на компьютере или на VDS-сервере в интернете и собирать на нем данные с контроллеров.

Инициировать соединение будет контроллер, поэтому контроллеру не нужен «белый» IP-адрес. Если контроллеров несколько, вы можете разделить данные от них на брокере, для этого в настройках моста укажите для каждого контроллера отдельный корневой топик.

#Установите <code>mosquitto</code>:

#:<syntaxhighlight lang="bash">

Брокер установлен и доступен с контроллера. Для подключения нужно ввести логин и пароль.

Создайте файл конфигурации моста, для этого:

# Создайте файл <code>/etc/mosquitto/conf.d/bridge1.conf</code>

remote_password wbpassword

topic /temp1/# both 2 /devices /controller

</syntaxhighlight>

Содержимое топика <code>/devices/temp1/#</code> контроллера будет отображаться на брокере в <code>/controller</code>. Вместо <code>/controller</code> можете указать уникальное имя контроллера, например, серийный номер.