148 lines
6.7 KiB
Markdown
148 lines
6.7 KiB
Markdown
# Home Assistant Tools for Open WebUI
|
||
|
||
Инструменты для управления умным домом через Home Assistant REST API с интерпретацией естественного языка.
|
||
|
||
## Возможности
|
||
|
||
### Управление (`smart`)
|
||
- Свет (вкл/выкл, яркость, цветовая температура)
|
||
- Розетки, реле, выключатели
|
||
- Климат (температура, режимы нагрев/охлаждение)
|
||
- Медиа (плей/пауза, громкость, переключение треков)
|
||
- Шторы и жалюзи
|
||
- Замки
|
||
- Вентиляторы
|
||
- Роботы-пылесосы
|
||
- **Кнопки** (button.press)
|
||
- Сценарии и скрипты
|
||
|
||
### Мониторинг (`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")`
|
||
|
||
## Установка
|
||
|
||
### Просто скопировать
|
||
|
||
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%
|
||
уютный свет в спальне
|
||
нажми кнопку в спальне
|
||
```
|
||
|
||
### Мониторинг
|
||
```
|
||
какие окна открыты?
|
||
что горит лишнего?
|
||
какая температура в спальне?
|
||
как воздух в квартире?
|
||
где сейчас движение?
|
||
батарейки садятся?
|
||
кто дома?
|
||
что сейчас играет?
|
||
отчёт по дому
|
||
```
|
||
|
||
### Диагностика (отдельный инструмент `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
|
||
list_devices(domain="binary_sensor", show_unavailable=False)
|
||
```
|
||
|
||
Или попросить LLM в чате:
|
||
```
|
||
покажи все binary_sensor
|
||
список устройств
|
||
какие устройства есть в HA?
|
||
```
|
||
|
||
## Безопасность
|
||
|
||
- Токен HA хранится в **Valves** Open WebUI, не в коде
|
||
- Глобальные команды («выключи весь свет») требуют подтверждения
|
||
- Ошибки на одной сущности не валят весь сценарий
|
||
- HTTP-запросы с ретраями и таймаутами
|
||
- Поддержка HTTPS с опцией отключения проверки сертификата
|
||
|
||
## Версионирование
|
||
|
||
- **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 |