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

Материал из Wiren Board
(→‎Описание: Исправлена опечатка)
Метки: правка с мобильного устройства правка из мобильной версии Расширенная мобильная правка
(не показано 106 промежуточных версий 1 участника)
Строка 1: Строка 1:
{{DISPLAYTITLE: Описание сервиса wb-mqtt-knx}}
{{Draft}}
{{DISPLAYTITLE: Новый MQTT KNX}}
== Описание ==
== Описание ==
[[Image: WB KNX Devices.png.png |300px|thumb|right| KNX-устройства в веб-интерфейсе контроллера Wiren Board ]]
[[Image: WB KNX Devices.png.png |500px|thumb|right| KNX-устройства в веб-интерфейсе контроллера Wiren Board ]]
Сервис предназначен для работы с KNX и MQTT в двух режимах:
# Сетевой мост, который обрабатывает, передаёт и принимает  KNX телеграммы в MQTT в специальном формате.
# Набор виртуальных устройств для работы с групповыми объектами и предварительной обработкой типов данных.


Здесь описан сервис версии 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], который может работать в двух режимах:
=== Сетевой мост 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 топик:
Строка 28: Строка 23:
<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'' - Индивидуальный адрес KNX устройства отправителя в формате "n/n/n" или "n/n".
* ''DstAddr'' — Групповой адрес KNX в формате <code>n/n/n</code> или <code>n/n</code>.
* ''DstAddr'' - Групповой адрес KNX в формате "n/n/n" или "n/n".
* ''APCI'' — Тип сообщения: строка или 4х-битное число.
* ''APCI'' - Тип сообщения: строка или 4х-битное число.
* ''Data'' — Сообщение в виде байт, разделенных пробелами. Первый байт сообщения должен иметь длину не более 6 бит.
* ''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>
Строка 41: Строка 36:
* <code>GroupValueWrite</code>
* <code>GroupValueWrite</code>


== Контроллер групповых объектов ==
=== Контроллер групповых объектов ===
{{YouTube|link=https://youtu.be/VjpN_-8SA-Q|text=Вебинар про импорт проектов из ETS, типы групповых адресов и настройку FeedBack}}
 
=== Описание ===
Для группового адреса KNX создаётся индивидуально настраиваемый MQTT контрол. Это означает, что можно работать с групповым адресом как с MQTT контролом: отправлять в него и принимать из него значения, например: битов, целых знаковых и беззнаковых чисел, чисел с плавающей точкой.
Чтобы представить групповой адрес в веб-интерфейсе контроллера Wiren Board, нужно создать контрол виртуального [[MQTT]]-устройства с параметрами, заданными объекту в программе ETS: типом данных и групповым адресом. Несколько групповых адресов можно объединять в одно или несколько произвольных MQTT-устройств.


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


Каждый контрол 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-устройства.
На данный момент поддерживаются 14 типов данных групповых адресов и один с возможностью обработки сырых данных:


Если нужного вам типа не оказалось, используйте в режиме 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].
* <code>Raw_Value</code> - обработка сырых данных: массив данных в виде строки (APDU payload);
* <code>1.xxx_B1</code> - 1-битовое значение;
* <code>2.xxx_B2</code> - 2-битовое значение;
* <code>3.xxx_B1U3</code> - составное: 1-битовое значение + 3-битовое целое без знака;
* <code>4.xxx_Character_Set</code> - один ASCII символ
* <code>5.xxx_8-Bit_Unsigned_Value</code> - 8-битовое целое без знака;
* <code>6.xxx_V8</code> - 8-битовое целое со знаком;
* <code>7.xxx_2-Octet_Unsigned_Value</code> - 16-битовое целое без знака;
* <code>8.xxx_2-Octet_Signed_Value</code> - 16-битовое целое со знаком;
* <code>9.xxx_2-Octet_Float_Value</code> - 2-байтовое значение с плавающей точкой.
* <code>12.001_4-Octet_Unsigned_Value</code> - 32-битовое целое без знака;
* <code>13.xxx_4-Octet_Signed_Value</code> - 16-битовое целое со знаком;
* <code>14.xxx_4-Octet_Float_Value</code> - 4-байтовое значение с плавающей точкой в формате IEEE 754
* <code>20.xxx_N8</code> - 8-битовое целое без знака;


<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>


=== Настройка ===
<pre>$ apt-get update && apt-get install wb-mqtt-knx</pre>
Для настройки Контроллера групповых адресов вы можете импортировать готовый проект из 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'''.
# Если вы работаете под обычным пользователем, то смените [[RS-485:Configuration via Web Interface#Смена уровня доступа к веб-интерфейсу| уровень доступа]]
# Перейдите '''Settings''' → '''Configs''' → '''KNX Group Object Configuration'''
 
Включите отладку через [[Wiren Board Web Interface|веб-интерфейс]] (выключено по умолчанию):
# Установите флажок '''Enable debug logging'''
# Нажмите на кнопку '''Save''', чтобы сохранить настройки.
 
Если выключено, то включите возможность обрабатывать телеграммы через контрол knx/data (включено по умолчанию):
# Установите флажок '''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'''.
# Нажмите на кнопку '''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''' из выпадающего списка. Тип точки данных определяет какой тип контрола будет создан и как KNX данные будут интерпретироваться.
# Для задания периода чтения группового объекта задайте интервал в миллисекундах: '''READ poll interval for Devices (ms)'''. Если интервал равен нулю, то опрос чтения для этого группового объекта не производится.
# Для задания максимального времени отклика на запрос чтения укажите время в миллисекундах: '''READ poll timeout for Devices (ms)'''. Если время равно нулю, то эта функция отключена. При превышении максимального времени отклика на запрос чтения генерируется ошибка в топик '''meta/error'''
# Для настройки контрола только на чтение установите флажок '''Read only'''
# Нажмите на кнопку '''Save''', чтобы сохранить настройки.
 
== Преобразование  KNX данных в значение контрола в зависимости от типа точки данных группового объекта ==
 
Если у в состав типа точки данных входит несколько полей, то на каждое поле создаётся свой контрол.
 
Топик для приёма и отправки DataPoint типов содержащих только одно поле данных:


Добавление контрола для группового объекта:
<code>/devices/<knx_device_id>/controls/<knx_device_control_id></code>
# Выберите в списке'''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-устройством ===
<code>/devices/<knx_device_id>/controls/<knx_device_control_id>/on</code>


Сервис получает KNX-телеграмму, извлекает из неё данные и помещает их в контрол в соответствующий контрол MQTT-устройства. Если в состав группового объекта входит несколько полей, то на каждое поле создаётся свой контрол.
Топик для приёма и отправки DataPoint типов содержащих несколько полей данных:


Если в групповом объекте одно поле, то топики будут выглядеть так:
<code>/devices/<knx_device_id>/controls/<knx_device_control_id>_<datapoint_field></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>_<datapoint_field>/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_id''' - имя виртуальной группы групповых объектов;
* '''knx_device_control_id''' — имя группового объекта;
* '''knx_device_control_id''' - имя группового объекта;
* '''datapoint_field''' — имя поля из DataPoint типа.
* '''datapoint_field''' - имя поля из DataPoint типа.
 
== Список поддерживаемых типов точек данных ==
 
Смотрите: [[MQTT_KNX_V2_DatapointTypes| Список типов точек данных]]


Список поддерживаемых типов точек данных смотрите по ссылке [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 типами.
[[Image: Wb-mqtt-knx_user-case_default.png |600px|thumb|left| Структурная схема взаимодействия 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 сервер в контроллере WB
* '''wb-mqtt-knx''' - сервис для преобразования групповых объектов в MQTT устройства и контролы
* '''representation in terms of MQTT''' - представление групповых объектов терминах MQTT
* '''Web UI/ wb-rules''' - пользовательский интерфейс или движок правил
* '''/Device1/control1''' - контрол, связанный с групповым адресом и типом датапоита 1


=== Структурная схема взаимодействия ===
Устройство 1 и 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 здесь].


[[Image: Wb-mqtt-knx_user-case_default.png |500px| thumb|center|Структурная схема взаимодействия KNX MQTT ]]
=== Случай 1. Передача данных исполнительному устройству при изменении состояния датчика ===


Пояснения к схеме:
[[Image: Wb-mqtt-knx-user-case-ptp.png |600px|thumb|center| Передача датчик -> исполнительное устройство ]]
* '''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.
# Датчик при изменении своего состояния посылает исполнительному устройству 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| Передача данных от датчика к исполнительному устройству ]]
=== Случай 2. Управление исполнительным устройством через движок правил или пользовательский интерфейс ===


=== Управление KNX-устройством через пользовательский интерфейс ===
[[Image: Wb-mqtt-knx-user-case-utp.png |600px|thumb|center| Передача интерфейс пользователя -> исполнительное устройство ]]


Вы можете управлять исполнительным 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.


Как это работает:
=== Случай 3. Периодическое чтение группового объекта ===
# Изменяется значение контрола, посредством публикации значения в топик <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| Передача данных от интерфейса пользователя к исполнительному устройству ]]
[[Image: Wb-mqtt-knx-user-case-t2p2u.png |600px|thumb|center| Передача интерфейс пользователя -> исполнительное устройство ]]


=== Периодическое чтение группового объекта ===
# После начала работы сервиса и при заданном для контрола периоде опроса отличном от нуля сервис wb-mqtt-knx рассылает телеграммы с запросом на чтение с APCI командой GroupValueRead на соответствующие групповые адреса.
Как это работает:
# Если групповой объект имеет флаг R и групповой адрес, равный запрашиваемому, он отсылает в KNX TP ответ с текущим своим значением и ACPI командой GroupValueResponse.
# После начала работы сервиса и при заданном для контрола периоде опроса отличном от нуля сервис wb-mqtt-knx рассылает телеграммы с запросом на чтение с APCI командой ''GroupValueRead'' на соответствующие групповые адреса.
# Если групповой объект имеет флаг R и групповой адрес, равный запрашиваемому, он отсылает в KNX TP ответ с текущим своим значением и ACPI командой ''GroupValueResponse''.
# Это телеграмму получает wb-mqtt-knx сервис и отправляет значение в контрол со связанным групповым адресом.
# Это телеграмму получает wb-mqtt-knx сервис и отправляет значение в контрол со связанным групповым адресом.
# Далее значение контрола публикуется в топике <code>/devices/Device1/controls/control1/</code>
# Далее значение контрола публикуется в топике '''/devices/Device1/controls/control1/'''
 
[[Image: Wb-mqtt-knx-user-case-t2p2u.png |600px|thumb|center| Чтение группового объекта]]


== Управление сервисом и просмотр журнала ==
== Управление сервисом и просмотр журнала ==
Строка 197: Строка 185:
</syntaxhighlight>
</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]]

Версия 17:15, 17 января 2022

Это черновик страницы. Последняя правка сделана 17.01.2022 пользователем A.Degtyarev.

Описание

KNX-устройства в веб-интерфейсе контроллера Wiren Board

Сервис предназначен для работы с KNX и MQTT в двух режимах:

  1. Сетевой мост, который обрабатывает, передаёт и принимает KNX телеграммы в MQTT в специальном формате.
  2. Набор виртуальных устройств для работы с групповыми объектами и предварительной обработкой типов данных.

Для работы сервиса необходима его установка и настройка.

Режимы работы

Сетевой мост MQTT <=> KNX

На данный момент считается устаревшим интерфейсом. Новая функциональность более в этот интерфейс добавляться не будет.

Чтобы отправить групповую телеграмму в 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

Контроллер групповых объектов

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

Тип контрола связан типом данных для группового адреса. Тип данных для конкретного группового адреса можно настроить в веб редакторе конфигурационных файлов.

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

На данный момент поддерживаются 14 типов данных групповых адресов и один с возможностью обработки сырых данных:

  • Raw_Value - обработка сырых данных: массив данных в виде строки (APDU payload);
  • 1.xxx_B1 - 1-битовое значение;
  • 2.xxx_B2 - 2-битовое значение;
  • 3.xxx_B1U3 - составное: 1-битовое значение + 3-битовое целое без знака;
  • 4.xxx_Character_Set - один ASCII символ
  • 5.xxx_8-Bit_Unsigned_Value - 8-битовое целое без знака;
  • 6.xxx_V8 - 8-битовое целое со знаком;
  • 7.xxx_2-Octet_Unsigned_Value - 16-битовое целое без знака;
  • 8.xxx_2-Octet_Signed_Value - 16-битовое целое со знаком;
  • 9.xxx_2-Octet_Float_Value - 2-байтовое значение с плавающей точкой.
  • 12.001_4-Octet_Unsigned_Value - 32-битовое целое без знака;
  • 13.xxx_4-Octet_Signed_Value - 16-битовое целое со знаком;
  • 14.xxx_4-Octet_Float_Value - 4-байтовое значение с плавающей точкой в формате IEEE 754
  • 20.xxx_N8 - 8-битовое целое без знака;

Установка

Запустите консоль и введите команду 

$ apt-get update && apt-get install wb-mqtt-knx

Настройка

Пример настройки KNX-устройства в веб-интерфейсе контроллера Wiren Board

Предварительные шаги для настройки сервиса:

  1. Зайдите в веб-интерфейс контроллера
  2. Если вы работаете под обычным пользователем, то смените уровень доступа
  3. Перейдите Settings → Configs → KNX Group Object Configuration

Включите отладку через веб-интерфейс (выключено по умолчанию):

  1. Установите флажок Enable debug logging
  2. Нажмите на кнопку Save, чтобы сохранить настройки.

Если выключено, то включите возможность обрабатывать телеграммы через контрол knx/data (включено по умолчанию):

  1. Установите флажок Enable the KNX Gateway Device: knx/data
  2. Нажмите на кнопку Save, чтобы сохранить настройки.

Создайте виртуальное устройство для группировки групповых объектов:

  1. Нажмите на кнопку + Device
  2. В появившемся новом устройстве укажите Device ID и опционально название Title
  3. Нажмите на кнопку Save, чтобы сохранить настройки.

Добавьте контрол для групповых объектов в устройство:

  1. Укажите устройство из List of Devices в котором хотите добавить контрол.
  2. Нажмите на кнопку + Control
  3. В появившемся новом контроле укажите Control ID и опционально название Title
  4. Укажите групповой адрес Group Address. Может быть в формате: 1/2/34, 1/234, 1234
  5. Укажите тип точки данных группового объекта Data point type из выпадающего списка. Тип точки данных определяет какой тип контрола будет создан и как KNX данные будут интерпретироваться.
  6. Для задания периода чтения группового объекта задайте интервал в миллисекундах: READ poll interval for Devices (ms). Если интервал равен нулю, то опрос чтения для этого группового объекта не производится.
  7. Для задания максимального времени отклика на запрос чтения укажите время в миллисекундах: READ poll timeout for Devices (ms). Если время равно нулю, то эта функция отключена. При превышении максимального времени отклика на запрос чтения генерируется ошибка в топик meta/error
  8. Для настройки контрола только на чтение установите флажок Read only
  9. Нажмите на кнопку Save, чтобы сохранить настройки.

Преобразование KNX данных в значение контрола в зависимости от типа точки данных группового объекта

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

Топик для приёма и отправки DataPoint типов содержащих только одно поле данных:

/devices/<knx_device_id>/controls/<knx_device_control_id>

/devices/<knx_device_id>/controls/<knx_device_control_id>/on

Топик для приёма и отправки DataPoint типов содержащих несколько полей данных:

/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 типа.

Список поддерживаемых типов точек данных

Смотрите: Список типов точек данных

Случаи использования

Структурная схема

Структурная схема взаимодействия 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 сервер в контроллере WB
  • wb-mqtt-knx - сервис для преобразования групповых объектов в MQTT устройства и контролы
  • representation in terms of MQTT - представление групповых объектов терминах MQTT
  • Web UI/ wb-rules - пользовательский интерфейс или движок правил
  • /Device1/control1 - контрол, связанный с групповым адресом и типом датапоита 1

Устройство 1 и 2 связаны одним групповым адресом и образуют предварительно заданный логический канал по которому передаются определённый тип данных.

Подробнее про KNX флаги групповых объектов можно почитать здесь.

Случай 1. Передача данных исполнительному устройству при изменении состояния датчика

Передача датчик -> исполнительное устройство
  1. Датчик при изменении своего состояния посылает исполнительному устройству KNX телеграмму с групповым адресом и APCI командой GroupValueWrite.
  2. knxd прослушивает телеграммы на шине и пересылает полученную телеграмму своим клиентам, в числе которых wb-mqtt-knx.
  3. wb-mqtt-knx по таблице соответствия, сформированной из файла конфигурации, находит MQTT контрол связанный с групповым адресом и конвертирует KNX данные в значение, публикуемое контролом. Преобразование данных зависит от типа датапоинта.
  4. Изменение значения в контроле публикуется в MQTT. Подписчиками в том числе являются движок правил и пользовательский интерфейс.

Случай 2. Управление исполнительным устройством через движок правил или пользовательский интерфейс

Передача интерфейс пользователя -> исполнительное устройство
  1. Изменяется значение контрола, посредством публикации значения в топик /devices/Device1/controls/control1/on, что приводит к публикации значения в топик /devices/Device1/controls/control1/.
  2. Значение из топика /on преобразуются в данные для KNX телеграммы в зависимости от типа датапоинта, связанного с контролом. # Формируется KNX телеграмма с KNX данными, адресом получателя GA1 и APCI командой GroupWalueWrite. Адрес получателя равен групповому адресу связанному с контролом.
  3. KNX телеграмма передаётся всем клиентам knxd и в KNX TP сеть.
  4. KNX телеграмму получают устройства 1 и 2. Обработка пакета c командой GroupValueWrite происходит только в групповом объекте m в устройстве 2, из-за того что в нём выставлен флаг W.

Случай 3. Периодическое чтение группового объекта

Передача интерфейс пользователя -> исполнительное устройство
  1. После начала работы сервиса и при заданном для контрола периоде опроса отличном от нуля сервис wb-mqtt-knx рассылает телеграммы с запросом на чтение с APCI командой GroupValueRead на соответствующие групповые адреса.
  2. Если групповой объект имеет флаг R и групповой адрес, равный запрашиваемому, он отсылает в KNX TP ответ с текущим своим значением и ACPI командой GroupValueResponse.
  3. Это телеграмму получает wb-mqtt-knx сервис и отправляет значение в контрол со связанным групповым адресом.
  4. Далее значение контрола публикуется в топике /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. Утилита принимает на вход 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
Источник — https://wirenboard.com/wiki/index.php?title=MQTT_KNX_V2&oldid=58215