本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 物质插件 **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) + [为其他集群添加 Support](#adding-support-for-additional-clusters) + [集成不同的物质控制器解决方案](#integrate-different-matter-controller-solutions) ## 什么是 Matter 插件 Matter Plugin 是使用托管集成中心 SDK 的[自定义协议插件](custom-protocol-plugin.md)功能构建的参考实现。它使您的集线器能够按照 Matter 规范在同一网络上本地控制 Matter 设备，也可以通过托管集成远程控制 Matter 设备。 ![架构图显示了 Matter 插件与托管集成 Hub SDK 的集成](https://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/iotmi-matter-plugin.png) Matter 插件包含在 Hub SDK 中。它与 Matter 设备通信，实现 Matter Controller 功能，并通过托管集成公开远程控制路径。 [chip-tool 是一款来自 connectedhomeip 的基于命令行的参考控制器。](https://github.com/project-chip/connectedhomeip)它充当 Commissioner/Controller on Matter 结构，允许您调试设备、 read/write 属性和调用命令，用于开发和互操作性测试。在本指南中，Matter Plugin 将使用芯片工具控制 Matter 设备，还将演示通过移动应用程序调试 Matter。 此发行版的范围不包括生产移动应用程序，也不包括认证和生产活动，例如 CSA 实验室测试和认证。这些仍然是您的产品开发过程的一部分。 ## 如何构建 Matter 插件 除了 Hub SDK 之外，Matter 插件还具有以下依赖关系： + OpenSSL 3.0.x：OpenSSL 版本要求并不严格——在大多数情况下，系统的默认版本可以正常工作。 + [nng v1.4.0](https://github.com/nanomsg/nng) + [cjSon v1.7.18](https://github.com/DaveGamble/cJSON) + [AWS 物联网设备软件开发工具包 CPP V2 v1.33.0](https://github.com/aws/aws-iot-device-sdk-cpp-v2) + [AWS 开发工具包 CPP 1.11.433](https://github.com/aws/aws-sdk-cpp) 使用以下命令配置 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 插件使用）使用默认节点 ID`112233`，移动应用程序 Raspberry Pi 上的芯片工具使用节点 ID。`123456`新调试的设备在同一架构上分配的节点 ID 不冲突（例如，快速入门中的 101）。 ### 先决条件 在您开始之前，请确保您已拥有以下各项： + 您的 Hub 已加入托管集成，并已部署 Hub SDK（通过脚本或 systemd）。如果尚未加载，请[Hub 入职设置](managedintegrations-sdk-v2-cookbook-hubsetup.md)进入托管集成，然后[安装和验证托管集成中心 SDK](managedintegrations-sdk-v2-cookbook-deployment.md)运行 Hub 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 并构建和安装芯片工具 + 按照[官方芯片工具构建指南构建芯片](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（它运行 Matter 插件） + 在集线器上构建或安装芯片工具（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/ ``` + 运行 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 上） 使用芯片工具使用设备解码后的二维码和配置凭证调试设备。 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 码解码的 Web 服务。 + `-bypass-attestation-verifier 1`仅供测试使用。对于生产，请更新 PAA 存储并执行认证检查。 chip-tool 支持不同的配对方法，包括与 Thread 或设备配对的 QR 码或 WiFi PIN 码。有关[芯片工具配对命令的](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。为设备创建托管事物（User-Guided 安装程序） + 开始发现（替换为 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 设备类型 | 案件设备类型 | 支持的功能 | | --- | --- | | [OnOffLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffPlug-inUnit.xml) | [识别 (0x0003)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) [[、电平控制 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [DimmableLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmableLight.xml) | [识别 (0x0003)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) [[、电平控制 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [ColorTemperatureLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/ColorTemperatureLight.xml) | [识别 (0x0003)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) [、电平控制 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) [、色彩控制 (0x0300](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)[)](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)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) [[、电平控制 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [DimmablePlug-InUnit](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmablePlug-InUnit.xml) | [识别 (0x0003)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) [[、电平控制 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [OnOffLightSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffLightSwitch.xml) | [[识别 (0x0003)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) | | [DimmerSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmerSwitch.xml) | [识别 (0x0003)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) [[、电平控制 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [ColorDimmerSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/ColorDimmerSwitch.xml) | [识别 (0x0003)、On/Off (0x0006)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml) [、电平控制 (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) [、色彩控制 (0x0300](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)[)](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)、[门锁](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/DoorLock.xml) (0x0101) | | [恒温器](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/Thermostat.xml) (0x0201)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.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)、[布尔状态](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/BooleanState.xml) (0x0045) | ## 为其他集群添加 Support 要扩展 Matter Plugin 以支持其他设备类型和功能，请按照以下模式修改 **matter\_action\_converter.cpp**： **实现模式：** 1. 为枚举和位图定义映射 1. 为可写属性添加 UpdateState 逻辑 1. 为集群操作添加命令处理 1. 为状态报告添加属性解析 **使用现有集群作为模板：** 1. OnOff cl@@ **uster**-最简单的参考文献显示了所有四个组件，包括基本枚举、可写属性、命令和属性报告 1. DoorLock clu@@ **ster**-演示多种枚举类型、位图字段、结构参数、可选命令参数和广泛的属性覆盖范围的复杂示例 所有支持的群集（识别、、、 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 源代码并引入其他逻辑： + 调整 STDIO 解析逻辑：如果您的自定义芯片工具生成了不同模式的日志，请相应地更新解析逻辑。 + 实现安全存储：Matter 插件为设备信息提供了一种基于文件的存储机制。对于生产用途，请将其替换为更安全的存储实现或对数据进行加密。卸载 Matter Plugin 后，它还需要适当的清理程序。 + 实施二进制签名和完整性保护：在生产部署中，您应该对自定义芯片工具和扩展的 Matter Plugin 强制执行完整性保护。这包括在软件发布过程中对二进制文件进行签名，在启动期间验证签名，以及集成平台安全功能，例如安全启动或 OS-level 完整性工具。 + 引入 task/event 速率限制：为防止过载，请确保 Matter Plugin 包含适当的任务和事件速率限制。在生产部署中，您还应添加基本指标和监控以检测异常的更新模式，并暂时限制或暂停受影响的设备或订阅。这种类似断路器的行为不是在参考实现中提供的，必须由客户实施。 + 直接集成芯片工具主功能逻辑：如果您不想依赖 STDIO，则可以将芯片工具的主功能集成到 Matter Plugin 中。然后可以将标准 input/output 逻辑连接到该 ChptoolProc 类的 read/write 函数。 + Support 代码生成：实现一种机制，通过代码生成来处理 Matter 规范版本更新。 + 实现案件管理功能，包括： + 为专员、控制器和案件设备分配节点 ID。 + 管理多个面料。 在切屑刀具方面，还建议进行以下增强： + 使用安全存储：芯片工具将 Matter 证书、私钥和统计信息存储在本地目录中。将其替换为安全的实现。 + 启用并行处理：默认情况下，一次 Chip-Tool 执行一条命令。在某些情况下，添加并行执行支持可以提高效率。 ### 使用具有托管集成的现有案件控制器 如果你的 Matter Controller 不是基于芯片工具（例如，基于 Python-based 实现或基于函数调用的解决方案），那么 STDIO 方法可能不合适。在这种情况下，您可以使用直接与托管集成集成[自定义协议插件](custom-protocol-plugin.md)，同时使用 Matter Plugin 作为参考。请注意以下事项： + 维护结构和节点 ID：确保始终如一地维护 adding/removing 设备元数据，例如设备和缓存属性。 + 管理订阅：每台设备应保持最多一个有效订阅，以便其状态可以持续更新。 + 传播状态更改：当设备更新其状态时，验证更改并将事件传播到托管集成。 + 实现 Matter 数据模型转换器：尽管托管集成使用 Matter 数据模型，但其表示形式为 JSON 格式。需要翻译人员在您的 Matter 数据模型格式和 JSON 表示形式之间进行映射。