home-assistant

Home Assistant

概要

このスキルは、スマートホームデバイスの制御やセンサーデータ、状態情報の取り込みなど、ユーザーがプロジェクトに Home Assistant を統合するのを支援します。接続設定を案内し、認証情報を検証するほか、Python と Node.js の両方を対象とした包括的な API リファレンスを提供します。

このスキルを使用する場面

ユーザーが次のことを希望する場合に、このスキルを使用してください。

• アプリケーションを Home Assistant に接続する
• スマートホームデバイス（照明、スイッチ、サーモスタットなど）を制御する
• Home Assistant からセンサーデータやエンティティの状態を読み取る
• 独自のロジックに基づいてホームコントロールを自動化する
• Home Assistant のデータを使ってダッシュボードや監視ツールを構築する
• 既存の Python または Node.js プロジェクトに Home Assistant を統合する

接続設定のワークフロー

ステップ 1：接続情報を収集する

ユーザーから次の 2 つの情報を収集します。

1. Home Assistant の URL：Home Assistant にアクセスできるウェブアドレス
2. 長期アクセストークン：API アクセス用の認証トークン

ステップ 2：URL を正規化する

ユーザーがパス部分を含む URL（例：http://homeassistant.local:8123/lovelace/dashboard）を指定した場合は、ホストとポートより後ろをすべて削除して正規化します。ベース URL に含めるのは、スキーム、ホスト、ポートのみです。

• ✓ 正しい例：http://homeassistant.local:8123
• ✗ 誤った例：http://homeassistant.local:8123/lovelace/dashboard

ステップ 3：トークンの確認方法を案内する

長期アクセストークンの場所がわからない場合は、次の手順を案内します。

1. Home Assistant のウェブインターフェースにログインします
2. ユーザープロフィール（左下にあるユーザーアイコンまたは名前）をクリックします
3. 「Security」タブをクリックします
4. 「Long-Lived Access Tokens」セクションまでスクロールします
5. 「Create Token」をクリックします
6. トークンに名前を付けます（例：「My Project」）
7. 生成されたトークンをコピーします（表示されるのは 1 回のみです）

ステップ 4：接続を検証する

curl を使って接続をテストし、Home Assistant の設定情報を取得します。

curl -X GET \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  <URL>/api/config

例：

curl -X GET \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  http://homeassistant.local:8123/api/config

成功時の出力：

{
  "location_name": "Home",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "elevation": 0,
  "unit_system": {
    "length": "km",
    "mass": "g",
    "temperature": "°C",
    "volume": "L"
  },
  "time_zone": "America/Los_Angeles",
  "version": "2024.1.0",
  "config_dir": "/config",
  "allowlist_external_dirs": [],
  "allowlist_external_urls": [],
  "components": ["automation", "light", "switch", ...],
  "config_source": "storage"
}

レスポンスから得られる主な情報：

• version：Home Assistant のバージョン（例：「2024.1.0」）
• location_name：Home Assistant インスタンスの名前
• time_zone：設定されているタイムゾーン
• components：読み込まれているコンポーネント／インテグレーションの一覧

失敗時のシナリオ：

認証エラー（401）：

{"message": "Invalid authentication"}

接続エラー：

curl: (7) Failed to connect to homeassistant.local port 8123: Connection refused

認証に失敗した場合は、次の点を確認します。

1. 長期アクセストークンが正しいこと
2. トークンが削除または期限切れになっていないこと
3. URL が正しいこと（http/https とポートを含む）

ステップ 5：実装に進む

接続の検証が完了したら、ユーザーのプログラミング言語と要件に応じて、インテグレーションの実装を支援します。

主なインタラクションパターン

重要：以下の WebSocket API コマンドは、ユーザーが Home Assistant とやり取りする際の中核となります。これらは自動化エンジンを活用し、Home Assistant のネイティブ構文を使うことでスクリプトを簡潔に保ちます。

自動化エンジンのコマンド（WebSocket API）

これらのコマンドには WebSocket API 接続が必要です。Home Assistant とやり取りする、最も強力で柔軟な方法を提供します。

1. subscribe_trigger - 特定のイベントをリッスンする

使用する場面：特定の条件（状態変化、時刻のパターン、Webhook など）が発生したときに通知を受けたい場合

コマンドの構造：

{
  "type": "subscribe_trigger",
  "trigger": {
    "platform": "state",
    "entity_id": "binary_sensor.motion_sensor",
    "to": "on"
  },
  "variables": {
    "custom_var": "value"
  }
}

使用する理由：すべての状態変化を購読してから絞り込むのではなく、対象とするトリガーを直接購読します。これにより効率が向上し、Home Assistant のネイティブなトリガー構文を使用できます。

2. test_condition - サーバー側で条件をテストする

使用する場面：スクリプトにロジックを実装せずに、条件が満たされているか確認したい場合

コマンドの構造：

{
  "type": "test_condition",
  "condition": {
    "condition": "numeric_state",
    "entity_id": "sensor.temperature",
    "above": 20
  },
  "variables": {
    "custom_var": "value"
  }
}

使用する理由：条件のロジックを Home Assistant に任せます。Home Assistant の強力な条件エンジンを使いながら、スクリプトを簡潔に保てます。

3. execute_script - 複数のアクションを実行する

次の場合に使用します：wait_for_trigger、遅延、サービス呼び出しなどを含む一連のアクションを実行する必要がある場合

コマンドの構造：

{
  "type": "execute_script",
  "sequence": [
    {
      "service": "light.turn_on",
      "target": {"entity_id": "light.living_room"}
    },
    {
      "wait_for_trigger": [
        {
          "platform": "state",
          "entity_id": "binary_sensor.motion",
          "to": "off",
          "for": {"minutes": 5}
        }
      ]
    },
    {
      "service": "light.turn_off",
      "target": {"entity_id": "light.living_room"}
    }
  ],
  "variables": {
    "custom_var": "value"
  }
}

使用する理由：

• Home Assistant のネイティブ構文を使って、複雑な自動化ロジックを実行できます
• wait_for_trigger を使ってイベントを待機できます
• 複数のアクションを連結できます
• スクリプトは最小限に保ちます。ロジックはすべて HA 構文で記述します
• 応答データの取得：サービス呼び出しの応答を取得するには、結果を応答変数に格納し、スクリプトの結果として設定します

応答データを含む例：

{
  "type": "execute_script",
  "sequence": [
    {
      "service": "weather.get_forecasts",
      "target": {"entity_id": "weather.home"},
      "response_variable": "weather_data"
    },
    {
      "stop": "Done",
      "response_variable": "weather_data"
    }
  ]
}

レジストリの重要情報

Home Assistant の情報アーキテクチャを理解するには、次の情報も使用してください。

• config/entity_registry/list：エンティティとその一意の ID を確認します
• config/device_registry/list：デバイスとそのエンティティを確認します
• config/area_registry/list：エリアの構成を把握します
• config/floor_registry/list：複数階のレイアウト情報を確認します

家の現在の状態

家の現在の状態を表示するアプリケーションをユーザーが構築する場合は、次を使用してください。

• subscribe_entities：すべてのエンティティ状態のリアルタイム更新を取得します（Home Assistant JS WebSocket は、この機能を標準でサポートしています）

実装ガイダンス

Python プロジェクト

Python ベースのプロジェクトでは、Python API リファレンスを参照してください。

• ファイル：references/python_api.md
• 使用方法：Python 統合を実装する際に、このリファレンスを読み込みます
• 内容：
  • サンプルコード：一般的なユースケースを示す Python スクリプトです
• 主な操作：自動化エンジンのコマンド、状態の取得、サービスの呼び出し、イベントのサブスクライブ、エラー処理

Node.js プロジェクト

Node.js ベースのプロジェクトでは、Node.js API リファレンスを参照してください。

• ファイル：references/node_api.md
• 使用方法：Node.js 統合を実装する際に、このリファレンスを読み込みます
• 内容：
  • home-assistant-js-websocket ライブラリを使用した WebSocket API の例

ベストプラクティス

1. エラー処理：ネットワーク障害や認証の問題に対して、必ず適切なエラー処理を実装してください
2. 接続テスト：実装を進める前に、接続を検証してください
3. リアルタイム更新：監視を行う場合は、REST エンドポイントのポーリングではなく、WebSocket API を使用してください

empty-hass でのテスト

実際の Home Assistant インスタンスに接続せずにコードをテストしたい場合は、empty-hass を使用できます。これは、認証が事前設定された空の Home Assistant インスタンスを起動する CLI ツールです。

クイックスタート

uvx を使って empty-hass を実行します（uv がインストールされた Python が必要です）。

uvx --from git+https://github.com/balloob/empty-hass empty-hass

これにより、次の機能を備えた Home Assistant インスタンスが http://localhost:8123 で起動します。

• セットアップウィザードをスキップできる、オンボーディング済みの設定
• 一時的な設定ディレクトリ（終了時にクリーンアップされます）

利用可能なオプションとログイン認証情報を確認するには、--help を付けて実行します。

uvx --from git+https://github.com/balloob/empty-hass empty-hass --help

これは次の場合に便利です。

• 本番環境のインスタンスに接続する前に、API 統合コードをテストする
• 実際のデバイスに影響を与えずに、開発やデバッグを行う
• テスト用に Home Assistant インスタンスが必要な CI/CD パイプライン

一般的な統合パターン

データダッシュボード

センサーの状態を読み取り、カスタムダッシュボードまたは監視アプリケーションに表示します。

自動化ロジック

エンティティの状態変化をサブスクライブし、条件に基づいてカスタムアクションを実行します。

外部トリガー

外部イベント（Webhook、スケジュールされたジョブ、ユーザーアクション）から Home Assistant サービスを呼び出します。

データエクスポート

分析やバックアップのために、Home Assistant から履歴データを取得します。