Matter ASR 恒温器示例实践:connectedhomeip 上的构建、配网与 Thermostat 集群控制
Matter ASR 恒温器示例实践:connectedhomeip 上的构建、配网与 Thermostat 集群控制
本文以 connectedhomeip(Project CHIP)仓库中的 ASR 恒温器示例为核心,完整覆盖该示例的构建命令、配网(Commissioning)流程,以及配网完成后使用 chip-tool 读写 local-temperature 属性、发送 SetpointRaiseLower 命令调整温度的实战操作,并结合示例源码剖析温度采样定时器与属性变更处理机制,帮助你在 ASR 系列芯片(ASR582X / ASR595X / ASR550X)上快速跑通一个符合 Matter 数据模型的温控设备。
示例概览
ASR Thermostat 示例位于 examples/thermostat/asr/README.md,其定位是演示"控制一个恒温器,并从本地传感器获取温度"这一典型 Matter 温控场景。示例基于 ASR FreeRTOS SDK 运行,平台文档见 ASR 入门指南。
从源码结构看,示例由以下部分构成:
| 路径 | 职责 |
|---|---|
| src/main.cpp | 入口:初始化 ASR 平台、启动 AppTask 并启动 FreeRTOS 调度器 |
| src/SensorManager.cpp | 周期性读取温度并写入 Thermostat 集群的 LocalTemperature 属性 |
| src/TemperatureManager.cpp | 缓存温度/设定点/系统模式,响应属性变更并刷新 UI |
| src/AppTask.cpp | 应用任务:事件队列处理 |
| src/DeviceCallbacks.cpp | Matter 设备层回调 |
| include/ | AppConfig.h、AppTask.h、CHIPProjectConfig.h 等头文件 |
| BUILD.gn / args.gni | GN 构建目标与编译参数 |
| thermostat-common | 各平台共用的恒温器业务逻辑与数据模型定义(thermostat.matter / thermostat.zap) |
其中 thermostat.matter 是由 ZAP 生成的 IDL 视图,可用来查看该示例启用的集群、属性与命令定义,确认 LocalTemperature、OccupiedHeatingSetpoint、OccupiedCoolingSetpoint、SystemMode 等属性均在其中。
构建与烧录
环境准备
构建恒温器示例前需要完成 Matter 开发环境搭建(参见 构建指南),并按芯片类型准备工具链(摘自 ASR 入门指南):
- ASR582X 与 ASR550X 使用 ARM GCC 9-2019q4 工具链,解压后设置:
export ASR_TOOLCHAIN_PATH={abs-path-to-toolchain}/gcc-arm-none-eabi-9-2019-q4-major/bin/ - ASR595X(RISC-V)使用 ASR 官方 RISC-V GNU 工具链,设置:
export ASR_TOOLCHAIN_PATH={abs-path-to-toolchain}/asr_riscv_gnu_toolchain_10.2_ubuntu-16.04/bin/
然后按目标板卡设置 ASR_BOARD 环境变量,这是构建命令中 - 前的板名来源:
export ASR_BOARD=asr582x # 或 asr595x / asr550x
执行构建
示例 README 给出的构建命令为:
./scripts/build/build_examples.py --target asr-$ASR_BOARD-thermostat build
构建输出存放在 out/ 下与 --target 参数同名的子目录中。从 BUILD.gn 可以看到产物的具体信息:
- 可执行目标
asr_executable("thermostat")的输出文件名为chip-asr-thermostat-example.out(output_name字段),output_dir为root_out_dir; - 构建断言
current_os == "freertos",确认该示例只在 FreeRTOS 环境下构建; - 公共依赖中显式列入了
${chip_root}/examples/thermostat/thermostat-common,即各平台共享的恒温器业务层,以及 QRCode 生成(examples/common/QRCode)和src/setup_payload等组件; - 编译宏
CHIP_DEVICE_CONFIG_USE_TEST_SETUP_PIN_CODE与CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR决定了配网 PIN 码与 Discriminator 来自构建参数(对应 examples/thermostat/asr/build_overrides/ 下的默认取值); - 当
chip_lwip_ip6_hook开启时,会追加CONFIG_LWIP_HOOK_IP6_ROUTE_DEFAULT、CONFIG_LWIP_HOOK_ND6_GET_GW_DEFAULT宏,用于 IPv6 路由与网关解析钩子; - 追加
-shell、-ota、-factory等 target 后缀可分别启用 Matter shell(CONFIG_ENABLE_CHIP_SHELL)、OTA Requestor(引入init_OTARequestor.cpp)与 ASR Factory Data Provider(CONFIG_ENABLE_ASR_FACTORY_DATA_PROVIDER=1),与入门指南中的 Shell/OTA/Factory 章节一一对应。
另外,args.gni 中关闭了 chip_stack_lock_tracking(设置为 "none"),注释说明原因是该 FreeRTOS 配置未定义 INCLUDE_xSemaphoreGetMutexHolder;同时它 import 了 ${chip_root}/src/platform/ASR/args.gni,把平台层通用编译参数纳入目标。
构建完成后使用 DOGO 工具将镜像烧录到开发板(工具用法见 ASR 官方 DOGO 文档,ASR 入门指南 中给出了链接入口)。
配网(Commissioning)
烧录后示例自动运行,配网流程与 ASR 平台通用流程一致,详见 ASR 入门指南的 Commissioning 一节。摘要如下:
- 先在板端 shell 中执行
recovery恢复出厂设置; - BLE 模式(仅 ASR582X 与 ASR595X 支持 BLE):
./chip-tool pairing ble-wifi <node_id> <ssid> <password> <pin_code> <discriminator> - IP 模式:先用
wifi_open sta [ssid] [password]连接 AP,再执行:./chip-tool pairing onnetwork-long <node_id> <pin_code> <discriminator>
其中 <pin_code> 与 <discriminator> 即构建时通过 setupPinCode / setupDiscriminator 参数注入的值,<node_id> 可用 1。
使用 chip-tool 控制 Thermostat 集群
配网成功后,即可用 chip-tool 对节点进行集群级控制。恒温器业务挂在端点 1 上——这一点可从 SensorManager.cpp 中的 constexpr EndpointId kThermostatEndpoint = 1 得到确认。
读取本地温度
示例 README 给出的读温度命令:
./chip-tool thermostat read local-temperature <NODE ID> 1
参数含义:thermostat 为集群名,read local-temperature 表示读取 LocalTemperature 属性(Matter 单位是 0.01 ℃,如返回 2350 即 23.5 ℃),<NODE ID> 为配网时指定的节点 ID,末尾的 1 为端点号。
升降温度设定点(SetpointRaiseLower)
通过 SetpointRaiseLower 命令相对调整加热/冷却设定点,命令参数为 <mode> <amount>:
- 升高设定点(+10 个 0.01 ℃ 单位步长):
./chip-tool thermostat setpoint-raise-lower 0 10 <NODE ID> 1 - 降低设定点:
./chip-tool thermostat setpoint-raise-lower 0 -10 <NODE ID> 1
其中第一个参数 0 表示 mode(0 表示不区分占用状态,即同时作用于 Occupied/Unoccupied 设定点),第二个参数为调整量。命令下发后,设备端的属性变更回调会同步刷新本地缓存——这一闭环由下一节的源码机制保证。
源码剖析:温度如何进入 Matter 数据模型
入口与任务启动
main.cpp 的启动顺序非常简洁:
init_asrPlatform()初始化 ASR 平台(来自 examples/platform/asr 平台目录);GetAppTask().StartAppTask()创建应用任务,失败则进入appError()死循环保护;vTaskStartScheduler()启动 FreeRTOS 调度器。
SensorManager:30 秒采样 + 0.5℃ 变化门限
SensorManager.cpp 是"本地传感器"的实现主体,关键参数:
constexpr EndpointId kThermostatEndpoint = 1;
constexpr uint16_t kSensorTimerPeriodMs = 30000; // 30s timer period
constexpr uint16_t kMinTemperatureDelta = 50; // 0.5 degree Celsius
工作流程:
Init()通过lega_rtos_init_timer()注册一个 30 秒周期定时器;- 定时器回调不直接操作 Matter 栈,而是向 AppTask 事件队列投递
kEventType_Thermostat事件,在任务上下文中处理,避免跨线程直接触碰 CHIP 栈; - 事件处理函数
SensorTimerEventHandler从模拟温度数组mSimulatedTemp[](2300、2400、2800……单位 0.01 ℃)中取值,每 2 次采样(kSimulatedReadingFrequency = 60000 / 30000 = 2,即每分钟)切换一个模拟读数; - 只有当新读数与上一次记录值的差值达到
kMinTemperatureDelta(50,即 0.5 ℃)时,才调用app::Clusters::Thermostat::Attributes::LocalTemperature::Set(kThermostatEndpoint, temperature)写入属性。整个 Set 过程被PlatformMgr().LockChipStack()/UnlockChipStack()包裹,确保对 CHIP 栈的互斥访问。
这意味着:属性只在温度"显著变化"时才会更新并触发订阅者的数据变更通知,既节省带宽也符合温控场景的实际语义。
TemperatureManager:属性变更 → 本地状态/ UI 同步
TemperatureManager.cpp 负责把 Matter 侧的状态映射回设备本地:
Init()在启动时一次性读取LocalTemperature、OccupiedCoolingSetpoint、OccupiedHeatingSetpoint、SystemMode四个属性并缓存,随后调用GetAppTask().UpdateThermoStatUI();AttributeChangeHandler()注册为属性变更回调,在LocalTemperature、两个设定点或SystemMode变化时更新缓存并再次刷新 UI——这正是上一节chip-tool下发setpoint-raise-lower后设备侧能感知设定点变化的机制;SystemMode枚举值被映射为 0~9 的显示模式(Off/Auto/Cool/Heat/Emergency Heat/Precooling/Fan Only/Dry/Sleep),便于界面呈现;ConvertToPrintableTemp()把 0.01 ℃ 单位换算为整数摄氏度(四舍五入),用于 LCD 无小数显示的场景。
从源码结构看,SystemMode::Get() 与 UpdateThermoStatUI() 等调用依赖 thermostat-common 提供的 delegate 实现(thermostat-mode-delegate-impl.cpp、thermostat-setpoints-delegate-impl.cpp 等),该公共库让 linux、ASR、genio、qpg 等各平台恒温器示例共享同一套业务逻辑,ASR 侧只需实现平台初始化与 UI 差异部分。
小结与关键路径索引
- 示例入口文档:examples/thermostat/asr/README.md
- 平台构建/配网/Shell/OTA 通用流程:docs/platforms/asr/asr_getting_started_guide.md
- 构建脚本与目标声明:examples/thermostat/asr/BUILD.gn、examples/thermostat/asr/args.gni
- 温度采样与属性写入:examples/thermostat/asr/src/SensorManager.cpp
- 属性缓存与变更处理:examples/thermostat/asr/src/TemperatureManager.cpp
- 公共恒温器业务层与数据模型 IDL:examples/thermostat/thermostat-common/BUILD.gn、examples/thermostat/thermostat-common/thermostat.matter
- 控制器工具:examples/chip-tool/README.md
掌握以上内容后,你即可在 ASR 平台上独立完成恒温器示例的编译、烧录、配网,并用标准 Matter 命令读写温度属性、下发设定点调整命令,同时理解属性更新从定时器采样、门限过滤、CHIP 栈锁保护到订阅通知的完整链路。