nRF Connect 示例中的 Matter CLI：Zephyr Shell 命令完全指南-酒店常州论坛

nRF Connect 示例中的 Matter CLI：Zephyr 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 115200

1.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_SHELL=y

该 Kconfig 通过 config/nrfconnect/chip-module/CMakeLists.txt 中的LIB_SHELL CONFIG_CHIP_LIB_SHELL映射为 GN 参数，进而控制 src/lib/shell 命令库的编译。仓库内 examples/shell/nrfconnect/prj.conf 是一个现成的启用示例（同时启用了CONFIG_OPENTHREAD_SHELL=y）。

启用后，每条 Matter 命令都必须以matter前缀开头，整体命令结构为：

matter <command-group> [subcommand] [options]

以下各小节按命令组逐一说明。

3.2`device`命令组：设备管理

用于管理设备状态，必须搭配子命令使用。源码定义见 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.3`onboardingcodes`命令组：入网码查看

用于查看设备入网（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?data=MT%3AW0GU2OTB00KA0648G00 ManualPairingCode: 34970112332

`none qrcode`：只打印 QR 码载荷

uart:~$ matter onboardingcodes none qrcode MT:W0GU2OTB00KA0648G00

`none qrcodeurl`：只打印 QR 码网页地址

uart:~$ matter onboardingcodes none qrcodeurl https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00

`none manualpairingcode`：只打印手动配对码

uart:~$ matter onboardingcodes none manualpairingcode 34970112332

3.4`config`命令组：设备配置查看

用于查看设备配置信息。不带子命令时打印全部配置：

uart:~$ matter config VendorId: 65521 (0xFFF1) ProductId: 32768 (0x8000) HardwareVersion: 1 (0x1) FabricId: PinCode: 020202021 Discriminator: f00 DeviceId:

各子命令对应输出：

子命令	作用	示例输出
`matter config pincode`	打印设备设置 PIN 码	`020202021`
`matter config discriminator`	打印设备设置鉴别符（discriminator）	`f00`
`matter config vendorid`	打印厂商 ID（Vendor ID）	`65521 (0xFFFF1)`
`matter config productid`	打印产品 ID（Product ID）	`32768 (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.5`ble`命令组：蓝牙 LE 传输控制

控制设备的 Bluetooth LE 传输状态，必须搭配子命令使用。

`help`：查看命令组帮助

uart:~$ matter ble help help Usage: ble <subcommand> adv Enable or disable advertisement. Usage: ble adv <start|stop|state>

`adv start`：开启 BLE 广播

uart:~$ matter ble adv start Starting BLE advertising

`adv stop`：停止 BLE 广播

uart:~$ matter ble adv stop Stopping BLE advertising

`adv state`：查询广播状态

uart:~$ matter ble adv state BLE advertising is disabled

3.6`nfc`命令组：NFC 标签模拟控制

控制设备 NFC 标签模拟状态（需硬件支持 NFC），必须搭配子命令使用：

uart:~$ matter nfc start NFC tag emulation started

uart:~$ matter nfc stop NFC tag emulation stopped

uart:~$ matter nfc state NFC tag emulation is disabled

3.7`dns`命令组：DNS 服务发现

用于触发 Matter 的 DNS-SD（mDNS）查询，实现位于 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:3b31

`resolve`：解析指定 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.8`stat`命令组：系统资源峰值统计

用于查看与重置 Matter 关键系统资源（packet buffer、定时器、TCP/UDP 端点、交换上下文、未请求消息处理器、平台事件等）的峰值占用。

注意：该命令组只有在启用CONFIG_CHIP_STATISTICS=yKconfig 选项后才可用。此选项同样通过 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.cpp），peak通过System::Stats::GetHighWatermarks()读取各资源的历史峰值水位线；若平台支持水位线统计，还会额外打印堆内存峰值（Heap allocated bytes）；在启用MBEDTLS_MEMORY_DEBUG的构建下还会打印 mbedTLS 堆分配峰值。

`reset`：重置峰值统计

uart:~$ matter stat reset

reset将各资源当前占用值写回水位线，作为新的统计基准（见 src/lib/shell/commands/Stat.cpp）。典型用法是先执行reset清零基线，运行一段业务后执行peak观察峰值增长，用于内存与资源占用评估。

四、实用调试思路

综合上述命令，可以在不连接任何上位机工具的情况下完成典型调试闭环：

连接：Minicom / Screen 以 115200 波特率连接套件，确认出现uart:~$提示符；
确认启用：确认prj.conf中CONFIG_CHIP_LIB_SHELL=y（必要时追加CONFIG_CHIP_STATISTICS=y以启用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.md
nRF Connect 平台概述：docs/platforms/nrf/nrfconnect_platform_overview.md
nRF Connect 示例配置说明（含更多 Kconfig 选项）：docs/platforms/nrf/nrfconnect_examples_configuration.md
Android 入网（commissioning）指南：docs/platforms/nrf/nrfconnect_android_commissioning.md
shell 命令库源码：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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析