home-assistant

Home Assistant

Home Assistant の REST API と Webhook を使ってスマートホームを操作します。

セットアップ

オプション 1：設定ファイル（推奨）

~/.config/home-assistant/config.json を作成します：

{
  "url": "https://your-ha-instance.duckdns.org",
  "token": "your-long-lived-access-token"
}

オプション 2：環境変数

export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"

長期有効アクセストークンの取得

1. Home Assistant → プロフィール（左下）を開きます
2. 「Long-Lived Access Tokens」までスクロールします
3. 「Create Token」をクリックし、名前を付けます（例：「Clawdbot」）
4. トークンをすぐにコピーします（一度しか表示されません）

クイックリファレンス

エンティティの一覧表示

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'

エンティティの状態を取得

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room"

デバイスの操作

# Turn on
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room"}'

# Turn off
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/light/turn_off" -d '{"entity_id": "light.living_room"}'

# Set brightness (0-255)
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room", "brightness": 128}'

スクリプトとオートメーションの実行

# Trigger script
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/script/turn_on" \
  -H "Content-Type: application/json" -d '{"entity_id": "script.goodnight"}'

# Trigger automation
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/automation/trigger" \
  -H "Content-Type: application/json" -d '{"entity_id": "automation.motion_lights"}'

シーンの有効化

curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/scene/turn_on" \
  -H "Content-Type: application/json" -d '{"entity_id": "scene.movie_night"}'

よく使うサービス

ドメイン	サービス	entity_id の例
light	turn_on、turn_off、toggle	light.kitchen
switch	turn_on、turn_off、toggle	switch.fan
climate	set_temperature、set_hvac_mode	climate.thermostat
cover	open_cover、close_cover、stop_cover	cover.garage
media_player	play_media、media_pause、volume_set	media_player.tv
scene	turn_on	scene.relax
script	turn_on	script.welcome_home
automation	trigger、turn_on、turn_off	automation.sunrise

受信 Webhook（HA → Clawdbot）

Home Assistant のオートメーションからイベントを受信するには：

1. Webhook アクションを含む HA オートメーションを作成する

# In HA automation
action:
  - service: rest_command.notify_clawdbot
    data:
      event: motion_detected
      area: living_room

2. HA で REST コマンドを定義する

# configuration.yaml
rest_command:
  notify_clawdbot:
    url: "https://your-clawdbot-url/webhook/home-assistant"
    method: POST
    headers:
      Authorization: "Bearer {{ webhook_secret }}"
      Content-Type: "application/json"
    payload: '{"event": "{{ event }}", "area": "{{ area }}"}'

3. Clawdbot で処理する

Clawdbot は Webhook を受信し、イベントに応じて通知したり、アクションを実行したりできます。

CLI ラッパー

scripts/ha.sh CLI を使うと、すべての HA 機能に簡単にアクセスできます：

# Test connection
ha.sh info

# List entities
ha.sh list all          # all entities
ha.sh list lights       # just lights
ha.sh list switch       # just switches

# Search entities
ha.sh search kitchen    # find entities by name

# Get/set state
ha.sh state light.living_room
ha.sh states light.living_room   # full details with attributes
ha.sh on light.living_room
ha.sh on light.living_room 200   # with brightness (0-255)
ha.sh off light.living_room
ha.sh toggle switch.fan

# Scenes & scripts
ha.sh scene movie_night
ha.sh script goodnight

# Climate
ha.sh climate climate.thermostat 22

# Call any service
ha.sh call light turn_on '{"entity_id":"light.room","brightness":200}'

トラブルシューティング

• 401 Unauthorized：トークンの期限が切れているか、無効です。新しいトークンを生成してください。
• Connection refused：HA_URL を確認し、HA が実行中でアクセス可能であることを確認してください。
• Entity not found：エンティティを一覧表示して、正しい entity_id を確認してください。

API リファレンス

高度な使い方については、references/api.md を参照してください。