ZigBee/Library

---

Файлы библиотеки

Все поддерживаемые устройства описаны в файлах библиотеки, находящихся в папке /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] файла конфигурации.

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