В этой статье я хочу рассказать про свой опыт разработки так называемого 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 — отдельный класс команд который отвечает за работу с термостатом
Структура документа
Можно выделить два логических блока:
- Описание и мета-информация об обработчике. Сюда входит информация об устройстве, как должен отрисовываться UI и прочая информация. Выделяется методом
metadata().
- Методы обработчика — являются логикой хэндлера. Они отвечают за “общение” с устройством.
Отдельно можно выделить метод parse(), который занимается интерпретацией полученных команд с устройства.
Более подробно описывать назначение и содержание каждого блока я буду в ходе цикла статей.
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 необходимо написать его код 0x60. Список доступных для 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"
}
...
}
Планируется полный цикл статей, вплоть до релиза. Надеюсь данная информация поможет вам в разработке.
Автор: baadev
