ZigBee: Библиотека устройств

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

Массив способностей устройства.

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]
    }
...

В этом случае к топикам fd и td, будет добавляться еще один уровень, содержащий номер конкретной конечной точки.

Расширения библиотеки

Поддержку новых устройств можно добавлять при помощи пользовательских расширений библиотеки. Расширения это файлы с произвольным именем. Содержимое таких файлов должно соответствовать формату основной библиотеки, описанному в данной статье.

Эти файлы можно создавать в каталоге, путь к которому настраивается параметром external в секции [device] файла конфигурации.

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