connectedhomeip Telink 温度测量 Matter 应用:构建、烧录、BLE+Thread 配网与 OTA 全流程实战

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

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()——它使用硬编码的静态凭据(MasterKey 00 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 是示例特有的全部业务逻辑,实现非常清晰:

  1. AppTask::Init() 先调用平台层 InitCommonParts()(初始化 LED/PWM/按键、CHIP Server、打印二维码与 Setup Code 等),再初始化 SensorMgr();
  2. 启动一个 5 秒周期的 Zephyr 内核定时器 kTemperatureMeasurementUpdateTimer(kTemperatureMeasurementUpdateTimerPeriodMs = 5000);
  3. 定时器回调不直接操作数据模型,而是 PostEvent 到应用事件队列(K_MSGQ_DEFINE(sAppEventQueue, ...)),由主事件循环统一派发——这是 Telink 平台"中断/定时器只投递事件、业务在单线程事件循环中处理"的并发模型;
  4. 事件处理中通过 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 码,示例使用测试 PIN 20202021;
  • ${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

构建 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 流程

  1. 配网 OTA Provider:

    ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021
    

    其中 ${OTA_PROVIDER_NODE_ID} 为 Linux OTA Provider 的节点 ID。

  2. 配置 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
    
  3. 通过 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 的模拟实现为真实传感器驱动,即可迁移到自己的产品。可进一步阅读的资料:

登录后查看全文
connectedhomeip