Метки: правка с мобильного устройства правка из мобильной версии Расширенная мобильная правка |
|
(не показана 131 промежуточная версия 2 участников) |
Строка 1: |
Строка 1: |
| {{DISPLAYTITLE: Описание сервиса wb-mqtt-knx}} | | {{Draft}} |
| == Описание ==
| | {{DISPLAYTITLE: Новый MQTT KNX}} |
| [[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 и MQTT в двух режимах. |
|
| |
|
| О том, что такое KNX и особенности адресации читайте в статье [[KNX]].
| | # Как сетевой мост, который обрабатывает, передаёт и принимает KNX телеграммы в MQTT в специальном формате. |
| | # Как набор виртуальных устройств для работы с групповыми объектами и предварительной обработкой типов данных. |
|
| |
|
| За работу с 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 === |
| | |
| == Сетевой мост == | |
| В режиме сетевого моста сервис пересылает телеграммы из [[MQTT]] в KNX и обратно.
| |
| | |
| Перед началом работы, настройте knxd по [[Knxd#Настройка | инструкции]].
| |
|
| |
|
| Чтобы отправить групповую телеграмму в KNX необходимо отправить подготовленное сообщение в MQTT топик: | | Чтобы отправить групповую телеграмму в KNX необходимо отправить подготовленное сообщение в MQTT топик: |
Строка 28: |
Строка 21: |
| <pre>i:${SrcAddr} g:${DstAddr} ${APCI} ${Data}</pre> | | <pre>i:${SrcAddr} g:${DstAddr} ${APCI} ${Data}</pre> |
|
| |
|
| * ''SrcAddr'' — Индивидуальный адрес KNX устройства отправителя в формате <code>n/n/n</code> или <code>n/n</code>. | | * ''SrcAddr'', ''DstAddr'' - Адреса KNX устройств в формате "n/n/n" или "n/n". |
| * ''DstAddr'' — Групповой адрес KNX в формате <code>n/n/n</code> или <code>n/n</code>.
| | * ''APCI'' - Тип сообщения: строка или 4х-битное число. |
| * ''APCI'' — Тип сообщения: строка или 4х-битное число. | | * ''Data'' - Сообщение в виде байт, разделенных пробелами. Первый байт сообщения должен иметь длину не более 6 бит. |
| * ''Data'' — Сообщение в виде байт, разделенных пробелами. Первый байт сообщения должен иметь длину не более 6 бит. | |
| | |
| При отправке сообщений для полей ''Data'' допускаются форматы: <code>0xAA</code>, <code>0XAA</code>, <code>0b10101010</code>, <code>0B10101010</code>, <code>170</code>
| |
|
| |
|
| Поддерживаемые типы сообщений (APCI): | | Поддерживаемые типы сообщений(APCI): |
|
| |
|
| * <code>GroupValueRead</code> | | * <code>GroupValueRead</code> |
Строка 41: |
Строка 31: |
| * <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 ]]
| |
| | |
| Первичная настройка:
| |
| # Настройте knxd по [[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''', используя один из форматов: <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>/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>/on</code>
| |
| | |
| где:
| |
| * '''knx_device_id''' — имя виртуальной группы групповых объектов;
| |
| * '''knx_device_control_id''' — имя группового объекта;
| |
| * '''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 флаги групповых объектов можно почитать в статье [https://support.knx.org/hc/en-us/articles/115003188089-Flags Flags на сайте knx.org].
| |
| | |
| [[Image: Wb-mqtt-knx_user-case_default.png |500px| thumb|center|Структурная схема взаимодействия KNX MQTT ]]
| |
| | |
| Пояснения к схеме:
| |
| * '''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. Подписчиками, в том числе являются движок правил и пользовательский интерфейс.
| |
| | |
| [[Image: Wb-mqtt-knx-user-case-ptp.png |600px|thumb|center| Передача данных от датчика к исполнительному устройству ]]
| |
| | |
| === Управление KNX-устройством через пользовательский интерфейс ===
| |
| | |
| Вы можете управлять исполнительным KNX-устройством через пользовательский интерфейс, или через [[wb-rules]].
| |
|
| |
|
| Как это работает:
| | Для группового адреса KNX создаётся индивидуально настраиваемый MQTT контрол. Это означает, что можно работать с групповым адресом как с MQTT контролом: отправлять в него и принимать из него значения, например: битов, целых знаковых и беззнаковых чисел, чисел с плавающей точкой. |
| # Изменяется значение контрола, посредством публикации значения в топик <code>/devices/Device1/controls/control1/on</code>, что приводит к публикации значения в топик <code>/devices/Device1/controls/control1/</code>.
| |
| # Значение из топика <code>/on</code> преобразуются в данные для KNX телеграммы в зависимости от типа данных, связанного с контролом.
| |
| # Формируется KNX телеграмма с KNX данными, адресом получателя GA1 и APCI командой ''GroupWalueWrite''. Адрес получателя равен групповому адресу связанному с контролом.
| |
| # KNX телеграмма передаётся всем клиентам knxd и в KNX TP сеть.
| |
| # KNX телеграмму получают устройства 1 и 2. Обработка пакета c командой ''GroupValueWrite'' происходит только в групповом объекте m в устройстве 2, из-за того что в нём выставлен флаг W.
| |
|
| |
|
| [[Image: Wb-mqtt-knx-user-case-utp.png |600px|thumb|center| Передача данных от интерфейса пользователя к исполнительному устройству ]]
| | Тип контрола связан типом данных для группового адреса. Тип данных для конкретного группового адреса можно настроить в веб редакторе конфигурационных файлов. |
|
| |
|
| === Периодическое чтение группового объекта ===
| | Несколько групповых адресов группируются в одно или несколько произвольных логических MQTT устройств. |
| Как это работает:
| |
| # После начала работы сервиса и при заданном для контрола периоде опроса отличном от нуля сервис wb-mqtt-knx рассылает телеграммы с запросом на чтение с APCI командой ''GroupValueRead'' на соответствующие групповые адреса.
| |
| # Если групповой объект имеет флаг R и групповой адрес, равный запрашиваемому, он отсылает в KNX TP ответ с текущим своим значением и ACPI командой ''GroupValueResponse''.
| |
| # Это телеграмму получает wb-mqtt-knx сервис и отправляет значение в контрол со связанным групповым адресом.
| |
| # Далее значение контрола публикуется в топике <code>/devices/Device1/controls/control1/</code>
| |
|
| |
|
| [[Image: Wb-mqtt-knx-user-case-t2p2u.png |600px|thumb|center| Чтение группового объекта]]
| | На данный момент поддерживаются пять типов данных групповых адресов и один с возможностью обработки сырых данных: |
|
| |
|
| == Управление сервисом и просмотр журнала ==
| | * <code>Raw_Value</code> - обработка сырых данных: массив данных в виде строки (APDU payload); |
| | * <code>1.xxx_B1</code> - 1-битовое значение; |
| | * <code>2.xxx_B2</code> - 2-битовое значение; |
| | * <code>5.xxx_8-Bit_Unsigned_Value</code> - 8-битовое целое без знака; |
| | * <code>6.xxx_V8</code> - 8-битовое целое со знаком; |
| | * <code>9.xxx_2-Octet_Float_Value</code> - 2-байтовое значение с плавающей точкой. |
|
| |
|
| Обычно сервис запускается автоматически при загрузке контроллера и перезапускается при сохранении файла конфигурации в веб-интерфейсе.
| | == Установка == |
| | Запустите консоль и введите командуː |
|
| |
|
| Также можно управлять сервисом в ручном режиме. Для выполнения команд подключитесь к контроллеру по [[SSH]]. Доступны команды:
| | <pre>$ apt-get update && apt-get install wb-mqtt-knx</pre> |
| <syntaxhighlight lang="bash"> | |
| $ systemctl stop wb-mqtt-knx # остановить | |
| $ systemctl start wb-mqtt-knx # запустить
| |
| $ systemctl restart wb-mqtt-knx # перезапустить
| |
| </syntaxhighlight> | |
|
| |
|
| Для просмотра [[Journalctl|служебного журнала]] сервиса:
| | == Настройка == |
| <syntaxhighlight lang="bash">
| | {{note|warn| Нужно описать как настроить сервис}} |
| $ journalctl -u wb-mqtt-knx
| |
| </syntaxhighlight>
| |
|
| |
|
| == Импорт из ETS == | | == Экспорт из ETS == |
|
| |
|
| Для импорта из инструмента ETS в файл конфигурации для работы с групповыми объектами <code>wb-mqtt-knx.conf</code>, | | Для импорта из инструмента ETS в файл конфигурации для работы с групповыми объектами <code>wb-mqtt-knx.conf</code>, |
| можно воспользоваться консольной утилитой <code>wb-knx-ets-tool</code>, которая идёт в комплекте с <code>wb-mqtt-knx</code>. | | можно воспользоваться консольной утилитой <code>wb-knx-ets-tool</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>
| |
|
| |
|
| == Полезные ссылки ==
| | * ''ETS_CONFIG'' - путь к XML файлу экспорта групповых объектов |
| * [[KNX | О KNX]] | | * ''WB_MQTT_KNX_CONFIG'' - путь к файлу конфигурации для работы с групповыми объектами <code>wb-mqtt-knx.conf</code> |
| * [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]]
| |