Многофункциональный навык УДЯ на Zeit Now

Внимание! Навык разрабатывался для себя и опубликован как есть. 
Буду очень рад обратной связи при тестировании и доработках. 
100%-ная работа "без сучка и задоринки" не гарантируется =)

Предисловие

Рассмотрим управление устройствами Умного дома Яндекс через http-запросы с помощью собственного приватного навыка. Не стоит пугаться показанного способа, он очень прост.

Да, есть прекрасный навык "Домовенок Кузя", но наш вариант подойдет тем, кто хочет быстро, легко и бесплатно поднять навык собственный, чтобы быть более уверенным в связи Умного дома Яндекса со своими устройствами.

Что может навык?

Навык умеет:

• Управлять устройствами через http-запросы.
• Поддерживать такие типы устройств, как:
  • "Выключатель",
  • "Розетка",
  • "Лампа",
  • "Другое" (кастомное многофункциональное устройство).
• Принимать статусы состояния устройств.

Поддерживаются варианты подключения:

• Blynk
• IFTTT, кроме типа значений "Range" ("ползунок")
• Any - устройства, которые управляются http-запросами в разных форматах (вариативно) - Требуется тестирование

Наши действия (для нетерпеливых)

1. Заливаем архив с навыком в свой репозиторий github
2. Подключаем учетную запись github к Zeit Now
3. Создаем навык УДЯ
4. Настраиваем файл конфига устройств device.txt

В статье много "начальной" информации; ведь не все, кто столкнулся с УДЯ, сразу имеют нужные знания. Поэтому опишем процесс как можно подробнее.
Бывалые могут просто промотать понятные им места)

От слов - к делу!

Регистрируемся на github.com

1. Cкачиваем файлы навыка по ссылке.
2. Переходим по ссылке регистрации на github.
3. Вводим Username (Имя пользователя), Email address (свой e-mail) и password (пароль), и нажимаем кнопку "Create account".
4. Выбираем бесплатный аккаунт, нажав кнопку Choose Free.
5. Теперь можно выбрать, для чего вы планируете использовать аккаунт (а можно и не выбирать =) ).
6. Нажимаем кнопку Complete Setup (появится предложение проверить свой почтовый ящик на наличие письма активации).
7. Переходим в почту, нажимаем в письме активации кнопку Verify email address.
8. После перехода по ссылке будет предложено создать новый репозиторий. Для этого потребуется:
   • придумать и указать имя-ссылку нового репозитория,
   • обязательно отметить, что репозиторий приватный (нам же не нужно, чтобы кто то видел наши токены и ссылки на устройства)!
   • ...и нажать Create repository.

Репозиторий создан, теперь в него требуется загрузить файлы нашего навыка. 
Это можно сделать установив git на пк, настроить, и заpushить в свой репозиторий. Шучу. 
Просто выбираем ссылку  uploading an existing file, а потом ссылку choose your files.
Загружаем файлы навыка (см иллюстрацию 3).

• 
  Создаем репозиторий
• 
  Ссылка "uploading an existing file"
• 
  Файлы для загрузки

Регистрируемся на Zeit Now и запускаем сервер

Теперь подключим наш репозиторий к серверу Zeit Now:

1. Переходим по ссылке регистрации, и выбираем Continue with GitHub.
2. Подключаем репозиторий, нажав на кнопку Authorize Now by ZEIT.
3. В следующем окне заполняем требуемые данные и соглашаемся со всем, пока нам не предложат создать проект (Create a new project).
4. Выбираем From Git Repository.
5. На предложение установить модуль для связи с GitHub жмём Install Now For GitHub и выбираем Only select repositories.
6. Из выпадающего списка выбираем свой репозиторий.
7. Нажимаем кнопку Install.
8. Модуль подключен, осталось создать проект с нашим навыком: нажимаем New Project From GitHub.
9. Выбираем репозиторий кнопкой Select и импортируем кнопкой Import.
10. Задаём имя проекта (посложнее, чтоб не пересекалось с другими именами проектов Zeit).
11. Корневую папку (ROOT) оставляем, как есть.

Если все в порядке, индикатор проекта станет бирюзовым, и появится ссылка на наш навык.

• 
  Регистрация в Zeit Now
• 
  From Git Repository
• 
  From Git Repository
• 
  Импортируем репозиторий
• 
  Задаем имя проекта
• 
  Индикатор проекта и ссылка на навык

Создаем приватный навык УДЯ

Для создания навыка УДЯ перейдём в кабинет разработчика платформы Диалогов.

1. Жмём большую кнопку "Создать навык", выбираем тип навыка "Умный дом".
2. Заполняем информацию о навыке (см рис 2, 3, 4), где:
   • Endpoint URL - Url из раздела DOMAINS в кабинете ZEIT. При этом обязательно ставим https:// в начале.
   • "Не показывать в каталоге" - ставим галочку (чтобы обойтись без долгой модерации, а сам навык не попал в общий каталог).
3. Нажав кнопку "Изменить", указываем:
   • Идентификатор приложения - любая строка (можно пару раз упасть головой на клавиатуру);
   • Секрет приложения - поступаем так же;
   • URL авторизации - ссылка, которую указывали в Endpoint URL
   • URL для получения токена - ссылка вида: https://ссылка_навыка/token
   • URL для обновления токена - ссылка вида: https://ссылка_навыка/refresh
   • Идентификатор группы действий - read,home:lights
4. Нажимаем "Сохранить" в окне "Создание связки аккаунтов" и в настройках нашего навыка.
5. Подтверждаем указанную нами электронную почту;
6. Подать навык на модерацию. Если не забыли указать, что навык приватный - она будет мгновенной.
7. После прохождения модерации нажимаем "Опубликовать".

Теперь наш навык должен появиться в списке навыков при добавлении устройств в Умный дом Яндекса (УДЯ).

• 
  1. Выбираем навык умного дома
• 
  2. Заполняем информацию
• 
  3. Кнопка "Изменить"
• 
  4. Заполняем трансфер до навыка
• 
  5. Навык в списке

Навык создан и работает! Перейти к самому вкусному - настройке.

Настройка навыка и добавление устройств

Первоначальная настройка очень проста. В файле config.py нужно указать префикс пользователя и токен для IFTTT (если он будет использоваться). Кроме того в файле есть строка blynk_ip = "139.59.206.133", которую изначально лучше не трогать, но если Blynk не работает, т.е. устройства не реагируют нужно из своего местоположения (где приложение на смартфоне нормально отрабатывает) сделать ping blynk-cloud.com в командной строке ПК и вписать полученный IP-адрес в значение blynk_ip. Если все работает эту строку лучше не трогать!!! И да на этом по настройке все.

Как редактировать конфиги для добавления устройств

Небольшое отступление.
Добавление устройств в навык происходит посредством прямого редактирования файла devices.txt, который должен находиться в корне репозитория GitHub.
Самый простой способ, который я вижу - это прямое редактирование в GitHub. Для этого нужно:

• Перейти к своему репозиторию
• Нажать файл для редактирования (в нашем случае devices.txt)
• Нажать иконку с карандашом справа сверху
• Отредактировать файл
• Применить изменения кнопкой "Commit changes"
• Подождать ~20-30 сек. Пока изменения применяться в Zeit Now

• 
  Выбираем файл
• 
  Редактируем
• 
  Сохраняем

Добавляем устройства в device.txt

Итак, мы разобрались как редактировать файлы конфига. Теперь отредактируем файл device.txt.
Что нужно знать?

• Одна строка = 1 устройство
• Порядок параметров менять нельзя
• Кавычки - это важно. Если их нет у параметра в примере - это тоже важно!
• Если, что-то не работает - читать с п.1

Формат

Начнем с того, что разберемся, как выглядит одна строка для одного устройства.
Например устройство blynk без запроса статуса:

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Выключатель","blynk","Номер пина V2","токен Blynk","nostatus"

Где:

• "id-устройства" - идентификатор устройства, по которому УДЯ будет их различать. Например, "Blink002"
• "Имя устройства" - Имя, с которым устройство будет отображаться в списке устройств. Например, "Выключатель"
• "Описание" - Описание устройства. Например "Выключатель в комнате через Blynk"
• "Комната" - Название комнаты, к которой относится устройство. Например, "Коридор"
• "Разработчик" - Имя разработчика или компании. Например, "Домашний хэндмэйд".
• "Модель" - модель устройства. Например, "BlNodemcu10"
• "Вер.железа" - Версия сборки. Например "1.0"
• "Вер. софта" - Версия прошивки. Например "2.00.15"
• "Тип" - Тип устройства (как устройство будет определено в УДЯ).

В навыке есть 4 типа устройства:
Выключатель - устройство которое может быть включено или выключено.
Розетка - устройство которое может быть включено или выключено. Но определится как розетка.
Лампа - устройство-лампочка. Определится как лампа и будет иметь настройку яркости (кроме IFTTT).
Другое - другое многофункциональное устройство. Поддерживает некоторые настройки и расширяет возможности, но об этом чуть ниже.

• "blynk" - тип подключения. Есть 3 варианта: "blynk", "ifttt", "any". Где "any" - управление через http-запросы, не подходящие под шаблон blynk и ifttt.

Перечисленные выше параметры по порядку идентичны для всех типов подключений.

• "Номер пина" - Номер виртуального пина blynk. Например "V3"
• "токен Blynk" - Токен от проекта blynk.
• "nostatus" - Параметр запроса статуса устройства. Если "status" - то будем запрашивать текущее состояние устройства, любое другое значение (например "nostatus") - состояние не будет запрашиваться.

В итоге, заполнив вышеуказанный шаблон мы должны получить что то вроде этого:

"UD-001","Выключатель","Выключатель Блинк","Комната","Компания Иванов+","BL100500","2.15","1.12.3","выключатель","blynk","V2","GYgyu7676HoiTig6t76G6t8","nostatus"

Также, для примера разберем, как будет выглядеть устройство "Лампа" управляемое типом "any", шаблон которого выглядит так:

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Лампа","any","ссылка на вкл","ссылка на выкл","status","ссылка на поиск статуса вкл/выкл","строка для поиска","ссылка на управление яркостью, заменить на --val--","ссылка на статус яркости",начальная строка поиска,конечная строка поиска

Предположим, что у нас есть определенный формат http-запроса, где:
http://anuapi.com/value-true - ссылка на включение устройства
http://anuapi.com/value-false - ссылка на выключение устройства
http://anuapi.com/status - ссылка на статус лампочки (включена или нет?), по которому возвращается какой то текст (например: {value:"on"} или {value:"off"})
http://anyapi.com/brigh/?val=50 - ссылка на изменение яркости на значение 50
http://anuapi.com/brigh/status - ссылка возвращающая значение яркости (например строку {value:"70"})
Строка описания устройства будет следующей:

"Noname02","Лампочка","Лампочка в туалете","Туалет","Левша","LampTula1","001","003","Лампа","any","http://anuapi.com/value-true","http://anuapi.com/value-false","status","http://anuapi.com/status","on","http://anyapi.com/brigh/?val=--val--","http://anuapi.com/brigh/status",value:","

в которой после ссылки на запрос статуса вкл/выкл устройства, мы указали строку включенного устройства, которую стоит искать в ответе. В данном случае "on". А в конце нашей строки указаны начальный и конечный шаблон для поиска значения яркости value:",". Что означает искать значение между value:" и между "
Также мы изменили значение 50 в ссылке на тэг --val-- для того, чтобы навык мог понять, в каком месте подставить полученное от УДЯ значение.

Важно! Эти значения записываются без кавычек, т.к. зачастую кавычка - это крайний символ для поиска. Поэтому формат немного отличается.

<button type="button" class="spoilers-button" aria-expanded="false">Все шаблоны можно посмотреть тут</button>

# Без статуса (IFTTT):

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Выключатель","ifttt","хук вкл","хук выкл","nostatus"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Розетка","ifttt","хук вкл","хук выкл","nostatus"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Лампа","ifttt","хук вкл","хук выкл","nostatus"

# Без статуса (Blynk):

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Выключатель","blynk","Номер пина V2","токен Blynk","nostatus"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Розетка","blynk","Номер пина V2","токен Blynk","nostatus"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Лампа","blynk","Номер пина V2","токен Blynk","nostatus","Номер пина яркости V3"

# Без статуса (Any):

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Выключатель","any","ссылка на вкл","ссылка на выкл","nostatus"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Розетка","any","ссылка на вкл","ссылка на выкл","nostatus"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Лампа","any","ссылка на вкл","ссылка на выкл","nostatus","ссылка на управление яркостью, заменить на --val--"

# Со статусом(IFTTT):

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Выключатель","ifttt","хук вкл","хук выкл","status","ссылка на статус","строка для поиска"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Розетка","ifttt","хук вкл","хук выкл","status","ссылка на статус","строка для поиска"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Лампа","ifttt","хук вкл","хук выкл","status","ссылка на статус","строка для поиска"

# Со статусом (Blynk):

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Выключатель","blynk","Номер пина V2","токен Blynk","status"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Розетка","blynk","Номер пина V2","токен Blynk","status"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Лампа","blynk","Номер пина V2","токен Blynk","status","Номер пина яркости V3"

# Со статусом (Any):

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Выключатель","any","ссылка на вкл","ссылка на выкл","status","ссылка на поиск статуса вкл/выкл","строка для поиска"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Розетка","any","ссылка на вкл","ссылка на выкл","status","ссылка на поиск статуса вкл/выкл","строка для поиска"

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Лампа","any","ссылка на вкл","ссылка на выкл","status","ссылка на поиск статуса вкл/выкл","строка для поиска","ссылка на управление яркостью, заменить на --val--","ссылка на статус яркости",начальная строка поиска,конечная строка поиска

# Другое устройство:

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Другое","Имя файла с умениями Пр. other.txt"

Вот так легко можно добавить свои устройства в навык. На самом деле тут нет ничего сложного, главное разобраться в формате записи=)
Да, на данный момент это выглядит "не очень", но дает возможность быстро и без труда заполнить список устройств. Возможно в будущем появится web-интерфейс для заполнения. А пока это тестовый вариант.
После того как вы заполнили все строки для всех устройств, можно сохранить device.txt и проверить в навыке, появились ли устройства. Для этого просто попробуйте их добавить в УДЯ.

Многофункциональное устройство "Другое"

Многофункциональное устройство с типом "Другое" - это отдельный вид устройств в навыке, который дает большие возможности, а именно - задать одному устройству несколько функций (например: выключатель, кнопки и несколько ползунков - яркость, канал, громкость и т.п.)
Для удобства записи функций шаблон такого устройства выглядит так:

"id-устройства","Имя устройства","Описание","Комната","Разработчик","Модель","Вер.железа","Вер.софта","Тип Другое","Имя файла с умениями Пр. other.txt"

Где после типа устройства ("Другое") мы будем использовать новый файл конфига с умениями, который указываем последним параметром в файле device.txt.
В конечном итоге строка для многофункционального устройства может выглядеть так:

"Anylamp-00","Хитрая лампа","Лампа с большими возможностями","Комната","ШизикИнтертейнмент","Alko11","09","03","Другое","anylamp.txt"

Тут мы создаем новый файл конфига для устройства с ID "Anylamp-00" под названием "anylamp.txt", в котором укажем все параметры для нее.
Файл мы также загружаем в корневую директорию репозитория.

Настраиваем "Другое" устройство

Многофункциональное устройство имеет 3 вида умений:

• "on_off" - умение включать/выключать устройство
• "toggle" - умение, при действии на которое можно получить одно текущее значение (например это кнопка)
• "range" - изменение значения от минимального к максимальному и наоборот. Попросту - "ползунок" (например громкости, яркости). - Не работает с IFTTT

Предположим мы создали устройство с типом "Другое", к которому привязали файл конфига "other.txt". Теперь в данном файле (каждая строка - оно умение) создаем умение "on_off" для нашего устройства, которое управляется через blynk и статус нас не интересует. Шаблон будет таким:

"on_off","blynk","Номер пина","токен Blynk","nostatus"

Тут мы указываем тип умения "on_off", тип подключения "blynk", номер виртуального пина, например "V2", токен проекта blynk, что то вроде "GYUgu678T6g67OIjoijo8677tyg", и "nostatus", чтобы отключить статус, как уже писалось выше. В итоге получаем что-то такое:

"on_off","blynk","V2","GYUgu678T6g67OIjoijo8677tyg","nostatus"

Если с умением "on_off" все просто, то с умениями "toggle" и "range" чуть посложнее. Но это и прекрасно, т.к. это дает дополнительные возможности нашему устройству. Конкретно для этих умений Яндекс предлагает список "интенсов", т.е. конкретных указателей на параметры, представляемые в УДЯ для данных умений.
Для "toggle" есть следующие интенты:

• "backlight" - подсветка
• "controls_locked" - блокировка управления
• "ionization" - ионизация
• "keep_warm" - включение поддержания тепла
• "mute" - режим "без звука"
• "oscillation" - включение вращения
• "pause" - пауза

Для "range" такие:

• "brightness" - яркость в %
• "open" - открытие в %
• "humidity" - влажность в %
• "temperature" - температура в градусах цельсия
• "channel" - канал без ед. изм.
• "volume" - громкость без ед. изм.

Рассмотрим на примере как создать умение "range" для управления влажностью. Шаблон выглядит так:

"range","humidity",0,100,10,"any","ссылка на управление", заменить на --val--","status","ссылка на статус",строка поиска начальная,строка поиска конечная

Расшифруем:

• "range" - тип умения
• "humidity" - интенс "Влажность" создаст "ползунок" с единицей измерения в %
• 0 - (без кавычек) - минимальное значение влажности
• 100 - (без кавычек) - максимальное значение влажности
• 10 - (без кавычек) - шаг с которым будут происходить изменения
• "any" - тип подключения нетипизированного http-запроса
• "ссылка на управление" - ссылка типа http://anyapi.com/hum/?val=50, где 50 мы меняем на --val--
• "status" - уже знакомое нам указание на то, что мы хотим получать текущее состояние.
• "ссылка на статус" - ссылка, по которой придет ответ со значением влажности http://anyapi.com/hum/status
• строка поиска начальная - (без кавычек) строка после которой искать значение влажности, например lue:"
• строка поиска конечная - (без кавычек) строка до которой искать значение влажности, например "

В конечном итоге получим что-то такое:

"range","humidity",0,100,10,"any","http://anyapi.com/hum/?val=--val--","status","http://anyapi.com/hum/status",lue:","

<button type="button" class="spoilers-button" aria-expanded="false">Все шаблоны можно посмотреть тут</button>

Без статуса (IFTTT):
"on_off","ifttt","хук вкл","хук выкл","nostatus"
"toggle","backlight","ifttt","хук вкл","nostatus"

Без статуса (Blynk):
"on_off","blynk","Номер пина","токен Blynk","nostatus"
"toggle","backlight","blynk","Номер пина","токен Blynk","nostatus"
"range","humidity",0,100,10,"blynk","Номер пина V3","токен Blynk","nostatus" тут 0 - минимальное значение, 100 - максимальное, 10 - шаг

Без статуса (Any):
"on_off","any","ссылка на вкл","ссылка на выкл","nostatus"
"toggle","backlight","any","ссылка на вкл","nostatus"
"range","brightness",0,100,10,"any","ссылка на управление. заменить на --val--","nostatus"

Со статусом(IFTTT):
"on_off","ifttt","хук вкл","хук выкл","status","ссылка на статус","строка поиска"
"toggle","backlight","ifttt","хук вкл","status","ссылка на статус","строка поиска"

Со статусом (Blynk):
"on_off","blynk","Номер пина","токен Blynk","status"
"toggle","backlight","blynk","Номер пина","токен Blynk","status"
"range","humidity",0,100,10,"blynk","Номер пина V3","токен Blynk","status" тут 0 - минимальное значение, 100 - максимальное, 10 - шаг

Со статусом (Any):
"on_off","any","ссылка на вкл","ссылка на выкл","status","ссылка на статус","строка поиска"
"toggle","backlight","any","ссылка на вкл","status","ссылка на статус","строка поиска"
"range","brightness",0,100,10,"any","ссылка на управление, заменить на --val--","status","ссылка на статус",строка поиска начальная,строка поиска конечная

Для каждого многофункционального устройства нужно создавать файл с умениями, который необходимо загружать в корень репозитория на GitHub, а его имя указывать  device.txt

Послесловие

Еще раз (не устану))) напомню, что навык разрабатывался для себя, для проверки себя и главными критериями было - сервис, на котором можно контролировать работу навыка (поэтому Zeit Now), простота добавления устройств, универсальность.
Некоторые вопросы, которые возможно возникнут и на них есть ответ: В: Почему IFTTT не поддерживает "range"?

О: Во-первых, потому что у IFTTT другой формат передачи value и он пока не укладывался в голове(возможно потом). Во-вторых, в голову пока не пришло устройств, которые бы поддерживали прием вариативных значений по IFTTT, поэтому не увидел смысла.

В: Почему для IFTTT токен задается сразу в config.py, а для blynk в каждом устройстве/умении?
О: Потому что аккаунт IFTTT обычно один, а у Blynk проектов с разными токенами может быть много.

В: Навык определился, но устройства не видны/видны но УДЯ показывает ошибки.
О: Если устройства не видны, то скорей всего вы их неправильно указали в device.txt или не указали вовсе. Совет: перечитать статью и проверить формат записи строк. Если видны, но есть ошибки, то есть смысл попробовать удалить устройство или отвязать и привязать заново аккаунт. Возможно при ваших последних изменениях параметры не прогрузились в УДЯ.

В: Как задается token и code для запросов Яндекса?
О: Токен и код генерируются при запуске сервера. Сделано для удобства.

В: Пытаюсь добавить два интенса яркости, но они не появляются в устройстве.
О: Яндекс позволяет добавить только одно умение с одноименным интенсом. Т.е. Одну "яркость", одну "влажность", один ползунок "громкости".

В: Про формат IFTTT ничего не написал. Что такое "хук вкл","хук выкл" в device.txt?
О: Согласен, упустил. Это названия webhook, которые вы задаете в ifttt. Например "relayON". В остальном принцип схож с шаблонами any. При этом запрос статуса ifttt-устройств происходит через сторонний http-запрос (если таковой имееется)

Ну и наконец, надеюсь, что у вас все получится при создании собственного навыка, а если нет
Буду очень рад обратной связи: e-mail: vkeduardyo@yandex.ru telegram: @Xottabb14