Matter Pump Controller 示例应用实战指南：在 nRF Connect、Telink 与 TI CC13XX/CC26XX 平台上实现泵控制器

Matter Pump Controller 示例应用实战指南在 nRF Connect、Telink 与 TI CC13XX/CC26XX 平台上实现泵控制器【免费下载链接】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原 Project CHIP官方仓库中的 Pump Controller 示例文档入口完整讲解这个“泵控制器”客户端设备的实现原理与三种平台nRF Connect、Telink、TI CC13XX/CC26XX的构建、烧录、配网和验证流程。读完后你可以理解 PumpManager 状态机如何与 OnOff 集群联动、示例的工程目录结构并能按各平台 README 独立完成从环境搭建到通过 chip-tool 控制泵的完整闭环。示例定位与仓库结构Pump Controller 示例的目标是演示如何实现一个泵控制器pump controller客户端设备具备基础的启动/停止start/stop功能通过按键改变泵的状态通过 LED 指示状态变化。该示例脱胎于lock-app并改造为模拟泵设备官方明确其定位为“创建自己泵应用的参考模板”同时声明 nRF Connect 版仅为 Matter 集成 nRF Connect SDK 的冒烟测试用途不建议直接作为市售产品基础。仓库中示例位于 examples/pump-controller-app 目录按平台分三套实现各平台自带 README即 文档入口 的 toctree 所聚合的内容平台入口目录设备构建系统nRF Connect SDKexamples/pump-controller-app/nrfconnectnRF52840 DKnrf52840dk/nrf52840、nRF5340 DKnrf5340dk/nrf5340/cpuappZephyr west sysbuildTelinkexamples/pump-controller-app/telinkB91TLSR9518ADK80D、B92TLSR9528A、W91TLSR9118BDK40DZephyr westDocker 容器TI SimpleLinkexamples/pump-controller-app/ti/cc13x4_26x4CC1354P10、CC2674P10、CC2674R10GN Ninja三套平台共用 examples/pump-controller-app/pump-controller-common 下的数据模型定义pump-controller-app.zap/pump-controller-app.matter与构建文件这体现了 Matter 示例“平台薄、数据模型厚”的组织方式。核心实现PumpManager 状态机以 nRF Connect 版为例Telink 与 TI 版结构相同均有PumpManager与ZclCallbacks核心逻辑集中在 PumpManager.h 和 PumpManager.cpp。状态与动作定义PumpManager定义了两组枚举enum Action_t { START_ACTION 0, STOP_ACTION, INVALID_ACTION }; enum State_t { kState_StartInitiated 0, kState_StartCompleted, kState_StopInitiated, kState_StopCompleted, };类以单例PumpMgr()形式暴露关键接口包括InitiateAction(int32_t aActor, Action_t aAction)发起启动/停止动作aActor用于记录触发者本地按键为 0Matter 命令则携带 actor 标识EnableAutoRestart(bool)/SetAutoStartDuration(uint32_t)自动重启开关与时长IsStopped()/IsActionInProgress()状态查询SetCallbacks(...)注册“动作已发起”与“动作已完成”两个回调供 UI 层LED/日志消费。状态迁移规则InitiateAction的核心约束是同一时间只允许一个动作在途且启动/停止必须成对完成当前为kState_StartCompleted时只接受STOP_ACTION迁移到kState_StopInitiated当前为kState_StopCompleted时只接受START_ACTION迁移到kState_StartInitiated迁移成功后启动PUMP_START_PERIOS_MS的硬件定时器k_timer并立即触发mActionInitiated_CB。定时器到期后TimerEventHandler在定时器任务上下文中并不直接改状态而是通过AppTask::Instance().PostEvent(event)把事件投递到应用主任务队列由PumpStartTimerEventHandler在主任务上下文中完成状态收尾kState_StartInitiated - kState_StartCompleted或kState_StopInitiated - kState_StopCompleted并回调mActionCompleted_CB。这种“定时器上下文只投递事件、主任务统一处理”的模式是 Zephyr 平台示例避免上下文竞争的标准做法。另外两个细节值得注意自动重启Auto Restart若mAutoRestart开启且动作是 Start 完成会再启动一个时长为mAutoStartDuration * 1000毫秒的定时器到期后AutoRestartTimerEventHandler以 actor0 自动发起一次START_ACTION。若期间有人手动发起 Stop代码会取消该定时器mAutoStartTimerArmed false; CancelTimer();保证手动操作优先。初始状态Init()将mState置为kState_StartCompleted即设备上电后默认可接受停止动作——这与“泵上电默认运行”的模拟设定一致。与 Matter 数据模型的桥接OnOff 集群回调泵设备的“开/关”在 Matter 数据模型中复用OnOff 集群。在 ZclCallbacks.cpp 中桥接逻辑非常直接void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath attributePath, uint8_t type, uint16_t size, uint8_t * value) { if (attributePath.mClusterId OnOff::Id attributePath.mAttributeId OnOff::Attributes::OnOff::Id) { PumpMgr().InitiateAction(0, *value ? PumpManager::START_ACTION : PumpManager::STOP_ACTION); } }也就是说无论 OnOff 属性是被控制器通过 On/Off/Toggle 命令改写还是被其他合法途径写入只要属性变更应用层都会把语义翻译成PumpManager::InitiateAction的启动/停止动作。配合emberAfOnOffClusterInitCallback中的AppTask::Instance().UpdateClusterState()在 OnOff 集群初始化时同步一次本地状态与 UI 显示就完成了“Matter 属性 → 应用状态机”的双向一致性。从 pump-controller-app.matter由 ZAP 从.zap生成、供代码评审用的 IDL可以看到该设备的数据模型包含 Identifycluster Identify 3、OnOffcluster OnOff 6、Descriptor、Binding、AccessControl、BasicInformation、OtaSoftwareUpdateProvider/Requestor、GeneralCommissioning 等集群即一个标准 Matter 从设备的最小完备集合。设备 UI 约定按键与 LED三个平台的 UI 语义一致都以按键触发“BLE 广播/配网、工厂重置、泵启停切换”以 LED 指示“配网/连接状态 泵运行状态”。nRF Connect 版LED 1整机状态短闪50ms 开/950ms 关 未配网等待连接快速均匀闪烁100ms/100ms 未配网且已有配网应用经 BLE 连上短闪灭950ms 开/50ms 关 已配网但无线全连接常亮 已配网且 Thread/服务全连接。LED 2模拟泵电机常亮 运行灭 停止2 秒内快速均匀闪烁 电机启动中。Button 1按住 6 秒发起工厂重置提前松手取消LED 1-4 同步闪烁提示按住少于 3 秒为 OTA 更新入口文档标注当前版本暂不支持。Button 2单击切换泵的开/关状态。Button 4单击启动 NFC 标签模拟并使能 BLE 广播默认 15 分钟窗口。Telink 版按键功能Button 1工厂重置连按 3 次忘记已配网 Thread 网络回到未配网状态Button 2手动触发泵状态切换Button 3使用静态凭据启动 Thread 组网Button 4打开配网窗口支持经 BLE 配网LED 分三路红色指示 Thread 网络状态短脉冲闪烁未入网/Thread 关闭密脉冲已配网正在尝试入网宽脉冲已作为 CHILD 加入 Thread 网络绿色指示 Identify 效果Blink/Breathe/Okay/Channel Change/Finish/Stop 六种效果对应Clusters::Identify::EffectIdentifierEnum各枚举值白色指示泵运行/停止。TI CC13XX/CC26XX 版操作功能左键 BTN-1 短按1000 ms开启/关闭 BLE 广播左键 BTN-1 长按5000 ms工厂重置右键 BTN-2 短按1000 ms切换泵状态红/绿 LED 闪烁泵正在 Start/Stop 过渡红绿 LED 常亮泵已启动红/绿 LED 熄灭泵已停止另外当在args.gni中设置chip_enable_icd_lit与chip_enable_icd_dsls为 true 启用 LIT ICD 与 DSLS 功能后右键长按1000 ms变为 User Active Mode 触发LIT 支持的一部分左键双击1000 ms用于 Dynamic Short/Long Idle Time Support——这展示了同一套 UI 如何在保持基本泵功能的同时复用按键支持 Thread 低功耗 ICD 特性。nRF Connect 版环境搭建、构建与 DFU环境准备同步子模块仅 nRF Connect 平台浅克隆python3 scripts/checkout_submodules.py --shallow --platform nrfconnectLinux 下需额外安装 SEGGER J-Link 软件README 中给出官方下载说明。安装 nRF Command Line Tools 与 nRF Connect for Desktop 中的 Toolchain Manager。通过 Toolchain Manager 安装 config/nrfconnect 中推荐版本的 nRF Connect SDK然后核对版本兼容性cd {connectedhomeip目录} python3 scripts/setup/nrfconnect/update_ncs.py --update构建与烧录cd examples/pump-controller-app/nrfconnect west build -b nrf52840dk/nrf52840 --sysbuild # 或 nrf5340dk/nrf5340/cpuapp west flash west debug输出zephyr.hex位于build/nrfconnect/zephyr/。切换开发板或修改配置前建议rm -r build清理构建产物。Release 构建关闭日志与 CLI 等诊断功能west build -b target --sysbuild -- -DFILE_SUFFIXrelease开启 BLE 通道 SMP DFUwest build -b target --sysbuild -- -DCONFIG_CHIP_DFU_OVER_BT_SMPymenuconfigwest build -b target --sysbuild -t menuconfig修改需写入prj.conf才能持久化。构建类型方面prj.conf是 debug 构建prj_release.conf等以“prj 下划线 类型名”命名如 releaseMCUboot 独立配置在 sysbuild/mcuboot 下修改外部 Flash 分区需编辑应用根目录的pm_static_build_target.yml如 pm_static_nrf52840dk_nrf52840.yml。DFU 双通道该示例默认启用Matter OTA对 Matter 合规设备是强制项并可叠加 BLE 通道的Simple Management ProtocolSMP专有升级通道两者都通过 MCUboot 引导加载器完成镜像替换。Matter OTA 区分 OTA Provider托管新镜像并响应查询与 OTA Requestor发起下载两种节点角色nRF52840 DK 单核使用单镜像 DFUnRF5340 DK 双核可用多镜像 DFU当前多镜像仅 BLE 通道支持。Telink 版Docker 构建与 OTA 验证构建与烧录Telink 版推荐在项目自带的 Docker 容器内构建容器镜像版本记录在仓库 CI 工作流中Dockerfile决定容器内的 Zephyr 版本# 1. 进入官方构建容器镜像 tag 由 CI 工作流指定 docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:tag # 2. 激活构建环境 source ./scripts/activate.sh -p all,telink # 3. 构建build_target 见支持设备表如 tlsr9518adk80d / tlsr9528a / tlsr9118bdk40d west build -b build_target # 板子 Flash 非 2MB 时追加例如 west build -b build_target -- -DFLASH_SIZE4m # 4. 烧录 west flash --erase产物zephyr.bin位于build/zephyr目录。UART 日志接 J34 的 PB2TX/PB3RX波特率 115200。chip-tool 配网./chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR} # 示例 ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840OTA 验证Linux OTA ProviderTelink 版的 README 给出了完整的 OTA 演练步骤在对应prj.conf中设置CONFIG_CHIP_OTA_REQUESTORy开启 Requestor 能力构建后使用merged.bin烧录需至少 2MB Flash 板子与matter.otaOTA Provider 使用两个二进制测试时让 OTA 镜像的软件版本高于基础固件在prj.conf中设CONFIG_CHIP_DEVICE_SOFTWARE_VERSION2。随后构建 Linux OTA Provider./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_blefalse运行 Provider 并指定镜像./chip-ota-provider-app -f matter.ota用 chip-tool 配网 Provider 节点./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021配置 Provider 的 ACL 放行访问accesscontrol write acl [...] ${OTA_PROVIDER_NODE_ID} 0广播 OTA 事件触发下载./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0。传输完成后 OTA Requestor 向 Provider 发送ApplyUpdateRequest设备在镜像应用成功后重启。这与数据模型中OtaSoftwareUpdateProviderQueryImage/ApplyUpdateRequest/NotifyUpdateApplied命令和OtaSoftwareUpdateRequestorAnnounceOTAProvider命令的定义一一对应可在 pump-controller-app.matter 中核对。TI CC13XX/CC26XX 版GN 构建与烧录TI 版基于 GN/Ninja 构建推荐 Ubuntu 22.04 SimpleLink SDK SysConfigcd ~/connectedhomeip source ./scripts/bootstrap.sh ./scripts/checkout_submodules.py --shallow --platform cc13xx_26xx linux --recursive source ./scripts/activate.sh cd examples/pump-controller-app/ti/cc13x4_26x4 gn gen out/debug --argsti_sysconfig_root\$HOME/ti/sysconfig_1.22.0\ ninja -C out/debug要点在 args.gni 中通过ti_simplelink_board选择板卡LP_EM_CC2674P10、LP_EM_CC1354P10_1或CC2674R10可通过target_defines[...]、chip_generate_link_map_filetrue等参数追加构建开关README 中给出了TI_ATTESTATION_CREDENTIALS1的完整示例烧录有两条路UniFlash无调试环境的擦除/烧录/检查加载out/debug下的*.out开启 OTA 后为含 MCUboot 的*-mcuboot.hex合并镜像OTA 开关由args.gni中chip_enable_ota_requestor决定与Code Composer Studio经 XDS110 建 target connection 后做 project-less debug session 加载 ELF支持源码级调试注意默认 CCXML 用 2-wire cJTAG 匹配 LaunchPad 跳线配置JTAG 烧录会置 Halt-in-Boot 标志软复位异常时重新上电即可。配网流程与验证三平台通用各平台的配网rendezvous流程一致设备默认禁用 IPv6 联网必须先由用户在设备上按键触发 BLE 广播使控制器commissioner 角色通过 BLE 获取配网信息二维码打印在 UART 日志、或经 NFC 标签模拟分享再由控制器把 Thread 网络凭据下发给设备Thread provisioning设备作为 Thread Minimal End Device 加入网络。配网成功后的验证步骤chip-tool 侧出现CHIP:CTL: Successfully finished commissioning step SendComplete设备侧出现Commissioning complete, notify platform driver to persist network credentials.读取 Basic 集群确认设备信息./chip-tool basicinformation read vendor-name 1 0对 OnOff 集群执行 On/Off/Toggle或直接写 OnOff 属性观察泵 LED 状态切换与PumpManager状态迁移日志如Auto Re-Start has been triggered!从而闭环验证“控制器命令 → OnOff 属性变更 →MatterPostAttributeChangeCallback→InitiateAction→ 定时器完成 → LED 更新”的完整链路。作为产品模板的使用建议从源码结构看该示例把“业务逻辑PumpManager 状态机 自动重启”与“Matter 桥接ZclCallbacks 属性回调”和“平台适配按键/LED/定时器”清晰分层平台差异体现在AppTask事件循环、按键、LED 驱动与构建配置中而状态机与集群桥接代码几乎原样复用到 nRF Connect、Telink、TI 三套实现。如果你要开发真实的泵控制产品可以按同样结构入手先确定 Pump 侧的数据模型OnOff、Identify 以及按需增加的 PumpConfiguration 等属性再用MatterPostAttributeChangeCallback把属性变更翻译为你的电机控制动作最后按目标平台对齐 README 中的构建与 DFU 配置。需要强调的是nRF Connect 版 README 明确说明该示例仅供冒烟测试、并非生产级质量产品化时还应参考 Nordic 官方的 Matter 样本获取额外软件组件与完整技术支持。【免费下载链接】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），仅供参考