はじめに
Home Assistantに登録されたデバイスやエンティティをMatterコントローラーへ公開するための[Matterbridge(https://matterbridge.io/ "Matterbridge")のインストール手順メモです。
2026/08/14追記
インストール後にmDNS警告が出る挙動に対する対応を[Matterbridgeアドオンインストール]章に追記しました。
Matterbridgeとは
Matterbrigeは、Home AssistantのデバイスやエンティティをMatter対応デバイスとして他のMatterコントローラーへ公開するためのブリッジソフトウェアです。
Home Assistantに作成した状態管理エンティティや、Home Assistantだけでしか対応できていない機器をMatterデバイスとして公開できるため、AlexaやApple Home、Google Homeなどと直接連携ができないデバイスがMatter連携できるようになります。
関連記事
【Home Assistant】インストールメモ
【Home Assistant】初期設定メモ
【Home Assistant】SSHアドオンインストールメモ
【Home Assistant】Matterbridgeインストールメモ
【Home Assistant】Google Drive Backupアドオンインストールメモ
前提環境
この手順は、以下の環境を前提としています。
| 項目 | バージョン |
|---|---|
| Home Assistant OS | 2026.7.4 |
インストール手順
ロングアクセストークン生成
MatterbridgeとHome Assistantが連携するためのトークンを予め生成するため、左メニュー下部のアカウント部を押してアカウント画面を開きます。
セキュリティタブコンテンツ下部の長期間有効なアクセストークンのトークンの作成を押します。
トークン名は任意の名称で問題ありませんが、ここではMatterbridge Access Tokenとして用途がわかる名前とします。
生成されたトークンは再表示されないため、必ず退避しておきます。
(後続手順における、Matterbridgeのmatterbridge-hassプラグイン設定で利用します)
Matterbridgeアドオンインストール
左メニューの設定を開き、アプリを選択します。
通常の公式アプリをインストールする場合と同様にアプリをインストールを押します。
Matterbridgeは通常公式アプリではないため、右上の…ボタンからリポジトリを選択し、Matterbridgeリポジトリを追加します。
リポジトリ一覧画面の右下の追加を押します。
リポジトリURLに以下を入力して追加を押して、一覧に追加されたことを確認します。
https://github.com/luligu/matterbridge-home-assistant-addon
一覧に確認されたことを確認し、左上の←からアプリストアに戻ります。
アプリの検索フィールドに"matterbdidge"で検索を行い、Matterbridgeを選択します。
Matterbridgeアプリ画面のインストールを押して、インストールします。
インストールが完了したら、コントロールの開始を押して、Matterbridgeを開始します。
なお、Matterbridgeは、Home Assistant起動と同時にサービスを提供させたいため、必ず起動時に開始を有効にしておきます。
サービスが開始されたらWeb UIを開くを押して、Matterbridge管理画面を表示します。
WebUI上ではサービスが開始されたように表示されても、実際にはサービスが完全に起動されるまではWeb UIを開くを押すと、アプリがまだ準備できていないようです。もう一度お試しください。と502: Bad Gatewayエラーレスポンス表示となります。
サーバースペックにもよりますが、1～2分かかることがあるため、しばらく待ってからリトライしてください。
正常にMatterbridgeが起動されて、管理画面が表示されることを確認します。
MatterbridgeのWebUI上部のSettingsを押します。
Matter settingsのMdns interfaceにSystem infoのInterface nameの内容を転記してください。
転記が完了したら、右上の回転矢印アイコンを押してMatterbridgeを再起動し、再度WebUIが表示されるまで待ちます。
Matterbridge-HASSプラグインインストール
Matterbridgeアドオンインストールのみでは何もデバイスは公開されない状態のため、MatterbridgeにとってのHome Assistantプラグインをインストールします。
Install pluginsの虫眼鏡マークを押します。
プラグイン一覧の中からmatterbridge-hassを選択(クリック)して、画面下のSELECTを押します。
選択されたことが分かりづらいですが、画面右下に選択されているプラグイン名が表示されていることを確認します。
(HASSとはHome Assistantの一般的な略称です)
この時点では、まだプラグインはインストールされていないため、INSTALL押してインストールします。
右下トーストにInstalled package matterbridge-hass@latestと表示され、インストールが完了したことを確認します。
インストールが完了するとProcess log画面は自動で閉じます(Close on successチェックボックスが外れている場合は閉じません)。
なお、Home Assistant Plugin: configure Host and Tokenと表示されますが、このタイミングでは無視します。
また、Restart requiredと再起動を促されますが、このタイミングでは無視します。
Plugins一覧に追加されたmatterbridge-hassのActions内の歯車アイコンを押して、プラグインの設定をします。
Matterbridge hass pluginの各種設定を行います。
このタイミングで手順序盤で生成したトークンを利用します(トークンを紛失した場合や未作成の場合は[ロングアクセストークン生成]手順の通りにトークンを生成してください)。
様々な設定項目がありますが、ここでは動作させるための最低限の項目のみを設定します。
表の内容の項目を設定したのち、設定ダイアログ下部のCONFIRMを押して設定を登録します。
| 項目 | 設定値 |
|---|---|
| Host | ws://localhost:8123 |
| Token | ([ロングアクセストークン生成]手順で生成したトークン文字列) |
画像ではIPアドレスが記載されてますが、localhostで問題ありません
Matterbridge管理画面上部の丸矢印アイコンを押して、Matterbridgeアドオンサービスを再起動します。
再起動中はReconnecting to Matterbridge (attempt 2)...と表示され、再度管理画面が表示されるまで数十秒程度待ちます。
管理画面が表示されてmatterbridge-hassプラグインのStatusがRunningとなっていることを確認して、アドオン自体のインストールは完了です。
公開デバイス設定
Matterbridge管理画面のDevices一覧にはHome AssistantがMatterデバイスとして提供できるエンティティを含むデバイス一覧が表示されます。
このうち、Actionsにチェックが付いているものについて、Matterデバイスとして公開されるため、公開する必要のあるものだけにチェックを入れます。
公開デバイス設定を変更後は、Matterbridgeアドオンサービスを再起動する必要があります。
- Matterbridgeインストールタイミングで既にデバイスやエンティティが登録されている場合、初期値ですべてチェックがついている状態となり、大量にMatterコントローラー側に公開されてしまうため、注意してください。
- Alexa Devicesなどの外部デバイスを連携するプラグインが導入されている場合、それらのデバイスも公開されます(Alexaアプリを利用していると、Alexaアプリと連携したデバイスと、Home Assistant+Matterbridge経由のデバイスが二重表示されるため、Matterbridge側は非表示にする必要があります)。
- Matterbridgeアドオンインストール後にHome Assistant側で公開するエンティティなどを新たに追加した場合は、公開適用するためにMatterbridgeアドオンサービスを再起動する必要があります(
Devices一覧末尾にRestart requiredと表示されます)。**
Matterデバイス登録
Matterbridgeで公開したエンティティやデバイスをMatterコントローラー側に登録する方法は通常のMatterデバイス同様手順で、管理画面のQRコードまたは、セットアップコード(Manual pairing code)をMatterコントローラー側で読み取って連携します。
Matterコントローラーに登録を行うとMatterbridge管理画面のQRコードは非表示となり、通常のMatterデバイス共有同様に、コントローラー側で共有コードを発行してその他のMatterコントローラーと登録する流れとなります。
なお、再ペアリングを行う場合は、Matterbridge管理画面のPaired fabricsパネル内のFabricゴミ箱ボタンを押して連携コントローラーを削除します。
例としてiOS(iPhone)のAqara Homeアプリと連携した場合、下記のようにデバイス認識が行われます。
Home Assistant側で登録した名称でデバイス認識がされず、どのデバイスがHome Assistant上のデバイスに対応するのかの把握が困難なため、1つずつの連携が現実的なようです(AlexaアプリやGoogleHomeアプリなどでは試していないため、アプリによって挙動は異なるかもしれません)。
- HomeAssistant Matterbrige : Matter連携時に登録対象となるブリッジデバイス本体で名称は登録時に自身で入力します。
- Matterbridge Virtual Device : Matterbridge再起動に対応するスイッチデバイス(認識順序によってアップデートと逆になるかもしれません)。
- Matterbridge Virtual Device-1 : Matterbridgeアップデートに対応するスイッチデバイス(認識順序によって再起動と逆になるかもしれません)。
- input_boolean : Home Assistantの切り替えタイプ種別で登録したヘルパーのいずれかに対応
- input_boolean-1 : Home Assistantの切り替えタイプ種別で登録したヘルパーのいずれかに対応
- input_botton : Home Assistantのボタン入力タイプで登録したヘルパーのいずれかに対応
