Matter nRF Connect Pump Controller 示例应用基于 Nordic nRF Connect SDK 的泵控制器客户端实战指南【免费下载链接】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仓库中的examples/pump-controller-app/nrfconnect示例完整讲解如何在一个基于 nRF Connect SDK 与 Zephyr RTOS 的 Nordic 开发板上实现具备基本启停功能的泵控制器Pump Controller客户端设备包括设备角色与网络拓扑、蓝牙 LE 配网rendezvous流程、Thread 网络配置、两种固件升级DFU方案、环境搭建、构建/烧录/调试命令以及设备 UI按钮与 LED行为定义。读完本文你将掌握该示例从源码到实物的完整落地流程并理解其状态机与事件驱动架构的内部实现。说明仓库中该示例的定位是 smoke test冒烟测试级别官方明确提示其质量并非生产就绪、可能存在小瑕疵或非最优配置不建议直接作为量产产品的基础如需生产级 Matter 样例官方建议参考 nRF Connect SDK 自带的 Matter samples。示例概述它是什么、跑在哪里、如何被控制该示例演示如何实现一个pump controller client泵控制器客户端设备具备最基本的 pump 启动/停止功能通过按钮测试泵状态与设备状态的切换通过 LED 显示状态变化。它源自 lock-app门锁应用示例被修改为模拟一台泵设备可作为开发自有泵应用的参考起点见 examples/pump-controller-app/nrfconnect/README.md。从运行平台看它运行在Nordic nRF Connect 平台上该平台基于 Nordic 的 nRF Connect SDK 与 Zephyr RTOS平台结构、依赖关系的完整介绍见 nRF Connect 平台总览。从网络角色看该示例表现为一个Matter accessory配件即可被配对进既有 Matter 网络、并受该网络控制在 Thread 网络中工作为Thread Minimal End DeviceThread 最小终端设备——这一点在 AppTask.cpp 的初始化代码 中通过ConnectivityMgr().SetThreadDeviceType(ConnectivityManager::kThreadDeviceType_MinimalEndDevice)设置默认IPv6 网络功能是关闭的必须通过蓝牙 LE 与 Matter 控制器配对由控制器下发配置后才能加入 Thread 或 Wi-Fi 网络。运行该应用并完成配网后你可以通过 Thread 或 Wi-Fi 协议对其进行远程测试这需要额外的设备参与包括一台 Matter 控制器可配置在 PC 或手机上。Bluetooth LE advertising蓝牙 LE 广播由于安全考虑设备上电后不会自动对外广播必须手动按下Button 4才会启动蓝牙 LE 广播使其可被发现并进行配网。Bluetooth LE rendezvous蓝牙 LE 交接本示例中配网过程称为 rendezvous在 Matter 设备与 Matter 控制器扮演 commissioner 角色之间通过蓝牙 LE 完成。要启动 rendezvous控制器必须先获取 Matter 设备的配网信息该信息载荷以两种方式提供编码在QR 码中打印到 UART 控制台通过NFC 标签共享。同样出于安全考虑NFC 标签模拟也需要在上电后手动按Button 4启动该按钮一次按压会同时启动 NFC 标签模拟与 BLE 广播默认持续一段预定义时间仓库 prj.conf 中配置了扩展广播并延长了广播时长。Thread provisioningThread 网络配置rendezvous 流程的最后一步是 provisioningMatter 控制器将 Thread 网络凭据发送给 Matter 设备设备据此加入 Thread 网络并可与网络内其他 Thread 设备通信。这一过程对应的底层网络配网驱动在 AppTask.cpp 中注册为Clusters::NetworkCommissioning::InstanceAndDriverNetworkCommissioning::GenericThreadDriver sThreadNetworkDriver(0)Thread 网络配网端点。配网信息输出与自动配对示例在启动时会通过PrintOnboardingCodes(chip::RendezvousInformationFlag::kBLE)打印配网 QR 码与手输配对码见 AppTask.cpp同时 prj.conf 开启了CONFIG_CHIP_ENABLE_PAIRING_AUTOSTARTy使 Matter 配对信息在应用启动时自动生成就绪配合 Button 4 手动广播即可快速进入配网状态。设备固件升级DFU该示例支持两种 OTA 固件升级方式升级方式是否 Matter 规范要求说明Matter OTA 更新是Matter 合规设备强制要求默认启用Simple Management ProtocolSMP否属私有方案通过蓝牙 LE 传输可选择性启用与默认的 Matter OTA 并存无论采用哪种方式固件镜像替换都由MCUbootbootloader 完成。Matter Over-the-Air UpdateMatter OTA 更新区分两类节点OTA Provider承载新固件镜像的节点能响应 OTA Requestor 关于新固件可用性的查询或响应开始发送更新包的请求OTA Requestor想要下载新固件镜像的节点向 OTA Provider 发送请求以启动更新流程。本示例设备运行 OTA Requestor 相关逻辑在 AppTask.cpp 中当 DNS-SD 初始化完成后会调用InitBasicOTARequestor()并注册OTATestEventTriggerHandler用于测试事件触发 OTA 流程同文件 L217。Matter 数据模型侧则通过OtaSoftwareUpdateRequestor集群暴露更新状态与进度见 pump-controller-app.matter 中的集群定义。Simple Management ProtocolSMPSMP 是一种用于设备管理的传输编码涵盖应用镜像管理等用途支持蓝牙 LE、UDP、串口 USB/UART 等多种传输。本示例中Matter 设备运行 SMP Server通过蓝牙 LE 传输下载应用更新镜像。构建时通过-DCONFIG_CHIP_DFU_OVER_BT_SMPy启用运行时按下 Button 1短按释放即可在 AppTask.cpp 的 FunctionHandler 中启动 SMP Server 进入软件更新模式。BootloaderMCUbootMCUboot 是一个安全 bootloader用于在不同版本固件镜像之间执行 swap交换并生成可用于设备固件升级流程的构建输出。bootloader 方案需要一块 flash 区域来在升级期间交换应用镜像——Nordic 设备通过QSPI 总线连接的外部存储芯片提供该区域。本示例通过静态分区表Partition Manager定义了外部 flash 的使用例如 pm_static_nrf52840dk_nrf52840.yml 中mcuboot_secondary: address: 0x0 size: 0xf4000 device: MX25R64 # 外部 SPI flash 芯片 region: external_flash external_flash: address: 0xf4000 size: 0x70c000 device: MX25R64 region: external_flash即 nRF52840 DK 的升级 slotmcuboot_secondary与其余外部 flash 空间都落在外部 MX25R64 芯片上主 flash 则分配给 mcuboot、app、factory_data、settings_storage 等分区。硬件需求与支持平台示例要求特定版本的 nRF Connect SDK 才能正常工作见下文环境搭建。支持构建与运行的硬件平台如下硬件平台构建目标Build target平台图片nRF52840 DKnrf52840dk/nrf52840nRF5340 DKnrf5340dk/nrf5340/cpuappnRF5340 DK 为双核应用核 网络核SoC其构建目标包含cpuapp应用核后缀配套的网络核配置位于 nrfconnect/sysbuild/ipc_radio由 sysbuild 自动构建。设备 UI按钮与 LED 行为定义设备 UI 元素对应开发板 PCB 上的实体组件用于控制与监控设备状态。LED 1设备整体状态与连接状态状态含义短闪亮亮 50 ms / 灭 950 ms设备处于未配网unprovisioned状态等待配网应用连接快速均匀闪烁亮 100 ms / 灭 100 ms设备未配网且已有配网应用通过蓝牙 LE 连接短闪灭亮 950 ms / 灭 50 ms设备已完成配网但尚不具备完整的 Thread/Wi-Fi 网络连接常亮设备已完成配网具备完整的 Thread 网络与服务连接该逻辑对应 AppTask.cpp 的 UpdateStatusLED()当sIsNetworkProvisioned sIsNetworkEnabled时常亮有 BLE 连接时以 100ms 均匀闪烁否则以 50/950ms 短闪。sIsNetworkProvisioned/sIsNetworkEnabled由kThreadStateChange事件驱动更新同文件 L506-L509。LED 2模拟泵电机状态状态含义常亮泵正在运行灭泵已停止快速均匀闪烁100 ms 亮 / 100 ms 灭持续 2 秒模拟泵电机正在启动LED 2 在动作发起时以 50ms/50ms 快速闪烁ActionInitiated动作完成后根据启/停设置常亮或熄灭ActionCompleted。模拟泵从一状态迁移到另一状态耗时由 AppConfig.h 中PUMP_START_PERIOS_MS2000ms 定义与 README 描述的2 秒启动闪烁吻合。Button 1功能键长按 6 秒触发设备 factory reset恢复出厂设置。在 6 秒窗口内松开按钮可取消恢复出厂设置流程当 factory reset 被发起时LED 1-4 会同步闪烁。短按少于 3 秒发起 OTA 软件更新流程。README 标注该功能当前不受支持从 AppTask.cpp 的 FunctionHandler 看短按释放路径只有在启用CONFIG_MCUMGR_TRANSPORT_BT即 SMP over BLE时才会真正启动软件更新服务否则仅打印 Software update is disabled。factory reset 的具体时序在源码中有更精确的定义按下 Button 1 超过kFactoryResetTriggerTimeout3000ms进入 factory reset 发起阶段随后进入kFactoryResetCancelWindowTimeout3000ms的取消窗口见 AppTask.cpp L66-L67总窗口约 6 秒。Button 2泵启停切换单击一次将泵状态切换为相反状态。对应源码中START_BUTTONDK_BTN2按下后投递StartActionEventHandler根据当前泵状态决定 START_ACTION 或 STOP_ACTION见 AppTask.cpp ButtonEventHandler 与 StartActionEventHandler。Button 4BLE 广播与 NFC 模拟单击一次启动 NFC 标签模拟并启用蓝牙 LE 广播持续一段预定义时间README 表述为默认 15 分钟prj.conf 中通过CONFIG_CHIP_BLE_EXT_ADVERTISINGy开启扩展广播并把时长配置为 60按配置文件注释其意图为延长至 1 小时实际时长以你构建时的 Kconfig 值为准。其他接口SEGGER J-Link USB 端口用于获取设备日志或通过命令行接口CLI与设备交互NFC 端口带天线通过提供 CHIP 设备的配网信息载荷来启动 rendezvous该载荷可通过 NFC 共享。按钮与 LED 的物理映射集中在 AppConfig.hSTART_BUTTONDK_BTN2、FUNCTION_BUTTONDK_BTN1、BLE_ADVERTISEMENT_START_BUTTONDK_BTN4、SYSTEM_STATE_LEDDK_LED1、PUMP_STATE_LEDDK_LED2、FACTORY_RESET_SIGNAL_LEDDK_LED3/DK_LED4。环境搭建构建示例前先检出 Matter 仓库并同步子模块$ python3 scripts/checkout_submodules.py --shallow --platform nrfconnect提示在 Linux 上还需安装 SEGGER J-Link Software含驱动与调试软件。安装命令行工具以管理员权限下载并安装nRF Command Line Tools包含 nrfjprog 等烧录/调试工具。安装 Toolchain ManagerToolchain Manager 来自nRF Connect for Desktop——一个跨平台工具支持 Windows、Linux、macOS提供多个简化 nRF Connect SDK 安装的应用程序。安装步骤下载 nRF Connect for Desktop按操作系统选择安装并在本机运行在APPS区域点击 Toolchain Manager 标签页上的Install按钮。安装 nRF Connect SDK在 nRF Connect for Desktop 中打开 Toolchain Manager点击Install按钮安装推荐版本的 nRF Connect SDK当前仓库该文件内容为v3.4.0弹窗会提示当前安装目录可点击Change directory修改或直接Continue installation安装完成后Install按钮变为Open VS Code按钮点击该按钮旁的菜单为已安装的 nRF Connect SDK 版本选择Open terminal确认 nRF Connect SDK 版本与 Matter SDK 版本兼容$ cd {connectedhomeip 目录} $ python3 scripts/setup/nrfconnect/update_ncs.py --update完成后即可进入构建环节。构建示例进入示例目录$ cd examples/pump-controller-app/nrfconnect注意原 README 该小节写的是cd examples/pump-app/nrfconnect但该示例实际位于examples/pump-controller-app/nrfconnectpump-app 是另一个被控端示例请以本仓库实际目录为准。运行构建命令build-target替换为你手中 Nordic 套件的构建目标例如nrf52840dk/nrf52840$ west build -b build-target --sysbuild首次构建才需要指定构建目标后续构建会复用 build 目录下的缓存配置。兼容套件的构建目标名称见支持平台。构建产物zephyr.hex位于build/nrfconnect/zephyr/目录。清除构建产物如需为不同套件构建或修改配置先删除全部构建产物$ rm -r build以 release 配置构建release 配置会关闭日志、命令行接口等诊断功能仅保留必要应用功能以优化性能$ west build -b build-target --sysbuild -- -DFILE_SUFFIXrelease构建带 DFU 支持的版本Matter OTA 的 DFU 支持默认启用如需启用蓝牙 LE 上的 DFUSMP$ west build -b build-target --sysbuild -- -DCONFIG_CHIP_DFU_OVER_BT_SMPy单镜像与多镜像 DFUsingle-image DFU只支持升级一个固件镜像应用镜像适用于单核的 nRF52840 DKmulti-image DFU支持升级多个固件镜像适合同时升级 nRF5340 DK 的应用核与网络核固件目前 multi-image 模式仅适用于 DFU over Bluetooth LE 方式。修改 bootloader 配置编辑sysbuild/mcuboot目录下的prj.conf可修改 MCUboot 默认配置。需注意bootloader 镜像是独立于用户应用的另一个应用拥有自己的配置文件修改时必须与应用侧配置保持一致否则配置将无法生效。修改 flash 存储设置默认配置下 MCUboot 使用 Partition Manager 配置用于 bootloader 应用镜像 slot 的 flash 分区你可以通过定义 static partitions 修改这些设置本示例正是用该选项定义使用外部 flash。要修改开发板build-target如nrf52840dk/nrf52840的 flash 设置编辑主应用目录下的pm_static_build_target.yml例如pm_static_nrf52840dk_nrf52840.yml具体内容可参考上文列出的 nRF52840 DK 分区表。配置示例Kconfig 与构建类型Zephyr 生态基于 Kconfig 文件可通过 menuconfig 工具修改设置。从示例目录运行$ west build -b build-target --sysbuild -t menuconfig注意用 menuconfig 做的修改在删除build目录后会丢失若要持久化请将配置选项保存到prj.conf文件中。示例构建类型示例按支持的特性使用不同配置文件均位于应用根目录。prj.conf代表 debug 构建类型其他构建类型以 prj 加类型后缀命名例如 release 类型为prj_release.conf。若开发板还有其他配置文件如分区布局、子镜像配置遵循同样的命名模式。本示例支持两种构建类型取决于所选开发板debug调试版应用可启用日志、命令行 shell 等用于验证应用行为的附加特性release发布版应用仅启用必要功能以优化性能。更完整的配置说明见 Configuring nRF Connect SDK examples。prj.conf 关键配置项解析以仓库 prj.conf 为例解读核心选项CONFIG_CHIPy CONFIG_CHIP_PROJECT_CONFIGmain/include/CHIPProjectConfig.h CONFIG_CHIP_DEVICE_PRODUCT_ID32785 # 0x8011pump-controller-app 的示例 Product ID CONFIG_STD_CPP17y CONFIG_CHIP_ENABLE_PAIRING_AUTOSTARTy # 应用启动时自动生成 Matter 配对信息 CONFIG_CHIP_BLE_EXT_ADVERTISINGy # 启用 Matter 扩展广播 CONFIG_CHIP_BLE_ADVERTISING_DURATION60 # 广播时长分钟级配合扩展广播使用 CONFIG_DK_LIBRARYy # 启用 Nordic DK 的 LED/按钮支持 CONFIG_BT_DEVICE_NAMEMatterPumpCtrl # 蓝牙广播设备名 CONFIG_THREAD_NAMEy CONFIG_MPU_STACK_GUARDy # MPU 栈保护 CONFIG_RESET_ON_FATAL_ERRORn CONFIG_USE_SEGGER_RTTn # 关闭 RTT 以减小体积 CONFIG_CHIP_FACTORY_DATAy # 启用 Factory Data 特性 CONFIG_CHIP_FACTORY_DATA_BUILDy CONFIG_CHIP_LOG_VERIFY_OR_DIEy CONFIG_FLASH_MAP_CUSTOMy而 prj_release.conf 则在 debug 基础上额外关闭全部调试特性以优化性能CONFIG_SHELLn、CONFIG_OPENTHREAD_SHELLn、CONFIG_CONSOLEn、CONFIG_UART_CONSOLEn、CONFIG_SERIALn、CONFIG_LOGn、CONFIG_PRINTKn、CONFIG_BOOT_BANNERn并开启CONFIG_RESET_ON_FATAL_ERRORy与CONFIG_PM_DEVICEyCPU 睡眠时挂起设备。Factory Data启用CONFIG_CHIP_FACTORY_DATA后设备的 Device Attestation 凭据、EnableKey 等将从工厂数据中读取在 AppTask.cpp 中通过mFactoryDataProvider.Init()完成工厂数据初始化并注册为设备实例信息、设备认证凭据与可配数据提供者未启用时则回退到示例 DAC 提供者Examples::GetExampleDACProvider()。sysbuild 配置examples/pump-controller-app/nrfconnect/sysbuild.conf 声明了SB_CONFIG_MATTERy SB_CONFIG_PARTITION_MANAGERy即 sysbuild 模式下启用 Matter 与 Partition Manager保证多镜像app、mcuboot、ipc_radio 等协同构建。烧录与调试在示例目录下使用 west 工具$ west flash如果同时连接了多块开发板west 会提示选择正确的那一块。在目标板上调试$ west debug测试示例学习应用命令行接口的用法参见 nRF Connect 示例 CLI 教程使用 Linux/macOS CHIP Tool 配网与控制先阅读 CHIP Tool 用户指南再参考 CHIP Tool 示例说明即可在 Matter 使能的 Thread 网络中完成配网与启停控制使用 Android CHIPTool先阅读 Android 配网指南再参考 Android CHIPTool 示例即可用 Android 手机在 CHIP 使能的 Thread 网络中配网与控制。附泵控制状态机与事件驱动实现原理理解 UI 行为背后的代码有助于你在该示例基础上做二次开发。PumpManager 状态机PumpManager.h 定义了四状态状态机kState_StartInitiated/kState_StartCompletedkState_StopInitiated/kState_StopCompleted以及两种动作START_ACTION、STOP_ACTION。InitiateAction()PumpManager.cpp仅在前一动作完成时接受新动作即只有在 StartCompleted 时允许 STOP、StopCompleted 时允许 START随后启动 2000ms 的 Zephyrk_timer模拟泵启动耗时定时器到期后通过 AppEvent 队列把完成事件投递回 apptask 上下文处理PumpStartTimerEventHandler并回调mActionCompleted_CB驱动 LED 与集群状态更新。它还支持自动重启EnableAutoRestart/SetAutoStartDuration可用于演示泵的自动重启动周期。事件驱动主循环AppTask.cpp 的StartApp()从sAppEventQueue容量 10中持续取事件并分发按键事件、定时器事件、LED 更新事件统一封装为AppEvent由DispatchEvent()调用各自的 handler。按钮事件在ButtonEventHandler中按掩码分发到 StartActionEventHandler、FunctionHandler、StartBLEAdvertisementHandler。集群回调OnOff 属性驱动泵启停ZclCallbacks.cpp 中的MatterPostAttributeChangeCallback监听OnOff 集群的 OnOff 属性变化属性值为真则发起START_ACTION为假则发起STOP_ACTION。这就是 Matter 控制器如 chip-tool通过 On/Off 命令控制泵启停的落点emberAfOnOffClusterInitCallback在集群初始化时同步一次集群状态。对应的数据模型由 pump-controller-app.matter及其同目录的 .zap 配置生成其中包含 OnOff、Identify、Descriptor、OTA Software Update 等集群的完整定义。由此可以看到一条完整的控制链路Matter 控制器发送 On/Off 命令 → OnOff 集群属性变化 → MatterPostAttributeChangeCallback → PumpManager::InitiateAction → 定时器模拟启动 → ActionCompleted 回调 → LED 与集群状态更新这便是整个 pump controller 客户端示例的运行时闭环。【免费下载链接】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），仅供参考