本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

事項外掛程式

什麼是事項外掛程式

事項外掛程式是使用 Managed Integrations Hub SDK 自訂通訊協定外掛程式功能建置的參考實作。它可讓您的中樞控制相同網路上的本機事項裝置，並遵循事項規格，以及透過受管整合從遠端控制。

重要外掛程式包含在 Hub SDK 中。它與事項裝置通訊、實作事項控制器功能，並透過受管整合公開遠端控制路徑。

chip-tool 是來自連線homeip 的命令列型參考控制器。它在事項結構上充當委託人/控制器，可讓您委託裝置、讀取/寫入屬性和叫用命令，並用於開發和互通性測試。在本指南中，事項外掛程式將使用晶片工具來控制事項裝置，並示範來自行動應用程式的事項委任。

此分佈的範圍不包含生產行動應用程式，也不涵蓋認證和生產活動，例如 CSA 實驗室測試和認證。這些仍是您的產品開發程序的一部分。

如何建置事項外掛程式

除了 Hub SDK 之外，Matter 外掛程式還具有下列相依性：

使用下列命令設定儲存庫：

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。

先決條件

開始之前，請務必備妥下列項目：

步驟 1. 準備 Raspberry Pi （代表行動應用程式）

產生的鏈結存放在： $HOME/iotmi/matter/chip_tool_config.alpha.ini

您稍後會將此檔案複製到 Hub。

步驟 2. 準備 Hub （執行事項外掛程式）

我們也需要晶片工具的 sha256sum 以供日後使用。您可以使用下列命令來取得 sha256sum：

sha256sum /path/to/chip-tool

下列步驟要在 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/

備註：

晶片工具支援不同的配對方法，包括與 Thread 或 WiFi 裝置配對的 QR 碼或 PIN 碼。如需 chip-tool 配對命令的詳細資訊，請參閱官方文件。

步驟 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. 為裝置建立受管物件 （使用者引導設定）

範例回應包含使用者引導的設定任務 ID：

{  
    "Id": "USER_GUIDED_SETUP_JOB_ID",  
    "StartedAt": 1753683326.056  
}

回應範例：

{  
    "Items": [  
        {  
            "DeviceTypes": [],  
            "DiscoveredAt": "2025-08-05T06:46:35.407000+08:00",  
            "AuthenticationMaterial": "<AUTH_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' <<EOF  
[  
  {  
    "endpointId": "1",  
    "capabilities": [  
      {  
        "id": "matter.OnOff@1.4",  
        "name": "On/Off",  
        "version": "1",  
        "actions": [  
          {  
            "name": "Toggle",  
            "parameters": {}  
          }  
        ]  
      }  
    ]  
  }  
]  
EOF  
)  
aws iot-managed-integrations send-managed-thing-command \  
    --managed-thing-id "DEVICE_MANAGED_THING_ID" \  
    --endpoints "$json"

步驟 7. 讀取裝置狀態

傳送下列命令以取得裝置狀態。

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. 從中樞移除受管物件

支援的事項裝置類型

新增對其他叢集的支援

若要擴充事項外掛程式以支援其他裝置類型和功能，請依照此模式修改 matter_action_converter.cpp：

實作模式：

使用現有叢集做為範本：

所有支援的叢集 (Identify、OnOff、LevelControl、DoorLock、Thermostat、ColorControl、BooleanState) 都遵循此結構。檢閱 matter_action_converter.cpp 中的現有實作，以了解完整的模式。

整合不同的事項控制器解決方案

本節提供如何將不同的事項控制器解決方案與事項外掛程式整合的指引。它概述了可能的方法和重要考量，但不提供詳細的實作程式碼。

整合事項控制器解決方案有兩種主要方式。第一個是將事項外掛程式與自訂的晶片工具搭配使用。第二個是使用您選擇的事項控制器，並透過自訂通訊協定程式庫與受管整合整合整合。

搭配自訂晶片工具使用事項外掛程式

在此方法中，Matter 外掛程式會擴展，以使用自訂版本的 Chip-Tool。若要達成此目的，您可能需要修改事項外掛程式原始碼，並引入其他邏輯：

在晶片工具端，也建議使用下列增強功能：

使用現有事項控制器搭配受管整合

如果您的事項控制器不是以晶片工具為基礎 （例如，Python 型實作或函數呼叫型解決方案），則 STDIO 方法可能不適合。在這種情況下，您可以使用 直接與受管整合整合整合自訂通訊協定外掛程式，同時使用事項外掛程式做為參考。適用下列注意事項：