Common/Topics: различия между версиями

Текущая версия от 16:48, 6 августа 2025

HOMEd > Структура MQTT-топиков

Общие сведения

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

В описании топиков используются следующие элементы:

{prefix} - корневой топик, как указано в файле конфигурации любого сервиса
{service} - название сервиса в нижнем регистре, например, recorder или zigbee
{deviceId} - идентификатор устройства или его имя (в зависимости от конфигурации соответствующего сервиса)
[/instance] - название инстанса, в случае, если оно указано в файле конфигурации (для сервисов, поддерживающих кластеризацию)
[/endpointId] - номер конечной точки для устройств с несколькими однотипными конечными точками, таких как многоканальные реле или выключатели

Топики сервисов

service

{prefix}/service/{service}[/instance]

Топики, в которые сервисы HOMEd публикуют состояние своей доступности. Данные топики являются LWT-топиками, это значит, что при потере соединения между каким-либо сервисом и MQTT-брокером (по причине плохой связи или некорректного завершения работы сервиса), брокер самостоятельно опубликует в соответствующий топик сообщение с содержимым {"status":"offline"}.

Топики публикуются с флагом retain.

status

{prefix}/status/{service}[/instance]

Топики, в которые сервисы HOMEd публикуют свои версии и статические данные, такие, как списки устройств, настройки дашбордов и автоматизаций.

Топики публикуются с флагом retain.

command

{prefix}/command/{service}[/instance]

Топики, в которые сервисы HOMEd публикуют сообщения для общения с другими сервисами, например, для запроса актуальных состояний или управления настройками устройств.

Топики публикуются без флага retain.

Топики устройств

device

{prefix}/device/{service}[/instance]/{deviceId}

Топики, в которые сервисы HOMEd, работающие с устройствами, публикуют состояния доступности своих устройств. Помимо прочего, сервис ZigBee публикует в эти топики метки времени "lastSeen", указывающие на момент получения последних данных от устройства.

Топики публикуются с флагом retain.

expose

{prefix}/expose/{service}[/instance]/{deviceId}

Топики, в которые сервисы HOMEd, работающие с устройствами, публикуют данные о способностях устройств и соответствующие им опции.

Топики публикуются с флагом retain.

fd - from device

{prefix}/fd/{service}[/instance]/{deviceId}[/endpointId]

Топики, в которые сервисы HOMEd, работающие с устройствами, публикуют данные, полученные от устройств. Помимо прочего, сервис ZigBee публикует в эти топики параметр "linkQuality", указывающий на качество связи с устройством (с ближайшим к координатору роутером, в случае, когда устройство работает через роутер).

Топики публикуются без флага retain.

td - to device

{prefix}/td/{service}[/instance]/{deviceId}[/endpointId]

Топики, из которых сервисы HOMEd, работающие с устройствами, получают данные для управления устройствами. Эти данные публикуются, например, сервисом автоматизаций.

Топики публикуются без флага retain.

Специальные топики

recorder

{prefix}/recorder

Топик, в который рекордер публикует данные для построения графиков. Топик публикуется без флага retain.

@@ Строка 3: / Строка 3: @@
 == Общие сведения ==
-Статья содержит обобщенные данные о структуре MQTT-топиков, посредством которых сервисы HOMEd общаются друг с другом, и не включает в себя описание данных, которые содержат эти топики. Для ознакомления со структурой данных можно почитать соответствующие статьи на страницах сервисов в этой вики или воспользоваться приложением [http://mqtt-explorer.com MQTT Explorer] для самостоятельного изучения (на мой взгляд - ''там нет ничего сложного'').
+Статья содержит обобщенные данные о структуре MQTT-топиков, посредством которых сервисы ''HOMEd'' общаются друг с другом, и не включает в себя описание данных, которые содержат эти топики. Для ознакомления со структурой данных можно почитать соответствующие статьи на страницах сервисов в этой вики или воспользоваться приложением [http://mqtt-explorer.com MQTT Explorer] для самостоятельного изучения (на мой взгляд, ''там нет ничего сложного'').
 В описании топиков используются следующие элементы:
@@ Строка 9: / Строка 9: @@
 * <code class="value">{service}</code> - название сервиса в нижнем регистре, например, <code class="value">recorder</code> или <code class="value">zigbee</code>
 * <code class="value">{deviceId}</code> - идентификатор устройства или его имя (в зависимости от конфигурации соответствующего сервиса)
-* <code class="value">[/instance]</code> - название инстанса, в случае, если указано (для сервисов, поддерживающих кластеризацию)
+* <code class="value">[/instance]</code> - название инстанса, в случае, если оно указано в файле конфигурации (для сервисов, поддерживающих кластеризацию)
-* <code class="value">[/endpointId]</code> - номер конечной точки устройства для устройств с несколькими однотипными конечными точками, таких как многоканальные реле или выключатели
+* <code class="value">[/endpointId]</code> - номер конечной точки для устройств с несколькими однотипными конечными точками, таких как многоканальные реле или выключатели
+== Топики сервисов ==
 === service ===
 {{#tag:pre|<nowiki>{prefix}/service/{service}[/instance]</nowiki>}}
-Топики, в которые сервисы HOMEd публикуют состояние своей доступности. Данные топики являются LWT-топиками, это значит, что при потере соединения между каким-либо сервисом и брокером (по причине плохой связи или некорректного завершения работы сервиса), брокер сам опубликует в соответсвующий топик сообщение с содержимым <code>{"status":"offline"}</code>.
+Топики, в которые сервисы ''HOMEd'' публикуют состояние своей доступности. Данные топики являются LWT-топиками, это значит, что при потере соединения между каким-либо сервисом и MQTT-брокером (по причине плохой связи или некорректного завершения работы сервиса), брокер самостоятельно опубликует в соответствующий топик сообщение с содержимым <code>{"status":"offline"}</code>.
+Топики публикуются с флагом '''retain'''.
 === status ===
 {{#tag:pre|<nowiki>{prefix}/status/{service}[/instance]</nowiki>}}
-Топики, в которые сервисы HOMEd публикуют свои версии и статические данные, такие, как списки устройств, настройки дашбордов и автоматизаций.
+Топики, в которые сервисы ''HOMEd'' публикуют свои версии и статические данные, такие, как списки устройств, настройки дашбордов и автоматизаций.
+Топики публикуются с флагом '''retain'''.
+=== command ===
+{{#tag:pre|<nowiki>{prefix}/command/{service}[/instance]</nowiki>}}
+Топики, в которые сервисы ''HOMEd'' публикуют сообщения для общения с другими сервисами, например, для запроса актуальных состояний или управления настройками устройств.
+Топики публикуются ''без'' флага '''retain'''.
+== Топики устройств ==
 === device ===
 {{#tag:pre|<nowiki>{prefix}/device/{service}[/instance]/{deviceId}</nowiki>}}
-Топики, в которые сервисы HOMEd, работающие с устройствами, публикуют состояния доступности своих устройств. Помимо прочего, сервис  [[ZigBee|ZigBee]] публикует в эти топики метки времени <code>"lastSeen"</code>, указывающие на момент получения последних данных от устройства.
+Топики, в которые сервисы ''HOMEd'', работающие с устройствами, публикуют состояния доступности своих устройств. Помимо прочего, сервис  [[ZigBee|ZigBee]] публикует в эти топики метки времени <code>"lastSeen"</code>, указывающие на момент получения последних данных от устройства.
+Топики публикуются с флагом '''retain'''.
 === expose ===
 {{#tag:pre|<nowiki>{prefix}/expose/{service}[/instance]/{deviceId}</nowiki>}}
-Топики, в которые сервисы HOMEd, работающие с устройствами, публикуют данные о [[Common/Exposes|способностях]] устройств и соответствующие им [[Common/Options|опции]].
+Топики, в которые сервисы ''HOMEd'', работающие с устройствами, публикуют данные о [[Common/Exposes|способностях]] устройств и соответствующие им [[Common/Options|опции]].
-=== fd - ''from device'' ===
+Топики публикуются с флагом '''retain'''.
+=== fd ''- from device'' ===
 {{#tag:pre|<nowiki>{prefix}/fd/{service}[/instance]/{deviceId}[/endpointId]</nowiki>}}
-Топики, в которые сервисы HOMEd, работающие с устройствами, публикуют данные, полученные от устройств. Помимо прочего, сервис  [[ZigBee|ZigBee]] публикует в эти топики параметр <code>"lastSeen"</code>, указывающий на качество связи с устройством (с ближайшим к координатору роутером, в случае, когда устройство работает через роутер).
+Топики, в которые сервисы ''HOMEd'', работающие с устройствами, публикуют данные, полученные от устройств. Помимо прочего, сервис  [[ZigBee|ZigBee]] публикует в эти топики параметр <code>"linkQuality"</code>, указывающий на качество связи с устройством (с ближайшим к координатору роутером, в случае, когда устройство работает через роутер).
-=== td - ''to device'' ===
+Топики публикуются ''без'' флага '''retain'''.
+=== td ''- to device'' ===
 {{#tag:pre|<nowiki>{prefix}/td/{service}[/instance]/{deviceId}[/endpointId]</nowiki>}}
-Топики, из которых сервисы HOMEd, работающие с устройствами, получают данные для управления устройствами. Эти данные публикуются, например, сервисом [[Automation|автоматизаций]].
+Топики, из которых сервисы ''HOMEd'', работающие с устройствами, получают данные для управления устройствами. Эти данные публикуются, например, сервисом [[Automation|автоматизаций]].
+Топики публикуются ''без'' флага '''retain'''.
+== Специальные топики ==
+=== recorder ===
+{{#tag:pre|<nowiki>{prefix}/recorder</nowiki>}}
+Топик, в который [[Recorder|рекордер]] публикует данные для построения графиков. Топик публикуется ''без'' флага '''retain'''.
+[[Category:Common]]
+[[Category:Automation]]
+[[Category:Cloud]]
+[[Category:Recorder]]
+[[Category:Web]]
+[[Category:Custom]]
+[[Category:Modbus]]
+[[Category:ZigBee]]