Home Assistant CLI
Коннектор к Home Assistant: подключился → сделал → напечатал → вышел.
CLI: python ~/.claude/tools/ha_client.py <command>.
Когда использовать
- Прочитать/изменить состояние устройств в Home Assistant (свет, розетки, климат, сенсоры).
- Вызвать любой HA-сервис (
light.turn_on, climate.set_temperature, media_player.play_media...).
- Посмотреть историю состояний сенсора, live-поток событий, конфиг инстанса, комнаты/устройства.
HA vs Яндекс умный дом (отдельный навык под Яндекс (в пак не входит))
| Критерий |
Home Assistant (этот skill) |
Яндекс IoT (отдельный навык под Яндекс (в пак не входит)) |
| Где живёт |
Локально (свой сервер/RPi/Docker), работает без интернета |
Облако Яндекса |
| Устройства |
2000+ интеграций: Zigbee, Z-Wave, MQTT, ESPHome, Xiaomi, и Яндекс-устройства тоже подключаемы |
Только устройства, привязанные к аккаунту Яндекса |
| Автоматизации |
Полноценные (triggers/conditions/scripts), история, дашборды |
Сценарии Алисы, проще |
| Голос |
Опционально (в т.ч. проброс в Алису) |
Алиса нативно |
| Когда брать |
Нужен локальный контроль, не-Яндекс устройства, history/events, сложные автоматизации |
Устройства уже в Яндекс-экосистеме и нужен быстрый доступ/Алиса |
Если HA-инстанса нет, CLI при отсутствии кредов сам печатает, что настроить.
Установка / настройка
- Нужен работающий HA-инстанс (Home Assistant OS на RPi/mini-PC или Docker:
docker run -d --name homeassistant --network=host ghcr.io/home-assistant/home-assistant:stable).
- Токен: HA web UI → профиль (слева внизу) → вкладка Security → Long-lived access tokens → Create Token.
- Env-переменные в
~/.claude/.credentials.master.env (значения заполняет владелец):
HA_URL — базовый URL, например http://homeassistant.local:8123 или http://192.168.x.x:8123HA_TOKEN — long-lived access token
- Зависимости:
requests (REST), websockets (events/areas/devices) — обе уже установлены локально (websockets 15.0.1).
Команды
| Команда |
Что делает |
API |
ping |
Жив ли API |
GET /api/ |
states [--domain light] |
Все состояния, фильтр по домену |
GET /api/states |
get <entity_id> |
Одна сущность + атрибуты |
GET /api/states/<id> |
call <domain> <service> [--entity id] [--data '{...}'] |
Любой сервис |
POST /api/services/<d>/<s> |
on <entity_id> / off <entity_id> / toggle <entity_id> |
Быстрые шорткаты |
homeassistant.turn_on/turn_off/toggle |
history <entity_id> [--hours 24] |
История состояний |
GET /api/history/period/<ts> |
events [--type state_changed] [--limit 50] |
Live-поток событий (WS), остановка по лимиту или Ctrl+C |
WS subscribe_events |
config |
Версия, локация, компоненты |
GET /api/config |
areas / devices |
Комнаты / устройства |
WS config/area_registry/list, config/device_registry/list — внутренний frontend-API, не гарантирован между версиями; CLI честно сообщит, если команда недоступна |
У каждой команды есть --json (машинный вывод) и --help.
Примеры
# Проверка связи
python ~/.claude/tools/ha_client.py ping
# Весь свет в доме
python ~/.claude/tools/ha_client.py states --domain light
# Включить свет на кухне на 50% яркости
python ~/.claude/tools/ha_client.py call light turn_on --entity light.kitchen --data '{"brightness_pct": 50}'
# Просто вкл/выкл/переключить
python ~/.claude/tools/ha_client.py on switch.heater
python ~/.claude/tools/ha_client.py toggle light.bedroom
# Температура за 12 часов
python ~/.claude/tools/ha_client.py history sensor.living_room_temperature --hours 12
# Следить за изменениями состояний (20 событий и выход)
python ~/.claude/tools/ha_client.py events --type state_changed --limit 20
# JSON для скриптов
python ~/.claude/tools/ha_client.py states --domain sensor --json
Гочи
- Креды не заданы → exit 2 + печать инструкции по настройке (не трейсбек). Так и задумано, пока HA-инстанса нет.
on/off/toggle идут через универсальный домен homeassistant.* — работают для light/switch/fan/media_player и т.п.; для доменных параметров (яркость, цвет, температура) — используй call с --data.--data — строго JSON в одинарных кавычках снаружи (PowerShell: --data '{\"brightness\": 128}' или через Git Bash без экранирования).history использует UTC-таймстамп в URL (закодированный +00:00) — окно задаётся --hours, не датами.events без --type подписывается на ВСЕ события — на живом инстансе это шумно; обычно нужен --type state_changed.areas/devices — WebSocket-команды внутреннего API реестров (их использует frontend HA). В официальной REST-документации их нет; стабильны годами, но формально «требуют проверки» на конкретной версии HA — при недоступности CLI сообщит об этом явно.- 401 → токен отозван/невалиден: создать новый long-lived token; 404 на
get → сущности не существует (проверь states).
- POST
/api/services/... возвращает список состояний, изменившихся за время вызова — пустой список не значит «не сработало» (например, устройство уже было в целевом состоянии).
Чек-лист
1---2name: home-assistant-23description: Умный дом Home Assistant через ha_client.py: состояния, сервисы, история, события. Триггеры: «включи свет через HA», «hass».4---56# Home Assistant CLI78Коннектор к Home Assistant: подключился → сделал → напечатал → вышел.9CLI: `python ~/.claude/tools/ha_client.py <command>`.1011## Когда использовать1213- Прочитать/изменить состояние устройств в Home Assistant (свет, розетки, климат, сенсоры).14- Вызвать любой HA-сервис (`light.turn_on`, `climate.set_temperature`, `media_player.play_media`...).15- Посмотреть историю состояний сенсора, live-поток событий, конфиг инстанса, комнаты/устройства.1617### HA vs Яндекс умный дом (отдельный навык под Яндекс (в пак не входит))1819| Критерий | Home Assistant (этот skill) | Яндекс IoT (отдельный навык под Яндекс (в пак не входит)) |20|----------|------------------------------|---------------------------|21| Где живёт | Локально (свой сервер/RPi/Docker), работает без интернета | Облако Яндекса |22| Устройства | 2000+ интеграций: Zigbee, Z-Wave, MQTT, ESPHome, Xiaomi, и Яндекс-устройства тоже подключаемы | Только устройства, привязанные к аккаунту Яндекса |23| Автоматизации | Полноценные (triggers/conditions/scripts), история, дашборды | Сценарии Алисы, проще |24| Голос | Опционально (в т.ч. проброс в Алису) | Алиса нативно |25| Когда брать | Нужен локальный контроль, не-Яндекс устройства, history/events, сложные автоматизации | Устройства уже в Яндекс-экосистеме и нужен быстрый доступ/Алиса |2627Если HA-инстанса нет, CLI при отсутствии кредов сам печатает, что настроить.2829## Установка / настройка30311. Нужен работающий HA-инстанс (Home Assistant OS на RPi/mini-PC или Docker:32 `docker run -d --name homeassistant --network=host ghcr.io/home-assistant/home-assistant:stable`).332. Токен: HA web UI → профиль (слева внизу) → вкладка Security → Long-lived access tokens → Create Token.343. Env-переменные в `~/.claude/.credentials.master.env` (значения заполняет владелец):35 - `HA_URL` — базовый URL, например `http://homeassistant.local:8123` или `http://192.168.x.x:8123`36 - `HA_TOKEN` — long-lived access token374. Зависимости: `requests` (REST), `websockets` (events/areas/devices) — обе уже установлены локально (websockets 15.0.1).3839## Команды4041| Команда | Что делает | API |42|---------|-----------|-----|43| `ping` | Жив ли API | `GET /api/` |44| `states [--domain light]` | Все состояния, фильтр по домену | `GET /api/states` |45| `get <entity_id>` | Одна сущность + атрибуты | `GET /api/states/<id>` |46| `call <domain> <service> [--entity id] [--data '{...}']` | Любой сервис | `POST /api/services/<d>/<s>` |47| `on <entity_id>` / `off <entity_id>` / `toggle <entity_id>` | Быстрые шорткаты | `homeassistant.turn_on/turn_off/toggle` |48| `history <entity_id> [--hours 24]` | История состояний | `GET /api/history/period/<ts>` |49| `events [--type state_changed] [--limit 50]` | Live-поток событий (WS), остановка по лимиту или Ctrl+C | WS `subscribe_events` |50| `config` | Версия, локация, компоненты | `GET /api/config` |51| `areas` / `devices` | Комнаты / устройства | WS `config/area_registry/list`, `config/device_registry/list` — **внутренний frontend-API**, не гарантирован между версиями; CLI честно сообщит, если команда недоступна |5253У каждой команды есть `--json` (машинный вывод) и `--help`.5455## Примеры5657```bash58# Проверка связи59python ~/.claude/tools/ha_client.py ping6061# Весь свет в доме62python ~/.claude/tools/ha_client.py states --domain light6364# Включить свет на кухне на 50% яркости65python ~/.claude/tools/ha_client.py call light turn_on --entity light.kitchen --data '{"brightness_pct": 50}'6667# Просто вкл/выкл/переключить68python ~/.claude/tools/ha_client.py on switch.heater69python ~/.claude/tools/ha_client.py toggle light.bedroom7071# Температура за 12 часов72python ~/.claude/tools/ha_client.py history sensor.living_room_temperature --hours 127374# Следить за изменениями состояний (20 событий и выход)75python ~/.claude/tools/ha_client.py events --type state_changed --limit 207677# JSON для скриптов78python ~/.claude/tools/ha_client.py states --domain sensor --json79```8081## Гочи8283- **Креды не заданы** → exit 2 + печать инструкции по настройке (не трейсбек). Так и задумано, пока HA-инстанса нет.84- `on`/`off`/`toggle` идут через универсальный домен `homeassistant.*` — работают для light/switch/fan/media_player и т.п.; для доменных параметров (яркость, цвет, температура) — используй `call` с `--data`.85- `--data` — строго JSON в одинарных кавычках снаружи (PowerShell: `--data '{\"brightness\": 128}'` или через Git Bash без экранирования).86- `history` использует UTC-таймстамп в URL (закодированный `+00:00`) — окно задаётся `--hours`, не датами.87- `events` без `--type` подписывается на ВСЕ события — на живом инстансе это шумно; обычно нужен `--type state_changed`.88- `areas`/`devices` — WebSocket-команды внутреннего API реестров (их использует frontend HA). В официальной REST-документации их нет; стабильны годами, но формально «требуют проверки» на конкретной версии HA — при недоступности CLI сообщит об этом явно.89- 401 → токен отозван/невалиден: создать новый long-lived token; 404 на `get` → сущности не существует (проверь `states`).90- POST `/api/services/...` возвращает список состояний, изменившихся **за время вызова** — пустой список не значит «не сработало» (например, устройство уже было в целевом состоянии).9192## Чек-лист9394- [ ] `HA_URL` + `HA_TOKEN` в `~/.claude/.credentials.master.env`95- [ ] `ping` отвечает `API running.`96- [ ] `states` показывает сущности → entity_id для дальнейших команд брать отсюда97- [ ] Перед `call` с нестандартным сервисом — проверить его существование в HA (Developer Tools → Services); CLI не валидирует имена сервисов98- [ ] Для скриптов/агентов — всегда `--json`
JHamidun