MQTT KNX V2: различия между версиями
(→Описание: Исправлена опечатка) Метки: правка с мобильного устройства правка из мобильной версии Расширенная мобильная правка |
|||
(не показаны 84 промежуточные версии 1 участника) | |||
Строка 1: | Строка 1: | ||
{{DISPLAYTITLE: Описание сервиса wb-mqtt-knx}} | |||
{{DISPLAYTITLE: | |||
== Описание == | == Описание == | ||
[[Image: WB KNX Devices.png.png | | [[Image: WB KNX Devices.png.png |300px|thumb|right| KNX-устройства в веб-интерфейсе контроллера Wiren Board ]] | ||
Здесь описан сервис версии 1.4.x и новее, [[MQTT KNX V.0.1.x | описание устаревшей версии 0.1.x]]. | |||
О том, что такое KNX и особенности адресации читайте в статье [[KNX]]. | |||
За работу с KNX-устройствами в контроллерах Wiren Board отвечает установленный с завода сервис [https://github.com/wirenboard/wb-mqtt-knx wb-mqtt-knx], который может работать в двух режимах: | |||
# ''Сетевой мост'', который обрабатывает, передаёт и принимает KNX телеграммы в MQTT в специальном формате. Оставлен для обратной совместимости, новые функции в этот режим внедряться не будут. | |||
# ''Контроллер групповых объектов''. Это набор виртуальных устройств для работы с групповыми объектами KNX и предварительной обработкой типов данных. | |||
Сервис хранит настройки в файле <code>wb-mqtt-knx.conf</code>, который редактируется из веб-интерфейса контроллера или генерируется на основе проекта из ETS. | |||
Пример настройки KNX-устройств для работы с wb-mqtt-knx смотрите в статье [[KNX_Quick_start| Быстрый старт KNX]]. | |||
== Сетевой мост == | |||
В режиме сетевого моста сервис пересылает телеграммы из [[MQTT]] в KNX и обратно. | |||
Перед началом работы, настройте knxd по [[Knxd#Настройка | инструкции]]. | |||
Чтобы отправить групповую телеграмму в KNX необходимо отправить подготовленное сообщение в MQTT топик: | Чтобы отправить групповую телеграмму в KNX необходимо отправить подготовленное сообщение в MQTT топик: | ||
Строка 23: | Строка 28: | ||
<pre>i:${SrcAddr} g:${DstAddr} ${APCI} ${Data}</pre> | <pre>i:${SrcAddr} g:${DstAddr} ${APCI} ${Data}</pre> | ||
* ''SrcAddr'' | * ''SrcAddr'' — Индивидуальный адрес KNX устройства отправителя в формате <code>n/n/n</code> или <code>n/n</code>. | ||
* ''DstAddr'' | * ''DstAddr'' — Групповой адрес KNX в формате <code>n/n/n</code> или <code>n/n</code>. | ||
* ''APCI'' | * ''APCI'' — Тип сообщения: строка или 4х-битное число. | ||
* ''Data'' | * ''Data'' — Сообщение в виде байт, разделенных пробелами. Первый байт сообщения должен иметь длину не более 6 бит. | ||
При отправке сообщений для полей ''Data'' допускаются форматы: <code>0xAA</code>, <code>0XAA</code>, <code>0b10101010</code>, <code>0B10101010</code>, <code>170</code> | При отправке сообщений для полей ''Data'' допускаются форматы: <code>0xAA</code>, <code>0XAA</code>, <code>0b10101010</code>, <code>0B10101010</code>, <code>170</code> | ||
Поддерживаемые типы сообщений(APCI): | Поддерживаемые типы сообщений (APCI): | ||
* <code>GroupValueRead</code> | * <code>GroupValueRead</code> | ||
Строка 36: | Строка 41: | ||
* <code>GroupValueWrite</code> | * <code>GroupValueWrite</code> | ||
== Контроллер групповых объектов == | |||
{{YouTube|link=https://youtu.be/VjpN_-8SA-Q|text=Вебинар про импорт проектов из ETS, типы групповых адресов и настройку FeedBack}} | |||
=== Описание === | |||
Чтобы представить групповой адрес в веб-интерфейсе контроллера Wiren Board, нужно создать контрол виртуального [[MQTT]]-устройства с параметрами, заданными объекту в программе ETS: типом данных и групповым адресом. Несколько групповых адресов можно объединять в одно или несколько произвольных MQTT-устройств. | |||
Далее вы можете работать с групповым адресом так же, как с обычным контролом: писать и читать из него текст, биты, целые знаковые и беззнаковые числа, числа с плавающей точкой. | |||
Каждый контрол MQTT-устройства может работать в двух режимах: | |||
# ''MQTT'' — данные представляются в виде готовых к обработке значений и публикуются в контролы нужного типа: value, switch и т.п. Поддерживаются только типы данных, которые можно представить в виде контролов MQTT-устройства, список можно посмотреть по ссылке [https://github.com/wirenboard/wb-mqtt-knx/blob/master/datapointformat.md#%D0%BF%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5-datapoint-%D1%82%D0%B8%D0%BF%D0%BE%D0%B2 Представление DataPoint типов]. | |||
# ''JSON'' — данные преобразовываются в JSON-сообщения, которые в виде текста помещаются в контрол и могут быть обработаны с помощью [[wb-rules]]. В этом режиме можно работать со специфичными для KNX типами, например, дата с днём недели. {{SupportedSinceRelease|release= wb-2204|nobanner= true}} | |||
При настройке устройства в ETS старайтесь выбирать базовые типы, сервис поддерживает только их, например, <code>1.*1-bit</code> — это <code>1.xxx_B1</code> или <code>1.xxx_B1_JSON</code>, зависит от выбранного режима контрола MQTT-устройства. | |||
Если нужного вам типа не оказалось, используйте в режиме MQTT специальный тип ''Raw_Value'' — это полученный массив байт, представленный в виде шестнадцатеричного числа, которое вы сможете самостоятельно преобразовать с помощью [[wb-rules]] и руководства [https://www.knx.org/wAssets/docs/downloads/Certification/Interworking-Datapoint-types/03_07_02-Datapoint-Types-v02.02.01-AS.pdf Datapoint-Types-v02.02.01-AS]. | |||
<gallery mode="traditional" widths="260px" caption="Настройка и работа с KNX-устройством"> | |||
Image: ETS Group Object Config.png | Настройка группового объекта в программе ETS | |||
Image: KNX MQTT Control Config.png | Настройка контрола MQTT-устройства в веб-интерфейсе контроллера Wiren Board | |||
Image: KNX Switch WebUI.png | Представление устройства в веб-интерфейсе контроллера Wiren Board | |||
</gallery> | |||
== Настройка == | === Настройка === | ||
Для настройки Контроллера групповых адресов вы можете импортировать готовый проект из ETS, или настроить всё мышкой в [[Wiren Board Web Interface | веб-интерфейсе контроллера]] Wiren Board. Инструкцию по импорту смотрите ниже на этой странице, в разделе «Импорт из ETS». | |||
{{Wbincludes:WebUI Change Access Level}} | |||
[[Image: WB KNX Settings.png |300px|thumb|right| Пример настройки KNX-устройства в веб-интерфейсе контроллера Wiren Board ]] | [[Image: WB KNX Settings.png |300px|thumb|right| Пример настройки KNX-устройства в веб-интерфейсе контроллера Wiren Board ]] | ||
Первичная настройка: | |||
# | # Настройте knxd по [[Knxd#Настройка | инструкции]]. | ||
# Перейдите '''Settings''' → '''Configs''' → '''KNX Group Object Configuration'''. | |||
# Перейдите '''Settings''' → '''Configs''' → '''KNX Group Object Configuration''' | |||
# Установите флажок '''Enable the KNX Gateway Device: knx/data''' | # Установите флажок '''Enable the KNX Gateway Device: knx/data''' | ||
# Нажмите на кнопку '''Save''', чтобы сохранить настройки. | # Нажмите на кнопку '''Save''', чтобы сохранить настройки. | ||
Создание MQTT-устройства для организации групповых объектов: | |||
# Нажмите на кнопку ''' + Device''' | # Нажмите на кнопку ''' + Device'''. | ||
# В появившемся новом устройстве укажите '''Device ID''' и опционально название '''Title''' | # В появившемся новом устройстве укажите '''Device ID''' и опционально название '''Title'''. | ||
# | # Добавьте контролы и потом сохраните настройки нажатием на кнопку '''Save'''. | ||
Добавление контрола для группового объекта: | |||
# | # Выберите в списке'''List of Devices''' нужное устройство. | ||
# Нажмите на кнопку ''' + Control''' | # Нажмите на кнопку ''' + Control'''. | ||
# | # Укажите '''Control ID''' и опционально название '''Title'''. | ||
# | # Впишите групповой адрес объекта в поле '''Group Address''', используя один из форматов: <code>1/2/34</code>, <code>1/234</code>, <code>1234</code>. | ||
# | # Выберите из выпадающего списка '''Data point type''' тип точки данных группового объекта. | ||
# | # Укажите интервал чтения группового объекта в поле '''READ poll interval for Devices (ms)'''. 0 — отключает опрос. | ||
# | # Задайте максимальное время отклика от группового объекта в поле '''READ poll timeout for Devices (ms)'''. Если время ответа на запрос вышло, генерируется ошибка в топик '''meta/error'''. 0 — не генерировать ошибку. | ||
# | # Если групповой объект предназначен только для чтения, установите флажок '''Read only'''. | ||
# | # Повторите процедуру для всех групповых объектов и сохраните настройки кнопкой '''Save''' вверху страницы. | ||
== | === Работа с KNX-устройством === | ||
Сервис получает KNX-телеграмму, извлекает из неё данные и помещает их в контрол в соответствующий контрол MQTT-устройства. Если в состав группового объекта входит несколько полей, то на каждое поле создаётся свой контрол. | |||
Если в групповом объекте одно поле, то топики будут выглядеть так: | |||
* <code>/devices/<knx_device_id>/controls/<knx_device_control_id></code> | * Приём: <code>/devices/<knx_device_id>/controls/<knx_device_control_id></code> | ||
* <code>/devices/<knx_device_id>/controls/<knx_device_control_id>/on</code> | * Отправка: <code>/devices/<knx_device_id>/controls/<knx_device_control_id>/on</code> | ||
Если в групповом объекте несколько полей, то топики будут выглядеть так: | |||
* <code>/devices/<knx_device_id>/controls/<knx_device_control_id>_<datapoint_field></code> | * Приём: <code>/devices/<knx_device_id>/controls/<knx_device_control_id>_<datapoint_field></code> | ||
* <code>/devices/<knx_device_id>/controls/<knx_device_control_id>_<datapoint_field>/on</code> | * Отправка: <code>/devices/<knx_device_id>/controls/<knx_device_control_id>_<datapoint_field>/on</code> | ||
где: | где: | ||
* '''knx_device_id''' | * '''knx_device_id''' — имя виртуальной группы групповых объектов; | ||
* '''knx_device_control_id''' | * '''knx_device_control_id''' — имя группового объекта; | ||
* '''datapoint_field''' | * '''datapoint_field''' — имя поля из DataPoint типа. | ||
Список поддерживаемых типов точек данных смотрите по ссылке [https://github.com/wirenboard/wb-mqtt-knx/blob/master/datapointformat.md#%D0%BF%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5-datapoint-%D1%82%D0%B8%D0%BF%D0%BE%D0%B2 Представление DataPoint типов]. | |||
{{SupportedSinceRelease | |||
| release = wb-2204 | |||
| deb = wb-mqtt-knx | |||
| version = 1.5 | |||
|content= | |||
В случае, если у контрола MQTT-устройства выбран режим JSON, то в зависимости от выбранного типа контрола будут приходить сообщения вида: | |||
* 1.001: | |||
*:<syntaxhighlight lang="js"> | |||
{"switch":true} | |||
</syntaxhighlight> | |||
* 10.001: | |||
*:<syntaxhighlight lang="js"> | |||
{"Day":0,"Hour":22,"Minutes":1,"Seconds":2} | |||
</syntaxhighlight> | |||
* 21.002: | |||
*:<syntaxhighlight lang="js"> | |||
{"UserStopped":true,"OwnIA":false,"VerifyMode":true} | |||
</syntaxhighlight> | |||
Дальше вы можете обрабатывать их правилами [[wb-rules]]: читаете, обрабатываете, формируете ответное JSON-сообщение и отправляете. Прием и отправка JSON-сообщений не отличается от работы обычными DataPoint типами. | |||
}} | |||
== Случаи использования == | == Случаи использования == | ||
=== Структурная схема взаимодействия === | === Структурная схема взаимодействия === | ||
Устройства ''KNX device #1'' и ''KNX device #2'' связаны одним групповым адресом и образуют предварительно заданный логический канал по которому | Устройства ''KNX device #1'' и ''KNX device #2'' связаны одним групповым адресом и образуют предварительно заданный логический канал по которому передаётся определённый тип данных. | ||
Подробнее про KNX флаги групповых объектов можно почитать в статье [https://support.knx.org/hc/en-us/articles/115003188089-Flags Flags на сайте knx.org]. | Подробнее про KNX флаги групповых объектов можно почитать в статье [https://support.knx.org/hc/en-us/articles/115003188089-Flags Flags на сайте knx.org]. | ||
Строка 124: | Строка 141: | ||
Пояснения к схеме: | Пояснения к схеме: | ||
* '''KNX TP''' — KNX сеть, витая пара | * '''KNX TP''' — KNX сеть, витая пара. | ||
* '''KNX device #1, group object #n''' — Групповой объект n устройства 1, привязанный к групповому адресу GA1, с флагами на чтение и передачу, и типом | * '''KNX device #1, group object #n''' — Групповой объект '''n''' устройства 1, привязанный к групповому адресу GA1, с флагами на чтение и передачу, и типом данных Dpt1, например, датчик. | ||
* '''KNX device #2, group object #m''' — Групповой объект m устройства 2, привязанный к групповому адресу GA1, с флагами на запись, и типом | * '''KNX device #2, group object #m''' — Групповой объект '''m''' устройства 2, привязанный к групповому адресу GA1, с флагами на запись, и типом данных Dpt1, например, исполнительное устройство. | ||
* '''knxd''' — knxd сервер в контроллере | * '''knxd''' — knxd сервер в контроллере Wiren Board. | ||
* '''wb-mqtt-knx''' — сервис для преобразования групповых объектов в MQTT устройства и контролы | * '''wb-mqtt-knx''' — сервис для преобразования групповых объектов в MQTT устройства и контролы. | ||
* '''representation in terms of MQTT''' — представление групповых объектов терминах MQTT | * '''representation in terms of MQTT''' — представление групповых объектов в терминах MQTT. | ||
* '''Web UI/ wb-rules''' — пользовательский интерфейс или движок правил | * '''Web UI/ wb-rules''' — пользовательский интерфейс или движок правил. | ||
* '''/Device1/control1''' — контрол, связанный с групповым адресом и типом | * '''/Device1/control1''' — контрол, связанный с групповым адресом и типом данных 1. | ||
=== Передача данных исполнительному устройству при изменении состояния датчика === | === Передача данных исполнительному устройству при изменении состояния датчика === | ||
Строка 137: | Строка 154: | ||
# Датчик при изменении своего состояния посылает исполнительному устройству KNX телеграмму с групповым адресом и APCI командой GroupValueWrite. | # Датчик при изменении своего состояния посылает исполнительному устройству KNX телеграмму с групповым адресом и APCI командой GroupValueWrite. | ||
# knxd прослушивает телеграммы на шине и пересылает полученную телеграмму своим клиентам, в числе которых wb-mqtt-knx. | # knxd прослушивает телеграммы на шине и пересылает полученную телеграмму своим клиентам, в числе которых wb-mqtt-knx. | ||
# wb-mqtt-knx по таблице соответствия, сформированной из файла конфигурации, находит MQTT контрол связанный с групповым адресом и конвертирует KNX данные в значение, публикуемое контролом. Преобразование | # wb-mqtt-knx по таблице соответствия, сформированной из файла конфигурации, находит MQTT контрол связанный с групповым адресом и конвертирует KNX данные в значение, публикуемое контролом. Преобразование зависит от типа данных. | ||
# Изменение значения в контроле публикуется в MQTT. Подписчиками, в том числе являются движок правил и пользовательский интерфейс. | # Изменение значения в контроле публикуется в MQTT. Подписчиками, в том числе являются движок правил и пользовательский интерфейс. | ||
[[Image: Wb-mqtt-knx-user-case-ptp.png |600px|thumb|center| Передача данных от датчика к исполнительному устройству ]] | [[Image: Wb-mqtt-knx-user-case-ptp.png |600px|thumb|center| Передача данных от датчика к исполнительному устройству ]] | ||
=== Управление | === Управление KNX-устройством через пользовательский интерфейс === | ||
Вы можете управлять исполнительным KNX-устройством через пользовательский интерфейс, или через [[wb-rules]]. | |||
Как это работает: | Как это работает: | ||
# Изменяется значение контрола, посредством публикации значения в топик <code>/devices/Device1/controls/control1/on</code>, что приводит к публикации значения в топик <code>/devices/Device1/controls/control1/</code>. | # Изменяется значение контрола, посредством публикации значения в топик <code>/devices/Device1/controls/control1/on</code>, что приводит к публикации значения в топик <code>/devices/Device1/controls/control1/</code>. | ||
# Значение из топика <code>/on</code> преобразуются в данные для KNX телеграммы в зависимости от типа | # Значение из топика <code>/on</code> преобразуются в данные для KNX телеграммы в зависимости от типа данных, связанного с контролом. | ||
# Формируется KNX телеграмма с KNX данными, адресом получателя GA1 и APCI командой ''GroupWalueWrite''. Адрес получателя равен групповому адресу связанному с контролом. | |||
# KNX телеграмма передаётся всем клиентам knxd и в KNX TP сеть. | # KNX телеграмма передаётся всем клиентам knxd и в KNX TP сеть. | ||
# KNX телеграмму получают устройства 1 и 2. Обработка пакета c командой GroupValueWrite происходит только в групповом объекте m в устройстве 2, из-за того что в нём выставлен флаг W. | # KNX телеграмму получают устройства 1 и 2. Обработка пакета c командой ''GroupValueWrite'' происходит только в групповом объекте m в устройстве 2, из-за того что в нём выставлен флаг W. | ||
[[Image: Wb-mqtt-knx-user-case-utp.png |600px|thumb|center| Передача данных от интерфейса пользователя к исполнительному устройству ]] | [[Image: Wb-mqtt-knx-user-case-utp.png |600px|thumb|center| Передача данных от интерфейса пользователя к исполнительному устройству ]] | ||
Строка 153: | Строка 174: | ||
=== Периодическое чтение группового объекта === | === Периодическое чтение группового объекта === | ||
Как это работает: | Как это работает: | ||
# После начала работы сервиса и при заданном для контрола периоде опроса отличном от нуля сервис wb-mqtt-knx рассылает телеграммы с запросом на чтение с APCI командой GroupValueRead на соответствующие групповые адреса. | # После начала работы сервиса и при заданном для контрола периоде опроса отличном от нуля сервис wb-mqtt-knx рассылает телеграммы с запросом на чтение с APCI командой ''GroupValueRead'' на соответствующие групповые адреса. | ||
# Если групповой объект имеет флаг R и групповой адрес, равный запрашиваемому, он отсылает в KNX TP ответ с текущим своим значением и ACPI командой GroupValueResponse. | # Если групповой объект имеет флаг R и групповой адрес, равный запрашиваемому, он отсылает в KNX TP ответ с текущим своим значением и ACPI командой ''GroupValueResponse''. | ||
# Это телеграмму получает wb-mqtt-knx сервис и отправляет значение в контрол со связанным групповым адресом. | # Это телеграмму получает wb-mqtt-knx сервис и отправляет значение в контрол со связанным групповым адресом. | ||
# Далее значение контрола публикуется в топике | # Далее значение контрола публикуется в топике <code>/devices/Device1/controls/control1/</code> | ||
[[Image: Wb-mqtt-knx-user-case-t2p2u.png |600px|thumb|center| | [[Image: Wb-mqtt-knx-user-case-t2p2u.png |600px|thumb|center| Чтение группового объекта]] | ||
== Управление сервисом и просмотр журнала == | == Управление сервисом и просмотр журнала == | ||
Строка 181: | Строка 202: | ||
можно воспользоваться консольной утилитой <code>wb-knx-ets-tool</code>, которая идёт в комплекте с <code>wb-mqtt-knx</code>. | можно воспользоваться консольной утилитой <code>wb-knx-ets-tool</code>, которая идёт в комплекте с <code>wb-mqtt-knx</code>. | ||
Утилита принимает на вход XML файлы экспорта из инструмента ETS версии 5 и 6 | Утилита принимает на вход XML файлы экспорта из инструмента ETS версии 5 и 6, использование: | ||
<pre>$ wb-knx-ets-tool ETS_CONFIG WB_MQTT_KNX_CONFIG</pre> | <pre>$ wb-knx-ets-tool ETS_CONFIG WB_MQTT_KNX_CONFIG</pre> | ||
где: | |||
* '''ETS_CONFIG''' — путь к XML файлу экспорта групповых объектов | |||
* '''WB_MQTT_KNX_CONFIG''' — путь к файлу конфигурации для работы с групповыми объектами <code>wb-mqtt-knx.conf</code> | |||
* | == Полезные ссылки == | ||
* | * [[KNX | О KNX]] | ||
* [https://github.com/wirenboard/wb-mqtt-knx Описание сервиса wb-mqtt-knx на GitHub] | |||
* [[KNX_Quick_start | Инструкция по настройке KNX-устройств]] | |||
* [[knxd | Описание и настройка роутера Knxd]] | |||
* [[WBE2-I-KNX_KNX_Extension_Module | Модуль расширения WBE2-I-KNX]] |
Текущая версия на 15:05, 27 декабря 2023
Описание
Здесь описан сервис версии 1.4.x и новее, описание устаревшей версии 0.1.x.
О том, что такое KNX и особенности адресации читайте в статье KNX.
За работу с KNX-устройствами в контроллерах Wiren Board отвечает установленный с завода сервис wb-mqtt-knx, который может работать в двух режимах:
- Сетевой мост, который обрабатывает, передаёт и принимает KNX телеграммы в MQTT в специальном формате. Оставлен для обратной совместимости, новые функции в этот режим внедряться не будут.
- Контроллер групповых объектов. Это набор виртуальных устройств для работы с групповыми объектами KNX и предварительной обработкой типов данных.
Сервис хранит настройки в файле wb-mqtt-knx.conf
, который редактируется из веб-интерфейса контроллера или генерируется на основе проекта из ETS.
Пример настройки KNX-устройств для работы с wb-mqtt-knx смотрите в статье Быстрый старт KNX.
Сетевой мост
В режиме сетевого моста сервис пересылает телеграммы из MQTT в KNX и обратно.
Перед началом работы, настройте knxd по инструкции.
Чтобы отправить групповую телеграмму в KNX необходимо отправить подготовленное сообщение в MQTT топик:
mosquitto_pub -t '/devices/knx/controls/data/on' -m "g:${DstAddr} ${APCI} ${Data}"
Все сообщения из KNX будут доставлены в MQTT топик /devices/knx/controls/data
в виде:
i:${SrcAddr} g:${DstAddr} ${APCI} ${Data}
- SrcAddr — Индивидуальный адрес KNX устройства отправителя в формате
n/n/n
илиn/n
. - DstAddr — Групповой адрес KNX в формате
n/n/n
илиn/n
. - APCI — Тип сообщения: строка или 4х-битное число.
- Data — Сообщение в виде байт, разделенных пробелами. Первый байт сообщения должен иметь длину не более 6 бит.
При отправке сообщений для полей Data допускаются форматы: 0xAA
, 0XAA
, 0b10101010
, 0B10101010
, 170
Поддерживаемые типы сообщений (APCI):
GroupValueRead
GroupValueResponse
GroupValueWrite
Контроллер групповых объектов
Описание
Чтобы представить групповой адрес в веб-интерфейсе контроллера Wiren Board, нужно создать контрол виртуального MQTT-устройства с параметрами, заданными объекту в программе ETS: типом данных и групповым адресом. Несколько групповых адресов можно объединять в одно или несколько произвольных MQTT-устройств.
Далее вы можете работать с групповым адресом так же, как с обычным контролом: писать и читать из него текст, биты, целые знаковые и беззнаковые числа, числа с плавающей точкой.
Каждый контрол MQTT-устройства может работать в двух режимах:
- MQTT — данные представляются в виде готовых к обработке значений и публикуются в контролы нужного типа: value, switch и т.п. Поддерживаются только типы данных, которые можно представить в виде контролов MQTT-устройства, список можно посмотреть по ссылке Представление DataPoint типов.
- JSON — данные преобразовываются в JSON-сообщения, которые в виде текста помещаются в контрол и могут быть обработаны с помощью wb-rules. В этом режиме можно работать со специфичными для KNX типами, например, дата с днём недели.
При настройке устройства в ETS старайтесь выбирать базовые типы, сервис поддерживает только их, например, 1.*1-bit
— это 1.xxx_B1
или 1.xxx_B1_JSON
, зависит от выбранного режима контрола MQTT-устройства.
Если нужного вам типа не оказалось, используйте в режиме MQTT специальный тип Raw_Value — это полученный массив байт, представленный в виде шестнадцатеричного числа, которое вы сможете самостоятельно преобразовать с помощью wb-rules и руководства Datapoint-Types-v02.02.01-AS.
- Настройка и работа с KNX-устройством
Настройка
Для настройки Контроллера групповых адресов вы можете импортировать готовый проект из ETS, или настроить всё мышкой в веб-интерфейсе контроллера Wiren Board. Инструкцию по импорту смотрите ниже на этой странице, в разделе «Импорт из ETS».
Для изменения настроек контроллера вам нужен уровень доступа Администратор, который можно выставить в разделе Настройки → Права доступа.
После завершения настроек рекомендуем поставить уровень доступа Пользователь или Оператор — это поможет не совершить случайных ошибок при ежедневной работе с веб-интерфейсом.
Первичная настройка:
- Настройте knxd по инструкции.
- Перейдите Settings → Configs → KNX Group Object Configuration.
- Установите флажок Enable the KNX Gateway Device: knx/data
- Нажмите на кнопку Save, чтобы сохранить настройки.
Создание MQTT-устройства для организации групповых объектов:
- Нажмите на кнопку + Device.
- В появившемся новом устройстве укажите Device ID и опционально название Title.
- Добавьте контролы и потом сохраните настройки нажатием на кнопку Save.
Добавление контрола для группового объекта:
- Выберите в спискеList of Devices нужное устройство.
- Нажмите на кнопку + Control.
- Укажите Control ID и опционально название Title.
- Впишите групповой адрес объекта в поле Group Address, используя один из форматов:
1/2/34
,1/234
,1234
. - Выберите из выпадающего списка Data point type тип точки данных группового объекта.
- Укажите интервал чтения группового объекта в поле READ poll interval for Devices (ms). 0 — отключает опрос.
- Задайте максимальное время отклика от группового объекта в поле READ poll timeout for Devices (ms). Если время ответа на запрос вышло, генерируется ошибка в топик meta/error. 0 — не генерировать ошибку.
- Если групповой объект предназначен только для чтения, установите флажок Read only.
- Повторите процедуру для всех групповых объектов и сохраните настройки кнопкой Save вверху страницы.
Работа с KNX-устройством
Сервис получает KNX-телеграмму, извлекает из неё данные и помещает их в контрол в соответствующий контрол MQTT-устройства. Если в состав группового объекта входит несколько полей, то на каждое поле создаётся свой контрол.
Если в групповом объекте одно поле, то топики будут выглядеть так:
- Приём:
/devices/<knx_device_id>/controls/<knx_device_control_id>
- Отправка:
/devices/<knx_device_id>/controls/<knx_device_control_id>/on
Если в групповом объекте несколько полей, то топики будут выглядеть так:
- Приём:
/devices/<knx_device_id>/controls/<knx_device_control_id>_<datapoint_field>
- Отправка:
/devices/<knx_device_id>/controls/<knx_device_control_id>_<datapoint_field>/on
где:
- knx_device_id — имя виртуальной группы групповых объектов;
- knx_device_control_id — имя группового объекта;
- datapoint_field — имя поля из DataPoint типа.
Список поддерживаемых типов точек данных смотрите по ссылке Представление DataPoint типов.
В случае, если у контрола MQTT-устройства выбран режим JSON, то в зависимости от выбранного типа контрола будут приходить сообщения вида:
- 1.001:
{"switch":true}
- 10.001:
{"Day":0,"Hour":22,"Minutes":1,"Seconds":2}
- 21.002:
{"UserStopped":true,"OwnIA":false,"VerifyMode":true}
Дальше вы можете обрабатывать их правилами wb-rules: читаете, обрабатываете, формируете ответное JSON-сообщение и отправляете. Прием и отправка JSON-сообщений не отличается от работы обычными DataPoint типами.
Случаи использования
Структурная схема взаимодействия
Устройства KNX device #1 и KNX device #2 связаны одним групповым адресом и образуют предварительно заданный логический канал по которому передаётся определённый тип данных.
Подробнее про KNX флаги групповых объектов можно почитать в статье Flags на сайте knx.org.
Пояснения к схеме:
- KNX TP — KNX сеть, витая пара.
- KNX device #1, group object #n — Групповой объект n устройства 1, привязанный к групповому адресу GA1, с флагами на чтение и передачу, и типом данных Dpt1, например, датчик.
- KNX device #2, group object #m — Групповой объект m устройства 2, привязанный к групповому адресу GA1, с флагами на запись, и типом данных Dpt1, например, исполнительное устройство.
- knxd — knxd сервер в контроллере Wiren Board.
- wb-mqtt-knx — сервис для преобразования групповых объектов в MQTT устройства и контролы.
- representation in terms of MQTT — представление групповых объектов в терминах MQTT.
- Web UI/ wb-rules — пользовательский интерфейс или движок правил.
- /Device1/control1 — контрол, связанный с групповым адресом и типом данных 1.
Передача данных исполнительному устройству при изменении состояния датчика
Как это работает:
- Датчик при изменении своего состояния посылает исполнительному устройству KNX телеграмму с групповым адресом и APCI командой GroupValueWrite.
- knxd прослушивает телеграммы на шине и пересылает полученную телеграмму своим клиентам, в числе которых wb-mqtt-knx.
- wb-mqtt-knx по таблице соответствия, сформированной из файла конфигурации, находит MQTT контрол связанный с групповым адресом и конвертирует KNX данные в значение, публикуемое контролом. Преобразование зависит от типа данных.
- Изменение значения в контроле публикуется в MQTT. Подписчиками, в том числе являются движок правил и пользовательский интерфейс.
Управление KNX-устройством через пользовательский интерфейс
Вы можете управлять исполнительным KNX-устройством через пользовательский интерфейс, или через wb-rules.
Как это работает:
- Изменяется значение контрола, посредством публикации значения в топик
/devices/Device1/controls/control1/on
, что приводит к публикации значения в топик/devices/Device1/controls/control1/
. - Значение из топика
/on
преобразуются в данные для KNX телеграммы в зависимости от типа данных, связанного с контролом. - Формируется KNX телеграмма с KNX данными, адресом получателя GA1 и APCI командой GroupWalueWrite. Адрес получателя равен групповому адресу связанному с контролом.
- KNX телеграмма передаётся всем клиентам knxd и в KNX TP сеть.
- KNX телеграмму получают устройства 1 и 2. Обработка пакета c командой GroupValueWrite происходит только в групповом объекте m в устройстве 2, из-за того что в нём выставлен флаг W.
Периодическое чтение группового объекта
Как это работает:
- После начала работы сервиса и при заданном для контрола периоде опроса отличном от нуля сервис wb-mqtt-knx рассылает телеграммы с запросом на чтение с APCI командой GroupValueRead на соответствующие групповые адреса.
- Если групповой объект имеет флаг R и групповой адрес, равный запрашиваемому, он отсылает в KNX TP ответ с текущим своим значением и ACPI командой GroupValueResponse.
- Это телеграмму получает wb-mqtt-knx сервис и отправляет значение в контрол со связанным групповым адресом.
- Далее значение контрола публикуется в топике
/devices/Device1/controls/control1/
Управление сервисом и просмотр журнала
Обычно сервис запускается автоматически при загрузке контроллера и перезапускается при сохранении файла конфигурации в веб-интерфейсе.
Также можно управлять сервисом в ручном режиме. Для выполнения команд подключитесь к контроллеру по SSH. Доступны команды:
$ systemctl stop wb-mqtt-knx # остановить
$ systemctl start wb-mqtt-knx # запустить
$ systemctl restart wb-mqtt-knx # перезапустить
Для просмотра служебного журнала сервиса:
$ journalctl -u wb-mqtt-knx
Импорт из ETS
Для импорта из инструмента ETS в файл конфигурации для работы с групповыми объектами wb-mqtt-knx.conf
,
можно воспользоваться консольной утилитой wb-knx-ets-tool
, которая идёт в комплекте с wb-mqtt-knx
.
Утилита принимает на вход XML файлы экспорта из инструмента ETS версии 5 и 6, использование:
$ wb-knx-ets-tool ETS_CONFIG WB_MQTT_KNX_CONFIG
где:
- ETS_CONFIG — путь к XML файлу экспорта групповых объектов
- WB_MQTT_KNX_CONFIG — путь к файлу конфигурации для работы с групповыми объектами
wb-mqtt-knx.conf