Matter ASR 恒温器示例实践:connectedhomeip 上的构建、配网与 Thermostat 集群控制

原创2026-09-17 09:55:091,855 阅读
文章标签:物联网智能家居嵌入式IoT协议通信网络蓝牙密码学认证鉴权

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 的启动顺序非常简洁:

  1. init_asrPlatform() 初始化 ASR 平台(来自 examples/platform/asr 平台目录);
  2. GetAppTask().StartAppTask() 创建应用任务,失败则进入 appError() 死循环保护;
  3. 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

工作流程:

  1. Init() 通过 lega_rtos_init_timer() 注册一个 30 秒周期定时器;
  2. 定时器回调不直接操作 Matter 栈,而是向 AppTask 事件队列投递 kEventType_Thermostat 事件,在任务上下文中处理,避免跨线程直接触碰 CHIP 栈;
  3. 事件处理函数 SensorTimerEventHandler 从模拟温度数组 mSimulatedTemp[](2300、2400、2800……单位 0.01 ℃)中取值,每 2 次采样(kSimulatedReadingFrequency = 60000 / 30000 = 2,即每分钟)切换一个模拟读数;
  4. 只有当新读数与上一次记录值的差值达到 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 差异部分。

小结与关键路径索引

掌握以上内容后,你即可在 ASR 平台上独立完成恒温器示例的编译、烧录、配网,并用标准 Matter 命令读写温度属性、下发设定点调整命令,同时理解属性更新从定时器采样、门限过滤、CHIP 栈锁保护到订阅通知的完整链路。

登录后查看全文
connectedhomeip