Многофункциональный навык УДЯ на Zeit Now
Содержание
Внимание! Навык разрабатывался для себя и опубликован как есть. Буду очень рад обратной связи при тестировании и доработках. 100%-ная работа "без сучка и задоринки" не гарантируется =)
Предисловие
Рассмотрим управление устройствами Умного дома Яндекс через http-запросы с помощью собственного приватного навыка. Не стоит пугаться показанного способа, он очень прост.
Да, есть прекрасный навык "Домовенок Кузя", но наш вариант подойдет тем, кто хочет быстро, легко и бесплатно поднять навык собственный, чтобы быть более уверенным в связи Умного дома Яндекса со своими устройствами.
Что может навык?
Навык умеет:
- Управлять устройствами через http-запросы.
- Поддерживать такие типы устройств, как:
- "Выключатель",
- "Розетка",
- "Лампа",
- "Другое" (кастомное многофункциональное устройство).
- Принимать статусы состояния устройств.
Поддерживаются варианты подключения:
- Blynk
- IFTTT, кроме типа значений "Range" ("ползунок")
- Any - устройства, которые управляются http-запросами в разных форматах (вариативно) - Требуется тестирование
Наши действия (для нетерпеливых)
- Заливаем архив с навыком в свой репозиторий github
- Подключаем учетную запись github к Zeit Now
- Создаем навык УДЯ
- Настраиваем файл конфига устройств device.txt
В статье много "начальной" информации; ведь не все, кто столкнулся с УДЯ, сразу имеют нужные знания. Поэтому опишем процесс как можно подробнее. Бывалые могут просто промотать понятные им места)
От слов - к делу!
Регистрируемся на github.com
- Cкачиваем файлы навыка по ссылке.
- Переходим по ссылке регистрации на github.
- Вводим Username (Имя пользователя), Email address (свой e-mail) и password (пароль), и нажимаем кнопку "Create account".
- Выбираем бесплатный аккаунт, нажав кнопку Choose Free.
- Теперь можно выбрать, для чего вы планируете использовать аккаунт (а можно и не выбирать =) ).
- Нажимаем кнопку Complete Setup (появится предложение проверить свой почтовый ящик на наличие письма активации).
- Переходим в почту, нажимаем в письме активации кнопку Verify email address.
- После перехода по ссылке будет предложено создать новый репозиторий. Для этого потребуется:
- придумать и указать имя-ссылку нового репозитория,
- обязательно отметить, что репозиторий приватный (нам же не нужно, чтобы кто то видел наши токены и ссылки на устройства)!
- ...и нажать Create repository.
Репозиторий создан, теперь в него требуется загрузить файлы нашего навыка. Это можно сделать установив git на пк, настроить, и заpushить в свой репозиторий. Шучу. Просто выбираем ссылку uploading an existing file, а потом ссылку choose your files. Загружаем файлы навыка (см иллюстрацию 3).
-
Создаем репозиторий -
Ссылка "uploading an existing file" -
Файлы для загрузки
Регистрируемся на Zeit Now и запускаем сервер
Теперь подключим наш репозиторий к серверу Zeit Now:
- Переходим по ссылке регистрации, и выбираем Continue with GitHub.
- Подключаем репозиторий, нажав на кнопку Authorize Now by ZEIT.
- В следующем окне заполняем требуемые данные и соглашаемся со всем, пока нам не предложат создать проект (Create a new project).
- Выбираем From Git Repository.
- На предложение установить модуль для связи с GitHub жмём Install Now For GitHub и выбираем Only select repositories.
- Из выпадающего списка выбираем свой репозиторий.
- Нажимаем кнопку Install.
- Модуль подключен, осталось создать проект с нашим навыком: нажимаем New Project From GitHub.
- Выбираем репозиторий кнопкой Select и импортируем кнопкой Import.
- Задаём имя проекта (посложнее, чтоб не пересекалось с другими именами проектов Zeit).
- Корневую папку (ROOT) оставляем, как есть.
Если все в порядке, индикатор проекта станет бирюзовым, и появится ссылка на наш навык.
-
Регистрация в Zeit Now -
From Git Repository -
From Git Repository -
Импортируем репозиторий -
Задаем имя проекта -
Индикатор проекта и ссылка на навык
Создаем приватный навык УДЯ
Для создания навыка УДЯ перейдём в кабинет разработчика платформы Диалогов.
- Жмём большую кнопку "Создать навык", выбираем тип навыка "Умный дом".
- Заполняем информацию о навыке (см рис 2, 3, 4), где:
- Endpoint URL - Url из раздела DOMAINS в кабинете ZEIT. При этом обязательно ставим https:// в начале.
- "Не показывать в каталоге" - ставим галочку (чтобы обойтись без долгой модерации, а сам навык не попал в общий каталог).
- Нажав кнопку "Изменить", указываем:
- Идентификатор приложения - любая строка (можно пару раз упасть головой на клавиатуру);
- Секрет приложения - поступаем так же;
- URL авторизации - ссылка, которую указывали в Endpoint URL
- URL для получения токена - ссылка вида: https://ссылка_навыка/token
- URL для обновления токена - ссылка вида: https://ссылка_навыка/refresh
- Идентификатор группы действий - read,home:lights
- Нажимаем "Сохранить" в окне "Создание связки аккаунтов" и в настройках нашего навыка.
- Подтверждаем указанную нами электронную почту;
- Подать навык на модерацию. Если не забыли указать, что навык приватный - она будет мгновенной.
- После прохождения модерации нажимаем "Опубликовать".
Теперь наш навык должен появиться в списке навыков при добавлении устройств в Умный дом Яндекса (УДЯ).
-
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--","ссылка на статус яркости",начальная строка поиска,конечная строка поиска,250
Предположим, что у нас есть определенный формат 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"})
250 - максимальный предел уровня яркости на устройстве (для некоторых светодиодных лент удобнее использовать не 100%, а уровень 255)
Строка описания устройства будет следующей:
"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:",",250
в которой после ссылки на запрос статуса вкл/выкл устройства, мы указали строку включенного устройства, которую стоит искать в ответе. В данном случае "on". А в конце нашей строки указаны начальный и конечный шаблон для поиска значения яркости value:",". Что означает искать значение между value:" и между "
Также мы изменили значение 50 в ссылке на тэг --val-- для того, чтобы навык мог понять, в каком месте подставить полученное от УДЯ значение.
Важно! Эти значения записываются без кавычек, т.к. зачастую кавычка - это крайний символ для поиска. Поэтому формат немного отличается.
Вот так легко можно добавить свои устройства в навык. На самом деле тут нет ничего сложного, главное разобраться в формате записи=)
Да, на данный момент это выглядит "не очень", но дает возможность быстро и без труда заполнить список устройств. Возможно в будущем появится 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
- "color_setting" - управление RGB. - Не работает с IFTTT, для ANY не поддерживается обработка статуса
Предположим мы создали устройство с типом "Другое", к которому привязали файл конфига "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","ссылка на статус",строка поиска начальная,строка поиска конечная,150
Расшифруем:
- "range" - тип умения
- "humidity" - интенс "Влажность" создаст "ползунок" с единицей измерения в %
- 0 - (без кавычек) - минимальное значение влажности
- 100 - (без кавычек) - максимальное значение влажности
- 10 - (без кавычек) - шаг с которым будут происходить изменения
- "any" - тип подключения нетипизированного http-запроса
- "ссылка на управление" - ссылка типа http://anyapi.com/hum/?val=50, где 50 мы меняем на --val--
- "status" - уже знакомое нам указание на то, что мы хотим получать текущее состояние.
- "ссылка на статус" - ссылка, по которой придет ответ со значением влажности http://anyapi.com/hum/status
- строка поиска начальная - (без кавычек) строка после которой искать значение влажности, например lue:"
- строка поиска конечная - (без кавычек) строка до которой искать значение влажности, например "
- 150 - (без кавычек) - максимальное значение влажности на устройстве (если нужно маппить значения и они разняться с максимальными в УДЯ)
В конечном итоге получим что-то такое:
"range","humidity",0,100,10,"any","http://anyapi.com/hum/?val=--val--","status","http://anyapi.com/hum/status",lue:",",150
Также рассмотрим, как создать умение "color_setting" для управления RGB-подсветкой для устройства со сторонним api. Шаблон выглядит так:
"color_setting",255,255,255,"any","ссылка на управление. заменить значение red на --vr-- значение green на --vg-- значение blue на --vb--","nostatus"
Расшифруем:
- "color_setting" - тип умения
- 255 - (без кавычек) - максимальное значение красного цвета (на случай, если не 255, а 100. Вдруг у кого то другие значения, как у меня для понижения расхода питания)
- 255 - (без кавычек) - максимальное значение зеленого цвета (на случай, если не 255)
- 255 - (без кавычек) - максимальное значение синего цвета (на случай, если не 255)
- "any" - тип подключения нетипизированного http-запроса
- "ссылка на управление" - ссылка типа http://anyapi.com/hum/?val=50&val=150&val=100, где 50 мы меняем на --vr--, 150 мы меняем на --vg--, 100 мы меняем на --vb-- (r,g,b)
- "nostatus" - указание на то, что мы не хотим получать текущее состояние.
В конечном итоге получим что-то такое:
"color_setting",255,255,255,"any","http://anyapi.com/hum/?val=50&val=150&val=100","nostatus"
Для каждого многофункционального устройства нужно создавать файл с умениями, который необходимо загружать в корень репозитория на 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