Matter (connectedhomeip) Telink 烟雾 CO 报警示例应用:构建、配网、自检与 OTA 完整实践
Matter (connectedhomeip) Telink 烟雾 CO 报警示例应用:构建、配网、自检与 OTA 完整实践
本文基于 connectedhomeip 仓库中的 Telink 平台烟雾 CO 报警示例(smoke-co-alarm-app)编写。读完后,你将能够完整掌握:在 Telink B91/B92/W91 系列开发板上构建并烧录一个基于 Zephyr 的 Matter 烟雾/一氧化碳报警设备、理解其按键与 LED 的人机交互设计、使用 chip-tool 完成 BLE 配网并下发自检命令,以及为该设备启用 OTA 升级并与 Linux OTA Provider 联调的全流程。
一、示例应用概述
smoke-co-alarm-app 是 Matter 规范中烟雾/一氧化碳报警设备类型的参考实现,官方定位是作为"创建你自己应用的参考模板"(README)。Telink 平台版本采用 Zephyr + OpenThread(Thread 网络)技术栈,支持 BLE 初始配网,设备类型标识为烟雾 CO 报警器(产品 ID 32774,即十六进制 0x8006,见 prj.conf 第 25~26 行)。
支持的硬件平台
该示例支持在以下 Telink 板卡/SoC 上构建和运行:
| 板卡/SoC | 构建目标(build target) | 说明 |
|---|---|---|
| B91(TLSR9518ADK80D) | tlsr9518adk80d、tlsr9518adk80d-mars、tlsr9518adk80d-usb |
B91 通用开发套件 |
| B92(TLSR9528A) | tlsr9528a、tlsr9528a_retention |
B92 通用开发套件 |
| W91(TLSR9118BDK40D) | tlsr9118bdk40d |
W91 通用开发套件(带 WiFi) |
注意:
-retention系列目标(如tlsr9528a_retention)面向带 retention RAM 布局的构建,Kconfig 层面对其有专门处理(例如 Kconfig.defaults 中针对BOARD_TLSR9528A_RETENTION使能TELINK_B9X_MATTER_RETENTION_LAYOUT并关闭 PWM),适用于低功耗睡眠场景。
源码结构
从源码结构看,Telink 版本由"平台相关代码 + 平台无关公共代码"两部分组成:
- 平台相关代码位于 examples/smoke-co-alarm-app/telink/:
- CMakeLists.txt:West/Zephyr 构建入口,复用
examples/platform/telink/common.cmake公共构建逻辑,并编译 AppTask.cpp、SmokeCoAlarmManager.cpp、ZclCallbacks.cpp 以及 Telink 公共的 mainCommon、LEDManager、ButtonManager、ThreadUtil 等模块; - Kconfig:声明 Kconfig 根菜单,并引入
../../../config/telink/chip-module/Kconfig.defaults作为全部 Matter 示例的默认配置; - prj.conf:本示例特有的 Zephyr/Kconfig 配置项。
- CMakeLists.txt:West/Zephyr 构建入口,复用
- 平台无关的 ZAP/Matter IDL 数据模型定义在 smoke-co-alarm-common/(smoke-co-alarm-app.zap 与 smoke-co-alarm-app.matter),CMake 构建时通过
chip_configure_data_model宏引用该 ZAP 文件生成代码。
prj.conf 关键配置
示例的 prj.conf 只包含该样本特有的选项或默认值覆盖,核心配置如下:
# 使能 CHIP(Matter)
CONFIG_CHIP=y
CONFIG_STD_CPP20=y
# 32774 == 0x8006 (示例 smoke-co-alarm-app 的产品 ID)
CONFIG_CHIP_DEVICE_PRODUCT_ID=32774
# 蓝牙设备名
CONFIG_BT_DEVICE_NAME="TelinkCOSensor"
# 禁用 Matter OTA DFU(本示例默认关闭,开启方式见"OTA"一节)
CONFIG_CHIP_OTA_REQUESTOR=n
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=1
# 禁用 CHIP shell 支持
CONFIG_CHIP_LIB_SHELL=n
# 禁用 factory data 支持
CONFIG_CHIP_FACTORY_DATA=n
CONFIG_CHIP_FACTORY_DATA_BUILD=n
CONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE=n
CONFIG_CHIP_CERTIFICATION_DECLARATION_STORAGE=n
# 使能电源管理(低功耗)
CONFIG_PM=y
CONFIG_CHIP_ICD_LIT_SUPPORT=y
从源码结构看有两点值得注意:
- OTA 默认值是开启的:Telink 公共默认配置 Kconfig.defaults 中
CONFIG_CHIP_OTA_REQUESTOR的默认值为y(并配套CHIP_OTA_REQUESTOR_BUFFER_SIZE=256),而本示例的 prj.conf 显式将其覆盖为n。这也印证了 README 中"OTA 特性默认只对 ota-requestor-app 示例开启,其他 Telink 示例需自行在 prj.conf 中设置CONFIG_CHIP_OTA_REQUESTOR=y"的说法。 - 低功耗与 Thread 角色的联动:
CONFIG_PM=y会连带调整大量默认值(主栈大小降为 3560、网络收发缓冲各 4、Thread 设备角色只能选择 sleepy end device、BLE 发射功率降为 3 等),这些默认值都定义在 Kconfig.defaults 中。
二、构建与烧录
1. 启动 Docker 构建容器
README 推荐使用官方 Docker 镜像构建,镜像中已包含 Telink 工具链与推荐版本的 Zephyr(推荐版本指定于 integrations/docker/images/stage-2/chip-build-telink/Dockerfile):
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 工作流(仓库内路径 .github/workflows/examples-telink.yaml)中固定的镜像 tag,保证与 CI 环境一致。
2. 激活构建环境
source ./scripts/activate.sh -p all,telink
3. 构建示例
将 <build_target> 替换为上文"支持的硬件平台"中的板卡名:
west build -b <build_target>
如果你的板卡 Flash 大小不是默认的 2 MB,需要通过 -DFLASH_SIZE 指定,例如 -DFLASH_SIZE=1m 或 -DFLASH_SIZE=4m:
west build -b <build_target> -- -DFLASH_SIZE=4m
构建完成后,目标固件 zephyr.bin 位于 build/zephyr 目录下。
4. 烧录固件
west flash --erase
三、使用:UART、按键与 LED
UART 输出引脚
获取设备串口输出时,按如下引脚连接(B91 开发板):
| 名称 | 引脚 |
|---|---|
| RX | PB3(J34 连接器第 17 脚) |
| TX | PB2(J34 连接器第 16 脚) |
| GND | GND |
波特率:115200 bits/s。
按键功能(tlsr9518adk80d 板卡)
| 按键 | 功能 | 说明 |
|---|---|---|
| Button 1 | 工厂重置(Factory reset) | 忘记当前已配网的 Thread 网络并回到未配网状态(需连按 3 次) |
| Button 2 | 自检(Self test) | 触发烟雾 CO 报警簇自检流程 |
| Button 3 | 无 | — |
| Button 4 | 打开配网窗口 | 通过 BLE 执行配网 |
Button 2 的自检路径在源码中清晰可辨:AppTask.cpp 中 AppTask::Init() 调用 SetExampleButtonCallbacks(SelfTestEventHandler) 注册按钮回调,事件经应用事件队列分发到 SelfTestHandler,后者在持有芯片栈锁的前提下调用 chip::app::Clusters::SmokeCoAlarmServer::Instance().RequestSelfTest(1),最终由簇服务端回调到应用层。
LED 指示
红色 LED —— 指示 Thread 网络当前状态:
| 状态 | 说明 |
|---|---|
| 短促脉冲闪烁 | 设备未配网至 Thread,Thread 已禁用 |
| 快速脉冲闪烁 | 已配网、Thread 已使能,设备正在尝试 JOIN Thread 网络 |
| 宽脉冲闪烁 | 已配网并作为 CHILD 加入 Thread 网络 |
绿色 LED —— 设备识别(Identify)指示: 收到 Identify 簇的 Identify 命令后开始闪烁,命令参数可指定具体效果:
| 效果 | 对应枚举 |
|---|---|
| 闪烁(200 ms 亮/200 ms 灭) | Clusters::Identify::EffectIdentifierEnum::kBlink |
| 呼吸(1000 ms) | Clusters::Identify::EffectIdentifierEnum::kBreathe |
| 闪烁(50 ms 亮/950 ms 灭) | Clusters::Identify::EffectIdentifierEnum::kOkay |
| 闪烁(1000 ms 亮/1000 ms 灭) | Clusters::Identify::EffectIdentifierEnum::kChannelChange |
| 闪烁(950 ms 亮/50 ms 灭) | Clusters::Identify::EffectIdentifierEnum::kFinishEffect |
| LED 熄灭 | Clusters::Identify::EffectIdentifierEnum::kStopEffect |
四、应用层核心实现解析
SmokeCoAlarmManager.cpp 是理解该示例业务逻辑的关键,篇幅很短,完整体现了代码驱动(Code-driven)簇的接入方式:
-
簇初始化:
SmokeCoAlarmManager::Init()构造SmokeCoAlarmCluster::Config,声明支持 SmokeAlarm 与 CoAlarm 两个特征,并启用全部可选属性,然后调用SmokeCoAlarmServer::Instance().Init(1, config, this)完成第 1 个端点上 SmokeCoAlarm 服务端的初始化,管理器自身注册为服务端事件回调对象。 -
状态优先级表:静态数组
sPriorityOrder定义了 9 种ExpressedStateEnum状态的优先级顺序(Inoperative → SmokeAlarm → InterconnectSmoke → COAlarm → InterconnectCO → HardwareFault → Testing → EndOfService → BatteryAlert),长度常量kPriorityOrderLength来自生成代码。 -
自检流程:收到
OnSelfTestRequested()回调后进入StartSelfTesting()——注释处// It will take some time here预留了真实检测耗时位置,随后依次执行SetTestInProgress(1, false)结束测试标记、SetExpressedStateByPriority(1, sPriorityOrder)按优先级设置 ExpressedState,即"取当前有效状态中优先级最高者"的语义。 -
属性变更回调:ZclCallbacks.cpp 中的
MatterPostAttributeChangeCallback用于在ExpressedState属性变化时打印日志,源码中的 TODO 注释说明:代码驱动迁移后该回调将不再被调用,可改用DataModel::Provider::RegisterAttributeChangeListener拦截属性变更——这对基于此模板开发新应用的读者是一个重要的 API 演进提示。
五、chip-tool 配网与自检
1. 构建 chip-tool CLI
按 chip-tool 文档 构建命令行控制器。
2. BLE Thread 配网
${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
README 给出的完整示例(DATASET 为设备出厂的整机组装数据集,PIN_CODE 为配对码 20202021,DISCRIMINATOR 为 3840):
./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840
从示例数据集中的 ThreadDemo 字符串可以看出,配网流程会同时完成 Thread 网络凭证的注入;Kconfig 默认配置使能了 CONFIG_CHIP_EXTENDED_DISCOVERY(扩展发现,数据集内含 Extended Discriminator),与该流程对应。
3. 发起自检请求
chip-tool smokecoalarm self-test-request 1 1
该命令向端点 1 的 SmokeCoAlarm 服务端下发 SelfTestRequest 命令,参数为 testMode: 1。设备侧的处理链路即上文第四节所述的回调链,最终把 ExpressedState 置为 Testing 相关状态,可同时在 UART 日志(Start self-testing! / End self-testing!)中观察到。
六、OTA:与 Linux OTA Provider 联调
1. 启用 OTA 特性
OTA 特性默认只对 ota-requestor-app 示例开启。要为 Telink 烟雾报警示例启用 OTA,在对应的 prj.conf 中设置:
CONFIG_CHIP_OTA_REQUESTOR=y
2. 产物与版本号要求
开启 OTA 并构建后,会得到两组二进制文件:
- merged.bin —— 用于烧录到 PCB 的主固件(要求 Flash 至少 2 MB);
- matter.ota —— 供 OTA Provider 使用的升级镜像。
两组二进制的软件版本号(CONFIG_CHIP_DEVICE_SOFTWARE_VERSION)必须体现版本差异:测试 OTA 时,matter.ota 的软件版本号应高于已烧录的基线固件。做法是在(用于制作 OTA 镜像的)prj.conf 中设置:
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2
从源码结构看,当构建启用了 CONFIG_BOOTLOADER_MCUBOOT 时,CMakeLists.txt 会额外编译 Telink 公共的 OTAUtil.cpp,配合 MCUboot 引导加载器完成镜像应用。
3. 构建并运行 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 镜像运行 Provider:
./chip-ota-provider-app -f matter.ota
4. 配网 OTA Provider
./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021
其中 ${OTA_PROVIDER_NODE_ID} 为 Linux OTA Provider 的节点 ID。
5. 配置访问控制(ACL)
允许请求方访问 OTA Provider:
./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
6. 触发 OTA 流程
使用 chip-tool 通知 Provider 向目标设备发起升级:
./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0
其中:
${OTA_PROVIDER_NODE_ID}—— Linux OTA Provider 的节点 ID;${DEVICE_NODE_ID}—— 已配网的目标设备(烟雾报警设备)节点 ID。
镜像传输完成后,OTA Requestor 会向 Provider 发送 ApplyUpdateRequest 命令请求应用镜像;镜像应用成功时设备将自动重启,从而完成一次完整的 OTA 升级闭环。
七、小结
该 Telink 示例以极小的代码量(应用层仅 AppTask、SmokeCoAlarmManager、ZclCallbacks 三个源文件)展示了 Matter 代码驱动簇在 Zephyr/Thread 平台上的完整落地路径:Kconfig 分层配置(公共默认 + 样本覆盖)、ZAP 数据模型生成、BLE/Thread 双模配网、Identify/工厂重置人机交互、以及基于 MCUboot 的 OTA 升级。由于官方将其定位为应用开发参考模板,其目录组织与配置方式可以直接作为在 Telink B91/B92/W91 平台上开发其他 Matter 设备类型的起点。