翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Matter プラグイン **Topics** + [Matter プラグインとは](#what-is-matter-plugin) + [Matter プラグインを構築する方法](#how-to-build-matter-plugin) + [クイックスタート: Matter プラグインをセットアップして実行する](#quickstart-setup-run-matter-plugin) + [以下の手順は、Raspberry Pi、つまりコミッショナーで実行します。](#raspberry-pi-commissioner-steps) + [サポートされている Matter デバイスタイプ](#supported-matter-device-types) + [追加のクラスターのサポートの追加](#adding-support-for-additional-clusters) + [Matter Controller のさまざまなソリューションを統合する](#integrate-different-matter-controller-solutions) ## Matter プラグインとは Matter Plugin は、 Managed Integrations Hub SDK [カスタムプロトコルプラグイン](custom-protocol-plugin.md)の機能を使用して構築されたリファレンス実装です。これにより、ハブは、Matter 仕様に従って、同じネットワーク上のローカルデバイスと、マネージド統合を介してリモートの両方で Matter デバイスを制御できます。 ![Matter Plugin と Managed Integrations Hub SDK の統合を示すアーキテクチャ図](https://docs.aws.amazon.com/ja_jp/iot-mi/latest/devguide/images/iotmi-matter-plugin.png) Matter プラグインは Hub SDK に含まれています。Matter デバイスと通信し、Matter Controller 機能を実装し、マネージド統合を介してリモートコントロールパスを公開します。 chip-tool は、[connectedhomeip](https://github.com/project-chip/connectedhomeip) のコマンドラインベースのリファレンスコントローラーです。Matter ファブリックのコミッショナー/コントローラーとして機能し、デバイスのコミッショニング、属性の読み取り/書き込み、コマンドの呼び出しを可能にし、開発と相互運用性のテストを目的としています。このガイドでは、Matter プラグインはチップツールを使用して Matter デバイスを制御し、モバイルアプリからの Matter コミッショニングもデモンストレーションします。 このディストリビューションの範囲には、本番稼働用モバイルアプリケーションは含まれません。また、CSA ラボテストや認定などの認定や本番稼働用アクティビティも対象としていません。これらは引き続き製品開発プロセスの一部です。 ## Matter プラグインを構築する方法 Matter プラグインには、Hub SDK に加えて次の依存関係があります。 + OpenSSL 3.0.x: OpenSSL のバージョン要件は厳しくありません。ほとんどの場合、システムのデフォルトバージョンは問題なく機能します。 + [nng](https://github.com/nanomsg/nng) v1.4.0 + [cJSON](https://github.com/DaveGamble/cJSON) v1.7.18 + [AWS IoT Device SDK CPP V2](https://github.com/aws/aws-iot-device-sdk-cpp-v2) v1.33.0 + [AWS SDK CPP](https://github.com/aws/aws-sdk-cpp) 1.11.433 次のコマンドを使用してリポジトリを設定します。 ``` cd IotMI-DeviceSDK-MatterPlugin mkdir build cd build cmake .. ``` 次に、次のコマンドを使用してビルドします。 ``` cmake --build . ``` 構築後、ライブラリパスを LD\_LIBRARY\_PATH に追加します。 ``` export LD_LIBRARY_PATH=/path/to/libraries:$LD_LIBRARY_PATH ``` ## クイックスタート: Matter プラグインをセットアップして実行する Matter プラグインと対応する Matter ソリューションをセットアップするには、以下のステップに従います。このフローでは、コミッショニングと基本制御用の「モバイルアプリ」を表す Hub (Hub SDK \+ Matter プラグインを実行) と Raspberry Pi の 2 つのマシンを想定しています。 ### ノード ID 管理 Matter では、デバイス、コントローラー、コミッショナーなど、ファブリック上のすべてのノードに一意のノード ID が必要です。衝突を回避するには、一貫した割り当てポリシーが必要です。このガイドでは、ノード IDsます。本番環境では、ノード IDsを適切に管理する必要があります。 このドキュメントの例では、Hub のチップツール ( Matter プラグインで使用) はデフォルトのノード ID を使用し`112233`、モバイルアプリ Raspberry Pi のチップツールはノード ID を使用します`123456`。新しくコミッショニングされたデバイスには、同じファブリック (クイックスタートの 101 など) に競合しないノード IDs が割り当てられます。 ### 前提条件 作業を開始する前に、次の項目が揃っていることを確認してください。 + Hub はすでに Managed Integrations にオンボードされており、Hub SDK がデプロイされています (スクリプトまたは systemd 経由）。まだオンボードしていない場合は、[ハブオンボーディングの設定](managedintegrations-sdk-v2-cookbook-hubsetup.md)「」に従って マネージド統合にオンボードし、[マネージド統合 Hub SDK をインストールして検証する](managedintegrations-sdk-v2-cookbook-deployment.md)「」に従ってハブ SDK を実行します。オンボーディングが完了したら、ハブのマネージドモノ ID を書き留めます。これは後で必要になります。 + チップツールと AWS CLI の両方を実行できる Raspberry Pi (または任意のマシン) がある。 + テスト用の Matter デバイスがあります。実際のデバイスでも仮想 Matter デバイスでもかまいません ([照明アプリケーション](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/linux)など) ### ステップ 1. Raspberry Pi (モバイルアプリを表す) を準備する + AWS CLI をインストールし、chip-tool を構築してインストールする + [公式の chip-tool ビルドガイドに従って chip-tool を構築](https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md#building-from-source)します。検証したバージョンは v1.4.2.0 です。 + [公式の手順に従って](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) AWS CLI をインストールします。 + チップツール用の永続的ストレージを準備する ``` mkdir -p $HOME/iotmi/matter/ ``` + コミッショナー証明書チェーンを生成する (このチップツール`123456`にノード ID を割り当てる) ``` cd connectedhomeip/ cd out/chip-tool/ ./chip-tool pairing get-commissioner-root-certificate \ --commissioner-nodeid 123456 \ --storage-directory $HOME/iotmi/matter/ ``` 生成されたチェーンは、次の場所に保存されます。 `$HOME/iotmi/matter/chip_tool_config.alpha.ini` このファイルは後で Hub にコピーします。 ### ステップ 2. ハブを準備する ( Matter プラグインを実行する) + Hub で chip-tool を構築またはインストールします ( Matter プラグインはそれを使用して Matter オペレーションを実行します）。[chip-tool ビルドガイド](https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md#building-from-source)を参照してください。検証したバージョンは v1.4.2.0 です。 また、後で使用するために、チップツールの sha256sum も必要です。次のコマンドを使用して sha256sum を取得できます。 ``` sha256sum /path/to/chip-tool ``` + ストレージを準備し、Raspberry Pi からコミッショナーファイルをコピーする ``` mkdir -p $HOME/iotmi/matter/ # From Raspberry Pi to Hub (example): # scp $HOME/iotmi/matter/chip_tool_config.alpha.ini user@HUB_HOST:$HOME/iotmi/matter/ ``` + Matter プラグインを実行する (チップツールパス、SHA256、ストレージフォルダを提供する) ``` ./iotmi_matter_plugin \ --chip-tool-path /path/to/chip-tool \ --sha256sum SHA256SUM_OF_THE_CHIP_TOOL \ --storage-folder $HOME/iotmi/matter/ \ --node-id 112233 ``` ## 以下の手順は、Raspberry Pi、つまりコミッショナーで実行します。 ### ステップ 3. Matter デバイスのコミッショニング (Raspberry Pi 上) チップツールを使用して、デコードされた QR コードを使用してデバイスをコミッショニングし、Wi-Fi 認証情報をプロビジョニングします。この例では、デバイスはノード ID 101 を使用し、コミッショナーノード ID は です`123456`。 ``` ./chip-tool pairing code-wifi 101 \ YOUR_WIFI_SSID YOUR_WIFI_PW \ MT:MFAA0W8C00UFQV2VL00 \ --bypass-attestation-verifier 1 \ --commissioner-nodeid 123456 \ --storage-directory $HOME/iotmi/matter/ ``` **注意**: + `101` はデバイスの Matter ノード ID です (別の値を選択できます）。 + `MT:MFAA0W8C00UFQV2VL00` は、デバイスのデコードされた QR コンテンツです。QR コードからデコードされたコンテキストを取得するには、QR コードアプリケーションまたはライブラリを選択してデコードする必要があります。QR コードのデコードをサポートするウェブサービスを使用することもできます。 + `-bypass-attestation-verifier 1` はテスト専用です。本番環境では、PAA ストアを更新し、認証チェックを実行します。 chip-tool は、QR コードや PIN コードと Thread または WiFi デバイスとのペアリングなど、さまざまなペアリング方法をサポートしています。[chip-tool pairing コマンド](https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md#pairing)の詳細については、公式ドキュメントを参照してください。 ### ステップ 4. デバイスに対する Hub アクセスの付与 (ACL の更新) コミッショニング後、Hub のチップツールがデバイスを制御できるようにします。この例では、ノード ID `123456` (Raspberry Pi) には管理者アクセス許可 (5) があり、ノード ID `112233` (Hub) には管理アクセス許可 (4) があります。 ``` chip-tool accesscontrol write acl \ '[{"fabricIndex":1,"privilege":5,"authMode":2,"subjects":[123456], "targets": null},{"fabricIndex":1,"privilege":4,"authMode":2,"subjects":[112233], "targets": null}]' \ 101 0 \ --commissioner-nodeid 123456 --storage-directory $HOME/iotmi/matter/ ``` ### ステップ 5. デバイスのマネージド型モノを作成する (ユーザーガイド付きセットアップ) + 検出を開始します ( を Hub のマネージドモノ ID に置き換えます）。 ``` aws iot-managed-integrations start-device-discovery \ --discovery-type CUSTOM \ --custom-protocol-detail '{"Name": "Matter", "NodeId":"101", "FabricId":"1"}' \ --controller-identifier ``` サンプルレスポンスには、ユーザーガイドの設定ジョブ ID が含まれます。 ``` { "Id": "USER_GUIDED_SETUP_JOB_ID", "StartedAt": 1753683326.056 } ``` + ジョブ ID を使用して検出されたデバイスをクエリします。 ``` aws iot-managed-integrations \ list-discovered-devices --identifier ``` レスポンス例: ``` { "Items": [ { "DeviceTypes": [], "DiscoveredAt": "2025-08-05T06:46:35.407000+08:00", "AuthenticationMaterial": "" } ] } ``` + AuthenticationMaterial を使用してデバイスのマネージドモノを作成します。 ``` aws iot-managed-integrations create-managed-thing \ --role DEVICE \ --authentication-material-type DISCOVERED_DEVICE \ --authentication-material "" ``` サンプルレスポンス (デバイスのマネージドモノ ID を使用): ``` { "Id": "DEVICE_MANAGED_THING_ID", "Arn": "arn:aws:iotmanagedintegrations:eu-west-1:228183742813:managed-thing/515cf5a707ec41aaabb9914a1dd2889f", "CreatedAt": "2025-08-06T15:00:08.718000+08:00" } ``` ### ステップ 6. マネージド統合によるデバイスの制御 `send-managed-thing-command` コマンドを使用して、マネージドモノにコマンドを送信します。 ``` json=$(jq -cr '.|@json' < 次のコマンドを送信して、デバイスの状態を取得します。 ``` aws iot-managed-integrations get-managed-thing-state \ --managed-thing-id "DEVICE_MANAGED_THING_ID" ``` サンプル結果: ``` { "Endpoints": [ { "endpointId": "1", "capabilities": [ { "id": "matter.OnOff@1.4", "name": "On/Off", "version": "1.4", "properties": [ { "value": { "lastChangedAt": "2025-08-14T13:16:02.132Z", "propertyValue": false }, "name": "OnOff" } ] } ] } ] } ``` ### ステップ 8. ハブからマネージド型モノを削除する + 次のコマンドを使用して、ハブからマネージドモノを削除する ``` aws iot-managed-integrations delete-managed-thing \ --identifier "DEVICE_MANAGED_THING_ID" ``` + Raspberry Pi のファブリックからデバイスのペアリングを解除します (必要な場合）。 ``` ./chip-tool pairing unpair 101 \ --commissioner-nodeid 123456 \ --storage-directory $HOME/iotmi/matter/ ``` ## サポートされている Matter デバイスタイプ | Matter デバイスタイプ | サポートされている機能 | | --- | --- | | [OnOffLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffPlug-inUnit.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)、[レベル制御 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) | | [DimmableLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmableLight.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)、[レベル制御 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) | | [ColorTemperatureLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/ColorTemperatureLight.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)、[レベルコントロール (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)、[カラーコントロール (0x0300)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/ColorControl.xml) | | [OnOffPlug-InUint](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffPlug-inUnit.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)、[レベル制御 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) | | [DimmablePlug-InUnit](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmablePlug-InUnit.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)、[レベル制御 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) | | [OnOffLightSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffLightSwitch.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [DimmerSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmerSwitch.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)、[レベル制御 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) | | [ColorDimmerSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/ColorDimmerSwitch.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[オン/オフ (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)、[レベルコントロール (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)、[カラーコントロール (0x0300)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/ColorControl.xml) | | [DoorLock](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DoorLock.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[ドアロック (0x0101)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/DoorLock.xml) | | [サーモスタット](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/Thermostat.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[サーモスタット (0x0201)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Thermostat.xml) | | [WaterLeakDetector](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/WaterLeakDetector.xml) | [識別 (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)、[ブール状態 (0x0045)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/BooleanState.xml) | ## 追加のクラスターのサポートの追加 Matter プラグインを拡張して追加のデバイスタイプと機能をサポートするには、次のパターンに従って **matter\_action\_converter.cpp** を変更します。 **実装パターン:** 1. 列挙型とビットマップのマッピングを定義する 1. 書き込み可能な属性に UpdateState ロジックを追加する 1. クラスターアクションのコマンド処理を追加する 1. 状態レポートの属性解析を追加する **既存のクラスターをテンプレートとして使用します。** 1. **OnOff クラスター** - 基本的な列挙型、書き込み可能な属性、コマンド、属性レポートを含む 4 つのコンポーネントすべてを示す最も簡単なリファレンス 1. **DoorLock クラスター** - 複数の列挙型、ビットマップフィールド、構造体パラメータ、オプションのコマンドパラメータ、広範な属性カバレッジを示す複雑な例 サポートされているすべてのクラスター (Identify、OnOff、LevelControl、DoorLock、サーモスタット、ColorControl、BooleanState) はこの構造に従います。matter\_action\_converter.cpp の既存の実装を確認して、完全なパターンを理解します。 ## Matter Controller のさまざまなソリューションを統合する このセクションでは、さまざまな Matter Controller ソリューションを Matter プラグインと統合する方法に関するガイダンスを提供します。考えられるアプローチと重要な考慮事項を概説していますが、詳細な実装コードは提供していません。 Matter Controller ソリューションを統合するには、主に 2 つの方法があります。1 つ目は、カスタマイズされたチップツールで Matter プラグインを使用することです。2 つ目は、選択した Matter Controller を使用し、カスタムプロトコルライブラリを介してマネージド統合と統合することです。 ### カスタマイズされたチップツールで Matter プラグインを使用する このアプローチでは、Matter プラグインが チップツールのカスタマイズされたバージョンで動作するように拡張されています。これを実現するには、Matter Plugin ソースコードを変更し、追加のロジックを導入する必要がある場合があります。 + STDIO 解析ロジックを調整する: カスタマイズされたチップツールが別のパターンのログを生成する場合は、それに応じて解析ロジックを更新します。 + 安全なストレージの実装: Matter プラグインは、デバイス情報用のファイルベースのストレージメカニズムを提供します。本番稼働用の場合は、これをより安全なストレージ実装に置き換えるか、データに暗号化を適用します。また、 Matter Plugin をアンインストールする場合は、適切なクリーンアップ手順も必要です。 + バイナリ署名と整合性保護を実装する: 本番デプロイでは、カスタマイズされたチップツールと拡張 Matter プラグインの両方に整合性保護を適用する必要があります。これには、ソフトウェアリリースプロセスの一環としてのバイナリの署名、起動時の署名の検証、セキュアブートや OS レベルの整合性ツールなどのプラットフォームセキュリティ機能の統合が含まれます。 + タスク/イベントレート制限の導入: 過負荷を防ぐには、Matter プラグインに適切なタスクとイベントレート制限が含まれていることを確認します。本番デプロイでは、異常な更新パターンを検出し、影響を受けるデバイスまたはサブスクリプションを一時的に調整または停止するための基本的なメトリクスとモニタリングも追加する必要があります。このサーキットブレーカーのような動作は、リファレンス実装では提供されないため、お客様が実装する必要があります。 + チップツールのメイン関数ロジックを直接統合する: STDIO に依存したくない場合は、チップツールのメイン関数を Matter プラグインに統合できます。その後、標準入出力ロジックを ChptoolProc クラスの読み取り/書き込み関数に接続できます。 + コード生成のサポート: コード生成を通じて Matter 仕様バージョンの更新を処理するメカニズムを実装します。 + Matter 管理機能を実装します。これには、以下が含まれます。 + コミッショナー、コントローラー、および Matter デバイスにノード IDs を割り当てる。 + 複数のファブリックの管理。 チップツール側では、次の機能強化も推奨されます。 + 安全なストレージを使用する: chip-tool は Matter 証明書、プライベートキー、統計をローカルディレクトリに保存します。これを安全な実装に置き換えます。 + 並列処理を有効にする: デフォルトでは、Chip-Tool は一度に 1 つのコマンドを実行します。並列実行のサポートを追加すると、特定のシナリオの効率が向上する可能性があります。 ### マネージド統合での既存の Matter Controller の使用 Matter Controller がチップツールに基づいていない場合 (Python ベースの実装や関数コールベースのソリューションなど）、STDIO アプローチが適していない可能性があります。このような場合は、 Matter プラグインをリファレンスとして使用しながら[カスタムプロトコルプラグイン](custom-protocol-plugin.md)、 を使用して マネージド統合と直接統合できます。以下の考慮事項に注意してください。 + ファブリック ID とノード IDs: デバイスの追加/削除やキャッシュ属性などのデバイスメタデータが一貫して維持されていることを確認します。 + サブスクリプションの管理: 各デバイスは、状態を継続的に更新できるように、最大 1 つのアクティブなサブスクリプションを維持する必要があります。 + 状態の変更を伝達する: デバイスが状態を更新するときに、変更を検証し、 マネージド統合にイベントを伝達します。 + Matter データモデルトランスレーターを実装する: マネージド統合は Matter データモデルを使用しますが、その表現は JSON 形式です。Matter データモデル形式と JSON 表現をマッピングするには、トランスレーターが必要です。