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

Версия 00:00, 24 октября 2015

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

Базовая информация по MQTT - статья на википедии. Используемый демон - брокер сообщений Mosquitto.

Краткая схема работы

Архитектура ПО Wiren Board:

thumb | 600px

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

Принцип работы системы сообщений

MQTT построена по следующему принципу: есть иерархическая система "топиков" (прямо как на обычных форумах), куда клиенты могут писать сообщения, и откуда могут читать. Чтобы было удобно следить за изменениями нужного топика (например, температуры), на него можно "подписаться".

Пример сообщения

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

/devices/wb-w1/controls/28-000004a7d3f9 24.687000

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

/devices - коренной топик для всех "устройств" - как встроенных модулей Wiren Board (реле, АЦП, ...), так и подключённых внешних,
/wb-w1 - подтопик, который наполняется драйвером 1-Wire,
/controls - подтопик, который есть у всех устройств - именно в него записываются все их параметры, которые меняются ("включено-выключено", значение датчика, ...),
/28-000004a7d3f9 - непосредственно сам "контрол" - топик, куда записывается значение с датчика. Его название совпадает с адресом 1-Wire датчика (аппаратно закладывается в каждый датчик на заводе),
24.687000 - значение температуры. Это и есть содержание сообщения, отправленного драйвером 1-Wire в топик.

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

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

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

root@wirenboard:~# mosquitto_sub -t '/devices/wb-w1/controls/28-000004a7d3f9' -v 
/devices/wb-w1/controls/28-000004a7d3f9 20.312000
/devices/wb-w1/controls/28-000004a7d3f9 20.312000
/devices/wb-w1/controls/28-000004a7d3f9 20.375000

(описание утилиты смотрите [1]).

Подписаться можно не только на один топик, но и на группу по wildcard:

root@wirenboard:~# mosquitto_sub -t '/devices/wb-w1/#' -v
/devices/wb-w1/meta/name 1-wire Thermometers
/devices/wb-w1/controls/28-000004a7d3f9 23.312000
/devices/wb-w1/controls/28-000004a7d3f9/meta/type temperature
/devices/wb-w1/controls/28-000004a7d3f9 23.312000
/devices/wb-w1/controls/28-000004a7d3f9 23.312000

, где # - означает любое количество топиков. Соответственно, вывелись не только значения с "контрола" устройства, но и топики с метаданными - название драйвера устройства и тип "контрола" - temperature.

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

Пример сообщения от веб-интерфейса

Подпишемся на сообщения о состоянии встроенного реле Wiren Board:

root@wirenboard:~# mosquitto_sub -t '/devices/wb-gpio/controls/Relay_1/#' -v
/devices/wb-gpio/controls/Relay_1/meta/type switch
/devices/wb-gpio/controls/Relay_1/on 0
/devices/wb-gpio/controls/Relay_1 0

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

Реле управляется драйвером wb-gpio (этот драйвер также управляет транзисторными выходами и всем, что в электрическом смысле управляется GPIO). У него есть соответствующий топик-"контрол" Relay_1. У него самого есть значение - 0 (реле выключено), и есть два подтопика. Один из них - служебный: в /meta/type записан тип "контрола". Здесь он switch - выключатель. Второй подтопик /on - интереснее: в него клиенты пишут то состояние, в которое они хотят установить реле. Заметим, что оно может не совпадать с тем состоянием, в котором реле находится, так как драйвер реле ведёт себя следующим образом: при получении сообщения в топик /devices/wb-gpio/controls/Relay_1/on он физически устанавливает его на реле, а лишь затем записывает новое значение реле в топик /devices/wb-gpio/controls/Relay_1.

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

/devices/wb-gpio/controls/Relay_1/on 1
/devices/wb-gpio/controls/Relay_1 1

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

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

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

mosquitto_pub -t "/devices/wb-gpio/controls/Relay_1/on" -m "1"

команда включает реле 1 (канал "Relay_1" устройства "wb-gpio").

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

Логика топиков, соответствующих разным устройствам и их параметрам, основывается на так называемых Conventions. Список актуальных типов здесь: [3]

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

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

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

Использование:

mqtt-delete-retained <маска mqtt>

например:

mqtt-delete-retained '/devices/noolite_tx_1234/#'

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

Использование данных внешними программами

Для многих языков программирования есть библиотеки MQTT. Примеры программ:

Python - [4]
C - [5]

Система правил

Вы можете написать свои правила на языке Javascript. Подробнее смотрите [6]

@@ Строка 1: / Строка 1: @@
 <languages/>
 <translate>
+<!--T:1-->
 '''MQTT''' - очередь сообщений, использующаяся в Wiren Board. Большая часть встроенных функций контроллера (АЦП, реле, транзисторный выход, watchdog) и внешних совместимых устройств транслируются туда в виде сообщений и реагируют на управляющие сообщения оттуда. [[Wiren Board 4:Веб-интерфейс | Веб-интерфейс]] работает также через систему сообщений MQTT - нажатие кнопки в интерфейсе вызывает отправку сообщения сообщения в MQTT-брокер, изменение показания датчика, поступившее в систему сообщений, тут же транслируется в веб-интерфейс.
+<!--T:2-->
 Базовая информация по MQTT - [http://en.wikipedia.org/wiki/MQTT статья] на википедии. Используемый демон - брокер сообщений [http://mosquitto.org/ Mosquitto].
-== Краткая схема работы ==
+== Краткая схема работы == <!--T:3-->
+<!--T:4-->
 Архитектура ПО Wiren Board:
+<!--T:5-->
 [[Special:MyLanguage/File:MQTT.png | thumb | 600px]]
+<!--T:6-->
 Специальные "драйверы" (отдельный для каждой функции контроллера и внешнего устройства) транслируют данные с устройства в очередь в виде сообщений специального формата. Сообщения из этой очереди получает веб-интерфейс и движок правил. Они же могут добавлять туда новые сообщения - например, "включить реле" после получения нажатия в интерфейсе или выполнения нужных условий в каком-нибудь правиле.
-== Принцип работы системы сообщений ==
+== Принцип работы системы сообщений == <!--T:7-->
+<!--T:8-->
 MQTT построена по следующему принципу: есть иерархическая система "топиков" (прямо как на обычных форумах), куда клиенты могут писать сообщения, и откуда могут читать. Чтобы было удобно следить за изменениями нужного топика (например, температуры), на него можно "подписаться".
-=== Пример сообщения ===
+=== Пример сообщения === <!--T:9-->
+<!--T:10-->
 Вот пример сообщения от драйвера датчика 1-Wire (драйвер регулярно опрашивает датчик и отправляет в виде сообщений значения с него):
 <pre>
@@ Строка 34: / Строка 41: @@
-=== Пример подписки ===
+=== Пример подписки === <!--T:11-->
+<!--T:12-->
 Клиенты, которые хотят следить за значением температуры, "подписываются" на этот топик, и им приходят все новые сообщения - меняющиеся значения температуры. Один из таких клиентов - веб-интерфейс.
+<!--T:13-->
 Подписаться на сообщения можно и из консоли Linux при помощи утилиты '''mosquitto_sub''':
 <pre>
@@ Строка 47: / Строка 56: @@
 (описание утилиты смотрите [http://mosquitto.org/man/mosquitto_sub-1.html]).
+<!--T:14-->
 Подписаться можно не только на один топик, но и на группу по wildcard:
 <pre>
@@ Строка 58: / Строка 68: @@
 , где ''#'' - означает любое количество топиков. Соответственно, вывелись не только значения с "контрола" устройства, но и топики с метаданными - название драйвера устройства и тип "контрола" - ''temperature''.
+<!--T:15-->
 Полное описание системы топиков и подписок: [http://mosquitto.org/man/mqtt-7.html].
-=== Пример сообщения от веб-интерфейса ===
+=== Пример сообщения от веб-интерфейса === <!--T:16-->
+<!--T:17-->
 Подпишемся на сообщения о состоянии встроенного реле Wiren Board:
 <pre>
@@ Строка 72: / Строка 84: @@
 Тут стоит отметить, что MQTT сохраняет часть сообщений (а именно с флагом retained) вечно, поэтому после подписки вы получите даже те сообщения, которые были отправлен раньше, чем вы подписались.
+<!--T:18-->
 Реле управляется драйвером ''wb-gpio'' (этот драйвер также управляет транзисторными выходами и всем, что в электрическом смысле управляется GPIO). У него есть соответствующий топик-"контрол" ''Relay_1''. У него самого есть значение - ''0'' (реле выключено), и есть два подтопика. Один из них - служебный: в ''/meta/type'' записан тип "контрола". Здесь он ''switch'' - выключатель. Второй подтопик ''/on'' - интереснее: в него клиенты пишут то состояние, в которое они хотят установить реле. Заметим, что оно может не совпадать с тем состоянием, в котором реле находится, так как драйвер реле ведёт себя следующим образом: при получении сообщения в топик ''/devices/wb-gpio/controls/Relay_1/on'' он физически устанавливает его на реле, а лишь затем записывает новое значение реле в топик ''/devices/wb-gpio/controls/Relay_1''.
+<!--T:19-->
 Например, если мы сейчас нажмем на реле в веб-интерфейсе (переключим его состояние), то получим новые сообщения:
 <pre>
@@ Строка 82: / Строка 96: @@
-=== Управление устройствами из командной строки ===
+=== Управление устройствами из командной строки === <!--T:20-->
+<!--T:21-->
 Как следует из написанного выше, для управления устройством (изменения значения канала), необходимо отправить сообщение в топик "/devices/<device-id>/controls/<control-id>/on" (обратите внимание на /on в конце).
 Это легко сделать с помощью консольной команды mosquitto_pub . Пример:
+<!--T:22-->
 <pre>
 mosquitto_pub -t "/devices/wb-gpio/controls/Relay_1/on" -m "1"
 </pre>
+<!--T:23-->
 команда включает реле 1 (канал "Relay_1" устройства "wb-gpio").
@@ Строка 98: / Строка 115: @@
-=== Отображение устройств в системе сообщений ===
+=== Отображение устройств в системе сообщений === <!--T:24-->
+<!--T:25-->
 Логика топиков, соответствующих разным устройствам и их параметрам, основывается на так называемых Conventions. Список актуальных типов здесь: [https://github.com/contactless/homeui/blob/contactless/conventions.md]
-== Очистка сообщений MQTT ==
+== Очистка сообщений MQTT == <!--T:26-->
+<!--T:27-->
 Ненужные retained-сообщения могут остаться в системе MQTT после удаления неиспользуемых драйверов или отключения каких-либо устройств.
 Это приводит к тому, что несуществующие больше устройства могут отображаться в разделе Devices веб-интерфейса.
+<!--T:28-->
 Для удаления топиков можно воспользоваться командой mqtt-delete-retained.
+<!--T:29-->
 Использование:
+<!--T:30-->
 <pre>
 mqtt-delete-retained <маска mqtt>
 </pre>
+<!--T:31-->
 например:
+<!--T:32-->
 <pre>
 mqtt-delete-retained '/devices/noolite_tx_1234/#'
 </pre>
+<!--T:33-->
 - удалит все топики, начинающиеся на '/devices/noolite_tx_1234/'
@@ Строка 127: / Строка 152: @@
-== Использование данных внешними программами ==
+== Использование данных внешними программами == <!--T:34-->
+<!--T:35-->
 Для многих языков программирования есть библиотеки MQTT. Примеры программ:
 * Python - [https://github.com/contactless/mqtt-tools]
@@ Строка 134: / Строка 160: @@
-== Система правил ==
+== Система правил == <!--T:36-->
+<!--T:37-->
 Вы можете написать свои правила на языке Javascript. Подробнее смотрите [https://github.com/contactless/wb-rules]
 </translate>

Навигация