本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

物质插件

什么是 Matter 插件

Matter Plugin 是使用托管集成中心 SDK 的自定义协议插件功能构建的参考实现。它使您的集线器能够按照 Matter 规范在同一网络上本地控制 Matter 设备，也可以通过托管集成远程控制 Matter 设备。

Matter 插件包含在 Hub SDK 中。它与 Matter 设备通信，实现 Matter Controller 功能，并通过托管集成公开远程控制路径。

chip-tool 是一款来自 connectedhomeip 的基于命令行的参考控制器。它充当 Commissioner/Controller on Matter 结构，允许您调试设备、 read/write 属性和调用命令，用于开发和互操作性测试。在本指南中，Matter Plugin 将使用芯片工具控制 Matter 设备，还将演示通过移动应用程序调试 Matter。

此发行版的范围不包括生产移动应用程序，也不包括认证和生产活动，例如 CSA 实验室测试和认证。这些仍然是您的产品开发过程的一部分。

如何构建 Matter 插件

除了 Hub SDK 之外，Matter 插件还具有以下依赖关系：

使用以下命令配置 repo：

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 SDK + Matter Plugin）和一台代表用于调试和基本控制的 “移动应用程序” 的 Raspberry Pi。

节点 ID 管理

在 Matter 中，结构上的每个节点（包括设备、控制器和调试员）都必须有一个唯一的节点 ID。为避免冲突，需要采用一致的分配策略。在本指南中，节点 ID 是手动分配的；在生产环境中，您应该正确管理节点 ID。

在本文档中的示例中，Hub 的芯片工具（由 Matter 插件使用）使用默认节点 ID112233，移动应用程序 Raspberry Pi 上的芯片工具使用节点 ID。123456新调试的设备在同一架构上分配的节点 ID 不冲突（例如，快速入门中的 101）。

先决条件

在您开始之前，请确保您已拥有以下各项：

步骤 1：准备 Raspberry Pi（代表移动应用程序）

生成的链存储在：$HOME/iotmi/matter/chip_tool_config.alpha.ini

稍后您将把此文件复制到 Hub。

步骤 2：准备 Hub（它运行 Matter 插件）

我们还需要芯片工具的 sha256sum 供以后使用。你可以使用以下命令来获取 sha256sum：

sha256sum /path/to/chip-tool

以下步骤将在 Raspberry Pi 上运行，即专员。

步骤 3：调试 Matter 设备（在 Raspberry Pi 上）

使用芯片工具使用设备解码后的二维码和配置凭证调试设备。 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/

备注：

chip-tool 支持不同的配对方法，包括与 Thread 或设备配对的 QR 码或 WiFi PIN 码。有关芯片工具配对命令的更多信息，请参阅官方文档。

步骤 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。为设备创建托管事物（User-Guided 安装程序）

示例响应包括用户指导的设置任务 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 设备类型

为其他集群添加 Support

要扩展 Matter Plugin 以支持其他设备类型和功能，请按照以下模式修改 matter_action_converter.cpp：

实现模式：

使用现有集群作为模板：

所有支持的群集（识别、、、 OnOff、 LevelControl DoorLock、Thermostat ColorControl、、 BooleanState）都遵循此结构。查看 matter_action_converter.cpp 中的现有实现以了解完整模式。

集成不同的物质控制器解决方案

本节提供有关如何将不同的 Matter Controller 解决方案与 Matter Plugin 集成的指导。它概述了可能的方法和重要的注意事项，但没有提供详细的实现代码。

集成 Matter Controller 解决方案的主要方法有两种。第一个是使用带有自定义芯片工具的 Matter 插件。第二个方法是使用您选择的 Matter Controller，并通过自定义协议库与托管集成。

将 Matter 插件与自定义插件一起使用 Chip-Tool

在这种方法中，Matter 插件被扩展为可与的自定义版本配合使用 Chip-Tool。为此，你可能需要修改 Matter Plugin 源代码并引入其他逻辑：

在切屑刀具方面，还建议进行以下增强：

使用具有托管集成的现有案件控制器

如果你的 Matter Controller 不是基于芯片工具（例如，基于 Python-based 实现或基于函数调用的解决方案），那么 STDIO 方法可能不合适。在这种情况下，您可以使用直接与托管集成集成自定义协议插件，同时使用 Matter Plugin 作为参考。请注意以下事项：