nRF Connect 示例中的 Matter CLIZephyr Shell 命令完全指南【免费下载链接】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导读Nordic Semiconductor 开发套件上的多个 Matter 示例程序内置了命令行接口它基于 Zephyr shell 子系统实现既能查看应用日志也能直接操作 Matter 设备的配置、入网、BLE 广播、NFC 模拟、DNS 服务发现与系统资源统计等功能。本指南以docs/platforms/nrf/nrfconnect_examples_cli.md为骨架结合仓库内 src/lib/shell 的源码实现完整讲解 CLI 控制台的接入方法、命令前缀规则、matter全部命令组的使用语法与输出解读帮助你掌握一条不依赖上位机工具即可完成设备调试与排障的命令行通道。一、CLI 控制台的接入1.1 原理与前置条件这些 Matter 示例使用的 CLI 由 Zephyr shell 子系统承载即通常看到的uart:~$提示符。在 nRF Connect 平台上Matter 的 shell 命令注册与分发逻辑位于 src/lib/shell/MainLoopZephyr.cpp系统启动时通过SYS_INIT(RegisterMatterCommands, POST_KERNEL, ...)注册默认命令SHELL_CMD_ARG_REGISTER(matter, NULL, Matter commands, ExecCommandInShellThread, 1, CHIP_SHELL_MAX_TOKENS)将matter注册为 Zephyr shell 的顶层命令前缀因此所有 Matter 专用命令都必须以matter开头。1.2 使用串口终端连接接入 CLI 控制台只需要一个串口终端模拟器如 Minicom 或 GNU Screen波特率固定为115200。以 Minicom 为例将/dev/ttyACM0替换为你开发套件的实际设备节点名minicom -D /dev/ttyACM0 -b 1152001.3 验证控制台是否工作重启套件后控制台会依次输出引导日志与 Matter 初始化信息uart:~$ I: nRF5 802154 radio initialized I: 8 Sectors of 4096 bytes I: alloc wra: 0, ff0 I: data wra: 0, 0 *** Booting Zephyr OS build v2.4.0-ncs1 *** I: Init CHIP stack ...看到uart:~$提示符即表示控制台工作正常。此时可以直接执行 Zephyr shell 的内置命令例如kernel threads会打印所有运行中的线程及其栈占用情况uart:~$ kernel threads Scheduler: 277 since last call Threads: 0x20006518 CHIP options: 0x0, priority: -1 timeout: 536896912 state: pending stack size 8192, unused 7256, usage 936 / 8192 (11 %) 0x20004ab0 SDC RX options: 0x0, priority: -10 timeout: 536890152 state: pending stack size 1024, unused 848, usage 176 / 1024 (17 %) ...1.4 列出所有可用命令Zephyr shell 支持 Tab 键补全。在空命令行下按 Tab会打印当前可用的全部命令uart:~$ clear date device flash help history kernel nrf_clock_control ot resize shell在命令行中输入部分命令后按 Tab则会循环切换该命令的候选补全项。注意默认列表里的device是 Zephyr shell 自身的子命令与后文 Matter 的matter device命令组是两回事。二、OpenThread 命令ot前缀在 nRF Connect 示例中OpenThread CLI 命令同样可以通过 shell 访问但必须加上ot前缀。例如查询网络密钥uart:~$ ot networkkey 00112233445566778899aabbccddeeff Done三、Matter 专用命令启用方式与matter前缀3.1 启用 Kconfig 选项Matter 专用 CLI 命令默认不可用必须先在对应示例的prj.conf中启用CONFIG_CHIP_LIB_SHELLy该 Kconfig 通过 config/nrfconnect/chip-module/CMakeLists.txt 中的LIB_SHELL CONFIG_CHIP_LIB_SHELL映射为 GN 参数进而控制 src/lib/shell 命令库的编译。仓库内 examples/shell/nrfconnect/prj.conf 是一个现成的启用示例同时启用了CONFIG_OPENTHREAD_SHELLy。启用后每条 Matter 命令都必须以matter前缀开头整体命令结构为matter command-group [subcommand] [options]以下各小节按命令组逐一说明。3.2device命令组设备管理用于管理设备状态必须搭配子命令使用。源码定义见 src/lib/shell/commands/Device.cpp。factoryreset子命令执行设备恢复出厂设置其动作是先擦除非易失性存储NVM中全部 Matter 设置再执行硬件复位。源码实现直接调用DeviceLayer::ConfigurationMgr().InitiateFactoryReset()见 src/lib/shell/commands/Device.cpp。uart:~$ matter device factoryreset Performing factory reset ...其他子命令从源码结构看device命令组还注册了另外两个与入网窗口相关的子命令matter device opencommissioningwindow打开基础 commissioning 窗口便于重新入网matter device closecommissioningwindow关闭 commissioning 窗口。3.3onboardingcodes命令组入网码查看用于查看设备入网onboarding相关的各类编码。命令格式为onboardingcodes none|softap|ble|onnetwork [qrcode|qrcodeurl|manualpairingcode]第一个参数为 rendezvous 类型none/softap/ble/onnetwork是必选参数第二个参数用于只打印某一种具体编码为可选参数。实现位于 src/lib/shell/commands/OnboardingCodes.cpp。none打印全部入网码uart:~$ matter onboardingcodes none QRCode: MT:W0GU2OTB00KA0648G00 QRCodeUrl: https://project-chip.github.io/connectedhomeip/qrcode.html?dataMT%3AW0GU2OTB00KA0648G00 ManualPairingCode: 34970112332none qrcode只打印 QR 码载荷uart:~$ matter onboardingcodes none qrcode MT:W0GU2OTB00KA0648G00none qrcodeurl只打印 QR 码网页地址uart:~$ matter onboardingcodes none qrcodeurl https://project-chip.github.io/connectedhomeip/qrcode.html?dataMT%3AW0GU2OTB00KA0648G00none manualpairingcode只打印手动配对码uart:~$ matter onboardingcodes none manualpairingcode 349701123323.4config命令组设备配置查看用于查看设备配置信息。不带子命令时打印全部配置uart:~$ matter config VendorId: 65521 (0xFFF1) ProductId: 32768 (0x8000) HardwareVersion: 1 (0x1) FabricId: PinCode: 020202021 Discriminator: f00 DeviceId:各子命令对应输出子命令作用示例输出matter config pincode打印设备设置 PIN 码020202021matter config discriminator打印设备设置鉴别符discriminatorf00matter config vendorid打印厂商 IDVendor ID65521 (0xFFFF1)matter config productid打印产品 IDProduct ID32768 (0x8000)matter config hardwarever打印硬件版本1 (0x1)matter config deviceid打印设备标识符—matter config fabricid打印 fabric 标识符—上表中的示例数值VendorId 0xFFF1、ProductId 0x8000 等来自示例默认配置deviceid、fabricid在设备尚未入网/未被分配 ID 时输出为空。实现位于 src/lib/shell/commands/Config.cpp。3.5ble命令组蓝牙 LE 传输控制控制设备的 Bluetooth LE 传输状态必须搭配子命令使用。help查看命令组帮助uart:~$ matter ble help help Usage: ble subcommand adv Enable or disable advertisement. Usage: ble adv start|stop|stateadv start开启 BLE 广播uart:~$ matter ble adv start Starting BLE advertisingadv stop停止 BLE 广播uart:~$ matter ble adv stop Stopping BLE advertisingadv state查询广播状态uart:~$ matter ble adv state BLE advertising is disabled3.6nfc命令组NFC 标签模拟控制控制设备 NFC 标签模拟状态需硬件支持 NFC必须搭配子命令使用uart:~$ matter nfc start NFC tag emulation starteduart:~$ matter nfc stop NFC tag emulation stoppeduart:~$ matter nfc state NFC tag emulation is disabled3.7dns命令组DNS 服务发现用于触发 Matter 的 DNS-SDmDNS查询实现位于 src/lib/shell/commands/Dns.cpp。browse浏览_matterc_udp服务浏览_matterc_udp类型的 DNS 服务并打印收到的响应不需要参数uart:~$ matter dns browse Browsing ... DNS browse succeeded: Hostname: 0E824F0CA6DE309C Vendor ID: 9050 Product ID: 20043 Long discriminator: 3840 Device type: 0 Device name: Commissioning mode: 0 IP addresses: fd08:b65e:db8e:f9c7:2cc2:2043:1366:3b31resolve解析指定 Matter 节点按fabric-id和node-id解析指定 Matter 节点服务uart:~$ matter dns resolve fabric-id node-id Resolving ... DNS resolve for 000000014A77CBB3-0000000000BC5C01 succeeded: IP address: fd08:b65e:db8e:f9c7:8052:1a8e:4dd4:e1f3 Port: 5540命令中的fabric-id、node-id需替换为实际值。dns browse输出的 Vendor ID、Long discriminator、IP 地址等信息对排查设备发现与入网问题非常有用。3.8stat命令组系统资源峰值统计用于查看与重置 Matter 关键系统资源packet buffer、定时器、TCP/UDP 端点、交换上下文、未请求消息处理器、平台事件等的峰值占用。注意该命令组只有在启用CONFIG_CHIP_STATISTICSyKconfig 选项后才可用。此选项同样通过 config/nrfconnect/chip-module/CMakeLists.txt 的chip_system_config_provide_statistics CONFIG_CHIP_STATISTICS映射到构建系统。peak打印资源峰值占用uart:~$ matter stat peak Packet Buffers: 1 Timers: 2 TCP endpoints: 0 UDP endpoints: 1 Exchange contexts: 0 Unsolicited message handlers: 5 Platform events: 2从源码看src/lib/shell/commands/Stat.cpppeak通过System::Stats::GetHighWatermarks()读取各资源的历史峰值水位线若平台支持水位线统计还会额外打印堆内存峰值Heap allocated bytes在启用MBEDTLS_MEMORY_DEBUG的构建下还会打印 mbedTLS 堆分配峰值。reset重置峰值统计uart:~$ matter stat resetreset将各资源当前占用值写回水位线作为新的统计基准见 src/lib/shell/commands/Stat.cpp。典型用法是先执行reset清零基线运行一段业务后执行peak观察峰值增长用于内存与资源占用评估。四、实用调试思路综合上述命令可以在不连接任何上位机工具的情况下完成典型调试闭环连接Minicom / Screen 以 115200 波特率连接套件确认出现uart:~$提示符确认启用确认prj.conf中CONFIG_CHIP_LIB_SHELLy必要时追加CONFIG_CHIP_STATISTICSy以启用stat命令组查看设备身份matter config查看 VID/PID、PIN 码与鉴别符用于生成/核对配对信息获取入网码matter onboardingcodes none获取 QR 码、QR 码 URL 与手动配对码控制可发现性matter ble adv start/stop、matter nfc start/stop控制广播与 NFC 标签模拟验证网络发现matter dns browse/matter dns resolve验证设备在网络上是否可被发现、解析结果是否正确资源健康检查matter stat reset后运行功能再用matter stat peak观察各资源峰值复位需要恢复出厂时执行matter device factoryreset会擦除 NVM 中的 Matter 设置并硬件复位。五、相关资源本指南原始出处docs/platforms/nrf/nrfconnect_examples_cli.mdnRF Connect 平台概述docs/platforms/nrf/nrfconnect_platform_overview.mdnRF Connect 示例配置说明含更多 Kconfig 选项docs/platforms/nrf/nrfconnect_examples_configuration.mdAndroid 入网commissioning指南docs/platforms/nrf/nrfconnect_android_commissioning.mdshell 命令库源码src/lib/shell命令实现位于 src/lib/shell/commands包含BLE.cpp、Config.cpp、Device.cpp、Dns.cpp、NFC.cpp、OnboardingCodes.cpp、Ota.cpp、Stat.cpp、WiFi.cpp等nRF Connect 构建配置与 Kconfig 到 GN 参数的映射config/nrfconnect/chip-module/CMakeLists.txt【免费下载链接】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），仅供参考