本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 事項外掛程式 **Topics** + [什麼是事項外掛程式](#what-is-matter-plugin) + [如何建置事項外掛程式](#how-to-build-matter-plugin) + [快速入門：設定和執行事項外掛程式](#quickstart-setup-run-matter-plugin) + [下列步驟要在 Raspberry Pi 上執行，即委託人。](#raspberry-pi-commissioner-steps) + [支援的事項裝置類型](#supported-matter-device-types) + [新增對其他叢集的支援](#adding-support-for-additional-clusters) + [整合不同的事項控制器解決方案](#integrate-different-matter-controller-solutions) ## 什麼是事項外掛程式 事項外掛程式是使用 Managed Integrations Hub SDK [自訂通訊協定外掛程式](custom-protocol-plugin.md)功能建置的參考實作。它可讓您的中樞控制相同網路上的本機事項裝置，並遵循事項規格，以及透過受管整合從遠端控制。 ![顯示事項外掛程式與受管整合中樞 SDK 整合的架構圖](https://docs.aws.amazon.com/zh_tw/iot-mi/latest/devguide/images/iotmi-matter-plugin.png) 重要外掛程式包含在 Hub SDK 中。它與事項裝置通訊、實作事項控制器功能，並透過受管整合公開遠端控制路徑。 chip-tool 是來自[連線homeip](https://github.com/project-chip/connectedhomeip) 的命令列型參考控制器。它在事項結構上充當委託人/控制器，可讓您委託裝置、讀取/寫入屬性和叫用命令，並用於開發和互通性測試。在本指南中，事項外掛程式將使用晶片工具來控制事項裝置，並示範來自行動應用程式的事項委任。 此分佈的範圍不包含生產行動應用程式，也不涵蓋認證和生產活動，例如 CSA 實驗室測試和認證。這些仍是您的產品開發程序的一部分。 ## 如何建置事項外掛程式 除了 Hub SDK 之外，Matter 外掛程式還具有下列相依性： + OpenSSL 3.0.x：OpenSSL 版本需求不嚴格 – 在大多數情況下，系統的預設版本可以正常運作。 + [nng](https://github.com/nanomsg/nng) 1.4.0 版 + [cJSON](https://github.com/DaveGamble/cJSON) v1.7.18 + [AWS IoT 裝置 SDK CPP V2](https://github.com/aws/aws-iot-device-sdk-cpp-v2) 版 1.33.0 + [AWS 開發套件 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 ``` ## 快速入門：設定和執行事項外掛程式 請依照下列步驟設定事項外掛程式和對應的事項解決方案。流程假設兩台機器：Hub （執行 Hub SDK \+ 事項外掛程式） 和代表「行動應用程式」的 Raspberry Pi，用於測試和基本控制。 ### 節點 ID 管理 In Matter 中，布料上的每個節點，包括裝置、控制器和委託人，都必須具有唯一的節點 ID。為了避免衝突，需要一致的配置政策。在本指南中，節點 IDs是手動指派的；在生產環境中，您應該正確管理節點 IDs。 對於本文件中的範例，Hub 的晶片工具 （由事項外掛程式使用） 使用預設節點 ID `112233`，而行動應用程式 Raspberry Pi 上的晶片工具使用節點 ID `123456`。新委任的裝置會在相同的結構 （例如快速入門中的 101) 上指派不衝突IDs。 ### 先決條件 開始之前，請務必備妥下列項目： + 您的 Hub 已加入受管整合，且 Hub SDK 已部署 （透過指令碼或系統化）。如果尚未加入，請遵循 [Hub 加入設定](managedintegrations-sdk-v2-cookbook-hubsetup.md)加入受管整合，並[安裝和驗證受管整合 Hub SDK](managedintegrations-sdk-v2-cookbook-deployment.md)執行中樞 SDK。加入後，記下您中樞的受管物件 ID。稍後會需要此項目。 + 您有可同時執行 chip-tool 和 AWS CLI 的 Raspberry Pi （或任何機器）。 + 您有一個用於測試的事項裝置。它可以是實物裝置或虛擬實物裝置 （例如 [lighting-app](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/ ``` + 產生委託人憑證鏈 （將節點 ID 指派給`123456`此晶片工具） ``` 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. 準備 Hub （執行事項外掛程式） + 在 Hub 上建置或安裝晶片工具 (Matter 外掛程式會使用它來執行Matter 操作）。您可以參考 [晶片工具建置指南](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/ ``` + 執行事項外掛程式 （提供晶片工具路徑、其 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。委託 a Matter 裝置 （在 Raspberry Pi 上） 使用 chip-tool，使用解碼的 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` 是裝置的事項節點 ID （您可以選擇不同的值）。 + `MT:MFAA0W8C00UFQV2VL00` 是裝置的解碼 QR 內容。若要從 QR 程式碼取得解碼的內容，您需要選擇 QR 程式碼應用程式或程式庫進行解碼。您也可以使用支援解碼 QR 程式碼解碼的 Web 服務。 + `-bypass-attestation-verifier 1` 僅供測試使用。對於生產，請更新 PAA 存放區並執行認證檢查。 晶片工具支援不同的配對方法，包括與 Thread 或 WiFi 裝置配對的 QR 碼或 PIN 碼。如需 [chip-tool 配對命令](https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md#pairing)的詳細資訊，請參閱官方文件。 ### 步驟 4. 在裝置上授予中樞存取權 （更新 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/ ``` ## 支援的事項裝置類型 | 事項裝置類型 | 支援的功能 | | --- | --- | | [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)、[Thermostat (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\_action\_converter.cpp**： **實作模式：** 1. 定義列舉和點陣圖的映射 1. 新增可寫入屬性的 UpdateState 邏輯 1. 新增叢集動作的命令處理 1. 新增狀態報告的屬性剖析 **使用現有叢集做為範本：** 1. **OnOff 叢集** - 顯示具有基本列舉、可寫入屬性、命令和屬性報告的所有四個元件的最簡單參考 1. **DoorLock 叢集** - 示範多種列舉類型、點陣圖欄位、結構參數、選用命令參數和廣泛屬性涵蓋範圍的複雜範例 所有支援的叢集 (Identify、OnOff、LevelControl、DoorLock、Thermostat、ColorControl、BooleanState) 都遵循此結構。檢閱 matter\_action\_converter.cpp 中的現有實作，以了解完整的模式。 ## 整合不同的事項控制器解決方案 本節提供如何將不同的事項控制器解決方案與事項外掛程式整合的指引。它概述了可能的方法和重要考量，但不提供詳細的實作程式碼。 整合事項控制器解決方案有兩種主要方式。第一個是將事項外掛程式與自訂的晶片工具搭配使用。第二個是使用您選擇的事項控制器，並透過自訂通訊協定程式庫與受管整合整合整合。 ### 搭配自訂晶片工具使用事項外掛程式 在此方法中，Matter 外掛程式會擴展，以使用自訂版本的 Chip-Tool。若要達成此目的，您可能需要修改事項外掛程式原始碼，並引入其他邏輯： + 調整 STDIO 剖析邏輯：如果您的自訂晶片工具產生具有不同模式的日誌，請相應地更新剖析邏輯。 + 實作安全儲存：事項外掛程式為裝置資訊提供以檔案為基礎的儲存機制。針對生產用途，請以更安全的儲存實作取代此項目，或對資料套用加密。解除安裝事項外掛程式時，也需要適當的清除程序。 + 實作二進位簽署和完整性保護：在生產部署中，您應該對自訂晶片工具和延伸的事項外掛程式強制執行完整性保護。這包括在您的軟體版本程序中簽署二進位檔、在啟動期間驗證簽章，以及整合平台安全功能，例如安全開機或作業系統層級完整性工具。 + 引入任務/事件速率限制：為防止過載，請確保事項外掛程式包含適當的任務和事件速率限制。在生產部署中，您也應該新增基本指標和監控，以偵測異常更新模式，並暫時調節或暫停受影響的裝置或訂閱。此斷路器類行為並非由參考實作提供，必須由客戶實作。 + 直接整合晶片工具的主要函數邏輯：如果您不想依賴 STDIO，您可以將晶片工具的主要函數整合到事項外掛程式。然後，標準輸入/輸出邏輯可以連接到 ChptoolProc 類別的讀取/寫入函數。 + 支援程式碼產生：實作機制，透過程式碼產生來處理事項規格版本更新。 + 實作事項管理功能，包括： + 將節點 IDs 指派給委託人、控制器和事項裝置。 + 管理多個 Fabric。 在晶片工具端，也建議使用下列增強功能： + 使用安全儲存：chip-tool 會在本機目錄中存放事項憑證、私有金鑰和統計資料。將此取代為安全實作。 + 啟用平行處理：根據預設，Chip-Tool 一次執行一個命令。在某些情況下，新增平行執行支援可能會提高效率。 ### 使用現有事項控制器搭配受管整合 如果您的事項控制器不是以晶片工具為基礎 （例如，Python 型實作或函數呼叫型解決方案），則 STDIO 方法可能不適合。在這種情況下，您可以使用 直接與受管整合整合整合[自訂通訊協定外掛程式](custom-protocol-plugin.md)，同時使用事項外掛程式做為參考。適用下列注意事項： + 維護 Fabric 和節點 IDs：確保持續維護裝置中繼資料，例如新增/移除裝置和快取屬性。 + 管理訂閱：每個裝置應維持最多一個作用中訂閱，以便持續更新其狀態。 + 傳播狀態變更：當裝置更新其狀態時，驗證變更並將事件傳播至受管整合。 + 實作事項資料模型轉譯器：雖然受管整合使用事項資料模型，但其表示方式為 JSON 格式。需要翻譯器才能在您的事項資料模型格式和 JSON 表示法之間進行映射。