企业官网建设流程全解析

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 所聚合的内容）：

三套平台共用 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用于记录触发者（本地按键为 0，Matter 命令则携带 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 平台示例避免上下文竞争的标准做法。

另外两个细节值得注意：

1. 自动重启（Auto Restart）：若mAutoRestart开启且动作是 Start 完成，会再启动一个时长为mAutoStartDuration * 1000毫秒的定时器；到期后AutoRestartTimerEventHandler以 actor=0 自动发起一次START_ACTION。若期间有人手动发起 Stop，代码会取消该定时器（mAutoStartTimerArmed = false; CancelTimer();），保证手动操作优先。
2. 初始状态：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）可以看到该设备的数据模型包含 Identify（cluster Identify = 3）、OnOff（cluster 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 版

LED 分三路：红色指示 Thread 网络状态（短脉冲闪烁=未入网/Thread 关闭；密脉冲=已配网正在尝试入网；宽脉冲=已作为 CHILD 加入 Thread 网络）；绿色指示 Identify 效果（Blink/Breathe/Okay/Channel Change/Finish/Stop 六种效果对应Clusters::Identify::EffectIdentifierEnum各枚举值）；白色指示泵运行/停止。

TI CC13XX/CC26XX 版

另外，当在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

环境准备

1. 同步子模块（仅 nRF Connect 平台，浅克隆）：

   python3 scripts/checkout_submodules.py --shallow --platform nrfconnect

   Linux 下需额外安装 SEGGER J-Link 软件（README 中给出官方下载说明）。

2. 安装 nRF Command Line Tools 与 nRF Connect for Desktop 中的 Toolchain Manager。

3. 通过 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_SUFFIX=release；
• 开启 BLE 通道 SMP DFU：west build -b <target> --sysbuild -- -DCONFIG_CHIP_DFU_OVER_BT_SMP=y；
• menuconfig：west build -b <target> --sysbuild -t menuconfig，修改需写入prj.conf才能持久化。

构建类型方面，prj.conf是 debug 构建，prj_release.conf等以“prj + 下划线 + 类型名”命名（如 release）；MCUboot 独立配置在 sysbuild/mcuboot 下，修改外部 Flash 分区需编辑应用根目录的pm_static_<build_target>.yml（如 pm_static_nrf52840dk_nrf52840.yml）。

DFU 双通道

该示例默认启用Matter OTA（对 Matter 合规设备是强制项），并可叠加 BLE 通道的Simple Management Protocol（SMP）专有升级通道；两者都通过 MCUboot 引导加载器完成镜像替换。Matter OTA 区分 OTA Provider（托管新镜像并响应查询）与 OTA Requestor（发起下载）两种节点角色；nRF52840 DK 单核使用单镜像 DFU，nRF5340 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_SIZE=4m # 4. 烧录 west flash --erase

产物zephyr.bin位于build/zephyr目录。UART 日志接 J34 的 PB2（TX）/PB3（RX），波特率 115200。

chip-tool 配网

./chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR} # 示例： ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840

OTA 验证（Linux OTA Provider）

Telink 版的 README 给出了完整的 OTA 演练步骤：在对应prj.conf中设置CONFIG_CHIP_OTA_REQUESTOR=y开启 Requestor 能力；构建后使用merged.bin（烧录，需至少 2MB Flash 板子）与matter.ota（OTA Provider 使用）两个二进制；测试时让 OTA 镜像的软件版本高于基础固件（在prj.conf中设CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2）。随后：

1. 构建 Linux OTA Provider：./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false；
2. 运行 Provider 并指定镜像：./chip-ota-provider-app -f matter.ota；
3. 用 chip-tool 配网 Provider 节点：./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021；
4. 配置 Provider 的 ACL 放行访问（accesscontrol write acl '[...]' ${OTA_PROVIDER_NODE_ID} 0）；
5. 广播 OTA 事件触发下载：./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0。

传输完成后 OTA Requestor 向 Provider 发送ApplyUpdateRequest，设备在镜像应用成功后重启。这与数据模型中OtaSoftwareUpdateProvider（QueryImage/ApplyUpdateRequest/NotifyUpdateApplied命令）和OtaSoftwareUpdateRequestor（AnnounceOTAProvider命令）的定义一一对应，可在 pump-controller-app.matter 中核对。

TI CC13XX/CC26XX 版：GN 构建与烧录

TI 版基于 GN/Ninja 构建（推荐 Ubuntu 22.04 + SimpleLink SDK + SysConfig）：

cd ~/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 --args="ti_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_file=true等参数追加构建开关（README 中给出了TI_ATTESTATION_CREDENTIALS=1的完整示例）；
• 烧录有两条路：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 加入网络。

配网成功后的验证步骤：

1. chip-tool 侧出现CHIP:CTL: Successfully finished commissioning step 'SendComplete'，设备侧出现Commissioning complete, notify platform driver to persist network credentials.；
2. 读取 Basic 集群确认设备信息：./chip-tool basicinformation read vendor-name 1 0；
3. 对 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