Интеграция Home Assistant с Алисой через Yandex Dialogs

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

Требования к подключению

Для успешной работы облачной интеграции ваш сервер Home Assistant должен отвечать следующим критериям:

1. Внешний доступ по протоколу HTTPS: Яндекс требует безопасного подключения. Вам понадобится настроить домен (например, через DuckDNS или Nabu Casa) и получить SSL-сертификат Let’s Encrypt.
2. Белый IP-адрес или туннель: Сервер должен быть доступен извне. Если у вас серый IP-адрес, используйте бесплатный инструмент Cloudflare Tunnel.

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

Настройка домена и SSL

Перед тем как переходить к Яндекс Диалогам, убедитесь, что ваш Home Assistant открывается из интернета по адресу вида https://myha.duckdns.org:8123 или https://ha.yourdomain.com. Наличие корректного SSL-сертификата обязательно. Если использовать самоподписанный сертификат, Яндекс выдаст ошибку авторизации. Для проверки откройте адрес на телефоне через мобильную сеть (не Wi-Fi) — сайт должен загружаться без предупреждений безопасности.

Например, в Home Assistant можно установить официальное дополнение DuckDNS, которое автоматически запрашивает и обновляет сертификаты Let’s Encrypt. Вам нужно лишь указать имя вашего субдомена и токен, полученный на сайте DuckDNS. Дополнение само настроит обновление, а вам останется прописать пути к файлам сертификатов в файле configuration.yaml в разделе http:.

Создание навыка в Яндекс Диалогах

Для интеграции вам необходимо создать приватный навык умного дома:

1. Перейдите в кабинет разработчика Яндекс Диалогов и авторизуйтесь под своей учетной записью Яндекса.
2. Нажмите Создать диалог и выберите тип Умный дом.
3. Заполните основные настройки:
   • Название навыка: Любое удобное имя (например, «Мой Дом HA»).
   • Endpoint URL: Адрес вашего сервера с указанием специального вебхука интеграции: https://your-domain.duckdns.org/api/yandex_smart_home.
4. В разделе Авторизация настройте следующие параметры OAuth2:
   • Идентификатор приложения (Client ID): https://social.yandex.net/
   • Секрет приложения (Client Secret): Любой набор символов (не используется интеграцией, но обязателен для заполнения).
   • URL авторизации: https://your-domain.duckdns.org/auth/authorize
   • URL получения токена: https://your-domain.duckdns.org/auth/token
   • URL освежения токена: https://your-domain.duckdns.org/auth/token
5. Сохраните изменения и опубликуйте навык. Публикация приватного навыка занимает несколько минут и не требует прохождения модерации.

Настройка конфигурации в configuration.yaml

Теперь необходимо указать Home Assistant, какие именно устройства нужно передать Яндексу. Для этого отредактируйте файл configuration.yaml вашего сервера, добавив следующий блок настроек:

yandex_smart_home:
  notifier:
    - oauth_token: "YourYandexOAuthTokenHere"
      user_id: "YourYandexUserID"
  filter:
    include_domains:
      - light
      - switch
      - climate
    exclude_entities:
      - switch.system_relay
  entity_config:
    light.living_room:
      name: "Свет в гостиной"
      room: "Гостиная"
      type: devices.types.light
    climate.bedroom_ac:
      name: "Кондиционер"
      room: "Спальня"

После редактирования файла перейдите в панель управления Home Assistant, проверьте конфигурацию на ошибки и перезапустите сервер. В разделе filter: вы также можете использовать списки include_entities, чтобы пробросить только определенные устройства, если не хотите передавать целые домены. Это полезно для больших инсталляций, содержащих сотни технических сущностей (сенсоры заряда батареек, таймштампы обновлений), которые не нужны в Алисе и будут только засорять интерфейс приложения Яндекса.

Связывание аккаунтов

Завершающий этап настройки выполняется на смартфоне:

1. Откройте приложение Дом с Алисой.
2. Нажмите кнопку + (Добавить) -> Устройство умного дома.
3. В списке производителей найдите имя вашего навыка (он будет отмечен иконкой шестеренки или находиться во вкладке тестируемых).
4. Нажмите Привязать к Яндексу. Откроется страница авторизации вашего Home Assistant. Введите логин и пароль пользователя HA.
5. Разрешите доступ. После успешной авторизации запустится поиск устройств. Все сущности, прошедшие фильтр, появятся в приложении.

Если в будущем вы добавите новые устройства в Home Assistant и захотите, чтобы они сразу появились в Алисе, используйте автоматический запуск поиска новых устройств в приложении Яндекса голосовой командой: «Алиса, обнови список устройств умного дома». Это существенно сэкономит время.

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

Возможные проблемы и их решение

1. Ошибка «405 Method Not Allowed» при проверке навыка:

   • Решение: Вы забыли добавить префикс /api/yandex_smart_home к вашему Endpoint URL в Яндекс Диалогах, либо сама интеграция не запущена в Home Assistant.

2. Яндекс не видит новые устройства после их добавления в HA:

   • Решение: По умолчанию список устройств обновляется раз в несколько часов. Чтобы обновить его мгновенно, зайдите в приложение «Дом с Алисой», откройте настройки вашей интеграции и нажмите «Обновить список устройств». Также убедитесь, что вы настроили notifier в YAML-конфигурации для автоматической отправки изменений.

3. Ошибка авторизации при связывании аккаунтов:

   • Решение: Проверьте правильность URL-адресов авторизации в Яндекс Диалогах. Частая ошибка — опечатка в пути /auth/authorize или /auth/token. Также убедитесь, что доменное имя доступно без VPN со стороны серверов Яндекса.