Matter Air Purifier 示例在 Ameba 平台RTL8722DM上的构建、配网与集群控制实战指南【免费下载链接】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导读本文基于 connectedhomeip 仓库中的 examples/air-purifier-app/ameba/README.md完整讲解 Matter 空气净化器示例应用在 Ameba RTL8722DM 开发板上的落地路径从获取配套 Ameba Matter SDK、搭建构建环境、编译固件、通过 Ameba Image Tool 烧录到使用 BLE / IP 两种模式完成配网最后借助 chip-tool 对多端点复合设备进行读写与控制。读完本文你将掌握一套可在真实嵌入式硬件上运行的 Matter 空气净化器设备全流程开发与验证方法并能理解该示例内部复合设备Composed Device的端点组织与集群实现原理。一、示例概览与支持的硬件平台本示例演示的是 Matter 空气净化器Air Purifier应用在Ameba平台上的实现。它并不只是一个孤立的风扇设备而是一个由多个设备类型组合而成的复合设备净化器本体承担风扇控制与滤芯监测同时聚合了空气质量、温度、湿度与恒温控制等传感/控制功能。示例官方支持的硬件为Ameba RTL8722DM 开发板AmebaD 系列。该平台由 Realtek 提供配套的 Ameba Matter SDK 仓库Matter SDK 与该仓库需要以同级目录的方式组织具体目录约束见下文构建示例应用。在深入构建之前先了解这个示例在仓库中的代码组织这对后续调试非常有帮助目录/文件作用examples/air-purifier-app/air-purifier-common/平台无关的共享逻辑净化器管理器、空气质量/温度/湿度/恒温管理器、滤芯 delegateexamples/air-purifier-app/air-purifier-common/include/air-purifier-manager.hAirPurifierManager单例类声明实现FanControl::Delegate与设备回调examples/air-purifier-app/air-purifier-common/src/air-purifier-manager.cpp风扇档位/百分比/模式联动、OnOff 联动、恒温加热回调等核心业务逻辑examples/air-purifier-app/air-purifier-common/README.md该示例实现的 PICSProtocol Implementation Conformance Statement清单examples/air-purifier-app/ameba/main/chipinterface.cppAmeba 平台入口端点宏定义、InitAirPurifierManager、网络配网初始化examples/air-purifier-app/ameba/main/include/CHIPProjectAppConfig.h设备类型Air Purifier0x002D与配网相关编译配置examples/air-purifier-app/ameba/chip_main.cmakeCMake 构建脚本源文件清单、ZAP 数据模型生成、编译宏examples/air-purifier-app/air-purifier-common/air-purifier-app.matterZAP 自动生成的 Matter IDL描述全部集群、命令与属性二、构建示例应用Ameba 平台采用外部 SDK 目录 本仓库源码的构建模式整个流程分为三步拉取 Ameba 仓库、初始化构建环境、编译固件。2.1 准备配套仓库Ameba Matter SDKambd_matter必须与 Matter SDK 仓库放在同一级目录下并保证目录名分别为connectedhomeip与ambd_mattergit clone https://github.com/ambiot/ambd_matter.git提示ambd_matter仓库内含 Ameba 特有的编译框架project_lp / project_hp 双核工程以及烧录工具不要省略此步骤。2.2 初始化构建环境进入 Matter SDK 仓库目录执行 bootstrap 脚本完成子模块与依赖环境的初始化$ cd connectedhomeip $ source scripts/bootstrap.shscripts/bootstrap.sh 是 connectedhomeip 的标准环境初始化入口它会拉取构建所需的第三方依赖并激活 Python 虚拟环境后续所有构建命令都依赖该环境。2.3 编译演示应用AmebaD 是双核架构KM0 低功耗核 KM4 高算力核因此编译分为 LP 与 HP 两个工程$ cd ambd_matter/project/realtek_amebaD_va0_example/GCC-RELEASE/project_lp/ $ make all $ cd ambd_matter/project/realtek_amebaD_va0_example/GCC-RELEASE/project_hp/ $ make -C asdk air_purifier From the same directory: $ make all几点说明project_lp工程编译 KM0 低功耗内核负责启动与低功耗管理固件project_hp工程编译 KM4 主核固件其中make -C asdk air_purifier指定目标应用为air_purifierHP 工程随后执行的make all完成整体链接与镜像生成。从 examples/air-purifier-app/ameba/chip_main.cmake 可以看出Matter 相关源码是以静态库chip_main的形式参与 Ameba 工程的它把air-purifier-common下四个管理器源文件air-purifier-manager.cpp、air-quality-sensor-manager.cpp、filter-delegates.cpp、thermostat-manager.cpp与 Ameba 平台文件chipinterface.cpp、DeviceCallbacks.cpp、CHIPDeviceManager.cpp统一编译并调用chip_configure_data_model基于 air-purifier-app.zap 生成集群数据模型最终将libchip_main.a拷贝到lib/application目录供链接。2.4 合并镜像并烧录编译完成后会产生三份关键镜像文件需要借助Ameba Image Tool将它们合并为一份可烧录镜像$ cd ambd_matter/tools/AmebaD/Image_Tool_Linux $ sudo ./AmebaD_ImageTool -combine \ ../../../project/realtek_amebaD_va0_example/GCC-RELEASE/project_lp/asdk/image/km0_boot_all.bin 0x0000 \ ../../../project/realtek_amebaD_va0_example/GCC-RELEASE/project_hp/asdk/image/km4_boot_all.bin 0x4000 \ ../../../project/realtek_amebaD_va0_example/GCC-RELEASE/project_hp/asdk/image/km0_km4_image2.bin 0x6000三份镜像的地址分配如下镜像文件烧录起始地址说明km0_boot_all.bin0x0000KM0 内核启动引导镜像km4_boot_all.bin0x4000KM4 内核启动引导镜像km0_km4_image2.bin0x6000KM0/KM4 应用镜像包含 Matter 应用合并后会在 Image Tool 同级目录生成Image_All.bin。接下来通过 Ameba Image Tool 的图形界面或命令行完成下载通过 USB 连接开发板编辑ambd_matter/tools/AmebaD/mpp.ini将端口port设置为正确的串口设备号其余配置项保持默认即可依次点击Download按钮与Reset按钮使开发板进入串口下载模式执行下载命令刷入合并镜像$ cd ambd_matter/tools/AmebaD/Image_Tool_Linux $ ./AmebaD_ImageTool -download烧录完成后开发板复位并自动运行 Matter 空气净化器示例。三、配网CommissioningAmeba 平台支持两种配网模式可根据调试环境选择。配网过程中会打印 Matter 的配对二维码/手动配对码Onboarding Codes供控制器侧扫描使用。在 examples/air-purifier-app/ameba/main/chipinterface.cpp 的InitServer中可以看到当设备尚未连接 AP 时会通过PrintOnboardingCodes打印基于 BLE 的配对信息。3.1 BLE 模式完成构建与烧录开发板启动后示例自动运行并开启 BLE 广播等待配网使用 Chip-Tool 作为控制器完成配网与后续测试。BLE 模式适合首次配网无需预先配置 Wi-Fi 凭据。3.2 IP 模式完成构建与烧录开发板启动后示例自动运行使用 AT 指令ATW0设置 Wi-Fi 模式、ATW1配置 SSID、ATWC发起连接让开发板接入 AP使用 Chip-Tool 作为控制器完成配网与后续测试。IP 模式要求设备与控制器处于同一局域网内配网走 IP 发现通道。配网能力相关的编译配置可在 examples/air-purifier-app/ameba/main/include/CHIPProjectAppConfig.h 中看到CHIP_DEVICE_CONFIG_DEVICE_TYPE 0x002D声明设备类型为 Air Purifier使设备在发现阶段即可被识别为空气净化器CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONABLE_DEVICE_TYPE 1/CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONABLE_DEVICE_NAME 1使能可配网设备类型与设备名Air PurifierCHIP_DEVICE_CONFIG_ENABLE_EXTENDED_DISCOVERY 1使能扩展发现便于控制器在局域网内发现设备CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONER_DISCOVERY 0/CHIP_DEVICE_CONFIG_ENABLE_COMMISSIONER_DISCOVERY_CLIENT 1本设备作为被配网端Commissionee作为客户端发现 Commissioner。四、集群控制Cluster Control配网成功后即可使用 Chip-Tool 对空气净化器的各集群进行读取与写入控制。4.1 复合设备的端点布局空气净化器是一个复合设备Composed Device示例中的端点Endpoint配置如下Endpoint设备/功能涉及主要集群1空气净化器本体Fan Control、On/Off、HEPA/活性炭滤芯监测Resource Monitoring、Identify 等2空气质量传感器Air Quality、甲醛/CO₂/PM2.5/PM10/VOC/氡等浓度测量集群3温度传感器Temperature Measurement4相对湿度传感器Relative Humidity Measurement5恒温器Thermostat这一布局在 examples/air-purifier-app/ameba/main/chipinterface.cpp 中有直接对应源码以宏形式定义了AIR_PURIFIER_ENDPOINT 1、AIR_QUALITY_SENSOR_ENDPOINT 2、TEMPERATURE_SENSOR_ENDPOINT 3、RELATIVE_HUMIDITY_SENSOR_ENDPOINT 4、THERMOSTAT_ENDPOINT 5InitAirPurifierManager通过AirPurifierManager::InitInstance注册这五个端点并调用SetParentEndpointForEndpoint将 2~5 号端点挂到 1 号净化器端点之下形成层级组合关系。AirPurifierManager的单例实现air-purifier-manager.h内部聚合了AirQualitySensorManager空气质量传感器管理器TemperatureSensorManager温度传感器管理器RelativeHumiditySensorManager湿度传感器管理器ThermostatManager恒温管理器HepaFilterMonitoringDelegate/ActivatedCarbonFilterMonitoringDelegate及对应的ResourceMonitoring::InstanceHEPA 滤芯与活性炭滤芯监测。4.2 使用 chip-tool 进行控制与读取以下为官方给出的示例命令${NODE_ID_TO_ASSIGN}为配网时分配的设备节点 ID最后一个参数为端点号$ ./chip-tool fancontrol write speed-setting 10 ${NODE_ID_TO_ASSIGN} 1 $ ./chip-tool formaldehydeconcentrationmeasurement read level-value ${NODE_ID_TO_ASSIGN} 2 $ ./chip-tool temperaturemeasurement read measured-value ${NODE_ID_TO_ASSIGN} 3 $ ./chip-tool relativehumiditymeasurement read measured-value ${NODE_ID_TO_ASSIGN} 4各命令含义与对应端点命令集群/动作端点说明fancontrol write speed-setting 10Fan Control 写入1将风扇速度设定为 10速度最大值SpeedMax 由FanControl::Attributes::SpeedMax提供见源码GetSpeedMaxformaldehydeconcentrationmeasurement read level-value甲醛浓度测量读取2读取甲醛浓度等级值temperaturemeasurement read measured-value温度测量读取3读取测量温度值MeasuredValue属性relativehumiditymeasurement read measured-value相对湿度测量读取4读取测量相对湿度值4.3 风扇控制的底层联动逻辑从 examples/air-purifier-app/air-purifier-common/src/air-purifier-manager.cpp 的源码可以看出fancontrol write speed-setting并非简单的属性写入而会触发一系列设备级联动SpeedSettingWriteCallback写入SpeedCurrent并根据速度值自动映射风扇模式——速度为0时置FanMode kOff1~3为kLow4~7为kMedium8~10为kHigh常量FAN_MODE_LOW_UPPER_BOUND、FAN_MODE_MEDIUM_UPPER_BOUND、FAN_MODE_HIGH_UPPER_BOUND分别取 3、7、10FanModeWriteCallback反向联动写入FanMode时会把SpeedSetting校正到对应档位的合法区间HandleOnOffOn/Off 集群关闭时SpeedCurrent与PercentCurrent均被置 0开启时恢复设定值若为自动模式两者均 NULL则回落到 100% 与最大速度HandleStep实现 Fan Control 集群的Step命令支持kIncrease/kDecrease方向、wrap循环与lowestOff语义HeatingCallback恒温器进入加热状态时若风扇当前关闭或速度为 0会自动将风扇调到速度 5实现加热时自动送风的场景联动。此外PostAttributeChangeCallback统一分发 Fan Control、Thermostat、On/Off 三类集群的属性变更事件回调骨架定义于 DeviceManager.h。4.4 设备能力清单PICSexamples/air-purifier-app/air-purifier-common/README.md 给出了该示例实现的完整 PICS 清单可作为功能验收与认证准备的依据要点如下Fan Control服务端FAN.S1支持 Step 命令FAN.S.C00.Rsp1全部 12 个属性A0000~A000B实现HEPA 滤芯监测HEPAFREMON.S1与活性炭滤芯监测ACFREMON.S1支持 6 个属性A0000~A0005与重置命令响应C00.RspAir QualityAIRQUAL.S1支持 4 个属性A0000~A0003事件AirQualityChange未实现0浓度测量集群甲醛、CO₂、NO₂、臭氧、PM1、PM2.5、PM10、TVOC、氡等全部以服务端实现如CDOCONC.S1、PMICONC.S1属性实现到A000aTemperature / Relative HumidityTMP.S1、RH.S1均非手动控制ManuallyControlled0ThermostatTSTAT.S1仅支持加热模式F001只实现部分属性如A0000本地温度、A0003加热设定点、A0012系统模式、A001b/A001c模式相关与加热设定点写命令C00.Rsp1。这些 PICS 与实际端点布局一一对应是理解为什么 2 号端点能读甲醛、5 号端点存在恒温器的直接依据。五、总结与验证路径在 Ameba RTL8722DM 上跑通 Matter 空气净化器示例核心链路可概括为准备同级放置ambd_matter与connectedhomeip两个仓库source scripts/bootstrap.sh初始化环境构建依次在project_lp与project_hp工程执行make其中 HP 工程以make -C asdk air_purifier指定应用烧录用 AmebaD Image Tool 将 KM0/KM4 引导与双核应用镜像按0x0000 / 0x4000 / 0x6000地址合并为Image_All.bin并下载配网BLE 模式直接配对IP 模式先用ATW0/ATW1/ATWC接入 AP验证用 chip-tool 对 1~5 号端点分别执行风扇写入、甲醛/温度/湿度读取并可通过修改speed-setting观察FanMode的档位联动验证复合设备的整体行为。如需修改设备能力可基于 air-purifier-app.zap 重新生成数据模型参考 chip_main.cmake 中的chip_configure_data_model再结合上文提到的 PICS 清单对照检查功能覆盖是否完整。【免费下载链接】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），仅供参考