Shell 系统使用指南

本页依据文档基线与后续更新中记录的 Zephyr main 快照更新。

Shell 提供命令树、参数检查、帮助、补全和交互后端。命令处理接口位于 <zephyr/shell/shell.h>。启用 CONFIG_SHELL=y 后，还应配置对应传输后端与硬件。

命令函数与参数数量

命令处理函数接收 Shell 实例、参数个数和字符串数组，返回状态码。参数数量包含命令自身名称。下面注册一个必须携带一个数值参数的根命令：

#include <zephyr/shell/shell.h>
#include <errno.h>
#include <stdlib.h>

static int cmd_value(const struct shell *sh, size_t argc, char **argv)
{
    char *end;
    long value;

    ARG_UNUSED(argc);
    errno = 0;
    value = strtol(argv[1], &end, 10);
    if (errno != 0 || end == argv[1] || *end != '\0' ||
        value < 0 || value > 1000) {
        shell_error(sh, "value must be an integer from 0 to 1000");
        return -EINVAL;
    }
    shell_print(sh, "value=%ld", value);
    return 0;
}

SHELL_CMD_ARG_REGISTER(value, NULL, "Print a value: value <0..1000>",
                       cmd_value, 2, 0);

2, 0 表示两个必需参数（命令名和值），没有可选参数。即使 Shell 做了数量检查，处理函数仍要验证数值范围与字符串解析结果。 Shell 命令回调中的 argv 由 Shell 管理，不能在回调返回后由异步工作继续引用。需要异步处理时先复制必要数据，再交给工作队列或消息队列。

静态子命令

static int cmd_ping(const struct shell *sh, size_t argc, char **argv)
{
    ARG_UNUSED(argc);
    ARG_UNUSED(argv);
    shell_print(sh, "pong");
    return 0;
}

SHELL_STATIC_SUBCMD_SET_CREATE(demo_commands,
    SHELL_CMD_ARG(ping, NULL, "Ping", cmd_ping, 1, 0),
    SHELL_SUBCMD_SET_END
);
SHELL_CMD_REGISTER(demo, &demo_commands, "Demo commands", NULL);

输入 demo ping 调用子命令。子命令回调的 argv[0] 是当前处理的子命令名称，不能固定按整条原始输入的索引解析。根命令名称必须唯一。

动态命令

SHELL_DYNAMIC_CMD_CREATE() 通过回调逐项枚举当前命令集，适合运行时发现的设备或对象。回调签名是 void get(size_t idx, struct shell_static_entry *entry)。枚举结束时设置 entry->syntax = NULL；有效条目应完整设置 syntax、help、subcmd 和 handler。

动态名称存储必须在 Shell 使用期间有效。不能返回临时栈上的字符串；更新动态列表应考虑与帮助/补全同时访问的同步问题，并按官方示例维护适合补全的排序。如果动态条目使用参数检查字段，也需要完整初始化它们，不能只更新名称而保留旧字段。

后端

UART：需 CONFIG_SHELL_BACKEND_SERIAL 与正确的控制台/串口设备。
RTT：需相应 RTT 配置和调试探针，可按支持的 runner 使用 west rtt。
USB CDC ACM：上游提供 cdc-acm-console snippet，可用于支持 USB 的开发板。
其他后端：包括 Telnet、MQTT、BLE NUS、RPMSG 等，依赖各自传输与配置。

例如在支持 USB 的目标上，构建时加入 -S cdc-acm-console：

west build -p always -b <board-target> -S cdc-acm-console samples/subsys/shell/shell_module

<board-target> 需替换。片段解决的是相关配置组合，仍需检查板卡的 USB 支持与连接端口。多个 Shell 实例可共存，处理函数应使用传入的 sh 输出，不要假设唯一 UART 实例。

交互、内置命令和日志

帮助使用 help、-h 或 --help。Tab 补全、历史、通配符、MetaKey、颜色和命令行编辑均有相应配置；默认值由目标配置决定。CONFIG_SHELL_MINIMAL 可减少功能与占用，但应核对实际保留了哪些交互能力。

启用对应 Shell 日志后端/命令配置，可把日志与交互界面协调输出。在 Shell 正在编辑输入时，直接对同一串口输出大量 printk 可能破坏显示，应优先使用 Shell 或日志提供的输出路径。

命令运行在线程上下文，但长时间阻塞会降低交互响应。需要硬件操作时，命令先检查参数、明确目标和当前状态，再把耗时操作交给专用线程，并返回适当结果。

Shell 系统使用指南

命令函数与参数数量

静态子命令

动态命令

后端

交互、内置命令和日志

上游依据