wb2ha

WirenBoard devices to Home Assistant MQTT Discovery

For English, translate with your browser.

Перенос устройств WirenBoard в Home Assistant

Скрипт позволяет отображать устройства WirenBoard в Home Assistant и управлять ими с помощью преобразования и публикации данных из топиков meta, которые создаются в WirenBoard для каждого устройства и контрола, в топики Home Assistant MQTT Discovery.

Этот скрипт является правилом для контроллера WirenBoard. Скрипт вдохновлен проектом WB Engine, автор которого поддерживает его в топике на форуме WirenBoard.

Настоящий проект написан для себя и поддерживается постольку поскольку. Он не является заменой WB Engine и не может создавать шторы и термостаты в WirenBoard. Данный скрипт написан для моих специфических нужд по отображению любых устройств WB в HA и требует консультации с документацией с Home Assistant MQTT Discovery, в то время как в WB Engine шаблоны топиков для устройств WB уже настроены автором. Используйте без каких-либо гарантий!

Как пользоваться

Созайте правило wb2ha и скопируйте туда содержимое файла release/wb2ha.js.

Настройка

Настройка осуществляется в веб-интерфейсе WirenBoard разделе Настройки / Конфигурационные файлы / wb2ha - Настройка отображения устройств WirenBoard в Home Assistant.

Верхние три поля отвечают за настройку топиков HA MQTT Discovery и их можно оставить без изменений, если HA настроен по умолчанию. MQTT Discovery ожидает информации о том, из каких топиков брать состояние устройств и в какие топики публиковать требуемые изменения состояния в сообщениях MQTT особого формата и в определенных топиках. Для того, чтобы топики и устройства из разных источников не путались между собой, каждый экземпляр wb2ha снабжает технические идентификаторы устройств идентификатором контроллера WirenBoard, а также пишет его в раздел node_id пути топика Discovery вместе с префиксом из второго поля. Пользователю это ничего не видно, но HA может отличить одно устройство от другого.

Далее идет галочка "Опубликовать все устройства WirenBoard и их контролы", которая добавит вообще всё, кроме того, что настроено, чтобы не добавлялось (см ниже).

Основные операции с контролами происходят во вкладке Устройства WirenBoard.

Добавление контролов без изменений

Для добавления контрола в качестве сущности ("entity") нужно поставить галочку у его устройства слева и затем, раскрыв список контролов, также поставить галочку у нужного контрола.

Скрипт будет ориентироваться на тип контрола и единицу измерения данных. В общем случае, реле будут добавлены как switches (выключатели), а контролы, значения которых нельзя менять вручную (readonly), будут добавлены как sensors (датчики). Изменяемые контролы должны добавиться как редактируемые поля, и если указана единица измерения, то они будут числовыми.

У нас есть контролы числового типа, для которых не указана единица изменения, например, это данные датчика движения в WB-MSW v.3, измеряемого в неизвестных мне крокодилах. Для таких случаев настроено принудительное снабжение данных "текущего значения интенсивности движения" единицей измерения % (процент).

Это все настраивается во вкладках Типы контролов и Единицы измерения. Там сложновато, поскольку для каждой единицы измерения и типа контрола надо указывать разные настройки Discovery в зависимости от того, изменяемое это поле или нет, и из-за этого там несколько вложенных редакторов, которые по умолчанию скрыты, чтобы не пугать пользователя.

Самое сложное, что там настроено - преобразование контрола с типом данных rgb в сущность light с возможностью выбора цвета и яркости светодиодной ленты. Таким образом, при переносе устройства WB-LED, подключённого к цветной ленте, нам нужно только перенести контрол RGB Palette, который как раз имеет тип данных rgb, и в Home Assistant образуется сущность, следящая также и за топиком RGB Strip и позволит и включать-выключать ленту, и менять ее цвет.

Добавление всех устройств и контролов

Если установить галочку "Опубликовать все устройства WirenBoard и их контролы", в Home Assistant будут добавлены, соответственно, все устройства и все их контролы, за исключением тех, где в настройках устройства будет стоять галочка "Все не добавлять" - для этих устройств будут добавлены только выбранные контролы, то есть те, у которых стоит своя галочка.

Изменение способа отображения контрола

Не все контролы правильно отображаются с помощью настроек во вкладках "Типы контролов" и "Единицы измерения". Например, хочется указать для Home Assistant, что данное реле является не просто выключателем, а лампочкой или светодиодной лентой, то есть относятся к категории light. Данная категория в Home Assistant называется то платформой, то доменом, и их много, например, fan - вентилятор, lock - замок, cover - нечто закрывающееся и открывающееся, типа штор или ворот, но не клапан, у которого своя платформа - valve, еще есть climate - как правило, термостат или кондиционер, в общем, что-то влияющее на температуру и влажность.

Чтобы представить один контрол как сущность другой категории, не меняя другие настройки, нужно в настройках выбранного контрола установить галочку у выпадающего списка Type, и затем в списке выбрать другой тип, кроме Any. Если сущности не нужны никакие топики, кроме включения-выключения и статуса, то это должно сработать.

Несколько контролов как одна сущность

Между прочим, мы можем представить сразу несколько контролов как одну сущность Home Assistant, используя редактор сообщения MQTT Discovery, открывающийся, когда мы выбираем нужную нам платформу в поле Type. Например, белую светодиодную ленту устройства WB-LED, управляемую двумя контролами, надо переносить как одну сущность: в интерфейсе Home Assistant и выключатель ленты, и ползунок выбора её яркости будут представлены одним квадратиком, на котором будут и выключатель, и ползунок.

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

В wb2ha есть редактор настроек для каждой платформы, и, в принципе, все поля снабжены подсказками из англоязычной документации (хотя могут встречаться ошибки, так как это все, естественно, сформировано автоматически из неких источников в интернете. Например, кто-то когда-то разобрал настройки редактора VSCode для редактирования хоумассистантовского yaml и превратил это в json-схему). К сожалению, без уродливой кнопки Properties мне не удаётся отображать редактор опций в более компактном виде из-за особенностей встроенного редактора конфигураций.

Если мы указываем тип Any, то можем в достаточно компактном виде добавлять произвольные опции в сообщение HA MQTT Discovery.

Однако, кое-что уже настроено мной и сохранено в виде так называемых "Именованнных модификаторов"

Именованные модификаторы и переменные

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

Например, для белой светодиодной ленты, управляемой WB-LED, имеется именованный модификатор wbLedSwitchLight. Если мы его применим к контролу Channels 1_2_3_4 или другому, управляющему белой лентой, у нас в Home Assistant она представится, как light с выбором яркости.

Именованные модификаторы настраиваются примерно также, как модификаторы для индивидуальных контролов, для типов контролов и для единиц измерения. Нужно выбрать желаемый тип сущности ("платформу", или "домен", или "категорию", типа light или fan), и дальше настраивать всевозможные опции.

При этом, естественно, когда мы применяем одну настройку к нескольким контролам, в ней должны быть изменяемые части. Я написал небольшой шаблонизатор, который позволяет вписывать в настройку не готовое значение, а ссылку на значение, которое мы можем взять из устройства или контрола. Например, добавляя контрол, который может только включать и выключать светодиодную ленту, нам нужно сослаться на соседний контрол, управляющий яркостью. Для этого в опции brightness_state_topic мы пишем /devices/{device.id}/controls/{control.id} Brightness, а в опции brightness_command_topic - /devices/{device.id}/controls/{control.id} Brightness/on. В процессе публикации контрола в HA последовательность {device.id} заменится на наше название устройства из WB, а {control.id} - например, на слово Channels 1_2_3_4, и таким образом у нас получится правильное название топиков WB, в которых публикуются изменения яркости.

У переменной control есть еще полезное свойство meta, где будут всевозможные полезные данные, которые WirenBoard пишет в топик meta: то есть, мы можем писать {control.meta.min}, и это заменится на числовое значение из мета-топика.

Кроме того, мы можем создавать и свои переменные и использовать их в настройках значений опций. Главное затем придать им значения при публикации конкретного контрола - это делается в разделе "Переменные".

Публикация выключателей света Zigbee

Для таких маленьких реле Zigbee, вкладываемых в подрозетник за выключателем, пришлось написать именованный модификатор zigbeeSwitchLight. Дело в том, что хотя zigbee2mqtt может публиковать устройства в Home Assistant, и диммеры и контроллеры светодиодных лент определяются как light, эти маленькие реле все определяются как switch, то есть какой-то просто выключатель, выключающий неизвестно что, и нам приходится выбирать в HA что-то типа "представить этот выключатель как что?" использовать какие-то там Helpers, которые непонятно как работают, что-то там задваивают, непонятно где хранятся и как про них не забыть.

WirenBoard представляет устройства Zigbee из своего встроенного zigbee2mqtt в одной куче со всеми другими устройствами и их даже по чёткой логике не отличить по метаданным. Я разрешаю zigbee2mqtt публиковать устройства в HA самостоятельно, но эти мини-реле я публикую еще раз, но с этим модификатором zigbeeSwitchLight, тогда они отображатся как лампочки; а при желании, можно и zigbeeSwitchLight применить, и еще добавить тип fan, если это выключатель вытяжки в ванной - тогда в HA это будет выглядеть как вентилятор

Термостаты и роллеты

Я написал свой собственный термостат с помощью правил WirenBoard, который выглядит примерно так:

Я написал его самостоятельно, поскольку хотел в общем иметь представление о ПИД-регуляторах - и я совершенно не уверен, что мне удалось, и что на деле он способен подстроить температуру помещения без "перелётов" и "недолётов", поэтому, в отличие от WB Engine, он не входит в состав wb2ha. К тому же он реализует требования, которых я ни у кого, кроме себя, не видел, а именно, все термостаты дома знают о существовании котла; динамически выбирается термостат с самой большой ошибкой, то есть самая холодная комната, у батареи которого клапан открывается полностью, а температура в этом помещении начинает управляться котлом напрямую. Для котла же в доме как будто только одна комната и он подбирает свой режим работы своим внутренним механизмом. Скрипт сложен, заточен под мои устройства и делать его настраиваемым для разных инсталляций пока неохота.

Для отображения этого термостата в HA я создал именованный модификатор, который удобнее представить в виде куска конфигурационного файла, чем скриншота редактора конфигураций:

        "namedModifiers": [
...
            {
                "code": "thermostat",
                "value": {
                    "mod": {
                        "climate": {
                            "action_template": "{{ 'heating' if value == '1' else 'idle' }}",
                            "action_topic": "/devices/{device.id}/controls/state",
                            "current_temperature_topic": "/devices/{device.id}/controls/temperature",
                            "max_temp": "{control.meta.max}",
                            "min_temp": "{control.meta.min}",
                            "mode_state_template": "{{ 'off' if value == 'off' else 'heat' }}",
                            "mode_state_topic": "/devices/{device.id}/controls/mode",
                            "modes": [
                                "heat",
                                "off"
                            ],
                            "preset_mode_command_topic": "/devices/{device.id}/controls/mode/on",
                            "preset_mode_state_topic": "/devices/{device.id}/controls/mode",
                            "preset_modes": [
                                "off",
                                "low",
                                "on",
                                "hi"
                            ],
                            "temperature_command_topic": "/devices/{device.id}/controls/{control.id}/on",
                            "temperature_state_topic": "/devices/{device.id}/controls/{control.id}",
                            "temperature_unit": "C"
                        }
                    },
                    "namedModifiers": []
                }
            },
...

С рольставнями такая же ситуация: встроенный шаблон управления шторами в реле "мини" на тот момент не существовал, а затем не запоминал положение штор, поэтому я написал свое несложное виртуальное устройство:

Для него сделал такой именованный модификатор:

            {
                "code": "rollshutter",
                "value": {
                    "mod": {
                        "cover": {
                            "device_class": "shutter",
                            "payload_close": "{control.meta.min}",
                            "payload_open": "{control.meta.max}",
                            "payload_stop": "null",
                            "position_closed": "{control.meta.min}",
                            "position_open": "{control.meta.max}",
                            "position_topic": "/devices/{device.id}/controls/targetPosition",
                            "set_position_topic": "/devices/{device.id}/controls/targetPosition/on",
                            "state_stopped": "stopped",
                            "state_topic": "/devices/{device.id}/controls/state"
                        }
                    },
                    "namedModifiers": []
                }
            }

Почему мне не подошёл WB Engine

Скрипт WB Engine отличный, но мне он не подошёл, поскольку я переименовываю устройства WirenBoard в "настройке драйвера Serial устройств", указывая им кодовое имя, говорящее о расположении и функции устройства, например, fl2_east_bedroom_upper_color или fl2_north_bedroom_sensor. WB Engine для определения способа представления сущностей в Home Assistant опирается на название устройства типа WB-LED, WB-MSW v.3 и т.п., которые нигде в метаданных не передаются, если указаны пользовательские имена. Также и для некоторых моих витруальных устройств, даже при указании единицы измерения, Home Assistant не мог определить характер данных и отображал их как текст.

Настоящий скрипт wb2ha написан за день, и еще три недели ушли на создание json-схемы для редактора конфигурации, чтобы пользователю не приходилось править настроечный файл в текстовом редакторе. Схема получилась сложноватой, к тому же она автоматически обновляется при добавлении или удалении физических и вирутальных устройств в WirenBoard, так как для каждого устройства и контрола нужно подготовить в редакторе раздел. Этих разделов столько же, сколько в вашем контроллере настроено устройств, и грузится этот редактор в два раза дольше редактора настройки WB Engine. Благодаря использованию встроенного редактора конфигураций, настраивать устройства вроде бы стало удобнее (хотя с этим можно поспорить), но сам файл конфигурации стал более бестолковым для редактирования вручную. Возможны случаи, когда в файле конфигурации /etc/wb-rules/wb2ha.config окажутся настройки, не соответствующие усложнённой json-схеме, редактор вменяемых сообщений об ошибке не выдает, что не так - непонятно, и тогда всё.