Интеграция с Home Assistant

VibeOS интегрируется с Home Assistant двумя способами:

1. Платформа-шлюз — подписывается на изменения состояний в реальном времени через WebSocket и реагирует на события
2. Инструменты для умного дома — четыре инструмента, вызываемых через LLM, для запросов и управления устройствами через REST API

Настройка

1. Создайте долгоживущий токен доступа

1. Откройте ваш экземпляр Home Assistant
2. Перейдите в Профиль (нажмите на своё имя в боковой панели)
3. Прокрутите до раздела Долгоживущие токены доступа
4. Нажмите Создать токен, дайте ему имя, например «VibeOS»
5. Скопируйте токен

2. Настройте переменные окружения

# Добавьте в ~/.vibeos/.env

# Обязательно: ваш долгоживущий токен доступа
HASS_TOKEN=ваш-долгоживущий-токен-доступа

# Опционально: URL HA (по умолчанию: http://homeassistant.local:8123)
HASS_URL=http://192.168.1.100:8123

к сведению

Набор инструментов homeassistant автоматически включается при установке HASS_TOKEN. И платформа-шлюз, и инструменты управления устройствами активируются от одного этого токена.

3. Запустите шлюз

vibeos gateway

Home Assistant появится как подключённая платформа рядом с другими платформами обмена сообщениями (Telegram, Discord и т. д.).

Доступные инструменты

VibeOS регистрирует четыре инструмента для управления умным домом:

ha_list_entities

Выводит список сущностей Home Assistant, опционально отфильтрованных по домену или зоне.

Параметры:

• domain (опционально) — Фильтр по домену сущности: light, switch, climate, sensor, binary_sensor, cover, fan, media_player и т. д.
• area (опционально) — Фильтр по названию зоны/комнаты (сопоставляется с дружественными именами): living room, kitchen, bedroom и т. д.

Пример:

Перечисли все лампы в гостиной

Возвращает ID сущностей, состояния и дружественные имена.

ha_get_state

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

Параметры:

• entity_id (обязательно) — Сущность для запроса, например light.living_room, climate.thermostat, sensor.temperature

Пример:

Какое текущее состояние climate.thermostat?

Возвращает: состояние, все атрибуты, временные метки последнего изменения/обновления.

ha_list_services

Выводит список доступных сервисов (действий) для управления устройствами. Показывает, какие действия можно выполнять для каждого типа устройств и какие параметры они принимают.

Параметры:

• domain (опционально) — Фильтр по домену, например light, climate, switch

Пример:

Какие сервисы доступны для климатических устройств?

ha_call_service

Вызывает сервис Home Assistant для управления устройством.

Параметры:

• domain (обязательно) — Домен сервиса: light, switch, climate, cover, media_player, fan, scene, script
• service (обязательно) — Имя сервиса: turn_on, turn_off, toggle, set_temperature, set_hvac_mode, open_cover, close_cover, set_volume_level
• entity_id (опционально) — Целевая сущность, например light.living_room
• data (опционально) — Дополнительные параметры в виде JSON-объекта

Примеры:

Включи свет в гостиной
→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")

Установи термостат на 22 градуса в режиме обогрева
→ ha_call_service(domain="climate", service="set_temperature",
    entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})

Установи свет в гостиной синим на 50% яркости
→ ha_call_service(domain="light", service="turn_on",
    entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})

Платформа-шлюз: события в реальном времени

Адаптер шлюза Home Assistant подключается через WebSocket и подписывается на события state_changed. Когда состояние устройства изменяется и соответствует вашим фильтрам, оно передаётся агенту как сообщение.

Фильтрация событий

Обязательная настройка

По умолчанию никакие события не передаются. Вы должны настроить хотя бы один из параметров watch_domains, watch_entities или watch_all, чтобы получать события. Без фильтров при запуске выводится предупреждение, и все изменения состояний молча игнорируются.

Настройте, какие события видит агент, в ~/.vibeos/config.yaml в разделе extra платформы Home Assistant:

platforms:
  homeassistant:
    enabled: true
    extra:
      watch_domains:
        - climate
        - binary_sensor
        - alarm_control_panel
        - light
      watch_entities:
        - sensor.front_door_battery
      ignore_entities:
        - sensor.uptime
        - sensor.cpu_usage
        - sensor.memory_usage
      cooldown_seconds: 30

Параметр	По умолчанию	Описание
watch_domains	(нет)	Отслеживать только эти домены сущностей (например, climate, light, binary_sensor)
watch_entities	(нет)	Отслеживать только эти конкретные ID сущностей
watch_all	false	Установите true, чтобы получать все изменения состояний (не рекомендуется для большинства настроек)
ignore_entities	(нет)	Всегда игнорировать эти сущности (применяется до фильтров по домену/сущности)
cooldown_seconds	30	Минимальное количество секунд между событиями для одной и той же сущности

подсказка

Начните с узкого набора доменов — climate, binary_sensor и alarm_control_panel охватывают наиболее полезные автоматизации. Добавляйте больше по мере необходимости. Используйте ignore_entities, чтобы подавить шумные датчики, такие как температура процессора или счётчики времени работы.

Форматирование событий

Изменения состояний форматируются как удобочитаемые сообщения в зависимости от домена:

Домен	Формат
climate	«Режим HVAC изменён с 'off' на 'heat' (текущая: 21, целевая: 23)»
sensor	«изменилось с 21°C на 22°C»
binary_sensor	«сработал» / «сброшен»
light, switch, fan	«включён» / «выключен»
alarm_control_panel	«состояние сигнализации изменилось с 'armed_away' на 'triggered'»
(другие)	«изменилось с 'old' на 'new'»

Ответы агента

Исходящие сообщения от агента доставляются как постоянные уведомления Home Assistant (через persistent_notification.create). Они появляются на панели уведомлений HA с заголовком «VibeOS».

Управление подключением

• WebSocket с 30-секундным heartbeat для событий в реальном времени
• Автоматическое переподключение с экспоненциальной задержкой: 5с → 10с → 30с → 60с
• REST API для исходящих уведомлений (отдельная сессия для избежания конфликтов WebSocket)
• Авторизация — события HA всегда авторизованы (белый список пользователей не требуется, так как HASS_TOKEN аутентифицирует подключение)

Безопасность

Инструменты Home Assistant применяют ограничения безопасности:

Заблокированные домены

Следующие домены сервисов заблокированы для предотвращения произвольного выполнения кода на хосте HA:

• shell_command — произвольные команды оболочки
• command_line — датчики/переключатели, выполняющие команды
• python_script — выполнение скриптов Python
• pyscript — более широкая интеграция скриптов
• hassio — управление аддонами, выключение/перезагрузка хоста
• rest_command — HTTP-запросы с сервера HA (вектор SSRF)

Попытка вызвать сервисы в этих доменах возвращает ошибку.

ID сущностей проверяются на соответствие шаблону ^[a-z_][a-z0-9_]*\.[a-z0-9_]+$ для предотвращения инъекционных атак.

Примеры автоматизации

Утренняя рутина

Пользователь: Запусти мою утреннюю рутину

Агент:
1. ha_call_service(domain="light", service="turn_on",
     entity_id="light.bedroom", data={"brightness": 128})
2. ha_call_service(domain="climate", service="set_temperature",
     entity_id="climate.thermostat", data={"temperature": 22})
3. ha_call_service(domain="media_player", service="turn_on",
     entity_id="media_player.kitchen_speaker")

Проверка безопасности

Пользователь: Дом в безопасности?

Агент:
1. ha_list_entities(domain="binary_sensor")
     → проверяет датчики дверей/окон
2. ha_get_state(entity_id="alarm_control_panel.home")
     → проверяет статус сигнализации
3. ha_list_entities(domain="lock")
     → проверяет состояния замков
4. Сообщает: «Все двери закрыты, сигнализация в режиме armed_away, все замки заперты.»

Реактивная автоматизация (через события шлюза)

При подключении в качестве платформы-шлюза агент может реагировать на события:

[Home Assistant] Входная дверь: сработал (был сброшен)

Агент автоматически:
1. ha_get_state(entity_id="binary_sensor.front_door")
2. ha_call_service(domain="light", service="turn_on",
     entity_id="light.hallway")
3. Отправляет уведомление: «Входная дверь открыта. Свет в коридоре включён.»

Устранение неполадок

Переменные окружения не подхватываются. Адаптер читает учётные данные из ~/.vibeos/.env (автоматически объединяется при запуске) или из config.yaml. Проверьте, что файл находится в домашней директории активного профиля VibeOS и что вокруг URL/токена нет лишних кавычек. Перезапустите шлюз после редактирования — изменения env применяются только при запуске процесса.

Ошибка аутентификации REST (401 Unauthorized). Токен должен быть долгоживущим токеном доступа, созданным на странице вашего профиля HA (Профиль → Безопасность → Долгоживущие токены доступа). Краткосрочные токены сессии UI не работают. Также убедитесь, что базовый URL включает схему и порт (например, http://homeassistant.local:8123) и доступен с хоста, на котором запущен VibeOS — curl -H "Authorization: Bearer <token>" <url>/api/ должен возвращать {"message": "API running."}.