Matter Telink All Clusters Minimal 示例:基于 Zephyr 的 B91/B92/W91 构建、烧录、配网与 OTA 实战指南
Matter Telink All Clusters Minimal 示例:基于 Zephyr 的 B91/B92/W91 构建、烧录、配网与 OTA 实战指南
本文是 Matter(Connected Home over IP,现由 Connectivity Standards Alliance 维护)开源 SDK 中 Telink 平台的 All Clusters Minimal 示例应用 的完整技术指南。该示例在三个端点上实现了多种 ZCL 集群,是开发者基于 Telink TLSR 系列 SoC 打造自有 Matter 设备的最佳参考起点。读完本文,你将掌握:在 Docker 构建环境下用 west 为 Telink 开发板编译并烧录固件、通过 UART 与按键进行调试与工厂复位、使用 chip-tool 通过 BLE + Thread 完成配网,以及用 Linux OTA Provider 为设备实现完整的 OTA 固件升级链路。
示例应用概述
Matter Telink All Clusters Minimal 示例应用(源码位于 examples/all-clusters-minimal-app/telink)在一个设备上填充了多个 ZCL(Zigbee Cluster Library)集群,这些集群分布在 三个端点上。其定位是"最小化但覆盖广":相比完整的 all-clusters-app,它保留了多集群覆盖能力,同时裁剪掉非核心逻辑,便于作为创建自有应用的模板。
从构建脚本 CMakeLists.txt 可以看到该示例的组成结构:
- 数据模型由
chip_configure_data_model基于 ZAP 文件 all-clusters-minimal-app.zap 生成,同时依赖src/app/chip_data_model.cmake接入 SDK 的数据模型构建流程; - 平台公共逻辑复用了
examples/platform/telink下的common.cmake,包括mainCommon.cpp、AppTaskCommon.cpp、LEDManager、PWMManager、ButtonManager、ThreadUtil以及zephyr_ext下的按键/灯池/PWM/WS2812 等 Zephyr 适配层; - 示例特有逻辑集中在 src/AppTask.cpp:初始化时调用
InitBindingHandlers()配置绑定(binding)能力,并注册StaticSupportedModesManager,为 ModeSelect 集群 提供静态支持的运行模式管理。
示例的 Kconfig 入口在 Kconfig,它通过 rsource 引入 config/telink/chip-module/Kconfig.defaults 中的平台公共默认配置,再叠加本示例自身的配置。
支持设备与构建目标
该示例支持 Telink 的 B91、B92、W91 三个系列开发板,每个板卡对应一个或多个 Zephyr west build -b 构建目标:
| 板卡 / SoC | 构建目标 | 说明 |
|---|---|---|
| B91(TLSR9518ADK80D,TLSR951x 系列) | tlsr9518adk80d、tlsr9518adk80d-mars、tlsr9518adk80d-usb |
B91 通用入门套件,本示例的按键/串口章节默认针对该板 |
| B92(TLSR9528A,TLSR952x 系列) | tlsr9528a、tlsr9528a_retention |
支持 retention 变体 |
| W91(TLSR9118BDK40D,TLSR911x 系列) | tlsr9118bdk40d |
Wi-Fi/Thread 融合系列 |
构建时用 -b <build_target> 指定上述任一目标即可。若使用 B91,可重点参考本文"使用指南"一节的 UART、按键与 LED 说明,因为这些外设映射是以 tlsr9518adk80d 为基准给出的。
环境准备:Docker 构建容器与激活脚本
Telink 示例基于 Zephyr RTOS 构建,官方推荐在 Docker 容器中完成,以规避本地 Zephyr 工具链版本不一致的问题。
- 启动构建容器(推荐方式,镜像版本从 CI 工作流中自动解析):
$ 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 镜像标签并挂载当前目录。仓库内的对应证据:
- 默认容器内置的推荐 Zephyr 版本由 integrations/docker/images/stage-2/chip-build-telink/Dockerfile 定义;
- 兼容的 Docker 镜像版本在 .github/workflows/examples-telink.yaml 中声明。
- 激活构建环境:
$ source ./scripts/activate.sh -p all,telink
-p 参数指定需要激活的平台包集合,all,telink 表示激活全部基础依赖并加入 Telink 平台支持(脚本位于 scripts/activate.sh)。
构建与烧录
构建固件
在容器内、仓库根目录下执行 west build:
$ west build -b <build_target>
其中 <build_target> 替换为上文"支持设备与构建目标"表中的板卡名称(如 tlsr9518adk80d)。
关于 Flash 大小的关键参数 -DFLASH_SIZE:默认按 2 MB 布局构建。若你的板载 Flash 不是 2 MB,必须显式指定,例如:
$ west build -b <build_target> -- -DFLASH_SIZE=1m
$ west build -b <build_target> -- -DFLASH_SIZE=4m
注意 -DFLASH_SIZE 需要放在 -- 之后,作为传给底层构建系统的额外 CMake 参数。构建完成后,目标固件位于 build/zephyr/zephyr.bin。
烧录固件
通过 J-Link 等调试器烧录(--erase 会先擦除目标 Flash,确保干净启动):
$ west flash --erase
源码级视角:prj.conf 关键配置解读
示例的工程配置在 examples/all-clusters-minimal-app/telink/prj.conf,它只保留本示例特有的配置,公共项由平台 Kconfig.defaults 兜底。理解这些开关,对修改自有应用至关重要:
| 配置项 | 值 | 含义 |
|---|---|---|
CONFIG_CHIP |
y |
启用 Matter(CHIP)核心 |
CONFIG_STD_CPP20 |
y |
启用 C++20 标准(构建脚本中通过 enable-gnu-std.cmake 配合) |
CONFIG_GPIO |
y |
启用 GPIO,支撑按键与 LED |
CONFIG_CHIP_DEVICE_PRODUCT_ID |
32769(0x8001) |
本示例的 Matter 产品 ID(all-clusters-minimal-app 专用 PID) |
CONFIG_BT_DEVICE_NAME |
"TelinkMinApp" |
BLE 广播的设备名称,配网时可在扫描结果中识别 |
CONFIG_CHIP_OTA_REQUESTOR |
n |
默认关闭 OTA 请求端功能(下文 OTA 章节需改为 y) |
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION |
1 |
设备软件版本号,OTA 测试时需要比镜像版本低 |
CONFIG_CHIP_LIB_SHELL |
n |
关闭 CHIP Shell(减少 Flash 占用) |
CONFIG_CHIP_FACTORY_DATA 等 |
n |
关闭工厂数据支持及相关 CD 存储 |
CONFIG_PM |
n |
关闭电源管理 |
其中 CONFIG_BT_DEVICE_NAME 是配网排查时最容易用到的项:如果手机或 chip-tool 扫描不到设备,首先确认该名称是否正常出现在 BLE 扫描结果中。
使用指南:UART、按键与 LED
UART 串口输出
将串口连接到以下引脚即可查看设备日志(以 tlsr9518adk80d 为基准):
| 名称 | 引脚 |
|---|---|
| RX | PB3(J34 连接器第 17 脚) |
| TX | PB2(J34 连接器第 16 脚) |
| GND | GND |
波特率:115200 bits/s。日志模块在 AppTask.cpp 中声明为 LOG_MODULE_DECLARE(app, CONFIG_CHIP_APP_LOG_LEVEL),日志级别跟随 Kconfig 的 CONFIG_CHIP_APP_LOG_LEVEL。
按键功能(tlsr9518adk80d)
| 名称 | 功能 | 说明 |
|---|---|---|
| Button 1 | 恢复出厂设置 | 忘记已配网的 Thread 网络并回到未配网状态;触发方式:连续按下 3 次 |
| Button 2 | 未使用 | — |
| Button 3 | 未使用 | — |
| Button 4 | 打开配网窗口 | 触发 BLE 配网窗口,供配网器执行基于 BLE 的 commissioning |
按键的底层映射与去抖逻辑由 examples/platform/telink/util/src/ButtonManager.cpp 及 zephyr_ext/zephyr_key_pool.c、zephyr_key_matrix.c 实现,具体 GPIO 引脚定义以板级设备树为准。
LED:Thread 网络状态指示
红色 LED 用于指示 Thread 网络当前状态,其闪烁模式与状态的对应关系:
| 状态 | 说明 |
|---|---|
| 短脉冲闪烁 | 设备未配网到 Thread,Thread 功能关闭 |
| 频繁脉冲闪烁 | 设备已配网,Thread 已启用,正在尝试 JOIN Thread 网络 |
| 宽间隔脉冲闪烁 | 设备已成功加入 Thread 网络并成为 CHILD 节点 |
LED 驱动位于 examples/platform/telink/util/src/LEDManager.cpp,支持 PWM 与 WS2812 等灯池扩展(见 zephyr_ext/zephyr_led_pool.c、zephyr_ws2812.c)。实际接线时需将 LED 与对应 GPIO 正确连接,否则状态不可见。
使用 chip-tool 配网
配网(commissioning)是让 Matter 设备加入网络的第一步。官方推荐使用 chip-tool 作为配网器(controller)。
-
先构建 chip-tool CLI,构建方法详见 examples/chip-tool/README.md(典型方式是通过
scripts/examples/gn_build_example.sh examples/chip-tool/linux out/chip-tool一类 GN 构建脚本生成可执行文件)。 -
通过 BLE + Thread 方式配网:
${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
参数含义:
${NODE_ID}:为该设备分配 Matter 节点 ID;${DATASET}:Thread 网络的 Active Operational Dataset(以hex:前缀传入十六进制字符串);${PIN_CODE}:设备的配网 PIN(如20202021);${DISCRIMINATOR}:BLE 配网判别器(如3840)。
完整示例:
./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840
执行成功后,设备将获得 Thread 网络凭据并开始入网流程,此时可通过上文"LED"一节观察设备从"尝试 JOIN"到"成为 CHILD"的状态迁移。
通过 Linux OTA Provider 实现 OTA 升级
OTA(Over-The-Air)升级是量产设备的关键能力。本示例默认未启用 OTA(CONFIG_CHIP_OTA_REQUESTOR=n,见 prj.conf),只有 ota-requestor-app 示例默认开启。如需为本示例(或其他 Telink 示例)启用 OTA:
- 在对应
prj.conf中设置:
CONFIG_CHIP_OTA_REQUESTOR=y
- 重新构建后,会生成两类二进制文件:
merged.bin:烧录到 PCB 的主固件(至少需要 2 MB Flash);matter.ota:提供给 OTA Provider 的升级镜像。
- 版本号约束:以上两个文件具有相同的 SW 版本。要实际测试 OTA 流程,
matter.ota的软件版本必须高于设备当前运行的版本。在prj.conf中把基础版本设为较低值即可,例如:
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2
(即设备基础固件用 =1,OTA 镜像用 =2,以此制造版本差。)
OTA 完整操作流程
- 构建 Linux OTA Provider(源码在 examples/ota-provider-app/linux):
./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false
这里通过 chip_config_network_layer_ble=false 关闭 BLE 网络层,OTA Provider 仅走 IP(on-network)配网。
- 运行 OTA Provider 并指定升级镜像:
./chip-ota-provider-app -f matter.ota
- 使用 chip-tool 配网 OTA Provider(on-network 方式,走 WiFi/Ethernet 直连):
./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021
其中 ${OTA_PROVIDER_NODE_ID} 是 Linux OTA Provider 的节点 ID。
- 配置 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
其中 ${OTA_PROVIDER_NODE_ID} 同上。第一条 ACL 条目授予管理权限(privilege 5)给主体 112233,第二条授予操作权限(privilege 3)给所有主体,targets: null 表示不限集群与端点。
- 通知设备开始 OTA(由 OTA Requestor 发起公告,触发下载):
./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}:已配网的目标设备(Telink 设备)的节点 ID;- 其余数字为 announce-otaprovider 命令所需的 provider endpoint、fabric index 等参数。
传输完成后,OTA Requestor 会向 OTA Provider 发送 ApplyUpdateRequest 命令请求应用新镜像;设备在成功应用 OTA 镜像后会自动重启。至此,整个"构建镜像 → 托管 Provider → 配网 → ACL 授权 → 公告下载 → 应用重启"的 OTA 闭环完成。
小结
Matter Telink All Clusters Minimal 示例是通往 Telink 平台 Matter 开发的最小完整闭环:三个端点的 ZCL 集群覆盖了从数据模型生成(ZAP → CMake)到应用任务初始化(绑定、ModeSelect 静态模式管理)的完整范式;prj.conf 中的 PID、BLE 设备名、OTA 与版本号等开关则直接决定设备的可配网性与可升级性。建议开发者在构建自有应用时:
- 以本示例为起点复制目录,保留 CMakeLists.txt 的 ZAP 驱动结构;
- 按实际硬件调整
prj.conf(Flash 大小、PID、设备名); - 量产前务必验证 OTA 链路,并按本文流程用 Linux OTA Provider 做一次端到端升级测试。