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本文围绕 MatterCSA 联盟主导的开源智能家居协议在 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.cppZCL 集群回调Identify、OnOff、LevelControl 等include/AppTask.h应用任务类与端点定义prj.confZephyr 构建配置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/SoCBuild target说明B91TLSR9518ADK80Dtlsr9518adk80d、tlsr9518adk80d-mars、tlsr9518adk80d-usbTLSR951x 系列通用入门套件B92TLSR9528Atlsr9528a、tlsr9528a_retentionTLSR952x 系列W91TLSR9118BDK40Dtlsr9118bdk40dTLSR911x 系列说明以上开发板硬件资料位于 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.0riscv64-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,telinkactivate.sh会为当前 shell 配置 GN/构建工具链与 Python 虚拟环境是 scripts/activate.sh 提供的标准入口。3. 构建示例将build_target替换为上面表格中的板卡名$ west build -b build_target如果你的板载 Flash 不是默认的 2 MB需要显式指定-DFLASH_SIZE例如-DFLASH_SIZE1m或-DFLASH_SIZE4m$ west build -b build_target -- -DFLASH_SIZE4m构建完成后目标固件位于build/zephyr目录下文件名为zephyr.bin。提示west是 Zephyr 的元构建工具示例的构建依赖west工程结构Docker 镜像已内置。4. 烧录固件$ west flash --erase--erase参数会在烧录前擦除目标 Flash保证全新状态运行。设备端默认配置速览示例的 Zephyr 配置集中在 prj.conf理解这些配置有助于调试配置项值含义CONFIG_CHIPyy启用 MatterCHIP协议栈CONFIG_CHIP_DEVICE_PRODUCT_ID327730x8005设备产品 ID0x8005即官方示例 lighting-app 的分配值CONFIG_BT_DEVICE_NAMETelinkLight—BLE 广播设备名配网时可见CONFIG_CHIP_OTA_REQUESTORnn默认关闭 OTA 请求端OTA 需单独开启CONFIG_PWMyy使用 PWM 驱动 RGB 灯关闭 PWM 时回退到普通 LEDCONFIG_PMnn关闭电源管理简化调试CONFIG_CHIP_LIB_SHELLnn关闭 CHIP shellCONFIG_CHIP_FACTORY_DATAnn关闭工厂数据使用默认开发证书使用串口与交互UART 输出设备串口输出需要连接以下引脚名称引脚RXPB3J34 连接器第 17 脚TXPB2J34 连接器第 16 脚GNDGND波特率115200 bit/s。使用任意串口终端minicom、screen、PuTTY连接即可看到设备日志与 Matter 协议栈输出。改用 USB COM 口代替 UART部分板卡如tlsr9518adk80d-usb支持通过 USB CDC 提供控制台无需外接串口线以如下参数重新构建$ west build -b build_target -- -DTLNK_USB_DONGLEy将 USB 线连接到设备系统会出现新的串口设备Linux 下如/dev/ttyACM0Windows 下为 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 配网并在设备上启用 ThreadButton 4打开配网窗口打开 commissioning 窗口以便通过 BLE 进行配网按键事件在 src/AppTask.cpp 的LightingActionEventHandler中处理kEventType_Button事件会翻转sfixture_on状态并调用UpdateClusterState()将新的 OnOff 值写入 Matter 集群属性Clusters::OnOff::Attributes::OnOff::Set实现按键与云端/控制器状态的同步。LED 状态指示红色 LED指示 Thread 网络状态状态描述短脉冲闪烁设备未配网到 ThreadThread 已禁用高频脉冲闪烁设备已配网、Thread 已启用正在尝试 JOIN Thread 网络宽脉冲闪烁设备已配网并作为 CHILD 加入 Thread 网络绿色 LED用于设备 Identify识别指示。收到 Identify 集群的 Identify 命令后开始闪烁命令参数可指定效果效果描述闪烁200 ms 亮/200 ms 灭BlinkClusters::Identify::EffectIdentifierEnum::kBlink呼吸1000 ms 周期BreatheClusters::Identify::EffectIdentifierEnum::kBreathe闪烁50 ms 亮/950 ms 灭OkayClusters::Identify::EffectIdentifierEnum::kOkay闪烁1000 ms 亮/1000 ms 灭Channel ChangeClusters::Identify::EffectIdentifierEnum::kChannelChange闪烁950 ms 亮/50 ms 灭FinishClusters::Identify::EffectIdentifierEnum::kFinishEffectLED 关闭StopClusters::Identify::EffectIdentifierEnum::kStopEffect从源码看灯光状态实际由 src/AppTask.cpp 的SetInitiateAction()驱动开启时通过PwmManager按 RGB 分量红/绿/蓝三路 PWM取值 0~1000 映射自 0~255点亮关闭时三路 PWM 全部熄灭LEVEL_ACTION亮度、COLOR_ACTION_XYXY 色度、COLOR_ACTION_HSVHSV、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 码20202021Discriminator3840./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 38403. 打开灯光${CHIP_TOOL_DIR}/chip-tool onoff on 1参数说明onoff—— 集群名On/Off 集群on—— 发送给集群的命令1—— 端点 IDEndpoint 1。4. 关闭灯光${CHIP_TOOL_DIR}/chip-tool onoff off 1onoff—— 集群名off—— 命令1—— 端点 ID。5. 读取灯光状态${CHIP_TOOL_DIR}/chip-tool onoff read on-off 1onoff—— 集群名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~2540—— 过渡时间transition time0—— option mask0—— option override1—— 端点 ID。7. 读取亮度等级./chip-tool levelcontrol read current-level 1levelcontrol—— 集群名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 ProviderOTA 功能默认仅在 ota-requestor-app 示例中启用。要为其他 Telink 示例开启 OTA在对应的prj.conf配置文件中设置CONFIG_CHIP_OTA_REQUESTORy。开启 OTA 后构建应用会产出两个二进制merged.bin—— 烧录到 PCB 的主固件至少需要 2 MB Flashmatter.ota—— 提供给 OTA Provider 的升级包。两个二进制具有相同的软件版本。要测试 OTAmatter.ota的软件版本必须高于基础固件版本在prj.conf中设置CONFIG_CHIP_DEVICE_SOFTWARE_VERSION2。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_blefalse② 携带 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} 0ACL 中第一条赋予 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_MCUBOOTy时编入。使用 Pigweed RPC 构建示例支持通过 Pigweed RPC 从 USB 连接的主机控制照明应用的各项功能其 RPC 服务定义于 lighting 应用公共目录公共 RPC 基础设施位于 examples/common/pigweed包含 echo、actions、attributes、boolean_state、device 等服务。构建启用 RPC 服务器的版本$ west build -b build_target -- -DOVERLAY_CONFIGrpc.overlay对应的 RPC 配置覆盖文件为 rpc.overlay其关键设置包括CONFIG_CHIP_PW_RPCy—— 启用 Pigweed RPC启用 Zephyr console 子系统CONFIG_CONSOLE_SUBSYSy、CONFIG_CONSOLE_GETCHARy用于 Pigweed 控制台关闭可能与 Pigweed HDLC 传输冲突的功能CONFIG_SHELLn、CONFIG_OPENTHREAD_SHELLn、CONFIG_BOOT_BANNERn关闭 Zephyr logger 的 UART/RTT 后端CONFIG_LOG_BACKEND_UARTn、CONFIG_LOG_BACKEND_RTTn因为应用自带基于 Pigweed HDLC 的日志通道提高 console 收发缓冲区CONFIG_CONSOLE_PUTCHAR_BUFSIZE256、CONFIG_CONSOLE_GETCHAR_BUFSIZE128。扩展多端点 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 中声明新端点 IDkExampleSecondaryEndpointId 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 硬件产品上。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考