Добавлена полная документация

2026-07-29 18:51:17 +03:00
parent ae514137d7
commit 55a34feda4
1 changed files with 109 additions and 2 deletions
@@ -1,3 +1,110 @@
-# home-assistant-tools
+# Home Assistant Tools for Open WebUI

-Инструменты Open WebUI для управления Home Assistant через REST API: умное управление домом и мониторинг состояний на естественном языке.
+Инструменты для управления умным домом через Home Assistant REST API с интерпретацией естественного языка.
+
+## Возможности
+
+### Управление
+- Свет (вкл/выкл, яркость, цветовая температура)
+- Розетки и выключатели
+- Климат (температура, режимы нагрев/охлаждение)
+- Медиа (плей/пауза, громкость, переключение треков)
+- Шторы и жалюзи
+- Замки
+- Вентиляторы
+- Роботы-пылесосы
+- Сценарии и скрипты
+
+### Мониторинг (ответы на вопросы)
+- Какие окна/двери открыты
+- Что горит лишнего
+- Какая температура в комнатах
+- Какие батарейки садятся
+- Что сейчас играет
+- Кто дома
+
+## Установка
+
+### 1. Скачайте файл
+
+```bash
+curl -sSL https://gitea.nasweb.ru/host/home-assistant-tools/raw/branch/main/home_assistant_tools.py -o home_assistant_tools.py
+```
+
+### 2. Создайте Long-Lived Access Token в Home Assistant
+
+1. Откройте HA → **Профиль** (левый нижний угол)
+2. Прокрутите вниз до **Long-Lived Access Tokens**
+3. Нажмите **Create Token**, дайте имя (например `open-webui`)
+4. **Скопируйте токен** — он покажется только один раз
+
+### 3. Узнайте URL вашего Home Assistant
+
+- HAOS VM на Proxmox → `http://192.168.31.X:8123`
+- Если HA в Docker → `http://<ip>:8123`
+
+### 4. Установите инструмент в Open WebUI
+
+1. Откройте Open WebUI → **Workspace → Tools**
+2. Нажмите **+ Create Tool**
+3. Скопируйте содержимое `home_assistant_tools.py` в редактор
+4. Сохраните
+
+### 5. Настройте Valves
+
+В настройках инструмента укажите:
+
+| Параметр | Значение |
+|---|---|
+| `ha_url` | `http://192.168.31.X:8123` |
+| `ha_token` | ваш Long-Lived Token |
+| `request_timeout` | `10` (по умолчанию) |
+| `max_retries` | `2` (по умолчанию) |
+| `cache_ttl` | `5` (секунд кэша состояний) |
+| `confirm_global_actions` | `true` — спрашивать подтверждение для команд типа «выключи весь свет» |
+| `dry_run` | `false` — если `true`, команды не выполняются, только показываются |
+
+### 6. Включите инструмент для пользователя
+
+Open WebUI → **Settings → Interface → Tools** → включите `Home Assistant Smart Control`.
+
+## Примеры команд
+
+### Управление
+```
+включи свет в спальне
+выключи весь свет
+поставь 23 градуса в детской
+открой шторы в гостиной
+пауза музыки
+громче
+запусти сцену вечерний отдых
+включи свет на 50%
+уютный свет в спальне
+```
+
+### Мониторинг
+```
+какие окна открыты?
+что горит лишнего?
+какая температура в спальне?
+батарейки садятся?
+кто дома?
+что сейчас играет?
+```
+
+## Безопасность
+
+- Токен HA хранится в **Valves** Open WebUI, не в коде
+- Глобальные команды («выключи весь свет») требуют подтверждения
+- Ошибки на одной сущности не валят весь сценарий — остальные устройства обрабатываются независимо
+- HTTP-запросы с ретраями и таймаутами
+
+## Версионирование
+
+- **v2.2.0** — добавлены мониторинг (окна, свет, климат, батарейки, медиа, присутствие), dry-run, dry-run, ретраи, кэш состояний
+- **v2.0.0** — базовое управление светом, климатом, медиа, шторами
+
+## Лицензия
+
+MIT