connectedhomeip 的 Ameba 全集群示例应用All Clusters App构建、配网与 Matter Shell 控制实战指南【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip导读本文围绕 Matter原 Project CHIP开源 SDK 中 examples/all-clusters-app/ameba 平台示例完整讲解如何在 Ameba RTL8722DM 开发板上编译、烧录并运行 All Clusters 应用涵盖 Docker 构建环境、BLE / IP 两种配网Commissioning方式、Chip-Tool 集群控制、Pigweed RPC 控制台、Matter Shell 以及基于 Binding 的开关设备控制被控设备的完整流程。读完本文你将能够在 Ameba 硬件上独立复现一套配网 → 控制 → 绑定联动的 Matter 端侧开发闭环并理解其底层初始化与命令分发实现。一、示例概览与硬件支持All Clusters Example 是一个原型应用用于演示 Matter 设备的配网Commissioning与集群Cluster控制能力官方描述为A prototype application that demonstrates device commissioning and cluster control。它通过一份.zap数据模型all-clusters-app.zap 及其对应的 all-clusters-app.matter挂载了大量集群覆盖开关、调光、色彩、温控、模式选择、空气质量等场景是验证 SDK 集群实现与平台移植是否完整的重要参考工程。受支持的硬件平台Ameba RTL8722DM 开发板AmebaD双频 Wi-Fi BLE瑞昱 Realtek 方案。仓库中针对该板卡的平台移植代码位于 examples/platform/ameba包括 RPC 日志、路由钩子route_hook、OTA 初始化、Shell 启动器等模块。从平台配置 config/ameba/args.gni 可以看到该示例的关键构建特征chip_device_platform ameba设备平台定向到 Amebachip_config_network_layer_ble true启用 BLE 网络层支撑 BLE 配网chip_build_tests false示例构建默认不编译单元测试chip_inet_config_enable_tcp_endpoint false、chip_inet_config_enable_udp_endpoint true仅启用 UDP 端点符合低资源 MCU 的裁剪策略。二、构建示例应用官方推荐使用预制的 Docker 镜像构建避免在本机搭建完整交叉编译链。1. 拉取 Docker 镜像$ docker pull ghcr.io/project-chip/chip-build-ameba:2112. 运行 Docker 容器将本机上的 SDK 目录挂载进容器${CHIP_DIR}指向本仓库根目录$ docker run -it -v ${CHIP_DIR}:/root/chip ghcr.io/project-chip/chip-build-ameba:2113. 初始化构建环境在容器内执行 SDK 自带的引导脚本完成子模块拉取、工具链安装与 Python 虚拟环境准备$ source ./scripts/bootstrap.sh4. 执行构建$ ./scripts/build/build_examples.py --target ameba-amebad-all-clusters build构建产物按以下目录输出应用镜像out/ameba-amebad-all-clusters/asdk/imageBootloader 镜像out/ameba-amebad-all-clusters/asdk/bootloader从构建脚本scripts/build/build_examples.py 及平台 CMake examples/all-clusters-app/ameba/chip_main.cmake可以确认整个应用被编译为静态库chip_main并通过chip_configure_data_model(... ZAP_FILE ...)由 ZAP 文件生成集群代码后链接进 Ameba SDK 工程。5. 烧录固件构建完成后使用Ameba Image Tool烧录通过 USB 连接开发板打开 Ameba Image Tool选择正确的串口波特率设为115200在 Flash Download 列表中按正确位置分别添加对应的镜像文件应用镜像与 Bootloader 镜像点击Download按钮开始烧录。构建特性开关源码级解读chip_main.cmake 中暴露了三个可裁剪功能宏它们决定了固件是否包含对应模块开关影响对应编译宏matter_enable_rpc集成 Pigweed RPCattributes/button/descriptor/device/lighting/locking/wifi 七个 proto 服务CONFIG_ENABLE_PW_RPC1及PW_RPC_*_SERVICE1matter_enable_shell集成 Matter Shell通过 UART 交互CONFIG_ENABLE_CHIP_SHELL1并额外定义CHIP_SHELL_MAX_TOKENS11matter_enable_ota_requestor集成 OTA RequestorBDX 下载器 DefaultOTARequestor 等—需要特别注意的是RPC 与 Matter Shell 共用同一路 UART二者不能同时启用详见下文第五节。另外该文件还全局定义-DINET_CONFIG_ENABLE_IPV40、-DCHIP_DEVICE_LAYER_TARGETAmeba等平台宏并默认关闭 Ameba 工厂数据CONFIG_ENABLE_AMEBA_FACTORY_DATA0与测试事件触发CONFIG_ENABLE_AMEBA_TEST_EVENT_TRIGGER0。三、配网CommissioningAmeba 平台支持两种配网模式固件启动后 All Clusters 示例会自动运行。BLE 模式完成上文的构建 烧录开发板启动后All Clusters 示例自动运行等待通过 BLE 被发现使用 Chip-Tool 执行 BLE 配网测试。从入口代码 examples/all-clusters-app/ameba/main/chipinterface.cpp 可以看到当板卡尚未连接 AP 时InitServer()会调用PrintOnboardingCodes(chip::RendezvousInformationFlags(chip::RendezvousInformationFlag::kBLE))打印 BLE 模式的配网二维码/手动配对码供 Chip-Tool 扫码或手动输入配对。IP 模式完成上文的构建 烧录开发板启动后示例自动运行通过串口 AT 指令连接 AP使用ATW0设置 Wi-Fi SSID、ATW1设置密码、ATWC发起连接三条命令完成联网使用 Chip-Tool 进行 IP 配网测试。两种模式的差异在于首次配对信道的不同BLE 模式依赖板载低功耗蓝牙完成 Discovery PASE/SASE 协商IP 模式则依赖设备已通过 AT 指令接入同一局域网走 Matter 的 IP 层配网流程。无论哪种模式配网成功后设备都会加入 Fabric之后便可被控制器通过 node ID 寻址。四、集群控制用 Chip-Tool 开关设备配网成功后即可使用 OnOff 集群命令控制设备的 OnOff 属性——把设备实现的一个参数在 On开与 Off关之间切换。参考 Chip-Tool 使用说明examples/chip-tool/README.md$ ./chip-tool onoff on nodeID 1 $ ./chip-tool onoff off nodeID 1参数说明nodeID配网时分配给被控设备的节点 ID末尾的1被控设备上的 Endpoint IDAll Clusters 示例的 Endpoint 1 挂载了主要应用集群。这条命令由控制器chip-tool通过 CASE 安全会话向设备 Endpoint 1 的 OnOff 集群发送On/Off命令。Ameba 侧对应的命令处理由 ZAP 生成的 server 端代码执行最终改变设备上的 LED/GPIO 等模拟负载状态板载状态 LED 定义在 chipinterface.cpp 中AmebaD 为PB_5。五、运行 RPC 控制台Pigweed启用 RPC 后可以像操作 Python 对象一样远程读写设备属性。硬件接线使用 USB-TTL 串口转接板连接 Ameba接线因芯片型号而异AmebaDRTL8722DMAmeba USB-TTL A19 TX A18 RX GND GNDAmebaZ2Ameba USB-TTL A13 TX A14 RX GND GND构建 chip-rpc 控制台构建启用 RPC 的示例时chip_rpcPython 交互式控制台会被一并安装进 venv同时会在输出目录生成 Python wheel 包out/debug/chip_rpc_console_wheels。若不想重新构建可直接安装 wheel$ pip3 install out/debug/chip_rpc_console_wheels/*.whl启动控制台复位 Ameba 板卡后启动控制台port为 USB-TTL 转接板对应的串口设备$ chip-console --device /dev/ttyport connected to USB-TTL adapter -b 115200直接读写照明属性进入控制台后通过 Pigweed RPC 读写 Lighting 服务rpcs.chip.rpc.Lighting.Get() rpcs.chip.rpc.Lighting.Set(onTrue, level128, colorprotos.chip.rpc.LightingColor(hue5, saturation5))其中Get()用于读取当前照明状态Set()用于同时设置开关状态、亮度level与颜色hue/saturation。这些 RPC 服务对应的 proto 定义位于 examples/common/pigweed/protoslighting_service.proto、device_service.proto、wifi_service.proto等chip_main.cmake 在matter_enable_rpc开启时将其逐一注册为 nanopb RPC 库并链接进固件。六、运行 Matter ShellMatter Shell 提供了一套基于串口的命令行交互界面便于在没有主机控制器的情况下直接调试设备。关键使用前提Matter Shell 仅在关闭 RPC 时启用RPC 控制台与 Matter Shell 使用同一路 UART二者不能同时启用接线方式与上文 RPC 一节完全相同。使用方法按 RPC 一节的示意图连接 USB-TTL打开 USB-TTL 串口波特率 115200输入help查看可用命令列表输入switch查看该命令下的全部子命令。从 BindingHandler.cpp 的RegisterSwitchCommands()可以看到switch命令树下注册了以下子命令子命令说明switch identify subcommandIdentify 集群identify、triggereffect、属性读取switch onoff subcommandOnOff 集群on、off、toggle、offWE、onWRGS、onWTO及属性读取switch levelcontrol subcommandLevelControl 集群movetolevel、move、step、stop等switch colorcontrol subcommandColorControl 集群movetohue、movetosat、movetoCT等switch thermostat subcommandThermostat 集群SPRLsetpoint raise/lower及属性读取switch groups subcommand向绑定组Group发送命令switch binding subcommand绑定操作group、unicast每个子命令都通过BindingCommandData携带目标集群/命令/参数并经ScheduleSwitchCommandWork()投递到 Matter 平台事件循环最终由SwitchWorkerFunction()触发绑定管理器Binding::Manager向对端设备下发命令BindingHandler.cpp。七、绑定Binding与设备互控本示例还演示了如何将一个**开关设备Switch Devicebinding client与一个被控设备Controlleebinding server**建立绑定然后通过开关设备的 Matter Shell 控制被控设备。该流程需要一台 Switch 设备与一台 Controllee 设备各一。1. 配网两台设备使用 Chip-Tool 分别将开关设备nodeID 1与被控设备nodeID 2通过 BLE Wi-Fi 方式配网$ ./chip-tool pairing ble-wifi 1 SSID PASSWORD 20202021 3840 $ ./chip-tool pairing ble-wifi 2 SSID PASSWORD 20202021 3840参数说明SSID/PASSWORD目标 AP 的账号与密码20202021配对码Setup PIN code对应 Matter 通用开发配对码3840Discriminator用于多设备场景下的 BLE 广告区分。2. 配置被控设备的 ACL配网成功后需要先在被控设备nodeID 2上配置访问控制列表ACL允许开关设备nodeID 1与 chip-toolsubjects 112233访问$ ./chip-tool accesscontrol write acl [{fabricIndex: 1, privilege: 5, authMode: 2, subjects: [112233], targets: null },{fabricIndex: 1, privilege: 5, authMode: 2, subjects: [1], targets: null }] 2 0字段含义privilege: 5表示 Administer 权限authMode: 2表示 CASE 认证模式subjects中的112233是 chip-tool 的控制器节点 ID1是开关设备节点 IDtargets: null表示不限制目标 Endpoint/Cluster。末尾的2 0分别是被控设备 nodeID 与被写入 ACL 的 Endpoint。3. 写入 Binding把被控设备node 2Endpoint 1 的 OnOff 集群cluster 6绑定到开关设备nodeID 1的 Endpoint 1$ ./chip-tool binding write binding [{fabricIndex: 1, node:2, endpoint:1, cluster:6}] 1 14. 通过开关设备的 Matter Shell 发送命令绑定完成后即可在开关设备的 Matter Shell 中控制被控设备switch onoff on switch onoff off底层实现上这些命令由 OnOffCommands.h 中的处理器解析单播绑定走Controller::InvokeCommandRequest()建立 CASE 会话下发命令组播绑定isGroup则走Controller::InvokeGroupCommandRequest()向绑定组广播。5. 同时绑定多个集群也可以把多个集群同时绑定到开关设备。下面这条命令一次绑定了 Identify3、OnOff6、LevelControl8、ColorControl768、Thermostat513五个集群$ ./chip-tool binding write binding [{fabricIndex: 1, node:2, endpoint:1, cluster:3}, {fabricIndex: 1, node:2, endpoint:1, cluster:6}, {fabricIndex: 1, node:2, endpoint:1, cluster:8}, {fabricIndex: 1, node:2, endpoint:1, cluster:768}, {fabricIndex: 1, node:2, endpoint:1, cluster:513}] 1 1绑定完成后按命令描述中给出的格式即可通过开关设备的 Matter Shell 下发对应集群命令switch onoff on switch levelcontrol movetolevel 100 0 0 0 switch colorcontrol movetohue 100 0 0 0 0 switch thermostat SPRL 0 0参数对照可在 Matter Shell 中通过help子命令查看完整用法switch levelcontrol movetolevel level transitiontime optionsmask optionsoverride100为目标亮度三个0依次为过渡时间、选项掩码、选项覆盖switch colorcontrol movetohue hue direction transitiontime optionsmask optionsoverride100为目标色相四个0依次为方向、过渡时间、选项掩码、选项覆盖switch thermostat SPRL mode amount0为模式0 升温模式后一个0为调整量。6. 读取被控设备的属性Matter Shell 还支持通过绑定关系读取远端集群属性switch cluster read attribute例如switch onoff read onoff switch levelcontrol read currentlevel switch colorcontrol read colortemp switch thermostat read localtemp这些读取操作由各集群的Process*UnicastBindingRead()处理器实现底层调用Controller::ReadAttribute...()见 OnOffCommands.h并通过isReadAttribute标志与命令下发路径区分因此可以基于同一套绑定表完成读 / 写双向交互。八、端侧初始化链路小结整个 Ameba All Clusters 示例的运行可以从 chipinterface.cpp 的ChipTest()入口串起来若启用 RPC先调用chip::rpc::Init()初始化持久化存储initPref()与CHIPDeviceManager通过PlatformMgr().ScheduleWork(InitServer, 0)在 Matter 事件循环中初始化Server数据模型 Provider、Fabric 表、网络配网实例等Endpoint 0 挂载 Wi-Fi NetworkCommissioning 实例Endpoint 0xFFFE 被显式禁用未连接 AP 时打印 BLE 配网二维码若启用 Matter Shell调用InitBindingHandler()注册switch命令树并初始化 Binding ManagerBindingHandler.cpp 的InitBindingHandlerInternal()依赖Server已初始化完成后投递执行初始化状态 LED随后进入事件循环等待配网与控制指令。这条链路与上文所有操作一一对应可作为排查构建成功但配网/控制异常问题的入口参考。参考资源仓库内平台示例说明examples/all-clusters-app/ameba/README.md示例入口与服务器初始化examples/all-clusters-app/ameba/main/chipinterface.cpp构建脚本RPC / Shell / OTA 开关examples/all-clusters-app/ameba/chip_main.cmakeBinding 与 Switch 命令实现examples/all-clusters-app/ameba/main/BindingHandler.cpp、examples/all-clusters-app/ameba/main/include/OnOffCommands.h数据模型定义examples/all-clusters-app/all-clusters-common/all-clusters-app.zap平台移植层examples/platform/ameba平台构建配置config/ameba/args.gni【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考