Matter Telink All Clusters 示例应用实战指南:构建、烧录、配网与 OTA 全流程解析

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

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,revision 1c96e97...),通过 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 中的集群替换为你自己的业务集群,即可快速产出产品级应用。

登录后查看全文
connectedhomeip