Yandex Home модуль: различия между версиями

Материал из MajorDoMo инфо
(создание новой страницы)
 
 
(не показаны 4 промежуточные версии 2 участников)
Строка 2: Строка 2:


автор: skysilver
автор: skysilver


==Описание==
==Описание==
Строка 8: Строка 7:


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


==Общие сведения==
==Общие сведения==
Строка 14: Строка 13:
Модуль '''Yandex Home''' предназначен для поддержки '''личных''' (приватных) навыков для платформы умного дома '''Яндекс'''.
Модуль '''Yandex Home''' предназначен для поддержки '''личных''' (приватных) навыков для платформы умного дома '''Яндекс'''.


Платформа умного дома '''Яндекс''' имеет открытое [https://tech.yandex.ru/dialogs/alice/doc/smart-home/start-docpage/ API] и позволяет интегрировать '''Яндекс Алису''' с оборудованием сторонних производителей и системами умного дома. Модуль реализует '''авторизационный сервис''' на основе стандарта '''OAuth 2.0''' и '''Provider Adapter API''' - промежуточный API, который принимает на вход запросы в формате платформы умного дома Яндекс и преобразует их в запросы к API '''MajorDoMo'''.
Платформа умного дома '''Яндекс''' имеет открытое [https://tech.yandex.ru/dialogs/alice/doc/smart-home/start-docpage/ '''API'''] и позволяет интегрировать '''Яндекс Алису''' с оборудованием сторонних производителей и системами умного дома. Модуль реализует '''авторизационный сервис''' на основе стандарта '''OAuth 2.0''' и '''Provider Adapter API''' - промежуточный API, который принимает на вход запросы в формате платформы умного дома Яндекс и преобразует их в запросы к API '''MajorDoMo'''.


Особенностью платформы умного дома '''Яндекс'''  является '''новая''' специальная '''категория''' навыков '''Алисы''', которая предназначена для голосового управления домашними устройствами и не требует предварительного запуска навыка по его имени. Теперь устройствами можно управлять прямыми командами вида ''"Алиса, включи свет в гостиной"'', ''"Алиса, сделай в спальне похолоднее"'' и т. п. При этом следует понимать, что в отличие от классических навыков, '''Яндекс''' не передает в '''MajorDoMo''' распознанный текст команды пользователя, а передается непосредственно управляющая команда для устройства, которая интерпретируется модулем и записывается в привязанное свойство объекта.
Особенностью платформы умного дома '''Яндекс'''  является '''новая''' специальная '''категория''' навыков '''Алисы''', которая предназначена для голосового управления домашними устройствами и не требует предварительного запуска навыка по его имени. Теперь устройствами можно управлять прямыми командами вида ''"Алиса, включи свет в гостиной"'', ''"Алиса, сделай в спальне похолоднее"'' и т. п. При этом следует понимать, что в отличие от классических навыков, '''Яндекс''' не передает в '''MajorDoMo''' распознанный текст команды пользователя, а передается непосредственно управляющая команда для устройства, которая интерпретируется модулем и записывается в привязанное свойство объекта.
Строка 32: Строка 31:
В модуле '''Yandex Home''' все обработчики запросов реализованы в виде отдельных файлов: ''authorize.php'', '''token.php''' и '''smarthome.php''', и размещаются в директории ''/modules/yandexhome''.
В модуле '''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
<table>
URL обработчика навыка /modules/yandexhome/smarthome.php https://majordomo.keenetic.pro/modules/yandexhome/smarthome.php
 
<tr>
<th>Назначение вебхука</th>
<th>URL вебхука</th>
<th>Пример опубликованной ссылки</th>
</tr>
 
 
<tr>
<td>URL авторизации</td>
<td>/modules/yandexhome/authorize.php</td>
<td><code>https://majordomo.keenetic.pro/modules/yandexhome/authorize.php</code></td>
</tr>
<tr>
<td>URL для получения и обновления токена</td>
<td>/modules/yandexhome/token.php</td>
<td><code>https://majordomo.keenetic.pro/modules/yandexhome/token.php</code></td>
</tr>
<tr>
<td>URL обработчика навыка</td>
<td>/modules/yandexhome/smarthome.php</td>
<td><code>https://majordomo.keenetic.pro/modules/yandexhome/smarthome.php</code></td>
</tr>
</table>
 
 
 


В конечном итоге '''запуск модуля''' сводится к такой последовательности шагов:
В конечном итоге '''запуск модуля''' сводится к такой последовательности шагов:
Строка 54: Строка 78:
==Поддерживаемые умения==
==Поддерживаемые умения==


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


* Имеется возможность переопределить диапазон значений и шаг изменения.
* Имеется возможность переопределить диапазон значений и шаг изменения.
Строка 76: Строка 172:
3. Валидный '''SSL-сертификат''' на DNS-имя.
3. Валидный '''SSL-сертификат''' на DNS-имя.


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


5. Зарегистрированный и опубликованный приватный навык категории Умный дом.
6. Активное PHP-расширение '''pdo_mysql'''.


6. Активное PHP-расширение pdo_mysql.
Примечание:
Не забывайте в файле config.php исправить/добавить следующие строки для доступа Яндекса к нашим вебхукам:
<pre>// Доступ к этим файлам без пароля
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');  // пароль
}</pre>


==Установка модуля==
==Установка модуля==
Строка 94: Строка 202:
==Настройка модуля==
==Настройка модуля==


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


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3737375f696d6167652e706e67.png|800px|мини|центр|Настройка]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3737375f696d6167652e706e67.png|800px|мини|центр|Настройка]]


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


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


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


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


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


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




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




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


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


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


1 URL авторизации                                       /modules/yandexhome/authorize.php
1 URL авторизации                                       /modules/yandexhome/authorize.php
Строка 126: Строка 234:
3 URL обработчика навыка                               /modules/yandexhome/smarthome.php
3 URL обработчика навыка                               /modules/yandexhome/smarthome.php


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


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


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


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


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


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


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


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


Навыки умного дома - специальная категория навыков Алисы, предназначенных для голосового управления домашними устройствами. Навыки создаются в [https://dialogs.yandex.ru/developer/ консоли разработчика] платформы Яндекс Диалогов.
'''Навыки умного дома''' - специальная категория навыков '''Алисы''', предназначенных для голосового управления домашними устройствами. Навыки создаются в [https://dialogs.yandex.ru/developer/ ''консоли разработчика''] платформы Яндекс Диалогов.


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


1. Настройка связки аккаунтов OAuth 2.0.
1. Настройка связки аккаунтов OAuth 2.0.
Строка 163: Строка 271:
5. Публикация навыка.
5. Публикация навыка.


Чтобы создать новый приватный навык, открываем [https://dialogs.yandex.ru/developer/ консоль разработчика] и авторизуемся под нужной учетной записью.
Чтобы создать новый '''приватный навык''', открываем [https://dialogs.yandex.ru/developer/ '''консоль разработчика'''] и авторизуемся под нужной учетной записью.


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3734395f696d6167652e706e67.png|800px|мини|без|Яндекс диалоги]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3734395f696d6167652e706e67.png|800px|мини|без|Яндекс диалоги]]


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


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735315f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735315f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]
Строка 173: Строка 281:
После чего добавляем новую связку и заполняем ее поля (детальное описание [https://tech.yandex.ru/dialogs/alice/doc/auth/account-linking-docpage/ здесь]).
После чего добавляем новую связку и заполняем ее поля (детальное описание [https://tech.yandex.ru/dialogs/alice/doc/auth/account-linking-docpage/ здесь]).


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


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


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


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


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


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


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


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735305f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735305f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]


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


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735325f696d6167652e706e67.png|800px|мини|центр|Создать диалог]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735325f696d6167652e706e67.png|800px|мини|центр|Создать диалог]]
Строка 201: Строка 309:
Последовательно заполняем поля (детальное описание [https://tech.yandex.ru/dialogs/alice/doc/smart-home/start-docpage/ здесь]).
Последовательно заполняем поля (детальное описание [https://tech.yandex.ru/dialogs/alice/doc/smart-home/start-docpage/ здесь]).


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


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


например, https://majordomo.keenetic.pro:8443/modules/yandexhome/smarthome.php.
например, https://majordomo.keenetic.pro:8443/modules/yandexhome/smarthome.php.
Строка 209: Строка 317:
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735355f696d6167652e706e67.png|800px|мини|центр|Основные настройки]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735355f696d6167652e706e67.png|800px|мини|центр|Основные настройки]]


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


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


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


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


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


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


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


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


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735365f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735365f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]


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


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735375f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735375f696d6167652e706e67.png|800px|мини|центр|Связка аккаунтов]]


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


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735385f696d6167652e706e67.png|800px|мини|центр|Черновик]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735385f696d6167652e706e67.png|800px|мини|центр|Черновик]]
Строка 240: Строка 348:
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735395f696d6167652e706e67.png|800px|мини|центр|Публикация]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3735395f696d6167652e706e67.png|800px|мини|центр|Публикация]]


Опубликованный приватный навык появится в списке навыков умного дома в приложении Яндекс (или в его веб-версии [https://quasar.yandex.ru/skills/iot/ quasar]).
Опубликованный приватный навык появится в списке навыков умного дома в '''приложении Яндекс''' (или в его веб-версии [https://quasar.yandex.ru/skills/iot/ '''quasar''']).


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3736305f696d6167652e706e67.png|800px|мини|центр|Первые шаги]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3736305f696d6167652e706e67.png|800px|мини|центр|Первые шаги]]
Строка 250: Строка 358:
Следующим этапом после регистрации и публикации приватного навыка является '''объединение аккаунтов''' в приложении умного дома '''Яндекс'''. Это - '''завершающий этап по интеграции сторонних систем (и MajorDoMo в частности) с платформой умного дома Яндекс, после которого становится доступным управление устройствами с помощью голосового ассистента Яндекс Алиса'''.
Следующим этапом после регистрации и публикации приватного навыка является '''объединение аккаунтов''' в приложении умного дома '''Яндекс'''. Это - '''завершающий этап по интеграции сторонних систем (и MajorDoMo в частности) с платформой умного дома Яндекс, после которого становится доступным управление устройствами с помощью голосового ассистента Яндекс Алиса'''.


Чтобы объединить аккаунты, с главной страницы приложения (Google Play или App Store) необходимо зайти в раздел '''''Умный дом''''', а затем тапнуть кнопку '''Добавить устройство''', после чего откроется раздел '''''Популярные производители'''''.
Чтобы объединить аккаунты, с главной страницы приложения ([https://play.google.com/store/apps/details?id=ru.yandex.searchplugin Google Play] или [https://itunes.apple.com/ru/app/id1050704155 App Store]) необходимо зайти в раздел '''''Умный дом''''', а затем тапнуть кнопку '''Добавить устройство''', после чего откроется раздел '''''Популярные производители'''''.


[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3736315f696d6167652e706e67.png|800px|мини|центр|Следующий шаг]]
[[Файл:68747470733a2f2f636f6e6e6563742e736d6172746c6976696e672e72752f636d732f646174615f696d616765732f3736315f696d6167652e706e67.png|800px|мини|центр|Следующий шаг]]

Текущая версия от 16:38, 1 мая 2020


автор: 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 и Яндекс Алиса. Алиса, включи канал Карусель.

Источник — https://mdminfo.ru/index.php?title=Yandex_Home_модуль&oldid=948