Matter Telink 照明应用示例（Lighting App）构建、烧录与调试全指南-平芜编程栈

Matter Telink 照明应用示例（Lighting App）构建、烧录与调试全指南

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip

本文围绕 Matter（CSA 联盟主导的开源智能家居协议）在 Telink 平台上的官方示例应用 —— Telink Lighting Example Application 展开。该示例演示如何远程控制一盏可调光白色灯泡：通过板载按键切换灯光与设备状态，通过 LED 反馈状态变化，并可作为你开发自有 Matter 设备的参考起点。读完本文，你将掌握：Telink 开发板的构建/烧录环境搭建、UART 与 USB 控制台调试方法、按键与 LED 的交互逻辑、使用 chip-tool 进行 Thread 配网与 OnOff/LevelControl 集群控制，以及 OTA 固件升级和 Pigweed RPC 扩展。

示例定位与整体架构

Telink Lighting 示例属于 examples/lighting-app 系列在 Zephyr RTOS 平台上的落地实现，仓库根目录为 examples/lighting-app/telink。它复用了 Telink 平台公共代码 examples/platform/telink（如mainCommon.cpp、AppTaskCommon.cpp、LEDManager.cpp、ButtonManager.cpp、ThreadUtil.cpp、PWMManager.cpp等），应用自身逻辑位于：

src/AppTask.cpp：应用任务入口，负责按键事件处理、集群状态同步（OnOff / LevelControl / ColorControl）与 LED/PWM 驱动；
src/ZclCallbacks.cpp：ZCL 集群回调（Identify、OnOff、LevelControl 等）；
include/AppTask.h：应用任务类与端点定义；
prj.conf：Zephyr 构建配置（Kconfig）。

构建系统通过 CMakeLists.txt 将以上源文件与chip_data_model.cmake、chip_configure_data_model（数据模型文件为 examples/lighting-app/lighting-common/lighting-app.zap）串联起来，最终产出可在 Telink B91/B92/W91 系列芯片上运行的固件。

支持的开发板与构建目标

示例支持以下 Telink 开发板/SoC，构建时以-b <build_target>指定目标：

Board/SoC	Build target	说明
B91（TLSR9518ADK80D）	`tlsr9518adk80d`、`tlsr9518adk80d-mars`、`tlsr9518adk80d-usb`	TLSR951x 系列通用入门套件
B92（TLSR9528A）	`tlsr9528a`、`tlsr9528a_retention`	TLSR952x 系列
W91（TLSR9118BDK40D）	`tlsr9118bdk40d`	TLSR911x 系列

说明：以上开发板硬件资料位于 Telink 官方 wiki，本文不展开外部链接，构建目标名即west build -b的参数值。

构建与烧录

1. 使用 Docker 容器搭建构建环境

官方推荐的构建方式是在 Docker 容器内进行，一条命令即可拉起包含推荐 Zephyr 版本的环境：

$ 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)

默认容器内包含的推荐 Zephyr 版本由 integrations/docker/images/stage-2/chip-build-telink/Dockerfile 指定。从仓库当前 Dockerfile 可以看到，其基于 Zephyr SDK0.17.0（riscv64-zephyr-elf工具链），Zephyr 内核来自 Telink 的tl_zephyr仓库（revision 固定为5421d0e...，对应 Zephyr 4.1.0 分支），并通过west blobs fetch hal_telink拉取芯片 HAL 闭源 blob；
兼容的镜像版本可在 .github/workflows/examples-telink.yaml 中查看（当前 CI 使用的为chip-build-telink:211）。

2. 激活构建环境

$ source ./scripts/activate.sh -p all,telink

activate.sh会为当前 shell 配置 GN/构建工具链与 Python 虚拟环境，是 scripts/activate.sh 提供的标准入口。

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

构建完成后，目标固件位于build/zephyr目录下，文件名为zephyr.bin。

提示：west是 Zephyr 的元构建工具，示例的构建依赖west工程结构，Docker 镜像已内置。

4. 烧录固件

$ west flash --erase

--erase参数会在烧录前擦除目标 Flash，保证全新状态运行。

设备端默认配置速览

示例的 Zephyr 配置集中在 prj.conf，理解这些配置有助于调试：

配置项	值	含义
`CONFIG_CHIP=y`	y	启用 Matter（CHIP）协议栈
`CONFIG_CHIP_DEVICE_PRODUCT_ID=32773`	0x8005	设备产品 ID，`0x8005`即官方示例 lighting-app 的分配值
`CONFIG_BT_DEVICE_NAME="TelinkLight"`	—	BLE 广播设备名，配网时可见
`CONFIG_CHIP_OTA_REQUESTOR=n`	n	默认关闭 OTA 请求端（OTA 需单独开启）
`CONFIG_PWM=y`	y	使用 PWM 驱动 RGB 灯（关闭 PWM 时回退到普通 LED）
`CONFIG_PM=n`	n	关闭电源管理，简化调试
`CONFIG_CHIP_LIB_SHELL=n`	n	关闭 CHIP shell
`CONFIG_CHIP_FACTORY_DATA=n`	n	关闭工厂数据（使用默认开发证书）

使用：串口与交互

UART 输出

设备串口输出需要连接以下引脚：

名称	引脚
RX	PB3（J34 连接器第 17 脚）
TX	PB2（J34 连接器第 16 脚）
GND	GND

波特率：115200 bit/s。使用任意串口终端（minicom、screen、PuTTY）连接即可看到设备日志与 Matter 协议栈输出。

改用 USB COM 口代替 UART

部分板卡（如tlsr9518adk80d-usb）支持通过 USB CDC 提供控制台，无需外接串口线：

以如下参数重新构建：

$ west build -b <build_target> -- -DTLNK_USB_DONGLE=y

将 USB 线连接到设备，系统会出现新的串口设备（Linux 下如/dev/ttyACM0，Windows 下为 COM 口）；
用任意终端软件连接该串口；

源码中需包含以下头文件并初始化 USB 设备栈：

#ifdef CONFIG_USB_DEVICE_STACK #include <zephyr/usb/usb_device.h> #endif /* CONFIG_USB_DEVICE_STACK */ #ifdef CONFIG_USB_DEVICE_STACK usb_enable(NULL); #endif /* CONFIG_USB_DEVICE_STACK */

板载按键（tlsr9518adk80d）

按键	功能	说明
Button 1	恢复出厂设置	连按 3 次触发，忘记当前已配网的 Thread 网络并回到未配网状态
Button 2	灯光控制	手动触发灯光状态切换（开/关）
Button 3	启动 Thread	使用静态凭据完成 Thread 配网并在设备上启用 Thread
Button 4	打开配网窗口	打开 commissioning 窗口，以便通过 BLE 进行配网

按键事件在 src/AppTask.cpp 的LightingActionEventHandler中处理：kEventType_Button事件会翻转sfixture_on状态并调用UpdateClusterState()，将新的 OnOff 值写入 Matter 集群属性（Clusters::OnOff::Attributes::OnOff::Set），实现按键与云端/控制器状态的同步。

LED 状态指示

红色 LED指示 Thread 网络状态：

状态	描述
短脉冲闪烁	设备未配网到 Thread，Thread 已禁用
高频脉冲闪烁	设备已配网、Thread 已启用，正在尝试 JOIN Thread 网络
宽脉冲闪烁	设备已配网并作为 CHILD 加入 Thread 网络

绿色 LED用于设备 Identify（识别）指示。收到 Identify 集群的 Identify 命令后开始闪烁，命令参数可指定效果：

效果	描述
闪烁（200 ms 亮/200 ms 灭）	Blink（`Clusters::Identify::EffectIdentifierEnum::kBlink`）
呼吸（1000 ms 周期）	Breathe（`Clusters::Identify::EffectIdentifierEnum::kBreathe`）
闪烁（50 ms 亮/950 ms 灭）	Okay（`Clusters::Identify::EffectIdentifierEnum::kOkay`）
闪烁（1000 ms 亮/1000 ms 灭）	Channel Change（`Clusters::Identify::EffectIdentifierEnum::kChannelChange`）
闪烁（950 ms 亮/50 ms 灭）	Finish（`Clusters::Identify::EffectIdentifierEnum::kFinishEffect`）
LED 关闭	Stop（`Clusters::Identify::EffectIdentifierEnum::kStopEffect`）

从源码看，灯光状态实际由 src/AppTask.cpp 的SetInitiateAction()驱动：开启时通过PwmManager按 RGB 分量（红/绿/蓝三路 PWM，取值 0~1000 映射自 0~255）点亮；关闭时三路 PWM 全部熄灭；LEVEL_ACTION（亮度）、COLOR_ACTION_XY（XY 色度）、COLOR_ACTION_HSV（HSV）、COLOR_ACTION_CT（色温）分别调用 ColorFormat.h 中的颜色转换（XYToRgb、HsvToRgb、CTToRgb）后写回 PWM。

对于多端点 Identify 配置，参见 MULTI_ENDPOINT_IDENTIFY.md（本文末尾有摘要）。

使用 chip-tool 控制设备

1. 构建 chip-tool

先构建 chip-tool 命令行工具（Matter 官方控制器）。

2. 通过 BLE + Thread 配网

${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}

示例（DATASET 为 Thread 网络操作数据集，十六进制；PIN 码20202021，Discriminator3840）：

./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840

3. 打开灯光

${CHIP_TOOL_DIR}/chip-tool onoff on 1

参数说明：

onoff—— 集群名（On/Off 集群）；
on—— 发送给集群的命令；
1—— 端点 ID（Endpoint 1）。

4. 关闭灯光

${CHIP_TOOL_DIR}/chip-tool onoff off 1

onoff—— 集群名；off—— 命令；1—— 端点 ID。

5. 读取灯光状态

${CHIP_TOOL_DIR}/chip-tool onoff read on-off 1

onoff—— 集群名；read—— 读取命令；on-off—— 要读取的属性；1—— 端点 ID。

6. 调节亮度

${CHIP_TOOL_DIR}/chip-tool levelcontrol move-to-level 32 0 0 0 1

参数说明：

levelcontrol—— Level Control 集群；
move-to-level—— 命令；
32—— 亮度值（0~254）；
0—— 过渡时间（transition time）；
0—— option mask；
0—— option override；
1—— 端点 ID。

7. 读取亮度等级

./chip-tool levelcontrol read current-level 1

levelcontrol—— 集群名；read—— 命令；current-level—— 属性；1—— 端点 ID。

原理补充：这些命令最终通过 Matter 协议栈写入设备侧集群属性。设备端 src/AppTask.cpp 的UpdateClusterState()以Clusters::OnOff::Attributes::OnOff::Set/Clusters::LevelControl::Attributes::CurrentLevel::Set将状态落到数据模型，并由 ZCL 回调（src/ZclCallbacks.cpp）触发 PWM/LED 动作。设备重启时还会读取持久化的 OnOff/Level 属性值恢复状态（见Init()中CurrentLevel::Get与OnOff::Get的用法）。

OTA 固件升级（Linux OTA Provider）

OTA 功能默认仅在 ota-requestor-app 示例中启用。要为其他 Telink 示例开启 OTA：

在对应的prj.conf配置文件中设置CONFIG_CHIP_OTA_REQUESTOR=y。

开启 OTA 后构建应用，会产出两个二进制：

merged.bin—— 烧录到 PCB 的主固件（至少需要 2 MB Flash）；
matter.ota—— 提供给 OTA Provider 的升级包。

两个二进制具有相同的软件版本。要测试 OTA，matter.ota的软件版本必须高于基础固件版本：在prj.conf中设置CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=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

② 携带 OTA 镜像运行 OTA Provider：

./chip-ota-provider-app -f matter.ota

③ 使用 chip-tool 为 Linux OTA Provider 配网：

./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021

其中${OTA_PROVIDER_NODE_ID}是 Linux OTA Provider 的节点 ID。

④ 配置 ota-provider-app 的 ACL 以允许访问：

./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 中第一条赋予 subject112233管理员权限（privilege 5），第二条允许同 Fabric 下的管理节点以操作权限（privilege 3）访问。

⑤ 使用 chip-tool 广播 OTA Provider 以启动 OTA 流程：

./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}—— 已配网设备（OTA 请求端）节点 ID。

传输完成后，OTA 请求端会向 OTA Provider 发送ApplyUpdateRequest命令以应用镜像；镜像应用成功后设备将自动重启。仓库侧 OTA 相关实现位于 examples/platform/telink/util/src/OTAUtil.cpp（由 CMakeLists 在CONFIG_BOOTLOADER_MCUBOOT=y时编入）。

使用 Pigweed RPC 构建

示例支持通过 Pigweed RPC 从 USB 连接的主机控制照明应用的各项功能（其 RPC 服务定义于 lighting 应用公共目录，公共 RPC 基础设施位于 examples/common/pigweed，包含 echo、actions、attributes、boolean_state、device 等服务）。

构建启用 RPC 服务器的版本：

$ west build -b <build_target> -- -DOVERLAY_CONFIG=rpc.overlay

对应的 RPC 配置覆盖文件为 rpc.overlay，其关键设置包括：

CONFIG_CHIP_PW_RPC=y—— 启用 Pigweed RPC；
启用 Zephyr console 子系统（CONFIG_CONSOLE_SUBSYS=y、CONFIG_CONSOLE_GETCHAR=y）用于 Pigweed 控制台；
关闭可能与 Pigweed HDLC 传输冲突的功能：CONFIG_SHELL=n、CONFIG_OPENTHREAD_SHELL=n、CONFIG_BOOT_BANNER=n；
关闭 Zephyr logger 的 UART/RTT 后端（CONFIG_LOG_BACKEND_UART=n、CONFIG_LOG_BACKEND_RTT=n），因为应用自带基于 Pigweed HDLC 的日志通道；
提高 console 收发缓冲区（CONFIG_CONSOLE_PUTCHAR_BUFSIZE=256、CONFIG_CONSOLE_GETCHAR_BUFSIZE=128）。

扩展：多端点 Identify 配置

原文档附带的多端点识别指南 MULTI_ENDPOINT_IDENTIFY.md 说明了如何把示例从单端点扩展为多灯光端点。核心步骤：

在 ZAP 工具配置 examples/lighting-app/lighting-common/lighting-app.zap 中为 Endpoint 2（及更多端点）新增独立端点类型并启用 Identify 集群；
重新生成数据模型：./scripts/tools/zap/generate.py examples/lighting-app/lighting-common/lighting-app.zap；生成的头文件中会出现MATTER_DM_IDENTIFY_CLUSTER_SERVER_ENDPOINT_COUNT宏（双端点时为(2)，六端点时为(6)）；
在 include/AppTask.h 中声明新端点 ID（kExampleSecondaryEndpointId = 2等）并扩展TELINK_APP_IDENTIFY_ENDPOINTS(X)宏列表——公共 Telink 代码会为列表中的每个端点创建一个 Identify 实例；
IdentifyStartHandler/IdentifyStopHandler使用 Identify 实例携带的端点 ID，并保持现有指示 PWM 行为不变；OnOff / Level Control / Color Control 集群无需额外实例，自动作用于 ZAP 中配置的所有端点。

总结

Telink Lighting Example 是理解 Matter 设备端开发流程的完整范本，覆盖了从环境搭建、编译烧录、串口/按键/LED 交互，到 chip-tool 配网控制、OTA 升级与 RPC 扩展的端到端链路。开发者可以此示例为蓝本，结合 examples/lighting-app/telink 目录下的源码与配置文件，快速迁移到自己的 Telink B91/B92/W91 硬件产品上。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考