directman

Добавляем новые или недостающие метрики управления устройств в модуле zigbee2mqtt

Краткая инструкция, как самостоятельно добавить поддержку устройств в модуль поддержки zigbee2mqtt.

Введение

Колиечетво поддерживаемых устройств zigbee2mqtt растет семимильными шагами, зачастую автор модуля интеграции для MajorDoMo не успевает отслеживать появление новых устройств. К тому-же, довольно часто требуется само устройство, чтобы пртестировать правильность отправляемых параметров.

Коротко о структуре взаимодействия

Взаимодействие с устройствами происходит по протоколу MQTT. Обычно на странице устройства проекте zigbee2mqtt уже имеется описание метрик, по которым возможно взаимодействие с устройством. Возьмем для примера датчик JTYJ-GD-01LM_BW. Страница устройства доступна по кликабельной ссылке.

Как видим, для того, чтобу изменить чувствительность сенсора, необходимо отправить координатору сети сообщение, типа:

zigbee2mqtt/FRIENDLY_NAME/set
необходимо отправлять

{"sensitivity": NEW_VALUE}

Возможные значения: low, medium, high

Отправка таких вариаций возможна вручную со страницы устройства, либо с вкладки Сервис, или из сценария.

Управление из сценария:

include_once(DIR_MODULES . 'zigbee2mqtt/zigbee2mqtt.class.php');
$z2m = new zigbee2mqtt();
$z2m->sendcommand('zigbee2mqtt/0x00158D0002EE1285/set', '{"sensitivity":"medium"}');

где 0x00158D0002EE1285 - IEEE адрес вашего устройства.

Теперь настроим это взамодействие в Majordomo.

В модуле интеграции пока не предусмотрена отправка текстовых значений, кроме как ON, OFF, TRUE, FALSE, поэтому мы можем только прописать метрики, куда их необходимо отправлять со страницы устройства.

Структура базы данных устройств хранится в 2 файлах, которые вы можете править самостоятельно:
База данных устройств database1.inc.php
Список метрик устройств database1.inc.php

Вы можете править эти файлы из самого MajorDoMo с помощью дополнения KodExplorer, который устанавливается из маркета. Это очень крутой браузерный проводник с отличным редактором файлов с подсветкой синтаксиса.

Для добавления устройства в список устройств, необходимо добавить новую запись по аналогии. Путь до файлов базы данных лежит по адресу /modules/zigbee2mqtt/. В нашем примере для устройства JTYJ-GD-01LM_BW необходимо завести следующие данные.

database1.inc.php:

$par1['zigbeeModel'] = "JTYJ-GD-01LM_BW";
$par1['model'] = "JTYJ-GD-01LM_BW";
$par1['vendor'] = "Xiaomi";
$par1['type'] = "ыутыщк";
$par1['description'] = "MiJia Honeywell smoke detector";
$par1['supports'] = "";
$par1['extend'] = "";
$par1['fromZigbee'] = "";
$par1['toZigbee'] = "";
SQLInsert('zigbee2mqtt_devices_list', $par1);

и добавим для него метрики управления чувствительностью sensitivity и состоянием state:

database1.inc.php:

//JTYJ-GD-01LM_BW;
$par2['zigbeeModel'] = 'JTYJ-GD-01LM_BW';
$par2['type'] = "sensor";
$par2['state_topic'] =  "<Z2M_PATH>/<FRIENDLY_NAME>";
$par2['availability_topic'] = "<Z2M_PATH>/bridge/state";
$par2['payload_off'] = ""  ;
$par2['payload_on'] = ""  ;
$par2['value_template'] = "sensitivity";
$par2['command_topic'] = "<Z2M_PATH>/<FRIENDLY_NAME>/set"  ;
$par2['json_attributes'] = "";
$par2['device_class'] = "";
$par2['unit_of_measurement'] = "";
$par2['brightness'] = "";
$par2['color_temp'] = "";
$par2['xy'] = "";
$par2['command_value'] = "sensitivity";
SQLInsert('zigbee2mqtt_devices_command', $par2);

//JTYJ-GD-01LM_BW;
$par2['zigbeeModel'] = 'JTYJ-GD-01LM_BW';
$par2['type'] = "sensor";
$par2['state_topic'] =  "<Z2M_PATH>/<FRIENDLY_NAME>";
$par2['availability_topic'] = "<Z2M_PATH>/bridge/state";
$par2['payload_off'] = ""  ;
$par2['payload_on'] = ""  ;
$par2['value_template'] = "state";
$par2['command_topic'] = ""  ;
$par2['json_attributes'] = "";
$par2['device_class'] = "";
$par2['unit_of_measurement'] = "";
$par2['brightness'] = "";
$par2['color_temp'] = "";
$par2['xy'] = "";
$par2['command_value'] = "state";
SQLInsert('zigbee2mqtt_devices_command', $par2);

Теперь, давайте разберем все параметры, которые необходимы работы с устройствами:

zigbeeModel - модель устройства из database1.inc.php
type - тип устройства, произвольный (relay, dimmer, sensor и тд)
value_template - параметр, который будет изменяться, например state
command_value  - параметр, который будет изменяться, например state
payload_on - действие, когда   MajorDoMo отправляет  логическую единицу, обычно ON
payload_off -  действие, когда   MajorDoMo отправляет  логический ноль, обычно OFF
command_topic -  путь mqtt, куда необходимо отправлять новые значения, которые можно передать устройству (яркость, состояние, положение заслонки и тд).
availability_topic - путь mqtt, по которому модуль будет определять состояние устройства - необязательный параметр.
xy - true, если устройство поддерживает управление цветом по цветовым координатам 
json_attributes - не используется
device_class - не используется
unit_of_measurement - не используется
brightness - не используется
color_temp - не используется
availability_topic - не используется

Прошу простить, если некоторые параметры повторяются, данная структура была портирована по структуре базы данных zigbee2mqtt.

Картинки устройств хранятся по адресу /templates/zigbee2mqtt/img по имени устройства. Вы можете их самостоятельно добавить для всех пользователей через github

После того, как добавите данные по устройствам, не забудьте обновить вашу базу данных устройств на вкладке Сервис -> Update metrics.

Публикация изменений в базу данных

После тестирования огромная просьба отправить Pull Reqest для обновления базы данных в репозиторий модуля zigbee2mqtt. Это совсем не сложно, изменения можно внести даже без создания клона репозитория, прямо из браузера.

Первым делом необходимо зарегистрироваться на github, если у вас еще нет акаунта.

Если необходимо внести изменение в файл database1.inc.php, то из браузера по адресу https://github.com/directman66/majordomo-zigbee2mq... вам будет доступна кнопка с карандашом (Edit this file). При внесении изменений через этот режим, на сайте github будет автоматически создан path проекта модуля zigbee2mqtt и будет предложено создание Pull Reqest автоматически.

Конечно самый удобный вариант внесения изменений - это вариант из консоли, о ним много написано в сети.

Инструкции о том, как сделать свой первый PR
1) https://starkovden.github.io/Pull-request-workflow...
2) https://rustycrate.ru/%D1%80%D1%83%D0%BA%D0%BE%D0%...

Сделай свой вклад в развитие свободного ПО, сделай свой первый Pull Reqest.

После того, как опубликуете свой Pull Reqest, напишите пож-та автору дополнения на почту sannikovdi@yandex.ru, чтобы я его принял, так как по какойто причине уведомления с github мне не приходят.

Обсуждение (2) (6)

Екатеринбург, Россия

На форуме: directman66