Matter (connectedhomeip) Telink 烟雾 CO 报警示例应用:构建、配网、自检与 OTA 完整实践

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

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 版本由"平台相关代码 + 平台无关公共代码"两部分组成:

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

从源码结构看有两点值得注意:

  1. 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"的说法。
  2. 低功耗与 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)簇的接入方式:

  1. 簇初始化:SmokeCoAlarmManager::Init() 构造 SmokeCoAlarmCluster::Config,声明支持 SmokeAlarm 与 CoAlarm 两个特征,并启用全部可选属性,然后调用 SmokeCoAlarmServer::Instance().Init(1, config, this) 完成第 1 个端点上 SmokeCoAlarm 服务端的初始化,管理器自身注册为服务端事件回调对象。

  2. 状态优先级表:静态数组 sPriorityOrder 定义了 9 种 ExpressedStateEnum 状态的优先级顺序(Inoperative → SmokeAlarm → InterconnectSmoke → COAlarm → InterconnectCO → HardwareFault → Testing → EndOfService → BatteryAlert),长度常量 kPriorityOrderLength 来自生成代码。

  3. 自检流程:收到 OnSelfTestRequested() 回调后进入 StartSelfTesting()——注释处 // It will take some time here 预留了真实检测耗时位置,随后依次执行 SetTestInProgress(1, false) 结束测试标记、SetExpressedStateByPriority(1, sPriorityOrder) 按优先级设置 ExpressedState,即"取当前有效状态中优先级最高者"的语义。

  4. 属性变更回调: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

构建 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 设备类型的起点。

登录后查看全文
connectedhomeip