Matter connectedhomeip 中 Telink 平台恒温器(Thermostat)示例应用:从构建、配网到 OTA 的完整实战
Matter connectedhomeip 中 Telink 平台恒温器(Thermostat)示例应用:从构建、配网到 OTA 的完整实战
本文基于 connectedhomeip 仓库中的 examples/thermostat/telink/README.md,系统讲解如何在 Telink(B91/B92/W91)开发板上编译、烧录 Matter 恒温器示例应用,如何通过按钮、LED、UART 与设备交互,如何使用 chip-tool 完成 BLE-Thread 配网,以及如何为设备启用 OTA 升级流程,并结合示例源码剖析恒温器端点(Thermostat Cluster)的初始化与属性回调机制。
支持的设备平台
该示例应用面向 Telink 的 Zephyr 生态构建,支持以下开发板与对应的 west 构建目标(build target):
| 开发板 / SoC | 构建目标(-b 参数值) |
|---|---|
| B91 板(TLSR9518ADK80D) | tlsr9518adk80d、tlsr9518adk80d-mars、tlsr9518adk80d-usb |
| B92 板(TLSR9528A) | tlsr9528a、tlsr9528a_retention |
| W91 板(TLSR9118BDK40D) | tlsr9118bdk40d |
各构建目标均对应 Telink 官方 Zephyr 仓库(tl_zephyr)中注册的 board 名称,编译时通过 -b <build_target> 指定即可。
构建环境准备
使用官方 Docker 构建镜像
Telink 平台的工具链与依赖(RISC-V 交叉编译器、Zephyr 版本)已由项目打包进官方 Docker 镜像。推荐在 Docker 容器内构建:
$ docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}' | head -n1)
该命令会从 CI 工作流定义文件中动态解析出当前 CI 使用的 chip-build-telink 镜像 tag,保证本地环境与 CI 环境一致。从当前仓库可以看到:
- 镜像定义位于 chip-build-telink/Dockerfile,其中安装了 Zephyr SDK 0.17.0,并将 Zephyr 锁定在 4.1.0(Telink 定制分支
dev-tlk_v4.1)——这是该示例能够编译成功的前提,换用其他 Zephyr 版本可能因 Telink board 支持缺失而失败; - CI 中使用的镜像版本可查阅 .github/workflows/examples-telink.yaml,当前 CI 使用的 tag 为
211。
激活构建环境
进入容器(或已准备好的环境)后,激活 Matter 构建环境并加载 Telink 平台支持:
$ source ./scripts/activate.sh -p all,telink
-p all,telink 表示启用全部平台支持,并额外加载 Telink 平台所需的 Pigweed 与工具链组件,脚本入口见 scripts/activate.sh。
编译示例(west build)
在仓库根目录下执行:
$ west build -b <build_target>
将 <build_target> 替换为上表中的板级目标,例如:
$ west build -b tlsr9518adk80d
$ west build -b tlsr9528a_retention
$ west build -b tlsr9118bdk40d
若所用板子的 Flash 大小不是默认的 2 MB,需要额外传入 -DFLASH_SIZE 参数:
$ west build -b <build_target> -- -DFLASH_SIZE=1m
$ west build -b <build_target> -- -DFLASH_SIZE=4m
构建完成后,可烧录的镜像文件为 build/zephyr/zephyr.bin。
烧录固件
$ west flash --erase
--erase 会先擦除 Flash 再写入,适合从旧版本固件覆盖升级的场景。
构建工程结构:从 CMakeLists.txt 看应用组成
本示例采用 Zephyr 模块化方式接入 Matter(CHIP)。工程入口为 examples/thermostat/telink/CMakeLists.txt,其组织方式值得逐行理解:
- 路径锚定:通过
get_filename_component定位到third_party/connectedhomeip(即 Matter 仓库根目录)、examples/platform/telink(Telink 公共平台层)以及zzz_generated/(代码生成目录); - 公共 CMake 片段:
include(${TELINK_COMMON}/common.cmake)引入 Telink 平台公共配置(工具链、Kconfig 默认值等);include(${CHIP_ROOT}/src/app/chip_data_model.cmake)提供数据模型(ZAP 文件)处理逻辑; - 应用级源码:编译
src/AppTask.cpp、src/TemperatureManager.cpp、src/ZclCallbacks.cpp三个应用源文件; - 平台公共层:复用 examples/platform/telink 中的
mainCommon.cpp(平台主流程)、AppTaskCommon.cpp(事件循环与芯片初始化)、SensorManagerCommon.cpp(模拟传感器读取),以及LEDManager.cpp、ButtonManager.cpp、ThreadUtil.cpp、PWMManager.cpp等工具模块和zephyr_ext/下的按键矩阵、LED 池、WS2812 等 Zephyr 扩展驱动; - 数据模型代码生成:
chip_configure_data_model(app ZAP_FILE ${CMAKE_CURRENT_SOURCE_DIR}/../thermostat-common/thermostat.zap)以 thermostat.zap 为输入生成 Thermostat 集群的端点/属性代码,生成结果位于zzz_generated/thermostat; - 公共恒温器逻辑:
chip_add_thermostat_common(app)引入 examples/thermostat/thermostat-common 中的 thermostat 委托实现(setpoint/hold/presets/suggestions 等 delegate 的通用实现); - 条件源码:当开启
CONFIG_BOOTLOADER_MCUBOOT时加入OTAUtil.cpp(MCUboot 双镜像 OTA 支持),开启CONFIG_OPENTHREAD_SNTP_CLIENT时加入ThreadTimeSync.cpp(通过 Thread 网络的时间同步)。
工程级 Kconfig 入口为 examples/thermostat/telink/Kconfig,其 mainmenu 声明本应用为 “Matter Telink Thermostat Example Application”,并通过 rsource 引入 config/telink/chip-module/Kconfig.defaults 作为所有 Telink 示例的公共默认配置。
应用级具体配置项集中在 examples/thermostat/telink/prj.conf,关键项如下:
| 配置项 | 取值 | 说明 |
|---|---|---|
CONFIG_CHIP |
y |
启用 CHIP(Matter)协议栈 |
CONFIG_STD_CPP20 |
y |
以 C++20 标准编译 |
CONFIG_CHIP_DEVICE_PRODUCT_ID |
32782(0x800E) |
设备产品 ID,即示例恒温器的产品标识 |
CONFIG_BT_DEVICE_NAME |
"TelinkThermo" |
BLE 广播设备名,配网时可用于识别设备 |
CONFIG_CHIP_OTA_REQUESTOR |
n |
默认禁用 Matter OTA 请求方(下文 OTA 章节详述如何开启) |
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION |
1 |
当前软件版本号(OTA 时用于版本比较) |
CONFIG_CHIP_LIB_SHELL |
n |
禁用 CHIP Shell |
CONFIG_CHIP_FACTORY_DATA* |
n |
禁用工厂数据相关功能 |
CONFIG_PM |
y |
启用 Zephyr 电源管理 |
设备交互:UART、按钮与 LED
UART 串口输出
连接串口查看设备日志,引脚定义如下:
| 名称 | 引脚 |
|---|---|
| RX | PB3(J34 连接器第 17 脚) |
| TX | PB2(J34 连接器第 16 脚) |
| GND | GND |
波特率为 115200 bps。
按键操作(以 tlsr9518adk80d 板为例)
| 按键 | 功能 | 说明 |
|---|---|---|
| Button 1 | 出厂复位(Factory reset) | 按下 3 次执行:清除当前已入网的 Thread 网络,回到未配网(decommissioned)状态 |
| Button 2 | 无 | — |
| Button 3 | 启动 Thread | 使用静态凭证入网,并开启设备上的 Thread 网络 |
| Button 4 | 打开配网窗口 | 打开 commissioning window,通过 BLE 进行配网 |
LED 状态指示
红色 LED 指示 Thread 网络状态:
| 状态 | 含义 |
|---|---|
| 短脉冲闪烁 | 设备未入网 Thread,Thread 处于禁用状态 |
| 快速闪烁 | 设备已入网、Thread 已启用,正在尝试 JOIN 到 Thread 网络 |
| 宽脉冲闪烁 | 设备已入网并作为 CHILD 节点加入 Thread 网络 |
绿色 LED 指示设备 Identify(识别)状态:收到 Identify 集群的 Identify 命令后开始闪烁,命令参数(effect)决定闪烁方式:
| 效果 | 对应枚举 |
|---|---|
| 200ms 亮 / 200ms 灭 闪烁 | Clusters::Identify::EffectIdentifierEnum::kBlink |
| 1000ms 内呼吸效果 | Clusters::Identify::EffectIdentifierEnum::kBreathe |
| 50ms 亮 / 950ms 灭 闪烁 | Clusters::Identify::EffectIdentifierEnum::kOkay |
| 1000ms 亮 / 1000ms 灭 闪烁 | Clusters::Identify::EffectIdentifierEnum::kChannelChange |
| 950ms 亮 / 50ms 灭 闪烁 | Clusters::Identify::EffectIdentifierEnum::kFinishEffect |
| LED 熄灭 | Clusters::Identify::EffectIdentifierEnum::kStopEffect |
这套枚举来自 Matter Identify 集群定义(src/app/Clusters/Identify 生成代码),可配合 controller 端的 identify 命令验证设备识别效果。
配网:chip-tool 通过 BLE-Thread 配对
使用流程分两步:
第一步:构建 chip-tool 命令行工具。 参考 examples/chip-tool/README.md 构建 chip-tool(controller 侧 CLI 工具)。
第二步:执行 BLE-Thread 配对。 命令格式:
${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
参数含义:${NODE_ID} 为分配给设备的节点 ID;${DATASET} 为 Thread 网络的静态凭证(thread dataset)十六进制串;${PIN_CODE} 为配网 PIN;${DISCRIMINATOR} 为判别器。文档给出的完整示例:
./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840
其中 20202021 是 Matter 标准测试 PIN 码,3840 为判别器。该方式下 Thread 网络凭证不经过 Thread Border Router 发现,而是由 controller 在配对时直接下发(static commissioning),适合快速演示环境。
为 Telink 恒温器启用 OTA(配合 Linux OTA Provider)
README 中的 OTA 章节描述了完整的 OTA 升级验证流程,要点如下:
1. 开启 OTA 请求方功能
Matter OTA 功能默认只在 ota-requestor-app 示例中启用。要为本 Telink 示例启用 OTA,需在对应的 prj.conf 中设置:
CONFIG_CHIP_OTA_REQUESTOR=y
2. 构建产物说明
开启 OTA 后构建,将得到两个二进制文件:
- merged.bin:主固件镜像,用于烧录 PCB(要求至少 2 MB Flash);
- matter.ota:供 OTA Provider 分发的 OTA 镜像包。
两者默认具有相同的软件版本号。要真正触发 OTA 升级,“matter.ota” 的软件版本必须高于设备上已运行的基础版本,因此应在 prj.conf 中设置:
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2
(基础固件使用 prj.conf 中默认的 CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=1。)
3. 构建 Linux OTA Provider
在 examples/ota-provider-app/linux 上构建 OTA Provider:
./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false
4. 运行 OTA Provider 并加载 OTA 镜像
./chip-ota-provider-app -f matter.ota
5. 用 chip-tool 配网 OTA Provider
./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021
其中 ${OTA_PROVIDER_NODE_ID} 是 Linux OTA Provider 的节点 ID。
6. 配置 OTA Provider 的 ACL 访问控制
./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' ${OTA_PROVIDER_NODE_ID} 0
该 ACL 允许 subject 为 112233 的节点以 privilege 5(admin)访问,其余同 fabric 节点以 privilege 3(operate)访问。
7. 宣告 OTA Provider,触发升级
./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0
其中 ${DEVICE_NODE_ID} 为已配网恒温器设备的节点 ID。
8. 升级完成
镜像传输完成后,OTA 请求方(恒温器设备)会向 OTA Provider 发送 ApplyUpdateRequest 命令请求应用镜像,OTA 镜像应用成功后设备自动重启。
从源码结构看,该流程依赖 CMake 中 CONFIG_BOOTLOADER_MCUBOOT 条件下编译的 OTAUtil.cpp(MCUboot 双槽镜像切换逻辑)与 matter.ota 镜像格式(由构建系统在开启 OTA 支持时一并生成)。
应用层实现剖析:恒温器端点与属性回调
以下结合示例源码说明设备侧如何维护恒温器状态,路径均相对仓库根目录。
端点初始化与 30 秒温度上报定时器
examples/thermostat/telink/src/AppTask.cpp 中:
- 恒温器端点固定为 Endpoint 1(
gThermostatEndpoint(1)); Init()中依次执行:InitCommonParts()(平台公共初始化)→Clusters::Thermostat::ServerInit(...)注册 5 组委托(基础、setpoints、hold、presets、suggestions)→ 初始化SensorMgr()与TempMgr();- 随后启动一个 30 秒周期 的 Zephyr
k_timer(kThermostatUpdateTimerPeriodMs = 30000)。定时器回调把事件投递到应用事件队列,ThermostatUpdateTimerEventHandler中通过SensorMgr().GetTempAndHumMeasurValue()读取温度(分辨率 0.01°C,int16_t),再调用app::Clusters::Thermostat::Attributes::LocalTemperature::Set(kExampleEndpointId, temperature)上报本地温度,整个读属性/写属性过程包裹在PlatformMgr().LockChipStack()/UnlockChipStack()中以保护芯片栈锁。
温度管理器与系统模式映射
examples/thermostat/telink/src/TemperatureManager.cpp 负责把集群属性转换为应用内状态:
Init()读取LocalTemperature、OccupiedCoolingSetpoint、OccupiedHeatingSetpoint、SystemMode四个属性,并把SystemModeEnum(kOff/kAuto/kCool/kHeat/kEmergencyHeat/kPrecooling/kFanOnly/kDry/kSleep)映射为内部mThermMode(0/1/3/4/5/6/7/8/9,未知值归为 2);ConvertToPrintableTemp()将 0.01°C 精度的属性值四舍五入为整数摄氏度用于显示;AttributeChangeHandler()处理LocalTemperature、OccupiedCoolingSetpoint、OccupiedHeatingSetpoint、SystemMode四类属性变更,更新内部缓存并调用GetAppTask().UpdateThermoStatUI()刷新日志/界面。
属性变更回调入口
examples/thermostat/telink/src/ZclCallbacks.cpp 实现了 Matter 数据模型的统一回调 MatterPostAttributeChangeCallback():对 Identify 集群打印调试信息,对 Thermostat 集群则将 (endpointId, attributeId, value, size) 转发给 TempMgr().AttributeChangeHandler()。这正是 controller 侧通过 chip-tool 写入 setpoint/mode 后,设备侧日志随之刷新的底层路径。
恒温器公共逻辑复用
Thermostat 集群的大部分服务端逻辑由跨平台公共库 examples/thermostat/thermostat-common 提供(thermostat-delegate-impl.cpp、thermostat-setpoints-delegate-impl.cpp、thermostat-mode-delegate-impl.cpp 等),Telink 平台只需实现传感器读取与 UI 映射,体现了 connectedhomeip 示例“平台薄层 + 公共集群逻辑”的分层设计。
小结与参考文件
本文覆盖了 examples/thermostat/telink 示例的完整生命周期:B91/B92/W91 板级构建目标选择、Docker 环境与 west build/west flash 流程、UART/按键/LED 交互、BLE-Thread 静态配网、以及基于 MCUboot + Linux OTA Provider 的 OTA 验证。相关核心文件:
| 文件 | 作用 |
|---|---|
| examples/thermostat/telink/README.md | 本文主要依据的官方操作文档 |
| examples/thermostat/telink/CMakeLists.txt | 工程组装与代码生成入口 |
| examples/thermostat/telink/prj.conf | 产品 ID、BLE 设备名、OTA 开关等应用级配置 |
| examples/thermostat/telink/Kconfig | Kconfig 入口与公共默认值引入 |
| examples/thermostat/telink/src/AppTask.cpp | 端点初始化与温度上报定时器 |
| examples/thermostat/telink/src/TemperatureManager.cpp | 温度/模式管理与属性变更处理 |
| examples/thermostat/telink/src/ZclCallbacks.cpp | 属性变更统一回调 |
| integrations/docker/images/stage-2/chip-build-telink/Dockerfile | Telink 构建镜像(Zephyr SDK 0.17.0 / Zephyr 4.1.0) |
| scripts/activate.sh | 构建环境激活脚本 |
| scripts/examples/gn_build_example.sh | 构建 Linux OTA Provider 使用 |
适用前提与限制:构建需使用官方 Telink 构建镜像或与其等价的工具链(Zephyr 4.1.0 Telink 定制分支),Flash 大小非 2 MB 的板子须显式传 -DFLASH_SIZE;OTA 验证要求至少 2 MB Flash 且 CONFIG_CHIP_OTA_REQUESTOR=y、CONFIG_BOOTLOADER_MCUBOOT 已启用。