Home Assistant

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 Яндекс умный дом

Навыка под Яндекс IoT в паке нет — колонка ниже нужна, чтобы понять, туда ли ты вообще пришёл, а не чтобы им пользоваться.

Если HA-инстанса нет, CLI при отсутствии кредов сам печатает, что настроить.

Установка / настройка

1. Нужен работающий HA-инстанс (Home Assistant OS на RPi/mini-PC или Docker: docker run -d --name homeassistant --network=host ghcr.io/home-assistant/home-assistant:stable).
2. Токен: HA web UI → профиль (слева внизу) → вкладка Security → Long-lived access tokens → Create Token.
3. Свои значения — в переменные окружения или в свой ~/.claude/.credentials.master.env (образец — ~/.claude/templates/.credentials.master.env.example; в репозиторий — никогда):
   • HA_URL — базовый URL, например http://homeassistant.local:8123 или http://192.168.x.x:8123
   • HA_TOKEN — long-lived access token из шага 2
4. Зависимости: pip install requests websockets — requests для REST, websockets для events/areas/devices. Проверено на websockets 15.x.

Команды

У каждой команды есть --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/... возвращает список состояний, изменившихся за время вызова — пустой список не значит «не сработало» (например, устройство уже было в целевом состоянии).

Чек-лист

• HA_URL + HA_TOKEN заведены в окружении (или в своём .credentials.master.env)
• ping отвечает API running.
• states показывает сущности → entity_id для дальнейших команд брать отсюда
• Перед call с нестандартным сервисом — проверить его существование в HA (Developer Tools → Services); CLI не валидирует имена сервисов
• Для скриптов/агентов — всегда --json