Matter Telink All Clusters 示例应用实战指南:构建、烧录、配网与 OTA 全流程解析
Matter Telink All Clusters 示例应用实战指南:构建、烧录、配网与 OTA 全流程解析
本指南以 connectedhomeip 仓库中 examples/all-clusters-app/telink/README.md 为骨架,系统讲解 Matter Telink All Clusters 示例应用在 Telink B91/B92/W91 系列 SoC 上的完整开发流程:从 Docker 构建环境的搭建、west 编译与烧录,到 UART 串口调试、按键与 LED 交互、chip-tool 配网,以及基于 Linux OTA Provider 的固件升级。读完本文,你将能独立完成一个 Telink Matter 设备的构建、调试、入网与 OTA 验证,并理解其背后的配置体系与源码实现。
示例应用概览:三个 Endpoint 的 ZCL 集群集合
Telink All Clusters Example Application 是 Matter SDK 中最具代表性的综合示例之一:它在 三个 Endpoint 上布满了各类 ZCL(Zigbee Cluster Library)集群,覆盖照明、开关、温控、门锁、能耗、模式选择等常见场景,官方定位是「作为开发自有应用的参考模板」。
从 CMakeLists.txt 可以看到,该应用的数据模型由 ZAP 文件驱动:
chip_configure_data_model(app
ZAP_FILE ${ALL_CLUSTERS_COMMON_DIR}/all-clusters-app.zap
)
ZAP 文件位于 examples/all-clusters-app/all-clusters-common/all-clusters-app.zap,构建时会通过 chip_data_model.cmake 自动生成对应的数据模型代码(生成产物在 zzz_generated/ 目录)。同时 CMakeLists.txt 还引入了大量 all-clusters-common 下的集群 stub 实现(如 fan、thermostat-mode、oven-modes、rvc-modes、air-quality 等),这些文件为各集群提供了静态的 SupportedModes、OperationalState 等委托实现,是理解「哪些集群可用、如何扩展」的最佳切入点。
应用自身代码非常精简,核心逻辑集中在 src/AppTask.cpp:初始化公共部件、配置 Binding Handler、注册 ModeSelect 集群的 SupportedModesManager。其余绝大多数功能(BLE、Thread、按键、LED、OTA、工厂复位)由 Telink 平台公共代码 examples/platform/telink 承载。
支持的设备与构建目标
当前版本支持以下三款 Telink 开发板/SoC:
| 开发板/SoC | 构建目标(-b 参数) |
说明 |
|---|---|---|
| B91 通用入门套件(TLSR9518ADK80D) | tlsr9518adk80d、tlsr9518adk80d-mars、tlsr9518adk80d-usb |
经典 B91 平台,Thread 网络 |
| B92 通用入门套件(TLSR9528A) | tlsr9528a、tlsr9528a_retention |
支持 retention(低功耗保留 RAM)变体 |
| W91 通用入门套件(TLSR9118BDK40D) | tlsr9118bdk40d |
Wi-Fi 平台(走 CONFIG_CHIP_WIFI 路径,而非 Thread) |
从 Kconfig.defaults 可以看出平台对 Thread 与 Wi-Fi 的自动分流:NET_L2_OPENTHREAD 默认在非 Wi-Fi 板上启用;而 CONFIG_CHIP_WIFI 仅在 tlsr9118bdk40d 类板上启用并自动 select WIFI_W91。因此 B91/B92 走 Thread 协议栈,W91 走 Wi-Fi 协议栈,两者在按键事件、配网路径上会有差异(详见下文)。
构建环境:Docker 容器与 Zephyr 工具链
1. 启动 Docker 构建容器
官方推荐在 Docker 容器中构建,一条命令即可拉取并进入与当前仓库版本匹配的构建镜像:
$ 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 中自动提取当前使用的镜像标签(例如 chip-build-telink:215),确保本地镜像与 CI 一致。
镜像内容由 integrations/docker/images/stage-2/chip-build-telink/Dockerfile 定义,其中包含:
- Zephyr SDK 0.17.0(
zephyr-sdk-0.17.0_linux-x86_64_minimal,安装riscv64-zephyr-elf工具链); - Telink 定制的 Zephyr 4.1.0 分支(
telink-semi/tl_zephyr,revision1c96e97...),通过west init -l、west update拉取全部模块; - 通过
west blobs fetch hal_telink获取 Telink HAL 二进制; - 为 W91 板执行
telink_w91_post_build后处理脚本。
也就是说,容器内已经装好了「推荐的 Zephyr 版本 + 完整工具链」,这是保证构建可复现的关键。如需核对版本兼容性,直接查看上述两个文件即可。
2. 激活构建环境
在容器内(或已自行安装 Zephyr 工具链的主机)激活 Matter 的 Python 构建环境:
$ source ./scripts/activate.sh -p all,telink
-p all,telink 表示安装包括 telink 平台在内的全部依赖(Zephyr、west 等)。该脚本定义在 scripts/activate.sh。
编译与烧录
3. 构建示例应用
在示例目录下执行 west build:
$ west build -b <build_target>
<build_target> 替换为上文表格中的板名,例如:
$ west build -b tlsr9518adk80d
如果你的板载 Flash 容量不是默认的 2 MB,需要通过 CMake 变量 -DFLASH_SIZE 指定,例如:
$ west build -b tlsr9518adk80d -- -DFLASH_SIZE=1m
# 或
$ west build -b tlsr9518adk80d -- -DFLASH_SIZE=4m
构建成功后,固件位于 build/zephyr/ 目录下,核心文件是 zephyr.bin。此外,若启用了 OTA 与 MCUboot 相关配置,该目录下还会生成 merged.bin(合并了 bootloader 的整包,用于烧录)和 matter.ota(OTA 升级镜像,用于 OTA Provider),详见「OTA 升级」一节。
4. 烧录固件
连接开发板后,使用 west 直接烧录,--erase 会先擦除 Flash:
$ west flash --erase
west flash 依赖 Zephyr 的 runner 机制自动识别调试器(B91/B92 通常使用 J-Link 或板载调试器,W91 走 telink_w91_post_build 流程)。
配置体系深入解析
应用级配置 prj.conf
examples/all-clusters-app/telink/prj.conf 只存放「本示例特有」的配置,其余默认值统一由平台级 Kconfig.defaults 提供。关键项如下:
| 配置项 | 值 | 含义 |
|---|---|---|
CONFIG_CHIP |
y |
启用 Matter/CHIP 协议栈 |
CONFIG_STD_CPP20 |
y |
使用 C++20 标准 |
CONFIG_CHIP_DEVICE_PRODUCT_ID |
32769(0x8001) |
产品 ID,all-clusters-app 专用 |
CONFIG_BT_DEVICE_NAME |
"TelinkApp" |
BLE 广播设备名 |
CONFIG_CHIP_OTA_REQUESTOR |
n |
本示例默认关闭 OTA 请求者角色(平台默认值为 y,此处显式覆盖) |
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION |
1 |
软件版本号,OTA 升级测试时需要调高 |
CONFIG_CHIP_LIB_SHELL |
n |
关闭 CHIP shell(节省 Flash) |
CONFIG_CHIP_FACTORY_DATA 等 |
n |
关闭工厂数据(DAC 使用示例默认证书) |
CONFIG_PM |
n |
关闭电源管理(本示例不做低功耗) |
注意 Kconfig.defaults 中平台默认 CONFIG_CHIP_OTA_REQUESTOR=y、CONFIG_CHIP_DEVICE_SOFTWARE_VERSION 通过其他渠道设置,而本示例在 prj.conf 中显式关闭 OTA 并设置版本号为 1——这正是 README 中「OTA 功能默认仅对 ota-requestor-app 启用」的配置来源。
平台默认值 Kconfig.defaults
config/telink/chip-module/Kconfig.defaults 是整个 Telink 平台的「配方」文件,值得关注的核心默认值包括:
- Thread 角色:默认
CHIP_THREAD_DEVICE_ROLE_ROUTER(FTD),可选 END_DEVICE(MTD)与 SLEEPY_END_DEVICE(低功耗 ICD); - BLE 参数:
BT_PERIPHERAL_PREF_MIN_INT/MAX_INT=36、BT_PERIPHERAL_PREF_TIMEOUT=500(5 秒,提升连接可靠性)、BT_CONN_PARAM_UPDATE_TIMEOUT=1000(避免配网期间连接参数更新过慢导致不稳定)、BT_MAX_CONN=1; - 网络缓冲:
NET_PKT_RX_COUNT/TX_COUNT在 PM 或 TLX 平台上压缩为 4,常规平台为 8; - 栈大小:
MAIN_STACK_SIZE按 SoC 区分(B91/W91 为 4864,B92/TL323X 为 3560); - OTA:
CONFIG_CHIP_OTA_REQUESTOR默认y,CHIP_OTA_REQUESTOR_BUFFER_SIZE=256; - mbedTLS:默认启用 AES/CCM/ECDH/ECDSA/HKDF 等,TLX 平台还默认开启硬件加速(
TELINK_TLX_MBEDTLS_HW_ACCELERATION); - 自动配网:
CONFIG_CHIP_ENABLE_PAIRING_AUTOSTART=y,设备未配网时开机自动打开配网窗口; - NVS:
SETTINGS_NVS_SECTOR_SIZE_MULT=1使 NVS 扇区为 4KB。
项目级配置 CHIPProjectConfig.h
examples/all-clusters-app/telink/include/CHIPProjectConfig.h 定义了 Matter 层的编译期常量:
#define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_PIN_CODE 20202021
#define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR 0xF00
#define CHIP_CONFIG_MAX_GROUP_ENDPOINTS_PER_FABRIC 3
#define CHIP_CONFIG_MAX_GROUPCAST_MEMBERSHIP_COUNT 24
#define CHIP_CONFIG_ENABLE_ACL_EXTENSIONS 1
其中 20202021 是默认配网 PIN 码,0xF00(3840) 是默认配对 Discriminator——这两者会直接用于下文 chip-tool 的配对命令。MAX_GROUP_ENDPOINTS_PER_FABRIC=3 对应本应用 3 个 Endpoint 上的 Group Key Management 集群,MAX_GROUPCAST_MEMBERSHIP_COUNT=24 是为兼容硬编码的 TestGroupKeyManagementCluster.yaml 测试用例而临时放宽的上限。
使用:串口、按键与 LED
UART 串口日志
开发板通过 UART 输出日志,连接 B91 的 J34 连接器对应引脚:
| 名称 | 引脚 |
|---|---|
| RX | PB3(J34 连接器第 17 脚) |
| TX | PB2(J34 连接器第 16 脚) |
| GND | GND |
波特率为 115200 bits/s。串口日志级别由 CONFIG_CHIP_APP_LOG_LEVEL 控制(平台默认 debug 级),开机时会打印 SW Version、Matter/Zephyr/OpenThread 的版本与提交信息(见 AppTaskCommon.cpp 中的 PrintFirmwareInfo())。
按键功能(tlsr9518adk80d)
| 按键 | 功能 | 说明 |
|---|---|---|
| Button 1 | 恢复出厂设置 | 连续按下 3 次触发工厂复位,清除已配网的 Thread 网络与 Fabric,回到未配网状态 |
| Button 2 | 未使用 | 预留 |
| Button 3 | Thread 启动 | 使用静态凭据配好 Thread 网络并在设备上使能 Thread |
| Button 4 | 打开配网窗口 | 打开配网窗口,通过 BLE 执行配网 |
这些逻辑在 AppTaskCommon.cpp 中有精确的源码对应:
- 工厂复位:
FactoryResetHandler()维护一个 3 次计数(kFactoryResetTriggerCntr = 3),配 3 秒超时定时器(kFactoryResetCalcTimeout = 3000),3 秒内按满 3 次才调用chip::Server::GetInstance().ScheduleFactoryReset();超时后计数自动清零,防止误触。 - Thread 启动:
StartThreadHandler()在设备未配网时调用SetThreadEnabled(true)与StartDefaultThreadNetwork()。静态凭据(MasterKey、网络名、PAN ID、XPANID 等)定义在 ThreadUtil.cpp 的StartDefaultThreadNetwork()中,可编译期通过 Kconfig 修改。 - 打开配网窗口:
ToggleBleAdvHandler()调用OpenBasicCommissioningWindow();若设备已配网,则切换 BLE 广播开关(并发模式下用于按需启用 BLE 广播)。
按键到处理函数的映射见 LinkButtons():Button 0 → 工厂复位、Button 1 → 示例动作、Button 2 → BLE 广播/OTA 测试、Button 3 → Thread/Wi-Fi 启动。
LED 状态指示
红色 LED 指示 Thread 网络当前状态(逻辑见 UpdateStatusLED()):
| 状态 | 闪烁模式 | 含义 |
|---|---|---|
| 短脉冲闪烁 | 50 ms 亮 / 950 ms 灭 | 未配网到 Thread,Thread 未启用 |
| 频繁脉冲闪烁 | 100 ms 亮 / 100 ms 灭 | 已配网、Thread 已启用,正在尝试 JOIN 网络 |
| 宽脉冲闪烁 | 950 ms 亮 / 50 ms 灭 | 已配网且已作为 CHILD 加入 Thread 网络 |
绿色 LED 用于设备 Identify(识别)指示:收到 Identify 集群的 Identify 命令后开始按指定效果闪烁。效果与命令参数(EffectIdentifier)的对应关系及底层实现如下:
| 效果 | 表现 | 枚举值 |
|---|---|---|
| Blink | 200 ms 亮 / 200 ms 灭 | Clusters::Identify::EffectIdentifierEnum::kBlink |
| Breathe | 1000 ms 呼吸渐变 | ...::kBreathe |
| Okay | 50 ms 亮 / 950 ms 灭 | ...::kOkay |
| Channel Change | 1000 ms 亮 / 1000 ms 灭 | ...::kChannelChange |
| Finish | 950 ms 亮 / 50 ms 灭 | ...::kFinishEffect |
| Stop | LED 熄灭 | ...::kStopEffect |
源码实现位于 AppTaskCommon.cpp 的 IdentifyEffectHandler(),通过 PwmManager 驱动 PWM 通道(EAppPwm_Indication)完成各种闪烁节奏;Identify 集群的实例注册见同文件的 sIdentifyInstances[](endpoint、Start/Stop Handler、IdentifyTypeEnum::kVisibleIndicator)。
配网:chip-tool 通过 BLE + Thread 配对
构建 chip-tool
chip-tool 是 Matter 官方命令行调试控制器,构建方法见 examples/chip-tool/README.md:
$ ./scripts/examples/gn_build_example.sh examples/chip-tool out/chip-tool
配对命令
${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
各参数含义:
${NODE_ID}:为设备分配的操作节点 ID(如1234);hex:${DATASET}:Thread 网络数据集(Active Operational Dataset)的十六进制 TLV 编码;${PIN_CODE}:设备配网 PIN 码,本示例默认 20202021(见 CHIPProjectConfig.h);${DISCRIMINATOR}:设备广播的 Discriminator,本示例默认 3840(0xF00)。
完整示例:
./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840
配对流程:chip-tool 先通过 BLE 与设备建立 Matter 配网会话(设备侧走 CONFIG_CHIP_ENABLE_PAIRING_AUTOSTART 开机自动打开的配网窗口),写入 Fabric 凭据与 Thread 数据集后,设备切换至 Thread 网络并完成操作发现(Operational Discovery)。
OTA 升级:以 Linux OTA Provider 为例
OTA 请求者功能默认只对 ota-requestor-app 示例启用;要为其他 Telink 示例(如本 all-clusters-app)启用,需要在对应 prj.conf 中设置:
CONFIG_CHIP_OTA_REQUESTOR=y
启用 OTA 后构建产物中会出现两个关键文件:
- merged.bin:合并了 bootloader 的主固件,烧录到 PCB(要求 PCB 至少 2 MB Flash);
- matter.ota:供 OTA Provider 分发的升级镜像。
两个文件使用相同的 SW 版本号。要测试 OTA 升级,matter.ota 的软件版本必须高于设备当前固件版本,因此在 prj.conf 中把版本号调高即可:
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=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
2. 运行 OTA Provider 并指定升级镜像:
./chip-ota-provider-app -f matter.ota
3. 使用 chip-tool 通过 on-network 方式配对 OTA Provider:
./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021
其中 ${OTA_PROVIDER_NODE_ID} 是 Linux OTA Provider 的节点 ID。
4. 配置 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
第一条 ACL 授予 privilege: 5(Administer)给 subjects: [112233](OTA 请求者节点),第二条授予 privilege: 3(Operate)给整个 Fabric。${OTA_PROVIDER_NODE_ID} 为 OTA Provider 节点 ID。
5. 发起 OTA 公告,触发升级:
./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0
其中 ${OTA_PROVIDER_NODE_ID} 为 OTA Provider 节点 ID,${DEVICE_NODE_ID} 为已配网目标设备(OTA 请求者)的节点 ID。
传输完成后,OTA 请求者会向 OTA Provider 发送 ApplyUpdateRequest 命令请求应用镜像;镜像应用成功后设备自动重启,进入新版本。设备侧的 OTA 状态机(DownloadInProgress / DownloadComplete / ApplyInProgress / ApplyComplete 等)日志可在 AppTaskCommon.cpp 的 OtaEventsHandler() 中看到对应打印。
源码结构导读
若想基于本示例开发自有产品,以下文件值得重点阅读:
| 路径 | 作用 |
|---|---|
| examples/all-clusters-app/telink/prj.conf | 应用级 Kconfig 配置(PID、BLE 名称、OTA 开关、版本号) |
| examples/all-clusters-app/telink/CMakeLists.txt | 构建目标定义:数据模型 ZAP、集群 stub 源文件、平台公共源文件 |
| examples/all-clusters-app/telink/src/AppTask.cpp | 应用入口与初始化(Binding、ModeSelect 管理器) |
| examples/all-clusters-app/telink/include/CHIPProjectConfig.h | Matter 编译期常量(PIN 码、Discriminator、Group 配置) |
| examples/platform/telink/common/src/AppTaskCommon.cpp | 平台公共任务:按键、LED/PWM、BLE、Thread、工厂复位、OTA 事件 |
| examples/platform/telink/util/src/ThreadUtil.cpp | 静态 Thread 网络凭据与 StartDefaultThreadNetwork() |
| config/telink/chip-module/Kconfig.defaults | Telink 平台全部默认 Kconfig 配方 |
| integrations/docker/images/stage-2/chip-build-telink/Dockerfile | 构建镜像内容(Zephyr 版本、工具链) |
| .github/workflows/examples-telink.yaml | CI 构建矩阵与镜像版本 |
常见注意事项
- Flash 容量:默认按 2 MB 设计,板载容量不同时务必使用
-DFLASH_SIZE调整,否则可能出现链接溢出或运行时异常; - OTA 版本号:分发用的
matter.ota版本必须高于设备当前版本,否则 OTA 请求者会拒绝更新; - 工厂复位:需在 3 秒内连按 3 次 Button 1,单次或慢速按压不会触发复位(源码中定时器会清零计数);
- BLE 与 Thread 切换:B91/B92 配网完成后 BLE 连接断开,系统自动切换到 Thread(
Switch to Thread日志);若配网中断,fail-safe 定时器会被强制到期,避免设备长时间停留在未完成状态; - W91 Wi-Fi 平台:构建目标为
tlsr9118bdk40d,默认 Wi-Fi SSID/密码可通过CONFIG_DEFAULT_WIFI_SSID/CONFIG_DEFAULT_WIFI_PASSWORD设置(仅用于测试,生产环境应关闭),按键 3 触发StartDefaultWiFiNetwork()。
通过以上全流程,你已具备从零构建、烧录、配网并 OTA 升级一个 Telink Matter 设备的能力;在此基础上,将 examples/all-clusters-app/all-clusters-common 中的集群替换为你自己的业务集群,即可快速产出产品级应用。