connectedhomeip Telink 温度测量 Matter 应用:构建、烧录、BLE+Thread 配网与 OTA 全流程实战
connectedhomeip Telink 温度测量 Matter 应用:构建、烧录、BLE+Thread 配网与 OTA 全流程实战
本文以 connectedhomeip(Matter,原 Project CHIP)仓库中的 Telink 温度测量示例应用(examples/temperature-measurement-app/telink)为主体,系统讲解该示例在 Telink B91/B92/W91 板卡上的 Docker 构建、west 烧录、UART 调试、按键/LED 交互、chip-tool 配对以及 Linux OTA Provider 升级的完整流程,并结合工程源码剖析温度属性上报、按钮事件循环与 Thread 静态配网等底层实现。读完本文,你可以独立完成该 Matter 温度传感器示例的编译、烧录、入网与固件升级,并具备将其改造为自有应用的参考基础。
1. 示例应用定位与组成
Telink 温度测量示例演示了如何从(当前为)模拟温度传感器获取数据并上报给 Matter 控制器,后续版本将支持真实传感器处理。它使用按键来测试设备状态变化,使用 LED 指示这些状态,官方文档明确建议可以将其作为创建自有 Matter 应用的参考。
该示例的工程结构非常精简,核心文件如下:
- CMakeLists.txt:West/CMake 工程入口,声明应用名
chip-telink-temperature-measurement-example,引入 Telink 公共构建脚本与数据模型; - prj.conf:Zephyr Kconfig 覆盖项,只放本示例特有选项(注释中明确说明通用选项由
Kconfig.defaults提供); - Kconfig:
mainmenu "Matter Telink Temperature Measurement Example Application",并通过rsource引入 config/telink/chip-module/Kconfig.defaults; - src/AppTask.cpp 与 include/AppTask.h:应用特有的温度定时采样逻辑;
- include/AppConfig.h:定义
APP_SET_NETWORK_COMM_ENDPOINT_SEC 0,即网络配置(Network Commissioning)仅在端点 0 上有效; - 公共部分全部复用 examples/platform/telink 平台层代码:
mainCommon.cpp、AppTaskCommon.cpp、SensorManagerCommon.cpp、LEDManager.cpp、ButtonManager.cpp、ThreadUtil.cpp等,在 CMakeLists 的target_sources中逐项列出。
CMakeLists 中有两处值得注意的细节:
add_compile_definitions(IDENTIFY_CLUSTER_DISABLED=1)
...
chip_configure_data_model(app
ZAP_FILE ${CMAKE_CURRENT_SOURCE_DIR}/../temperature-measurement-common/temperature-measurement.zap
)
其一,通过编译宏 IDENTIFY_CLUSTER_DISABLED=1 禁用了 Identify 集群(平台层 AppTaskCommon.cpp 中所有 Identify 效果处理器均被 #ifndef IDENTIFY_CLUSTER_DISABLED 包裹,不会参与编译);其二,数据模型由公共的 temperature-measurement.zap 文件经 chip_configure_data_model 宏自动生成,端点/集群配置不需要手写。
2. 支持的板卡与构建目标
示例支持在以下 Telink 板卡上构建和运行:
| 板卡/SoC | Build target |
|---|---|
| B91 / TLSR9518ADK80D | tlsr9518adk80d、tlsr9518adk80d-mars、tlsr9518adk80d-usb |
| B92 / TLSR9528A | tlsr9528a、tlsr9528a_retention |
| W91 / TLSR9118BDK40D | tlsr9118bdk40d |
对应 Zephyr 官方板级文档为 Telink 社区维护的 tl_zephyr 中各板卡的 doc/index.rst。源码中可以看到板级差异确实被平台层感知,例如 AppTaskCommon.cpp 的 LinkPwms() 对 CONFIG_BOARD_TLSR9118BDK40D_V1(W91 EVK 只有单路 LED PWM)和 WS2812 灯带板做了不同的 PWM 通道映射;深睡眠 workaround 也区分了 CONFIG_SOC_SERIES_RISCV_TELINK_B9X_RETENTION 与 TlX_RETENTION 系列。
3. 构建与烧录(Docker + West)
3.1 启动 Telink 专用构建容器
$ 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 工作流中动态解析当前使用的 chip-build-telink 镜像 tag,保证本地容器与 CI 环境一致。默认容器已包含推荐的 Zephyr 版本,版本声明位于 integrations/docker/images/stage-2/chip-build-telink/Dockerfile。
3.2 激活构建环境
$ source ./scripts/activate.sh -p all,telink
-p all,telink 表示加载通用与 Telink 平台两类依赖路径(Zephyr 工具链、HAL 等)。
3.3 构建应用
$ west build -b <build_target>
将 <build_target> 替换为第 2 节表格中的板级目标。如果板卡 Flash 大小不是默认的 2 MB,需要追加 -DFLASH_SIZE,例如:
$ west build -b <build_target> -- -DFLASH_SIZE=1m
$ west build -b <build_target> -- -DFLASH_SIZE=4m
构建成功后,目标固件 zephyr.bin 位于 build/zephyr 目录下。
3.4 烧录
$ west flash --erase
--erase 表示烧录前先整片擦除 Flash,适合验证完整固件或首次烧录。
4. 使用:UART 日志、按键与 LED
4.1 UART 调试串口
设备日志输出接线的 J34 连接器引脚:
| 名称 | 引脚 |
|---|---|
| RX | PB3(J34 连接器第 17 脚) |
| TX | PB2(J34 连接器第 16 脚) |
| GND | GND |
波特率:115200 bits/s。
4.2 按键功能(以 tlsr9518adk80d 板为例)
| 按键 | 功能 | 说明 |
|---|---|---|
| Button 1 | Factory reset | 工厂复位:忘记当前已入网的 Thread 网络并回到未入网状态(需连按 3 次) |
| Button 2 | NA | NA |
| Button 3 | Thread start | 使用静态凭据配网 Thread 并启用设备上的 Thread |
| Button 4 | Open commission window | 打开配网窗口,通过 BLE 执行入网 |
这些功能与源码中的按钮注册一一对应。AppTaskCommon.cpp 的 LinkButtons() 中:
buttonManager.addCallback(FactoryResetButtonEventHandler, 0, true);
buttonManager.addCallback(ExampleActionButtonEventHandler, 1, true);
// 未启用 CONFIG_TELINK_OTA_BUTTON_TEST 时:
buttonManager.addCallback(StartBleAdvButtonEventHandler, 2, true);
#if CHIP_DEVICE_CONFIG_ENABLE_THREAD
buttonManager.addCallback(StartThreadButtonEventHandler, 3, true);
#endif
- Button 1(工厂复位):
FactoryResetHandler采用"3 秒内连按 3 次"的防误触逻辑(常量kFactoryResetCalcTimeout = 3000、kFactoryResetTriggerCntr = 3),超时则清零计数;达标后调用chip::Server::GetInstance().ScheduleFactoryReset()。 - Button 3(Thread start):
StartThreadHandler在未入网时执行ThreadStackMgrImpl().SetThreadEnabled(true)并调用 ThreadUtil.cpp 中的StartDefaultThreadNetwork()——它使用硬编码的静态凭据(MasterKey00 11 22 ... FF、网络名/通道/PANID/XPANID 来自 Kconfig 的CONFIG_OPENTHREAD_*选项)构建 OperationalDataset,然后SetThreadProvision并SetThreadEnabled(true),最后启动 mDNS(DnssdServer::Instance().StartServer())以便 Thread 网络内被发现。源码注释中同样强调这类 Key 仅用于测试/认证,不应出现在生产设备中。 - Button 4(打开配网窗口):
StartBleAdvHandler在未入网时调用GetCommissioningWindowManager().OpenBasicCommissioningWindow(),即打开 Basic Commissioning Window(BCD),设备随后以 BLE 广播形式等待配对器连接。
4.3 LED 状态指示(Thread 网络状态)
红色 LED 指示当前 Thread 网络状态:
| 状态 | 说明 |
|---|---|
| 短脉冲闪烁 | 设备未入网 Thread,Thread 已禁用 |
| 高频闪烁 | 设备已配网、Thread 已启用,正在尝试 JOIN Thread 网络 |
| 宽脉冲闪烁 | 设备已入网并作为 CHILD 加入 Thread 网络 |
对应源码为 UpdateStatusLED():已入网且已启用时,已 attach 用 setLed(EAppLed_Status, 950, 50)(950ms 亮/50ms 灭的宽脉冲),未 attach 用 setLed(..., 100, 100)(100ms 亮/100ms 灭的高频闪烁);未入网或 Thread 未启用时用 setLed(..., 50, 950)(短脉冲)。LED 硬件后端由 LedManager 对接板级 LedPool(见 LEDManager.h),PWM 通道映射因板而异(第 2 节所述)。
此外 prj.conf 末尾启用了 CONFIG_PM=y(Power Management),平台层 ChipEventHandler 在 BLE 广播开始/停止时对 SUSPEND_TO_IDLE 做了 pm_policy_state_lock_get/put,让设备在配网期保持唤醒、空闲期可进入低功耗——这与 Telink 平台的深睡眠特性(B9x/TLX retention 板在深睡后 BLE 状态损坏会自动重启,见 AppTaskCommon.cpp 尾部的 __wrap_bt_is_ready)相配合。
5. 应用核心逻辑:5 秒周期的温度模拟上报
AppTask.cpp 是示例特有的全部业务逻辑,实现非常清晰:
AppTask::Init()先调用平台层InitCommonParts()(初始化 LED/PWM/按键、CHIP Server、打印二维码与 Setup Code 等),再初始化SensorMgr();- 启动一个 5 秒周期的 Zephyr 内核定时器
kTemperatureMeasurementUpdateTimer(kTemperatureMeasurementUpdateTimerPeriodMs = 5000); - 定时器回调不直接操作数据模型,而是
PostEvent到应用事件队列(K_MSGQ_DEFINE(sAppEventQueue, ...)),由主事件循环统一派发——这是 Telink 平台"中断/定时器只投递事件、业务在单线程事件循环中处理"的并发模型; - 事件处理中通过
PlatformMgr().LockChipStack()加锁后调用代码生成的访问器更新属性:
// Init 阶段:声明测量范围
chip::app::Clusters::TemperatureMeasurement::SetMeasuredValueRange(
kExampleEndpointId, SensorMgr().GetMinMeasuredTempValue(), SensorMgr().GetMaxMeasuredTempValue());
// 每 5 秒:上报当前温度(单位 0.01 °C)
chip::app::Clusters::TemperatureMeasurement::SetMeasuredValue(kExampleEndpointId, temperature);
温度数据来自 SensorManagerCommon.h 中的 SensorManager 单例:当前版本为模拟实现,GetTempAndHumMeasurValue(&temperature, NULL) 返回模拟值,测量范围(mMinMeasuredTempCelsius/mMaxMeasuredTempCelsius)在无 MARS 传感器时为 -40 ~ 120°C(启用 CONFIG_CHIP_USE_MARS_SENSOR 时为 SHT30 的 -40 ~ 125°C)。温度单位为 0.01°C,日志打印为 LOG_INF("Current temperature is (%d*0.01)°C", temperature)。
设备身份信息方面,prj.conf 中:
# 32781 == 0x800D (example temperature-measurement-app)
CONFIG_CHIP_DEVICE_PRODUCT_ID=32781
CONFIG_BT_DEVICE_NAME="TelinkTerm" # BLE 广播设备名
产品 ID 0x800D 是 Matter 分配给温度测量示例应用的产品标识;BLE 名称 TelinkTerm 便于在配对器上识别。同时该配置显式关闭了 CONFIG_CHIP_OTA_REQUESTOR=n(OTA 默认不启用,见第 7 节)、CONFIG_CHIP_LIB_SHELL=n(关闭 CHIP shell)、工厂数据支持(CONFIG_CHIP_FACTORY_DATA=n 等,即使用示例 DAC 证书而非工厂烧录数据)。
6. 使用 chip-tool 配对设备
6.1 构建 chip-tool
先按仓库说明构建 chip-tool CLI(GN 构建,产物为 chip-tool)。
6.2 BLE + Thread 入网配对
${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
完整示例:
./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840
参数说明:
${NODE_ID}(示例为 1234):设备在本配网 Fabric 中的节点号;hex:${DATASET}:Thread OperationalDataset 的十六进制编码(与第 4.2 节StartDefaultThreadNetwork()使用的静态网络参数一致:通道 11、网络名ThreadDemo等);${PIN_CODE}:Matter PIN 码,示例使用测试 PIN20202021;${DISCRIMINATOR}:Setup Code 中的判别符,示例为3840。
配对成功后,控制器可通过标准 Temperature Measurement 集群接口(Read MeasuredValue 等)读取设备每 5 秒更新的模拟温度。
7. 使用 Linux OTA Provider 完成 OTA 升级
7.1 在 Telink 侧启用 OTA
OTA 功能默认仅对 ota-requestor-app 示例启用。要为本示例启用 OTA,只需在本示例的 prj.conf 中设置:
CONFIG_CHIP_OTA_REQUESTOR=y
构建出的两个二进制文件用途如下:
- merged.bin:烧录到 PCB 的主固件(至少需要 2 MB Flash 的 PCB);
- matter.ota:供 OTA Provider 分发的 OTA 镜像。
为验证升级成功,OTA 镜像必须具有高于设备当前版本的软件版本:两份固件版本不同时,在 OTA 镜像对应的 prj.conf 中设置:
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2
(默认镜像版本见 prj.conf 中的 CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=1。)
启用 CONFIG_CHIP_OTA_REQUESTOR 后,平台层会在 Thread 网络就绪(kDnssdInitialized)时调用 InitBasicOTARequestor(),注册 OTA Requestor 并处理 mcuboot 镜像确认逻辑;CMakeLists.txt 中 CONFIG_BOOTLOADER_MCUBOOT 成立时会额外编入 OTAUtil.cpp 提供 OtaConfirmNewImage()。
7.2 构建并运行 Linux OTA Provider
./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false
加载 OTA 镜像并运行:
./chip-ota-provider-app -f matter.ota
7.3 用 chip-tool 完成 OTA 流程
-
配网 OTA Provider:
./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021其中
${OTA_PROVIDER_NODE_ID}为 Linux OTA Provider 的节点 ID。 -
配置 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 -
通过 chip-tool 让设备向 OTA Provider 通告以启动 OTA:
./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0其中
${DEVICE_NODE_ID}为已配对的温度传感器节点 ID。
传输完成后,OTA Requestor 会向 OTA Provider 发送 ApplyUpdateRequest 命令请求应用镜像;OTA 镜像应用成功后设备自动重启。
8. 小结与延伸阅读
本示例展示了在 Telink 硬件上构建一个完整 Matter 温度传感器的最小路径:ZAP 文件驱动的数据模型生成(chip_configure_data_model)、prj.conf/Kconfig.defaults 分层配置、平台层事件循环 + 按键/LED/Thread 静态配网的公共实现(examples/platform/telink),以及示例层仅需几十行代码(AppTask.cpp)即可完成属性周期上报。将其作为参考模板,替换 SensorManager 的模拟实现为真实传感器驱动,即可迁移到自己的产品。可进一步阅读的资料:
- Telink 平台通用说明 与
config/telink下的 Kconfig 默认项; - OTA Requestor 示例(OTA 默认启用的参考实现);
- chip-tool 使用说明(更多控制器侧命令);
- Docker 集成文档(其他构建容器)。