homeassistant-skill について
Home Assistant REST APIを通じてスマートホーム機器を操作するスキルです。エンティティの検出やサービス操作を案内し、安全に関わる操作には事前の明示的な確認を求めます。
主な機能
- 01エンティティと状態の検出
- 02照明、スイッチ、空調の操作
- 03シーン、スクリプト、自動化の実行
- 04履歴、カレンダー、天気の参照
- 05安全に関わる操作前の確認
活用シーン
- 01機器の状態や在宅状況の確認
- 02照明やサーモスタットの調整
- 03シーンや自動化の実行
- 04エンティティの履歴やログブックの確認
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ anotb/ homeassistant-skill --skill homeassistant-skillインストール後、Claude Code で/homeassistant-skillを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
README.md.env.example.gitignoreLICENSE詳細
Home Assistant スキル
Home Assistant REST API を介してスマートホームデバイスを制御します。
セットアップ
環境変数を設定します。
HA_URL— Home Assistant の URL(例:http://10.0.0.10:8123)HA_TOKEN— 長期アクセストークン(HA → Profile → Long-Lived Access Tokens で作成)
安全ルール
次の操作を行う前に、必ずユーザーに確認してください。
- ロック — ロックの施錠または解錠
- 警報パネル — 警戒モードの設定または解除
- ガレージドア — 開閉(
device_class: garageのcover.*) - セキュリティオートメーション — セキュリティまたは安全に関するオートメーションの無効化
- カバー — 物理的な出入りを制御するカバー(ゲート、バリア)の開閉
明示的なユーザー確認なしに、セキュリティ上重要なデバイスを操作しないでください。
エンティティの検出
すべてのエンティティを一覧表示
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[].entity_id' | sort
ドメイン別にエンティティを一覧表示
# Switches
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("switch.")) | "\(.entity_id): \(.state)"'
# Lights
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("light.")) | "\(.entity_id): \(.state)"'
# Sensors
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("sensor.")) | "\(.entity_id): \(.state) \(.attributes.unit_of_measurement // "")"'
任意のドメインのエンティティを検出するには、ドメインの接頭辞(switch.、light.、sensor. など)を置き換えます。
単一エンティティの状態を取得
curl -s "$HA_URL/api/states/ENTITY_ID" -H "Authorization: Bearer $HA_TOKEN"
エリアとフロアの検出
テンプレート API を使用して、エリア、フロア、ラベルを照会します。
# List all areas
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ areas() }}"}'
# Entities in a specific area
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ area_entities(\"kitchen\") }}"}'
# Only lights in an area
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ area_entities(\"kitchen\") | select(\"match\", \"light.\") | list }}"}'
# Find which area an entity belongs to
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ area_name(\"light.kitchen\") }}"}'
# List all floors and their areas
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{% for floor in floors() %}{{ floor }}: {{ floor_areas(floor) }}\n{% endfor %}"}'
スイッチ
# Turn on
curl -s -X POST "$HA_URL/api/services/switch/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "switch.office_lamp"}'
# Turn off
curl -s -X POST "$HA_URL/api/services/switch/turn_off" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "switch.office_lamp"}'
# Toggle
curl -s -X POST "$HA_URL/api/services/switch/toggle" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "switch.office_lamp"}'
ライト
# Turn on with brightness
curl -s -X POST "$HA_URL/api/services/light/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "light.living_room", "brightness_pct": 80}'
# Turn on with color (RGB)
curl -s -X POST "$HA_URL/api/services/light/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "light.living_room", "rgb_color": [255, 150, 50]}'
# Turn on with color temperature (mireds)
curl -s -X POST "$HA_URL/api/services/light/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "light.living_room", "color_temp": 300}'
# Turn off
curl -s -X POST "$HA_URL/api/services/light/turn_off" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "light.living_room"}'
シーン
curl -s -X POST "$HA_URL/api/services/scene/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "scene.movie_time"}'
スクリプト
# List all scripts
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("script.")) | "\(.entity_id): \(.state)"'
# Run a script
curl -s -X POST "$HA_URL/api/services/script/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "script.bedtime_routine"}'
# Run a script with variables
curl -s -X POST "$HA_URL/api/services/script/bedtime_routine" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"variables": {"brightness": 20, "delay_minutes": 5}}'
オートメーション
# List all automations
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("automation.")) | "\(.entity_id): \(.state)"'
# Trigger an automation
curl -s -X POST "$HA_URL/api/services/automation/trigger" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "automation.morning_routine"}'
# Enable automation
curl -s -X POST "$HA_URL/api/services/automation/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "automation.morning_routine"}'
# Disable automation
curl -s -X POST "$HA_URL/api/services/automation/turn_off" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "automation.morning_routine"}'
空調制御
# Get thermostat state
curl -s "$HA_URL/api/states/climate.thermostat" -H "Authorization: Bearer $HA_TOKEN" \
| jq '{state: .state, current_temp: .attributes.current_temperature, target_temp: .attributes.temperature}'
# Set temperature
curl -s -X POST "$HA_URL/api/services/climate/set_temperature" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "climate.thermostat", "temperature": 72}'
# Set HVAC mode (heat, cool, auto, off)
curl -s -X POST "$HA_URL/api/services/climate/set_hvac_mode" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "climate.thermostat", "hvac_mode": "auto"}'
カバー(ブラインド、ガレージドア)
安全: ガレージドアまたはゲートを開閉する前に、ユーザーに確認してください。
# Open
curl -s -X POST "$HA_URL/api/services/cover/open_cover" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "cover.garage_door"}'
# Close
curl -s -X POST "$HA_URL/api/services/cover/close_cover" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "cover.garage_door"}'
# Set position (0 = closed, 100 = open)
curl -s -X POST "$HA_URL/api/services/cover/set_cover_position" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "cover.blinds", "position": 50}'
ロック
安全: 施錠または解錠する前に、必ずユーザーに確認してください。
# Lock
curl -s -X POST "$HA_URL/api/services/lock/lock" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "lock.front_door"}'
# Unlock
curl -s -X POST "$HA_URL/api/services/lock/unlock" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "lock.front_door"}'
ファン
# Turn on
curl -s -X POST "$HA_URL/api/services/fan/turn_on" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "fan.bedroom", "percentage": 50}'
# Turn off
curl -s -X POST "$HA_URL/api/services/fan/turn_off" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "fan.bedroom"}'
メディアプレーヤー
# Play/pause
curl -s -X POST "$HA_URL/api/services/media_player/media_play_pause" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "media_player.living_room_tv"}'
# Set volume (0.0 to 1.0)
curl -s -X POST "$HA_URL/api/services/media_player/volume_set" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "media_player.living_room_tv", "volume_level": 0.5}'
掃除機
# Start cleaning
curl -s -X POST "$HA_URL/api/services/vacuum/start" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "vacuum.robot"}'
# Return to dock
curl -s -X POST "$HA_URL/api/services/vacuum/return_to_base" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "vacuum.robot"}'
警報制御パネル
安全: 警戒モードを設定または解除する前に、必ずユーザーに確認してください。
# Arm (home mode)
curl -s -X POST "$HA_URL/api/services/alarm_control_panel/alarm_arm_home" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "alarm_control_panel.home"}'
# Disarm (requires code if configured)
curl -s -X POST "$HA_URL/api/services/alarm_control_panel/alarm_disarm" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "alarm_control_panel.home", "code": "1234"}'
通知
# List available notification targets
curl -s "$HA_URL/api/services" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.domain == "notify") | .services | keys[]' | sort
# Send a notification to a mobile device
curl -s -X POST "$HA_URL/api/services/notify/mobile_app_phone" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "Front door opened", "title": "Home Alert"}'
# Send to all devices (default notify service)
curl -s -X POST "$HA_URL/api/services/notify/notify" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "System alert", "title": "Home Assistant"}'
一覧表示コマンドから取得した実際のサービス名に、mobile_app_phone を置き換えます。
人物とプレゼンス
# Who is home?
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("person.")) | "\(.attributes.friendly_name // .entity_id): \(.state)"'
# Device tracker locations
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("device_tracker.")) | "\(.entity_id): \(.state)"'
状態:home、not_home、またはゾーン名です。
天気
# Current weather
curl -s "$HA_URL/api/states/weather.home" -H "Authorization: Bearer $HA_TOKEN" \
| jq '{state: .state, temperature: .attributes.temperature, humidity: .attributes.humidity, wind_speed: .attributes.wind_speed}'
# Get forecast (daily)
curl -s -X POST "$HA_URL/api/services/weather/get_forecasts" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "weather.home", "type": "daily"}'
# Get forecast (hourly)
curl -s -X POST "$HA_URL/api/services/weather/get_forecasts" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "weather.home", "type": "hourly"}'
入力ヘルパー
# Toggle an input boolean
curl -s -X POST "$HA_URL/api/services/input_boolean/toggle" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "input_boolean.guest_mode"}'
# Set input number
curl -s -X POST "$HA_URL/api/services/input_number/set_value" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "input_number.target_temperature", "value": 72}'
# Set input select
curl -s -X POST "$HA_URL/api/services/input_select/select_option" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "input_select.house_mode", "option": "Away"}'
# Set input text
curl -s -X POST "$HA_URL/api/services/input_text/set_value" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "input_text.welcome_message", "value": "Welcome home!"}'
# Set input datetime
curl -s -X POST "$HA_URL/api/services/input_datetime/set_datetime" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "input_datetime.alarm_time", "time": "07:30:00"}'
カレンダー
# List all calendars
curl -s "$HA_URL/api/calendars" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[].entity_id'
# Get upcoming events (next 7 days)
curl -s "$HA_URL/api/calendars/calendar.personal?start=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)&end=$(date -u -v+7d +%Y-%m-%dT%H:%M:%S.000Z)" \
-H "Authorization: Bearer $HA_TOKEN" \
| jq '[.[] | {summary: .summary, start: .start.dateTime, end: .end.dateTime}]'
テキスト読み上げ
curl -s -X POST "$HA_URL/api/services/tts/speak" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "tts.google_en", "media_player_entity_id": "media_player.living_room_speaker", "message": "Dinner is ready"}'
tts.google_en をお使いの TTS エンティティに、media_player.living_room_speaker を対象のスピーカーに置き換えます。
任意のサービスを呼び出す
任意の HA サービスで使用する一般的なパターン:
curl -s -X POST "$HA_URL/api/services/{domain}/{service}" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "domain.entity_name", ...}'
一括操作
エンティティ ID の配列を渡すことで、1 回の呼び出しで複数のエンティティを制御できます。
# Turn off all living room lights at once
curl -s -X POST "$HA_URL/api/services/light/turn_off" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": ["light.living_room", "light.living_room_lamp", "light.living_room_ceiling"]}'
エラー処理
API 接続を確認する
curl -s -o /dev/null -w "%{http_code}" "$HA_URL/api/" \
-H "Authorization: Bearer $HA_TOKEN"
# Expect: 200
操作前にエンティティの存在を確認する
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
"$HA_URL/api/states/light.nonexistent" \
-H "Authorization: Bearer $HA_TOKEN")
# 200 = exists, 404 = not found
HTTP ステータスコード
| コード | 意味 |
|---|---|
| 200 | 成功 |
| 400 | 不正なリクエスト(JSON の形式が不正、またはサービスデータが無効) |
| 401 | 認証されていません(トークンが無効または未指定) |
| 404 | エンティティまたはエンドポイントが見つかりません |
| 405 | メソッドが許可されていません(HTTP メソッドが誤っています) |
| 503 | Home Assistant の起動中、または利用できません |
レスポンス形式
サービス呼び出しは、影響を受けたエンティティの状態オブジェクトの配列を返します。
[{"entity_id": "light.living_room", "state": "on", "attributes": {...}, "last_changed": "..."}]
- 状態に変化がない場合の呼び出し成功:
[](空の配列)を返します - 状態の読み取り(
/api/states/...):単一の状態オブジェクトを返します - エラー:HTTP エラーコードとともに
{"message": "..."}を返します
テンプレート評価
/api/template エンドポイントは、サーバー側で Jinja2 テンプレートを評価します。計算を伴うクエリに便利です。
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "TEMPLATE_STRING"}'
例
# Count entities by domain
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ states.light | list | count }} lights"}'
# Get entity state in a template
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ states(\"light.living_room\") }}"}'
# List all entities that are "on"
curl -s -X POST "$HA_URL/api/template" \
-H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ states | selectattr(\"state\", \"eq\", \"on\") | map(attribute=\"entity_id\") | list }}"}'
利用可能なテンプレート関数:states()、is_state()、state_attr()、areas()、area_entities()、area_name()、floors()、floor_areas()、labels()、label_entities()、devices()、device_entities()、now()、relative_time()。
履歴とログブック
エンティティの状態履歴
# Last 24 hours for a specific entity
curl -s "$HA_URL/api/history/period?filter_entity_id=sensor.temperature" \
-H "Authorization: Bearer $HA_TOKEN" \
| jq '.[0] | [.[] | {state: .state, last_changed: .last_changed}]'
# Specific time range (ISO 8601)
curl -s "$HA_URL/api/history/period/2025-01-15T00:00:00Z?end_time=2025-01-15T23:59:59Z&filter_entity_id=sensor.temperature" \
-H "Authorization: Bearer $HA_TOKEN" \
| jq '.[0]'
ログブック
# Recent logbook entries
curl -s "$HA_URL/api/logbook" -H "Authorization: Bearer $HA_TOKEN" \
| jq '.[:10]'
# Logbook for a specific entity
curl -s "$HA_URL/api/logbook?entity=light.living_room" \
-H "Authorization: Bearer $HA_TOKEN" \
| jq '.[:10] | [.[] | {name: .name, message: .message, when: .when}]'
ダッシュボードの概要
すべてのアクティブなデバイスの簡易ステータス:
# All lights that are on
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("light.")) | select(.state == "on") | .entity_id'
# All open doors/windows (binary sensors)
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("binary_sensor.")) | select(.state == "on") | select(.attributes.device_class == "door" or .attributes.device_class == "window") | .entity_id'
# Temperature sensors
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("sensor.")) | select(.attributes.device_class == "temperature") | "\(.attributes.friendly_name // .entity_id): \(.state)\(.attributes.unit_of_measurement // "")"'
# Climate summary (all thermostats)
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("climate.")) | "\(.attributes.friendly_name // .entity_id): \(.state), current: \(.attributes.current_temperature)°, target: \(.attributes.temperature)°"'
# Lock status
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("lock.")) | "\(.attributes.friendly_name // .entity_id): \(.state)"'
# Who is home
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
| jq -r '.[] | select(.entity_id | startswith("person.")) | "\(.attributes.friendly_name // .entity_id): \(.state)"'
エンティティドメイン
| ドメイン | 例 |
|---|---|
switch.* | スマートプラグ、汎用スイッチ |
light.* | ライト(Hue、LIFX など) |
scene.* | 事前設定されたシーン |
script.* | 再利用可能なアクションシーケンス |
automation.* | オートメーション |
climate.* | サーモスタット、エアコン |
cover.* | ブラインド、ガレージドア、ゲート |
lock.* | スマートロック |
fan.* | ファン、換気設備 |
media_player.* | テレビ、スピーカー、ストリーミングデバイス |
vacuum.* | ロボット掃除機 |
alarm_control_panel.* | セキュリティシステム |
notify.* | 通知先 |
person.* | 人/在宅状況の追跡 |
device_tracker.* | デバイスの位置 |
weather.* | 天気の状況と予報 |
calendar.* | カレンダーの予定 |
tts.* | テキスト読み上げエンジン |
sensor.* | 温度、湿度、電力など |
binary_sensor.* | 動体、ドア/窓、在室状況 |
input_boolean.* | 仮想トグル |
input_number.* | 数値スライダー |
input_select.* | ドロップダウンセレクター |
input_text.* | テキスト入力 |
input_datetime.* | 日付/時刻入力 |
注意事項
- API はデフォルトで JSON を返します
- 長期間有効なトークンは期限切れにならないため、安全に保管してください
- まずリストコマンドを使って、エンティティ ID をテストしてください
- ロック、アラーム、ガレージドアの操作は、必ずユーザーに確認してください