home-assistant

Home Assistant ヘルパー

概要

このスキルは、Home Assistant のインストール環境で作業するためのツールとワークフローを提供します。稼働中の HA インスタンスに問い合わせて、エンティティ、サービス、設定データを取得したり、オートメーションをデバッグしたり、オートメーションやダッシュボード用の YAML 設定を生成したりできます。

主な機能：

• 稼働中の HA インストール環境からエンティティ、状態、サービスを取得
• 例として使える類似エンティティを検索
• オートメーションの状態と実行履歴を確認
• HA にコピーして貼り付けられる YAML 設定を生成
• ユーザーの環境から実例を見つけ、新しい設定の参考にする

基本的なワークフロー

Home Assistant に関するタスクを支援する際は、次の一般的な手順に従います。

1. 要件を把握する - ユーザーは何を実現しようとしていますか？
2. 既存のエンティティを見つける - スクリプトを使って、ユーザーの環境内にある関連エンティティを探します
3. 類似の例を見つける - 同様の処理を行う既存のオートメーションやエンティティを検索します
4. YAML を生成する - HA に直接コピーできる、適切な形式の YAML を作成します
5. 設定を説明する - YAML の動作とインストール方法を説明します

利用可能なスクリプト

すべてのスクリプトを実行するには、Home Assistant の長期アクセストークンを格納する環境変数 HA_TOKEN を設定する必要があります。HA インスタンスには http://homeassistant.local:8123 でアクセスできます。

重要： すべてのスクリプトは、コードの一貫性と保守性を確保するため、インライン PEP 723 依存関係宣言と homeassistant-api ライブラリを使用し、uv で実行するようになりました。初回実行時に、依存関係は uv によって自動的にインストールされます。

エンティティの検出

ha_get_entities.py [domain]

すべてのエンティティを取得します。ドメインを指定すると、対象を絞り込めます。

使用方法：

uv run scripts/ha_get_entities.py           # All entities
uv run scripts/ha_get_entities.py light     # Just lights
uv run scripts/ha_get_entities.py sensor    # Just sensors

使用する場面： 利用可能なエンティティを調べるとき、特に新しいオートメーションを作成するときに使用します。

ha_get_state.py <entity_id>

特定のエンティティの現在の状態と属性を取得します。

使用方法：

uv run scripts/ha_get_state.py light.living_room

使用する場面： 現在の状態や利用可能な属性を確認するとき、またはエンティティの存在を確かめるときに使用します。

ha_search_similar_entities.py <pattern>

エンティティ ID またはフレンドリーネームに指定したパターンが含まれるエンティティを検索します。

使用方法：

uv run scripts/ha_search_similar_entities.py "bedroom"
uv run scripts/ha_search_similar_entities.py "motion"
uv run scripts/ha_search_similar_entities.py "temperature"

使用する場面： ユーザーが自動化したい操作に関連するエンティティを探すときに使用します。新しいオートメーションを作成する前に例を見つけるのに特に役立ちます。

オートメーションの管理

ha_get_automations.py [search_term]

すべてのオートメーションを取得します。検索語を指定すると、対象を絞り込めます。

使用方法：

uv run scripts/ha_get_automations.py              # All automations
uv run scripts/ha_get_automations.py motion       # Automations with 'motion'
uv run scripts/ha_get_automations.py light        # Automations with 'light'

使用する場面： ユーザーが作成したいものに似た既存のオートメーションを見つけるときに使用します。これらをテンプレートとして使います。

オートメーションのトレース分析

ha_list_traces.py [automation_id]

オートメーションの実行トレースを、タイムスタンプとステータスとともに一覧表示します。

使用方法：

uv run scripts/ha_list_traces.py                    # All traces
uv run scripts/ha_list_traces.py 1761430536701      # Specific automation traces (using numeric ID)

重要： 完全な entity_id（例：automation.bedroom_light）ではなく、数値のオートメーション ID（例：1761430536701）を使用してください。数値 ID は、ha_get_automations.py の出力にあるオートメーションの属性で確認できます。

使用する場面： 最近のオートメーションの実行、そのステータス、実行時刻を確認するときに使用します。さらに調査する実行 ID を特定するのに役立ちます。

出力に含まれる情報：

• 実行 ID（ha_get_trace.py で使用）
• タイムスタンプ
• 実行状態（停止中、実行中など）
• スクリプトの実行ステータス（finished、failed_single、failed_conditions など）
• 最後に実行されたステップ
• エラー

ha_get_trace.py <automation_id> <run_id>

特定のオートメーション実行について、詳細なステップごとのトレースを取得します。

使用方法：

uv run scripts/ha_get_trace.py 1761430536701 1ceef6b2b6f63a8745eb5dba3fe12f71

重要： 完全な entity_id ではなく、数値のオートメーション ID（例：1761430536701）を使用してください。

使用する場面： 特定のオートメーション実行をデバッグするときに使用します。次の情報を含む実行経路全体が表示されます。

• トリガーの詳細
• 条件の評価（成功／失敗）
• 実行されたアクション
• 各ステップでの変数
• タイミング情報
• 失敗した場合のエラー詳細

ヒント： ha_list_traces.py の出力から run_id を取得してください。

ha_trace_summary.py <automation_id>

オートメーションの実行履歴に関する集計統計を取得します。

使用方法：

uv run scripts/ha_trace_summary.py 1761430536701

重要： 完全な entity_id ではなく、数値のオートメーション ID（例：1761430536701）を使用してください。

使用する場面： オートメーションの信頼性とパフォーマンスの経時変化を把握するときに使用します。

出力内容：

• 実行回数の合計
• 成功／失敗の件数と割合
• 実行時間の平均／最小／最大
• よく見られるエラーパターン
• 実行が完了した場所の分布

サービスの検索

ha_get_services.py [domain]

利用可能なすべてのサービスについて、説明とフィールド情報を取得します。

使用方法：

uv run scripts/ha_get_services.py              # All services
uv run scripts/ha_get_services.py light        # Just light services
uv run scripts/ha_get_services.py climate      # Just climate services

使用する場面： 利用可能なサービスと、それぞれが受け付けるパラメーターを調べるときに使用します。

設定

ha_get_config.py

バージョン、場所、コンポーネントなど、Home Assistant の設定を取得します。

使用方法：

uv run scripts/ha_get_config.py

使用する場面： HA の設定、利用可能なインテグレーション、またはシステム情報を確認するときに使用します。

ha_get_config_entries.py [domain]

Home Assistant の設定エントリーを取得します。必要に応じてドメインで絞り込めます。telegram_bot.send_message など、config_entry_id が必要なサービスで不可欠です。

使用方法：

uv run scripts/ha_get_config_entries.py              # All config entries
uv run scripts/ha_get_config_entries.py telegram_bot # Just Telegram bots
uv run scripts/ha_get_config_entries.py mqtt         # Just MQTT entries

使用する場面： Telegram 通知などのサービスで必要な config_entry_id を取得するときや、設定済みのインテグレーションを調べるときに使用します。

サービスの呼び出し

ha_call_service.py <domain> <service> <json_data>

Home Assistant のサービスを呼び出します（注意して使用してください）。

使用方法：

uv run scripts/ha_call_service.py light turn_on '{"entity_id": "light.living_room"}'

使用する場面： 使用することはまれです。通常はテスト目的、またはユーザーから明示的に制御を依頼された場合にのみ使用します。

一般的なワークフロー

新しいオートメーションの作成

1. 目標を把握する - トリガー、条件、アクションについて確認の質問をします
2. 類似するエンティティを探す - ha_search_similar_entities.py を使用して、関連するエンティティを探します
3. 類似するオートメーションを検索する - ha_get_automations.py に検索語を指定して、例を探します
4. 既存のオートメーションを確認する - 類似のものがあれば、その構造を調べます
5. YAML を生成する - 次の内容を含む、適切に整形された YAML を作成します：
   • わかりやすいエイリアス
   • 明確な説明
   • 適切なトリガー
   • 関連する条件
   • 必要なアクション
   • 適切なモード（single、restart、queued、parallel）
6. コピーして貼り付けられる YAML を提供する - HA の設定に簡単にコピーできる形式に整えます
7. 説明する - オートメーションの動作と、HA への追加方法を説明します

オートメーションのデバッグ

1. オートメーションの状態を確認する - uv run scripts/ha_get_state.py automation.automation_name を使用して、次の項目を確認します：
   • 現在の状態（on/off）
   • 最後にトリガーされた時刻
   • 現在の実行数
   • オートメーションのモード
2. 実行履歴を確認する - トレース分析ツールを使用します（属性から数値のオートメーション ID を使用してください）：
   • uv run scripts/ha_trace_summary.py <numeric_id> - 成功率とよくある問題を確認します
   • uv run scripts/ha_list_traces.py <numeric_id> - 最近の実行を確認します
   • uv run scripts/ha_get_trace.py <numeric_id> <run_id> - ステップごとの詳細なトレースを確認します
3. トレースデータを分析する - 次の項目を確認します：
   • どのトリガーが実行されたか
   • 条件が満たされたか、満たされなかったか
   • どのアクションが正常に実行されたか
   • オートメーションがどこで停止またはエラーになったか
   • 各ステップでの変数の値
4. 関連するエンティティを確認する - uv run scripts/ha_get_state.py を使用して、トリガーとなるエンティティが想定どおりの状態か確認します
5. オートメーションの設定を確認する - uv run scripts/ha_get_automations.py を使用して、オートメーションの詳細をすべて確認します
6. 問題を特定する - トレースデータ、状態情報、設定の確認結果に基づいて特定します
7. 修正案を提示する - 修正した YAML または設定の変更内容を提示します

トレースに基づくデバッグのワークフロー：

# Step 1: Get the automation details to find the numeric ID
uv run scripts/ha_get_automations.py problem_automation

# Step 2: Check if automation has been running and get stats (use numeric ID from step 1)
uv run scripts/ha_trace_summary.py 1761430536701

# Step 3: List recent runs to find failing ones (use numeric ID)
uv run scripts/ha_list_traces.py 1761430536701

# Step 4: Get detailed trace for a specific failed run (use numeric ID)
uv run scripts/ha_get_trace.py 1761430536701 <run_id_from_step_3>

# Step 5: Examine the trace to see exactly where and why it failed

ダッシュボードの変更

1. 変更内容を把握する - ダッシュボードに何を表示する必要があるかを確認します。
2. 関連するエンティティを見つける - エンティティ検出スクリプトを使用します。
3. Lovelace YAML を生成する - ダッシュボードカードの設定を作成します。
4. コピーして貼り付けられる YAML を提供する - ユーザーがダッシュボードに手動で追加します。
5. カード設定を説明する - オプションとカスタマイズ方法を説明します。

エンティティの状態を確認する

1. 検索またはドメインによる絞り込みを使用する - 関心のあるエンティティを見つけます。
2. 特定の状態を確認する - 状態の詳細情報を取得します。
3. 調査結果を報告する - 関連情報をわかりやすく提示します。

Telegram 通知の送信

Telegram 通知を送信するには、notify サービスのパターンではなく、config_entry_id パラメーターを指定して telegram_bot.send_message サービスを使用する必要があります。

ワークフロー：

1. Telegram ボットの config_entry_id を取得する - uv run scripts/ha_get_config_entries.py telegram_bot を使用して、設定エントリー ID を確認します。
2. telegram_bot.send_message サービスを使用する - アクションデータに config_entry_id を含めます。

Telegram 通知を使ったオートメーションの例：

alias: Example Telegram Alert
description: Send a Telegram notification when something happens
triggers:
  - entity_id: binary_sensor.front_door
    to: "on"
    trigger: state
conditions: []
actions:
  - action: telegram_bot.send_message
    data:
      message: "Front door opened at {{ now().strftime('%I:%M %p') }}"
      config_entry_id: 01JZE11D7Y6B7C3WCARWVZRYNH  # Get this from ha_get_config_entries.py
mode: single

注： config_entry_id は Telegram ボットの設定ごとに異なります。ご利用の環境に合った ID を取得するには、必ず uv run scripts/ha_get_config_entries.py telegram_bot を使用してください。

重要な注意事項

YAML の出力形式

YAML 設定を生成する際は、必ず次のようにしてください。

• 2 スペースのインデントを使い、適切な YAML 形式にします。
• 適切な箇所に役立つコメントを含めます。
• わかりやすいエイリアスと説明を付けます。
• 適切なトリガープラットフォーム（state、time、numeric_state など）を使用します。
• モード設定（single、restart、queued、parallel）を含めます。
• HA に簡単にコピーして貼り付けられる形式にします。

手動インストールが必要です

ユーザーは、生成された YAML を Home Assistant に手動でコピーして貼り付ける必要があります。そのことを明確に伝え、手順を案内してください。

• オートメーションの場合：Configuration → Automations & Scenes → Add Automation → Edit in YAML
• ダッシュボードの場合：Dashboard → Edit Dashboard → Raw Configuration Editor
• configuration.yaml に追加する場合：ファイルを編集して HA を再起動します。

スクリーンショット用のブラウザー自動化

ユーザーがダッシュボードのスクリーンショットを求める場合や、現在の UI の状態を見たい場合は、Playwright のブラウザー自動化ツールを使用して HA インスタンスに移動し、スクリーンショットを撮影できます。認証はユーザー自身で行う必要があります。

サービス呼び出し

状態を変更するサービスの呼び出しには注意してください。通常、ユーザーから明示的に依頼された場合、またはテスト目的の場合にのみ実行します。

エンティティの命名

すべてのエンティティは domain.object_id の形式に従います。一般的なドメインは次のとおりです。

• light - ライト
• switch - スイッチ
• sensor - センサー（読み取り専用）
• binary_sensor - バイナリーセンサー（オン／オフ）
• climate - サーモスタット
• automation - オートメーション
• script - スクリプト
• input_boolean、input_number、input_select、input_text、input_datetime - ヘルパーエンティティ
• person - 人
• device_tracker - デバイス追跡
• camera - カメラ
• media_player - メディアプレーヤー
• cover - カバー（ブラインド、ガレージドア）
• fan - ファン
• lock - ロック

一般的なトリガープラットフォーム

• state - エンティティの状態変化
• numeric_state - 数値がしきい値を超える
• sun - 日の出／日の入り
• time - 指定した時刻
• time_pattern - 時刻のパターン（N 分ごと）
• event - HA イベントの発生
• webhook - Webhook トリガー
• zone - ゾーンへの入場／退出
• device - デバイス固有のトリガー

一般的な条件プラットフォーム

• state - エンティティの状態が値と一致する
• numeric_state - 数値の比較
• time - 時間帯
• sun - 日の出／日の入りの前後
• zone - 人がゾーン内にいる
• template - テンプレートの評価

オートメーションのモード

• single - すでに実行中の場合、新しい実行を開始しません。
• restart - 実行中にトリガーされた場合、オートメーションを再起動します。
• queued - すでに実行中の場合、実行をキューに入れます。
• parallel - 複数の実行を同時に許可します。