Хабрахабр

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

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

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

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

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

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

  • 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.

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

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

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

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’ и нажать на интересующее нас устройство (перед этим устройство необходимо добавить в сеть).

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

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

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

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

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

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

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

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

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

metadata { definition(...) { ... fingerprint mfr: "0115", prod: "0110", model: "0001", inClusters: "0x60" fingerprint mfr: "0115", prod: "0111", inClusters: "0x60" } ...
}

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

Теги
Показать больше

Похожие статьи

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Кнопка «Наверх»
Закрыть