Як я додавав новий пристрій у SmartThings Hub

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

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

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

Підключається пристрій — це плата, яка дозволяє додати управління практично будь-яким пристроєм в Z-Wave. Причому підключених пристроїв може бути різна кількість (до 10шт.). Відповідно на програмному рівні всі типи пристроїв необхідно також обробити і вивести управління в додаток.

Список оброблюваних типів

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

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

Можна виділити два логічних блоки:

  • Опис і мета-інформація про процесор. Сюди входить інформація про пристрої, як повинен отрисовываться UI та інша інформація. Виділяється методом metadata().

    Приклад UI

  • Методи обробника — є логікою хендлер. Вони відповідають за “спілкування” з пристроєм.

    Окремо можна виділити метод 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,7 A role:06 ff:8C07 ui:8C07

Значення кожного ключа, як раз і використовується для заповнення “Fingerprint”. Докладний опис кожного елемента можна знайти тут. Ми розглянемо ті, які будуть використовуватися в нашому обробника.

Як знайти raw descriptionДля того щоб знайти цю рядок з інформацією, необхідно зайти у вкладку ‘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"
}

...
}

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

Читайте також  Пишемо гру на LWJGL

Степан Лютий

Обожнюю технології в сучасному світі. Хоча частенько і замислююся над тим, як далеко вони нас заведуть. Не те, щоб я прям і знаюся на ядрах, пікселях, коллайдерах і інших парсеках. Просто приходжу в захват від того, що може в творчому пориві вигадати людський розум.

You may also like...

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *