Yandex Home модуль

автор: skysilver

Описание

Модуль Yandex Home

Установка модуля

Установка осуществляется через Маркет дополнений

Общие сведения

Модуль Yandex Home предназначен для поддержки личных (приватных) навыков для платформы умного дома Яндекс.

Платформа умного дома Яндекс имеет открытое API и позволяет интегрировать Яндекс Алису с оборудованием сторонних производителей и системами умного дома. Модуль реализует авторизационный сервис на основе стандарта OAuth 2.0 и Provider Adapter API - промежуточный API, который принимает на вход запросы в формате платформы умного дома Яндекс и преобразует их в запросы к API MajorDoMo.

Особенностью платформы умного дома Яндекс является новая специальная категория навыков Алисы, которая предназначена для голосового управления домашними устройствами и не требует предварительного запуска навыка по его имени. Теперь устройствами можно управлять прямыми командами вида "Алиса, включи свет в гостиной", "Алиса, сделай в спальне похолоднее" и т. п. При этом следует понимать, что в отличие от классических навыков, Яндекс не передает в MajorDoMo распознанный текст команды пользователя, а передается непосредственно управляющая команда для устройства, которая интерпретируется модулем и записывается в привязанное свойство объекта.

Модуль реализует классическую концепцию MajorDoMo для взаимодействия с пользователем через метрики и привязанные к ним свойства объекта. К метрикам привязываются уже существующие объекты и свойства, через которые реализовано управление устройствами.

Обсуждение модуля на Форуме.

Исходный код модуля на Github.

Модуль в Connect.

Module yandexhome

Для успешного функционирования модуля и управления устройствами, подключенными к MajorDoMo, через ассистента Яндекс Алиса требуется, в первую очередь, опубликовать обработчики запросов (конечные точки, вебхуки) в сеть Интернет и обеспечить тем самым их доступность со стороны облака Яндекс по доменному имени (DNS) и протоколу HTTPS. Во вторую очередь, необходимо в консоли разработчика платформы Яндекс Диалогов создать, настроить и опубликовать приватный навык специальной категории Умный дом.

В модуле Yandex Home все обработчики запросов реализованы в виде отдельных файлов: authorize.php, token.php и smarthome.php, и размещаются в директории /modules/yandexhome.

Назначение вебхука	URL вебхука	Пример опубликованной ссылки
URL авторизации	/modules/yandexhome/authorize.php	https://majordomo.keenetic.pro/modules/yandexhome/authorize.php
URL для получения и обновления токена	/modules/yandexhome/token.php	https://majordomo.keenetic.pro/modules/yandexhome/token.php
URL обработчика навыка	/modules/yandexhome/smarthome.php	https://majordomo.keenetic.pro/modules/yandexhome/smarthome.php

В конечном итоге запуск модуля сводится к такой последовательности шагов:

1. Установка модуля из маркета дополнений.

2. Настройка модуля.

3. Публикация обработчиков запросов.

4. Регистрация приватного навыка.

5. Объединение аккаунтов в приложении Яндекс.

6. Добавление и управление устройствами в модуле

Поддерживаемые умения

#	Метрика (умение)	Описание	Значения в модуле	Значения от Яндекс
1	on	Включить/выключить (1 - включено, 0 выключено).	1 и 0	true и false
2	volume	Громкость (проценты).	1 - 100 (*)	1 - 100, либо +1/-1
3	channel	ТВ-канал.	№ канала (*)	№ канала, либо +1/-1
4	temperature	Температура (градусы цельсия).	1 - 100 (*)	°C
5	temperature_k	Температура цвета (кельвины).	2700 - 9000	2700 - 9000
6	thermostat	Температурный режим.	auto, heat, cool, eco, dry, fan_only	auto, heat, cool, eco, dry, fan_only
7	mute	Режим без звука (1 - включено, 0 выключено).	1 и 0	true и false
8	fan_speed	Скорость вентиляции.	auto, low, medium, high	auto, low, medium, high
9	rgb	Цвет в формате RGB (hex).	000000 - FFFFFF	0 - 16777215
10	brightness	Яркость (проценты).	1 - 100 (*)	1 - 100

• Имеется возможность переопределить диапазон значений и шаг изменения.

Требования

1. Публичный (глобальный, белый) IP-адрес, выдаваемый интернет-провайдером.

2. Доменное имя (DNS), привязанное к публичному IP-адресу.

3. Валидный SSL-сертификат на DNS-имя.

4. Опубликованные в Интернет обработчики запросов (без требования ввода логина и пароля).

5. Зарегистрированный и опубликованный приватный навык категории Умный дом.

6. Активное PHP-расширение pdo_mysql.

Примечание: Не забывайте в файле config.php исправить/добавить следующие строки для доступа Яндекса к нашим вебхукам:

// Доступ к этим файлам без пароля
if (!(preg_match('/\/authorize\.php/is', $_SERVER['REQUEST_URI']) ||
      preg_match('/\/token\.php/is', $_SERVER['REQUEST_URI']) ||
      preg_match('/\/smarthome\.php/is', $_SERVER['REQUEST_URI'])))
{
   Define('HOME_NETWORK', '192.168.0.*');      // домашняя сетка (доступ без пароля)
   Define('EXT_ACCESS_USERNAME', 'admin');     // имя 
   Define('EXT_ACCESS_PASSWORD', 'password');  // пароль
}

Установка модуля

Чтобы установить модуль, нужно в Панели управления MajorDoMo перейти в раздел Система и открыть Маркет дополнений. Модуль находится в категории Взаимодействие. Открываем эту вкладку и ищем в списке строку с модулем. Для установки нажимаем кнопку Добавить.

рис 1

Процесс установки отобразится в виде лога. После успешной установки система перенаправит обратно на страницу Маркета дополнений, а в разделе Устройства Панели управления появится новый пункт с модулем Yandex Home.

Установка

Настройка модуля

Настройка модуля заключается в генерации значений OAuth2 ID и OAuth2 KEY с помощью соответствующей кнопки, а также ввод произвольных логина и пароля пользователя, которые впоследствии будут запрошены в ходе объединения аккаунтов в приложении Яндекс.

Настройка

На ранних этапах использования модуля рекомендуется включить ведение логов событий - Отладка DebMes.

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

Публикация обработчиков запросов

Механизм взаимодействия платформы умного дома Яндекс со сторонними системами (провайдерами) реализуется посредством вебхуков (webhook). Облако Яндекс для запроса состояния устройств и управления ими посылает POST- и GET- запросы на конечные точки (endpoint) вебхуков и получает ответы от них. Таким образом, для корректной работы этого механизма необходимо обеспечить постоянную доступность вебхуков из сети Интернет со стороны облака Яндекс.

Согласно API платформы умного дома Яндекс требуется реализовать три типа конечных точек:

1. URL авторизации (authorization endpoint) - страница, на которой авторизуется пользователь, чтобы разрешить навыку доступ к своему аккаунту.

2. URL для получения и обновления токена (token endpoint) - адрес, на который отправляются запросы с авторизационным кодом, чтобы получить OAuth-токен доступа, и запросы для обновления ранее полученного токена.

3. URL обработчика навыка (smarthome endpoint) - основной вебхук, который отвечает непосредственно за работу с устройствами.

В модуле Yandex Home все три типа конечных точек реализованы в виде отдельных файлов: authorize.php, token.php и smarthome.php, размещаемых в директории /modules/yandexhome.

# Назначение вебхука URL вебхука

1 URL авторизации /modules/yandexhome/authorize.php

2 URL для получения и обновления токена /modules/yandexhome/token.php

3 URL обработчика навыка /modules/yandexhome/smarthome.php

Чтобы опубликовать эти три вебхука в сеть Интернет и обеспечить тем самым их доступность со стороны облака Яндекс, необходимо выполнить ряд условий.

Условие №1. Публичный (глобальный, белый) IP-адрес, выдаваемый интернет-провадером.

Белый IP-адрес при этом может быть как статическим, так и динамическим. В случаях, когда невозможно получить белый адрес у интернет-провайдера, возможны варианты использования сторонних сервисов. Например, некоторые производители роутеров предоставляют их владельцам сервис по доступу к ресурсам домашней локальной сети (KeenDNS от Keenetic и др). Либо использовать VPN-сервисы на подобие vpnki.ru или собственный VPN-сервер, развернутый на VPS.

Условие №2. Доменное имя (DNS), привязанное к публичному IP-адресу.

Это требование в большинстве случаев закрывается классическими сервисами динамических DNS, которых представлено в сети в большом ассортименте, как платных, так и бесплатных. Большинство современных роутеров уже имеют встроенную поддержку сервисов Dynamic DNS. При использовании сервисов удаленного доступа типа KeenDNS или VPNKI это условие выполняется автоматически - доменное имя выбирается и присвается в ходе регистрации и подключения услуги.

Условие №3. Валидный SSL-сертификат на DNS-имя.

По требованиям платформы умного дома Яндекс весь обмен трафиком между их облаком и MajorDoMo должен идти в зашифрованном виде по протоколу HTTPS, что обеспечивается либо установкой SSL-сертификата на веб-сервер с MajorDoMo, либо услугами сервисов удаленного доступа (см. выше). Бесплатный SSL-сертификат можно получить у удостоверяющего центра Let’s Encrypt сроком на 3 месяца, затем его нужно будет регулярно обновлять. Сертификат устанавливается либо на тот же виртуальный сервер Apache, который обслуживает MajorDoMo, либо на отдельный виртуальный сервер (Apache или Nginx), выступающий в роли обратного прокси (reverse proxy) для MajorDoMo.

Корректность установки сертификата и доступность вашего сервера из сети Интернет по HTTPS можно проверить с помощью специализированных сервисов, например:

https://ssllabs.com/ssltest/analyze.html https://www.geocerts.com/ssl-checker https://www.digicert.com/help/ https://www.sslshopper.com/ssl-checker.html

Регистрация приватного навыка

Навыки умного дома - специальная категория навыков Алисы, предназначенных для голосового управления домашними устройствами. Навыки создаются в консоли разработчика платформы Яндекс Диалогов.

Основные шаги по созданию навыка это:

1. Настройка связки аккаунтов OAuth 2.0.

2. Добавление навыка и выбор его типа.

3. Заполнение информационных полей.

4. Модерация навыка.

5. Публикация навыка.

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

Яндекс диалоги

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

Связка аккаунтов

После чего добавляем новую связку и заполняем ее поля (детальное описание здесь).

- Название - понятное вам название связки.

- Идентификатор приложения - значение OAuth2 ID из настроек модуля Yandex Home.

- Секрет приложения - значение OAuth2 KEY из настроек модуля Yandex Home.

- URL авторизации - адрес вебхука авторизации (см. предыдущую статью), например, - https://majordomo.keenetic.pro:8443/modules/yandexhome/authorize.php

- URL для получения токена - адрес вебхука получения токена (см. предыдущую статью), например, https://majordomo.keenetic.pro:8443/modules/yandexhome/token.php

- URL для обновления токена - тот же самый, что и пунктом выше, например, https://majordomo.keenetic.pro:8443/modules/yandexhome/token.php

- Идентификатор группы действий - оставляем пустым.

- Идентификатор OAuth приложения - оставляем пустым.

Связка аккаунтов

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

Создать диалог

Тип навыка выбираем Умный дом.

Тип диалога

Последовательно заполняем поля (детальное описание здесь).

- Название - указываем название навыка.

- Endpoint URL - адрес вебхука обработчика навыка (см. предыдущую статью),

например, https://majordomo.keenetic.pro:8443/modules/yandexhome/smarthome.php.

Основные настройки

- Приватность - обязательно ставим галочку Не показывать в каталоге.

- Подзаголовок - пишем краткое описание навыка.

- Имя разработчика - фамилия, имя.

- E-mail разработчика - пишем аккаунт Яндекс.Почты.

- Сайт для верификации прав использования бренда - оставляем пустым.

- Описание - произвольное описание нашего навыка.

- Заметки для модератора - оставляем пустым.

- Иконка - логотип навыка в формате PNG или JPG.

Связка аккаунтов

- Связка аккаунтов - в выпадающем списке выбрать ранее созданную связку.

Связка аккаунтов

Сохраняем изменения, после чего становится активной кнопка На модерацию. Кликаем на нее и отправляем наш навык на модерацию. На сегодняшний день модерация автоматическая и происходит мгновенно.

Черновик

После модерации остается завершающий этап - публикация навыка. Нажимаем кнопку ОпубликоватьКурсивное начертание и на главной странице консоли разработчика видим, что навык сменил статус и переместился в раздел Опубликованные.

Публикация

Опубликованный приватный навык появится в списке навыков умного дома в приложении Яндекс (или в его веб-версии quasar).

Первые шаги

На следующем шаге можно приступать к объединению аккаунтов.

Объединение аккаунтов в приложении Яндекс

Следующим этапом после регистрации и публикации приватного навыка является объединение аккаунтов в приложении умного дома Яндекс. Это - завершающий этап по интеграции сторонних систем (и MajorDoMo в частности) с платформой умного дома Яндекс, после которого становится доступным управление устройствами с помощью голосового ассистента Яндекс Алиса.

Чтобы объединить аккаунты, с главной страницы приложения (Google Play или App Store) необходимо зайти в раздел Умный дом, а затем тапнуть кнопку Добавить устройство, после чего откроется раздел Популярные производители.

Следующий шаг

В списке производителей выбираем наш приватный навык и тапаем кнопку Объединить аккаунты. Приложение переадресует на страницу авторизации навыка, на которой нужно ввести логин пользователя и пароль пользователя, указанные ранее в настройках модуля Yandex Home. После успешной авторизации подтверждаем сопряжение кнопкой Предоставить.

Следующий шаг

Приложение переадресует обратно на страницу свойств навыка, а кнопка Объединить аккаунты изменится на Обновить список устройств. Тапаем на нее и после успешной синхронизации будет предложено перейти на страницу со списком устройств. Если в этот момент в модуле Yandex Home уже были добавлены устройства, то они отобразятся в приложении. В дальнейшем при добавлении устройств в модуле или изменении их свойств необходимо каждый раз выполнять такую синхронизацию для обновления списка устройств в приложении Яндекс.

Следующий шаг

Добавление и управление устройствами в модуле

Модуль реализует классическую концепцию MajorDoMo для взаимодействия с пользователем через метрики и привязанные к ним свойства объекта. К метрикам (умениям) привязываются уже существующие объекты и свойства, через которые реализовано управление устройствами. К каждому умению устройства можно привязать свое свойство объекта.

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

Настройка

Дальнейшее конфигурирование выполняется на странице редактирования (настройки) устройства.

Конфигурирование

Настройка устройств

Обязательные для заполнения поля устройства:

1. Название.

2. Тип.

3. Местоположение.

4. Умения.

У каждого устройства должно быть указано минимум одно умение.

Не обязательные для заполнения поля устройства:

1. Описание.

2. Производитель.

3. Модель.

4. Версия программного обеспечения (ПО).

5. Версия аппаратного обеспечения (АО).

Описание полей

Набор умений представлен в виде выпадающего списка.

Набор умений

Привязка свойства объекта к конкретному умению выполняется также с помощью выпадающих списков.

Привязка свойств

При добавлении устройств в модуле или изменении их свойств для обновления списка устройств в приложении Яндекс необходимо каждый раз выполнять синхронизацию с помощью кнопки Обновить список устройств в окне свойств навыка. Удаляются устройства из приложения Яндекс вручную, либо через отвязывание аккаунта и последующее повторное объединение аккаунтов.

Документация по модулю

1. MajorDoMo и Яндекс Алиса. Общие сведения.

2. MajorDoMo и Яндекс Алиса. Публикация вебхуков.

3. MajorDoMo и Яндекс Алиса. Регистрация приватного навыка.

4. MajorDoMo и Яндекс Алиса. Объединение аккаунтов.

5. MajorDoMo и Яндекс Алиса. Модуль Yandex Home.

6. MajorDoMo и Яндекс Алиса. Алиса, включи свет на кухне.

7. MajorDoMo и Яндекс Алиса. Алиса, сделай ярче настольную лампу.

8. MajorDoMo и Яндекс Алиса. Алиса, измени цвет бра на красный.

9. MajorDoMo и Яндекс Алиса. Алиса, включи канал Карусель.