hoval-connect-api

このリポジトリは、Hoval Connect IoTクラウドAPIの非公式かつリバースエンジニアリングされた文書と、HACS経由でインストール可能なHome Assistantカスタム統合を提供します。Hovalとは提携しておらず、以前のCANバス/MQTTゲートウェイプロジェクトの後継として提示されています。クラウド方式では追加ハードウェアは不要で、Hoval Connectアカウントの認証情報のみが必要です。 統合の機能 インストールは、リポジトリをカスタムHACS統合として追加し、Home Assistantを再起動して、Hoval Connectのメールアドレスとパスワードを入力することで行います。プラントと回路は自動的に検出されます。READMEではバージョン1.0.8以降が必要であることが強調されています。HovalのAzure Application Gatewayは、User-Agentに「homeassistant」を含むリクエストを拒否するため、統合は独自の識別子を送信します。古いリリースでは、認証情報やネットワークの問題に似たHTTP 403で失敗すると報告されています。 公開されるエンティティには以下が含まれます： - HV換気回路ごとのファンエンティティ：デバウンス入力付きの0～100%連続速度スライダー、オン/オフトグル、設定可能な起動モード（最後に観測された週間プログラムを再開、または明示的にweek1/week2）。 - HK暖房回路ごとの気候エンティティ：目標温度、現在の室温、HVACモードHeat/Auto/Off、回路ステータスを反映するHVACアクション。 - WW給湯回路ごとの給湯器エンティティ：10～65°Cを0.5°C刻みで設定する一時ブースト（深夜0時に失効）、およびヒートポンプとオフの動作モード。 - HV/HK/WW回路ごとのプログラム選択：week1、week2、エコモード、スタンバイ、定常。ユーザー定義のプログラム名を表示し、重複を区別します。 - 回路タイプでフィルタリングされたセンサーエンティティ：外気、排気、流量、室温、タンク、バッファ温度、風量、湿度、CO2/VOC、制御ステータス、運転時間、スイッチングサイクル、生成熱量、消費エネルギー、変調および関連値。 - プラントレベルのセンサー：天気状態、予報気温、最新イベントの種類/メッセージ/タイムスタンプ、アクティブイベント数。 - バイナリセンサー：オンライン/オフライン、エラーステータス、回路ごとの一時変更状態。 - 診断エクスポート：トークン、認証情報、プラントIDを自動的に秘匿化。 オプションには、起動モード、一時上書き期間、ポーリング間隔（デフォルト60秒）が含まれます。サービスhoval_connect.reset_temporary_changeは、ファン、気候、給湯器エンティティのアクティブな上書きをキャンセルします。内部的に統合は、TTLキャッシュ、自動更新、シングルフライトロックを備えた2段階トークン管理（IDトークンとPlant Access Token）を使用し、プラントがオフラインの場合は呼び出しをスキップし、進行中の回路リクエスト数を制限した並列フェッチを実行し、プラントと回路ごとに制御コマンドを直列化し、プログラム、イベント、天気に段階的キャッシュを適用します。再起動なしで新しい回路の動的検出をサポートし、ページ分割された応答を正規化します。 同梱のHome Assistant Blueprintは、オプションのサマーブーストを実装します。これは、オフィス以外の部屋が快適性しきい値を超え、外気が適度で室内より涼しい暖かい午後にHomeVentを90%に上げ、設定可能な条件で終了します。ライブ値、天気、イベントを読み取るためのスタンドアロンPythonおよびBash/curlの例も含まれています。 文書化された制限には、HV、HK、BL、WW、PS回路のみのサポート（ソーラーやフレッシュウォーターは対象外）、時間プログラム編集なし、エネルギーや温度履歴なし、休暇モード制御なし、Hovalアカウントごとに1つの設定エントリが含まれます。要件はHoval ConnectアカウントとHome Assistant 2024.11.0以降です。 APIドキュメント READMEは、クラウドアーキテクチャ（デバイスからIoTゲートウェイ、Azure IoT Hub、コアAPI、アプリ/統合へ）、インフラストラクチャURL、および2段階認証フローを文書化しています。SAP Cloud Identity Servicesに対するOAuth2パスワードグラントでIDトークン（約30分）を取得し、これをBearerトークンとして使用し、続いてプラント設定呼び出しでPlant Access Token（約15分）を取得し、X-Plant-Access-Tokenとして送信します。ブートストラップ、ユーザー設定、プラント、契約、プラント設定、回路、プログラム、設定、一時変更、休暇モード、パートナーエンドポイントのエンドポイントを、JSONペイロード例と回路タイプ（HK、BL、WW、FRIWA、HV、SOL、SOLB、PS、GW）に関する注記とともに列挙しています。2026年4月のAPI変更でv1回路エンドポイントが削除され、v3（一時変更はv4）が採用されたことを記録し、HTTP 204を返す制御エンドポイントを説明し、文書化されているが未テストのエンドポイントを注記しています。