[Из песочницы] Как я добавлял новое устройство в SmartThings Hub, часть 127.10.2018 13:49

В этой статье я хочу рассказать про свой опыт разработки так называемого Device Handler для умного дома SmartThings. Задача состояла в добавлении универсального устройства на базе протокола Z-Wave — Z-Uno, а так же обработка подключаемых к нему дочерних устройств.

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

Весь процесс разработки происходит в веб-приложении SmartThings IDE на языке Groovy. Тестирование удобнее проводить с мобильного устройства, однако есть возможность создавать симуляторы устройств в той же среде разработки. В случае тестирования графической оболочки уже появляется необходимость использования мобильного приложения SmartThings Classic (Android, iOS).

Подключаемое устройство — это плата, которая позволяет добавить управление практически любым устройством в Z-Wave. Причём подключаемых устройств может быть разное количество (до 32шт.). Соответственно на программном уровне все типы подключаемых устройств необходимо также обработать и вывести управление в приложение.

Список обрабатываемых типов:

Switch Binary — устройства имеющие всего два положения: on/off
Switch Multilevel — устройства, которые могут быть выключены или включены с различным значением. Например димер.
Sensor Multilevel — датчики отправляющие не бинарные значения. Например датчик температуры.
Meter — устройства подобные счетчику
Notification — бинарные датчики, будут относиться к этому типу. Например, герконовый датчик.
Thermostat — отдельный класс команд который отвечает за работу с термостатом

Структура документа

Можно выделить два логических блока:
Более подробно описывать назначение и содержание каждого блока я буду в ходе цикла статей.

Metadata

Как можно заметить из названия метода — здесь содержится метаинформация.

Рассмотрим по порядку что входит в этот блок:

Definition ()

В этом методе аргументами указываются три вещи, соответственно: название обработчика, пространство имен и имя автора.

Название обработчика в дальнейшем будет использоваться при публикации и при создании дочерних устройств.
Пространство имен используется при поиске хэндлеров по имени, чтобы убедиться что найден правильный, например, среди обработчиков с одинаковым названием. SmartThings рекомендует использовать свой никнейм на github.
Имя автора заполняется вашим именем.

    definition(name: "Your device", namespace: "yournamespace", author: "your name") {}

В теле метода могут объявляться следующие переменные: attribute, capability, command, fingerprint. Далее мы более подробно рассмотрим что это и когда применяется.

Подключение и fingerprinting

Подключаем наше устройство. В нашем случае будут использоваться SmartThings V2 Hub и Z-Uno.

В момент добавления нового устройства Z-Wave или ZigBee, хаб будет пытаться распознать, какой тип устройства к нему пытаются подключить и начнет искать наиболее релевантный хендлер. Выбирать он его будет по «Fingerprints». Если хаб не найдет соответствий в пользовательских обработчиках, он попытается использовать один из наиболее близких стандартных шаблонов.

«Fingerprints» задаются в самом обработчике для указания, какие типы устройств он поддерживает. В официальной документации сообщается, что они будут разные для устройств Z-Wave и устройств ZigBee, мы будем рассматривать реализацию для Z-Wave.

Устройства протокола Z-Wave хранят в себе информацию об их производителе, типе устройства, его возможностях и т.п. Во время так называемого «интервью» с устройством, ST собирает эту информацию в Z-Wave raw description. Пример такой строки:

zw:Ss type:2101 mfr:0086 prod:0102 model:0064 ver:1.04 zwv:4.05 lib:03 cc:5E,86,72,98,84 ccOut:5A sec:59,85,73,71,80,30,31,70,7A role:06 ff:8C07 ui:8C07

Значение каждого ключа, как раз и используется для заполнения «Fingerprint». Подробное описание каждого элемента можно найти здесь. Мы рассмотрим те, которые будут использоваться в нашем обработчике.

Для того чтобы найти эту строку с информацией, необходимо зайти во вкладку «My Devices» и нажать на интересующее нас устройство (перед этим устройство необходимо добавить в сеть).

mfr — 16-битное значение содержащее ID производителя (Manufacturer ID). Список производителей и их ID можно найти здесь.

prod — 16-битное значение содержащее Product Type ID — уникальный ID типа устройства.

model — 16-битное значение содержащее Product ID.

inClusters — 8-битное значение, устанавливающее необходимость в том или ном Command Class. Например, если нам нужно указать что наш обработчик будет работать с MultiChannel CC необходимо написать его код 0×60. Список доступных для SmartThings CC
можно найти здесь.

Этих четырех ключей достаточно, что бы хаб точно понимал, к какому устройству относиться этот обработчик. Пример, как они используются у меня:

fingerprint mfr: "0115", prod: "0110", model: "0001", inClusters: "0x60"
fingerprint mfr: "0115", prod: "0111", inClusters: "0x60"

Устройство может иметь большее количество параметров, в таком случае оно может успешно подключится с этим хэндлером, однако, если хотя бы один из них не совпадает с объявленным fingerprint — устройство проигнорирует этот обработчик.

Smartthings рекомендует добавлять в fingerprint информацию о производителе (mfr) и модели (prod, model), чтобы исключить случаи, когда выбор обработчика будет не очевиден. Например, когда fingerprints одного из шаблонов или примеров, используемых по умолчанию будет совпадать с вашим.

Расположение в коде

metadata {
    definition(...) {
        ...

        fingerprint mfr: "0115", prod: "0110", model: "0001", inClusters: "0x60"
        fingerprint mfr: "0115", prod: "0111", inClusters: "0x60"
    }
    ...
}

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