home-assistant-tools/README.md

Home Assistant Tools for Open WebUI

Инструменты для управления умным домом через Home Assistant REST API с интерпретацией естественного языка.

Возможности

Управление (smart)

• Свет (вкл/выкл, яркость, цветовая температура)
• Розетки, реле, выключатели
• Климат (температура, режимы нагрев/охлаждение)
• Медиа (плей/пауза, громкость, переключение треков)
• Шторы и жалюзи
• Замки
• Вентиляторы
• Роботы-пылесосы
• Кнопки (button.press)
• Сцены (scene.turn_on) и скрипты
• Переименование сущностей (NL: «переименуй сертификат в Обновление SSL»)
• Включение/выключение автоматизаций (NL: «выключи автоматизацию Гирлянда»)

Мониторинг (smart — ответы на вопросы)

• Какие окна/двери открыты (с показом «Неизвестно»)
• Что горит лишнего
• Какая температура в комнатах (только реальные термометры)
• Качество воздуха (TVOC, CO2, PM2.5/10, влажность)
• Где есть движение прямо сейчас
• Какие батарейки садятся
• Что сейчас играет
• Кто дома
• Что в розетках включено
• Системный статус (бэкапы, обновления, ноды, мосты)
• Общий отчёт одной фразой

Диагностика (list_devices)

• Полный список устройств по доменам
• Фильтр по device_class (door, window, motion, battery, ...)
• Фильтр по состоянию (on, off, open, closed, unavailable, ...)
• Скрытие unavailable / unknown
• Спецкатегория domain="window_door" для окон и дверей (строгий фильтр)
• NL-маршрутизация: «покажи все binary_sensor» → list_devices(domain="binary_sensor")

Управление автоматизациями (отдельные инструменты)

• rename_entity — переименовать любую сущность
• toggle_automation — включить/выключить автоматизацию
• trigger_automation — запустить автоматизацию вручную

Установка

Просто скопировать

1. Открой файл в Gitea:
   https://gitea.nasweb.ru/host/home-assistant-tools/src/branch/main/home_assistant_tools.py

2. Нажми кнопку Raw (справа вверху) — откроется plain text

3. Скопируй всё (Ctrl+A → Ctrl+C)

4. В Open WebUI: Workspace → Tools → + Новый инструмент

5. Вставь код (Ctrl+V или долгое нажатие → "Вставить") и сохрани

Создание токена Home Assistant

1. Откройте HA (https://ha.nasweb.ru) → Профиль (левый нижний угол)
2. Прокрутите вниз до Long-Lived Access Tokens
3. Create Token, имя — open-webui
4. Скопируйте токен (покажется один раз)

Настройка Valves

После импорта инструмента откройте его настройки (⚙️) и укажи:

Параметр	Значение	По умолчанию
ha_url	URL вашего HA	https://ha.nasweb.ru
ha_token	Long-Lived Token из шага выше	(пусто)
verify_ssl	Проверять SSL: false для самоподписанных	false
request_timeout	Таймаут HTTP, сек	10
max_retries	Количество ретраев	2
cache_ttl	TTL кэша состояний, сек	5
confirm_global_actions	Спрашивать подтверждение для «выключи весь свет»	true
dry_run	Только показывать, не выполнять	false

Включение для пользователя

Open WebUI → Settings → Interface → Tools → включите Home Assistant Smart Control.

Примеры команд

Управление

включи свет в спальне
выключи весь свет
поставь 23 градуса в детской
открой шторы в гостиной
пауза музыки
громче
запусти сцену вечерний отдых
включи свет на 50%
уютный свет в спальне
нажми кнопку в спальне

Управление автоматизациями

переименуй сертификат в Обновление SSL
переименуй automation.сертификат в Обновление SSL
выключи автоматизацию Гирлянда крыльцо
включи автоматизацию Свет в спальне
триггерни автоматизацию Вентиляция душевая

Мониторинг

какие окна открыты?
что горит лишнего?
какая температура в спальне?
как воздух в квартире?
где сейчас движение?
батарейки садятся?
кто дома?
что в розетках включено?
как система? есть обновления?
что сейчас играет?
отчёт по дому

Диагностика (отдельный инструмент list_devices)

LLM может вызвать инструмент list_devices с параметрами, например:

list_devices()                                    # все устройства
list_devices(domain="binary_sensor")               # все бинарные датчики
list_devices(domain="window_door")                 # только окна/двери
list_devices(device_class="battery")               # только батарейки
list_devices(only_with_state="unavailable")        # все offline
list_devices(show_unavailable=False)               # скрыть offline

Или попросить LLM в чате:

покажи все binary_sensor
список устройств
какие устройства есть в HA?

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

• Токен HA хранится в Valves Open WebUI, не в коде
• Глобальные команды («выключи весь свет») требуют подтверждения
• Ошибки на одной сущности не валят весь сценарий
• HTTP-запросы с ретраями и таймаутами
• Поддержка HTTPS с опцией отключения проверки сертификата

Версионирование

• v2.5.2 — фикс порядка блоков («батарейки» → в батареи, не в климат), фикс форматирования state+unit, список «Неизвестно», мониторинг розеток, системный статус (бэкапы/обновления), поддержка scene
• v2.5.1 — строгий фильтр окон/дверей только по device_class
• v2.5.0 — rename_entity, toggle_automation, trigger_automation + NL-маршрутизация
• v2.4.0 — мониторинг воздуха (TVOC, CO2, влажность), движения, исправлен баг батареек, маршрутизация «покажи» в list_devices, поддержка кнопок, общий «отчёт»
• v2.3.0 — добавлен инструмент list_devices для диагностики и инвентаризации
• v2.2.2 — восстановлен полный код после повреждения при обновлении
• v2.2.1 — HTTPS по умолчанию, verify_ssl в Valves
• v2.2.0 — мониторинг (окна, свет, климат, батарейки, медиа, присутствие), dry-run, ретраи, кэш
• v2.0.0 — базовое управление светом, климатом, медиа, шторами

Лицензия

MIT