Файлы библиотеки
Все поддерживаемые устройства описаны в файлах библиотеки, находящихся в папке /usr/share/homed-zigbee. Путь к папке библиотеки может быть изменен в конфигурации. Библиотека может быть дополнена при помощи пользовательских расширений.
Характеристики устройств
Структура библиотеки
Каждый файл библиотеки представляет из себя JSON-объект, описывающий характеристики конечных точек каждого поддерживаемого устройства. Актуальные файлы библиотеки доступны на GitHub. Устройства идентифицируются по аттрибутам "ManufacturerName" и "ModelIdentifier" кластера "Basic".
Существуют исключения из правил, такие, как устройства TUYA, у которых всегда относительно одинаковое значение аттрибута "ModelIdentifier", зато аттрибут "ManufacturerName" всегда разный. Для этих устройств название производителя подменяется на "TUYA", а в качестве названия модели используется значение аттрибута "ManufacturerName".
Общая структура библиотеки выглядит так:
{
"manufacturer_a":
[
{
"modelNames": ["model_m", "model_n"],
"properties": ["property", "property", "property"],
"actions": ["action", "action"],
"bindings": ["binding"],
"reportings": ["reporting"],
"exposes": ["expose", "expose"],
"endpointId": 2
},
{
"modelNames": ["model_x"],
"properties": ["property"],
"actions": ["action"],
"exposes": ["expose"],
"options": {"option": "value"}
}
],
"manufacturer_b":
[
{
"modelNames": ["model_z"],
"properties": ["property", "property"],
"bindings": ["binding"],
"polls": ["poll"],
"options": {"pollInterval": 3600}
}
]
}
Поля и значения
description
Необязательное поле, имеющее исключительно информационный характер, используется для "человекопригодного" описания секции библиотеки.
modelNames
Массив значений аттрибута "ModelIdentifier" для устройств с одинаковым набором характеристик. Допускается использовать повторяющиеся значения этого поля в одном блоке производителя устройств, например:
...
{
"modelNames": ["model_a", "model_b"],
"properties": ["status", "level"],
"actions": ["status", "level"]
},
{
"modelNames": ["model_a"],
"properties": ["colorTemperature"],
"actions": ["colorTemperature"]
}
...
properties
Массив свойств конечной точки устройства. К свойствам относятся данные о состоянии устройства, например, температура, заряд батарейки, сигнал срабатывания датчика движения и так далее.
actions
Массив действий, которые могут быть применены к конечной точке устройства. К действиям относится то, как пользователь может управлять устройством, например, включать или выключать, изменять настройки и так далее.
bindings
Массив биндингов для конечной точки устройства. Дело в том, что далеко не все устройства после подключения к сети начинают отправлять отчеты координатору. Эту проблему решают биндинги, назначая адресом для отправки отчетов адрес координатора.
reportings
Массив предустановленных параметров отправки отчетов конечной точки устройства. Отчеты - это функция устройства, с помощью которой оно периодически передает координатору некоторые свои свойства. Отчеты отправляются по заданным критериям - временным интервалам и изменению значения соответствующего аттрибута. Параметры отчетов хранятся на самом устройстве и настраиваются при добавлении устройства в сеть, при обновлении характеристик устройства или вручную.
polls
Массив опросов конечной точки устройства. Опросы - это способ принудительно получить некоторые свойства устройств, не поддерживающих отчеты. В этом случае координатор сам обращается к устройству, либо один раз, при запуске сервиса, либо раз в заданный промежуток времени.
exposes
Массив интеграций конечной точки устройства. Интеграции - это абстрактные сущности, на которых основана работа функции Home Assistant MQTT Discovery, а так же работа веб-интерфейса. Например, интеграция "temperature" добавляет в Home Assistant датчик темературы, а "light" добавляет лампочку.
options
Опции позволяют задавать дополнительные настройки для других элементов библиотеки, например корректировать значения свойств.
endpointId
Хитрое поле, описывающее, к каким конечным точкам устройства применимы перечисленные характеристики. Если поле отсутствует, используятся конечнная точка по умолчанию, то есть 1. Допускается перечисление нескольких конечных точек для одной и той же модели устройства:
...
{
"modelNames": ["lumi.sensor_cube", "lumi.sensor_cube.aqgl01"],
"properties": ["lumiBatteryVoltage"],
"endpointId": 1
},
{
"modelNames": ["lumi.sensor_cube", "lumi.sensor_cube.aqgl01"],
"properties": ["lumiCubeMovement"],
"endpointId": 2
},
{
"modelNames": ["lumi.sensor_cube", "lumi.sensor_cube.aqgl01"],
"properties": ["lumiCubeRotation"],
"endpointId": 3
}
...
Кроме того, поле может содержать не только одиночное значение номера конечной точки, но и массив значений. Это применимо к устройстам, имеющим несколько конечных точек c идентичным набором характеристик, таким, как многоканальные реле или выключатели. В таком случае, к топикам статусных сообщений, содержащих перечисленные свойства, будет добавляться еще один уровень, содержащий в себе номер конкретной конечной точки.
Например:
...
{
"modelNames": ["multi_channel"],
"properties": ["status"],
"actions": ["status"],
"endpointId": [1, 2, 3]
}
...
Расширения библиотеки
Поддержку новых устройств можно добавлять при помощи пользовательских расширений библиотеки. Расширения это файлы с произвольным именем. Содержимое таких файлов должно соответствовать формату основной библиотеки, описанному в данной статье.
Эти файлы можно создавать в папке, путь к которой настраивается парамером external в секции [device] файла конфигурации.
Пользовательские расширения имеют приоритет над основной библиотекой, список файлов расширений сортируется по имени, парсер библиотеки прекращает поиск описания устройства, как только найдет первое совпадение.