Home Assistant 統合（HACS）

Yunkan は公式の Home Assistant カスタム統合を提供開始しました。これは薄いクライアントで、Yunkan サーバーの通常 API と通信し、サーバーの機能を Home Assistant のネイティブエンティティ・メディアブラウザ・サービスにマッピングします。録画・検知・アカウントのロジックはすべてサーバー側に残ります。

お使いの Home Assistant の HACS でこのリポジトリをカスタムリポジトリとして開きます。

できること

• カメラ：ネイティブ WebRTC（低遅延、HLS フォールバック）+ JPEG スナップショット——ピクチャーグランスカード、エリアダッシュボード、HomeKit エクスポート、camera.snapshot。
• 検知センサー（カメラごと）：人・車両・動物・荷物・顔・転倒・赤ちゃんの泣き声・動き——認識した名前 / ナンバーも付与。
• オブジェクト数センサー + 認識した顔 / ナンバーセンサー。
• スイッチ：AI 検知、録画、機能別検知トグル、PTZ 自動追尾——さらにハブ上のサーバー全体検知スイッチ。
• デバイスページの操作：スナップショット更新と PTZ 方向ボタン、PTZ プリセットのドロップダウン、音声ブロードキャスト入力欄。
• デバイストリガーとアクション（自動化用）、およびすぐ使える通知ブループリント。
• メディアブラウザで録画・イベント・スナップショットを閲覧（Home Assistant 自身の認証を経由）。

必要条件

• Home Assistant 2024.11 以降（ネイティブ WebRTC カメラのため）。
• 到達可能な Yunkan サーバー——メイン入口アドレス（nginx 入口、通常ポート 23406）を使用。
• Yunkan アカウント。PTZ・検知スイッチ・音声ブロードキャストには 管理者 アカウントが必要。閲覧は任意のアカウントで可能。

HACS でインストール

1. 1

   HACS で開く

   上の HACS で開く ボタンをクリック（または HACS で右上のメニュー → カスタムリポジトリからリポジトリ URL をカテゴリ *Integration* で追加）。

2. 2

   インストールして再起動

   HACS で Yunkan を検索してインストールし、Home Assistant を再起動します。

3. 3

   統合を追加

   設定 → デバイスとサービス → 統合を追加 → Yunkan を開き、サーバー URL を入力します。続いて Home Assistant が Yunkan のログイン画面を開くので、いつもの方法でログインして「許可する」を押します。詳しくは次のセクションで説明します。

接続方法：Yunkan に移動して許可を押す

新しいバージョンの統合はパスワードを尋ねません。統合を追加するときは Yunkan のサーバーアドレスだけを入力します。Home Assistant が Yunkan のログイン画面を開くので、いつもの方法でログインし（パスワード、確認コード、パスキー、シングルサインオンのどれでも構いません）、内容を確認して「許可する」を押します。Yunkan は専用のトークンを Home Assistant に渡すので、パスワードは常にあなたの手元にとどまります。

• 2 段階認証を有効にしたアカウントでも接続できます —— ログインの手順は Yunkan 自身の画面で完結し、確認コードもそこで入力します。
• いつでも切断できます —— システム設定 → API トークンにこのトークンが表示されます（名前に Home Assistant が入っています）。削除すれば統合はただちにアクセス権を失います。戻したいときは Home Assistant 側で許可の手順をもう一度行ってください。
• 古い Yunkan サーバーには許可の画面がありません —— 統合は自動的にユーザー名とパスワードの入力に切り替わり、以前と同じ動作になります。この方式では 2 段階認証を有効にしたアカウントに接続できないので、先にサーバーを新しいバージョンへ更新してください。

無料版 vs Pro

カメラ・スナップショット・イベント・センサー・メディアブラウザ・PTZ はどの Yunkan サーバーでも利用できます。AI 検知 と 音声ブロードキャスト は Pro 機能で、無料版ではこれらの操作はアップグレード案内を表示し、無言で失敗しません。