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

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

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

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

#	Назначение вебхука	URL вебхука	Пример опубликованной ссылки
1	URL авторизации	/modules/yandexhome/authorize.php	https://majordomo.keenetic.pro:8443/modules/yandexhome/authorize.php
2	URL для получения и обновления токена	/modules/yandexhome/token.php	https://majordomo.keenetic.pro:8443/modules/yandexhome/token.php
3	URL обработчика навыка	/modules/yandexhome/smarthome.php	https://majordomo.keenetic.pro:8443/modules/yandexhome/token.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.

---

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

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

Процесс установки отобразится в виде лога. После успешной установки система перенаправит обратно на страницу Маркета дополнений, а в разделе Устройства Панели управления появится новый пункт с модулем 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. Версия аппаратного обеспечения (АО).

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

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

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

---

Дополнительная информация и ссылки

• Обсуждение модуля на Форуме
• Модуль в Connect
• Алиса, включи свет на кухне.
• Алиса, сделай ярче настольную лампу.
• Алиса, измени цвет бра на красный.

---

Поддержать разработку и развитие модуля

---