Matter connectedhomeip 中 Telink 平台恒温器(Thermostat)示例应用:从构建、配网到 OTA 的完整实战

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

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,其组织方式值得逐行理解:

  1. 路径锚定:通过 get_filename_component 定位到 third_party/connectedhomeip(即 Matter 仓库根目录)、examples/platform/telink(Telink 公共平台层)以及 zzz_generated/(代码生成目录);
  2. 公共 CMake 片段:include(${TELINK_COMMON}/common.cmake) 引入 Telink 平台公共配置(工具链、Kconfig 默认值等);include(${CHIP_ROOT}/src/app/chip_data_model.cmake) 提供数据模型(ZAP 文件)处理逻辑;
  3. 应用级源码:编译 src/AppTask.cpp、src/TemperatureManager.cpp、src/ZclCallbacks.cpp 三个应用源文件;
  4. 平台公共层:复用 examples/platform/telink 中的 mainCommon.cpp(平台主流程)、AppTaskCommon.cpp(事件循环与芯片初始化)、SensorManagerCommon.cpp(模拟传感器读取),以及 LEDManager.cpp、ButtonManager.cpp、ThreadUtil.cpp、PWMManager.cpp 等工具模块和 zephyr_ext/ 下的按键矩阵、LED 池、WS2812 等 Zephyr 扩展驱动;
  5. 数据模型代码生成:chip_configure_data_model(app ZAP_FILE ${CMAKE_CURRENT_SOURCE_DIR}/../thermostat-common/thermostat.zap) 以 thermostat.zap 为输入生成 Thermostat 集群的端点/属性代码,生成结果位于 zzz_generated/thermostat;
  6. 公共恒温器逻辑:chip_add_thermostat_common(app) 引入 examples/thermostat/thermostat-common 中的 thermostat 委托实现(setpoint/hold/presets/suggestions 等 delegate 的通用实现);
  7. 条件源码:当开启 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 已启用。

登录后查看全文
connectedhomeip