Matter Telink All Clusters Minimal 示例:基于 Zephyr 的 B91/B92/W91 构建、烧录、配网与 OTA 实战指南

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

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 工具链版本不一致的问题。

  1. 启动构建容器(推荐方式,镜像版本从 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 镜像标签并挂载当前目录。仓库内的对应证据:

  1. 激活构建环境:
$ 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)。

  1. 先构建 chip-tool CLI,构建方法详见 examples/chip-tool/README.md(典型方式是通过 scripts/examples/gn_build_example.sh examples/chip-tool/linux out/chip-tool 一类 GN 构建脚本生成可执行文件)。

  2. 通过 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:

  1. 在对应 prj.conf 中设置:
CONFIG_CHIP_OTA_REQUESTOR=y
  1. 重新构建后,会生成两类二进制文件:
  • merged.bin:烧录到 PCB 的主固件(至少需要 2 MB Flash);
  • matter.ota:提供给 OTA Provider 的升级镜像。
  1. 版本号约束:以上两个文件具有相同的 SW 版本。要实际测试 OTA 流程,matter.ota 的软件版本必须高于设备当前运行的版本。在 prj.conf 中把基础版本设为较低值即可,例如:
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2

(即设备基础固件用 =1,OTA 镜像用 =2,以此制造版本差。)

OTA 完整操作流程

  1. 构建 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)配网。

  1. 运行 OTA Provider 并指定升级镜像:
./chip-ota-provider-app -f matter.ota
  1. 使用 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。

  1. 配置 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 表示不限集群与端点。

  1. 通知设备开始 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 做一次端到端升级测试。
登录后查看全文
connectedhomeip