Shell 框架¶

概述¶

Shell 框架为 Nexus 嵌入式平台提供交互式命令行界面（CLI）。它支持命令注册、行编辑、命令历史、自动补全和多种 I/O 后端。

特性¶

命令注册: 动态注册命令，支持帮助和用法说明
行编辑: 光标移动、插入、删除、Home/End 键
命令历史: 使用上下箭头浏览历史
自动补全: Tab 键补全命令和参数
内置命令: help、version、clear、history、echo
多后端支持: UART、Console 和自定义后端
参数解析: 支持引号和转义字符
线程安全: 多任务环境下安全使用
资源可配置: 支持静态分配，适用于资源受限系统

快速开始¶

基本用法：

#include "shell/shell.h"

// Custom command handler
static int cmd_led(int argc, char* argv[])
{
    if (argc < 2) {
        shell_printf("Usage: led <on|off>\r\n");
        return -1;
    }

    if (strcmp(argv[1], "on") == 0) {
        hal_gpio_write(LED_PIN, 1);
        shell_printf("LED turned on\r\n");
    } else if (strcmp(argv[1], "off") == 0) {
        hal_gpio_write(LED_PIN, 0);
        shell_printf("LED turned off\r\n");
    }
    return 0;
}

// Command definition
static const shell_command_t led_cmd = {
    .name = "led",
    .handler = cmd_led,
    .help = "Control LED state",
    .usage = "led <on|off>"
};

void app_init(void)
{
    // Initialize Shell
    shell_config_t config = SHELL_CONFIG_DEFAULT;
    shell_init(&config);

    // Set backend (UART)
    shell_set_backend(&shell_uart_backend);

    // Register built-in commands
    shell_register_builtin_commands();

    // Register custom command
    shell_register_command(&led_cmd);

    // Print prompt
    shell_print_prompt();
}

void app_loop(void)
{
    // Process Shell input (non-blocking)
    shell_process();
}

配置¶

自定义配置：

shell_config_t config = {
    .prompt = "nexus> ",        // Custom prompt
    .cmd_buffer_size = 128,     // Command buffer size
    .history_depth = 16,        // History depth
    .max_commands = 64          // Max command count
};

shell_init(&config);

默认配置：

参数	默认值	描述
`prompt`	`"$ "`	Shell 提示符字符串
`cmd_buffer_size`	`128`	命令缓冲区大小
`history_depth`	`8`	历史记录数量
`max_commands`	`32`	最大注册命令数

命令定义¶

命令结构：

typedef struct {
    const char* name;               // Command name
    shell_cmd_handler_t handler;    // Handler function
    const char* help;               // Help text
    const char* usage;              // Usage string
    shell_completion_t completion;  // Auto-completion (optional)
} shell_command_t;

处理函数签名：

typedef int (*shell_cmd_handler_t)(int argc, char* argv[]);

argc: 参数数量（包括命令名）
argv: 参数数组
返回值：0 表示成功，非 0 表示错误

带自动补全的命令示例：

// Auto-completion function
static int led_completion(const char* partial, char* completions[], int max)
{
    const char* options[] = {"on", "off", "toggle", "status"};
    int count = 0;

    for (int i = 0; i < 4 && count < max; i++) {
        if (strncmp(options[i], partial, strlen(partial)) == 0) {
            completions[count++] = (char*)options[i];
        }
    }
    return count;
}

static const shell_command_t led_cmd = {
    .name = "led",
    .handler = cmd_led,
    .help = "Control LED state",
    .usage = "led <on|off|toggle|status>",
    .completion = led_completion
};

内置命令¶

命令	描述	用法
`help`	显示可用命令	`help [command]`
`version`	显示 Shell 版本	`version`
`clear`	清除终端屏幕	`clear`
`history`	显示命令历史	`history`
`echo`	打印参数	`echo [text...]`

行编辑快捷键¶

按键	功能
`←` / `Ctrl+B`	光标左移
`→` / `Ctrl+F`	光标右移
`Home` / `Ctrl+A`	移到行首
`End` / `Ctrl+E`	移到行尾
`Backspace`	删除前一字符
`Delete` / `Ctrl+D`	删除当前字符
`Ctrl+K`	删除到行尾
`Ctrl+U`	删除到行首
`↑` / `Ctrl+P`	上一条历史
`↓` / `Ctrl+N`	下一条历史
`Tab`	自动补全
`Ctrl+C`	取消当前输入
`Ctrl+L`	清屏

后端¶

UART 后端¶

#include "shell/shell_backend.h"

// Initialize UART
hal_uart_config_t uart_cfg = {
    .baudrate = 115200,
    .wordlen = HAL_UART_WORDLEN_8,
    .stopbits = HAL_UART_STOPBITS_1,
    .parity = HAL_UART_PARITY_NONE
};
hal_uart_init(HAL_UART_0, &uart_cfg);

// Use UART backend
shell_set_backend(&shell_uart_backend);

自定义后端¶

static int my_read(char* buf, size_t len)
{
    // Implement read logic
    return bytes_read;
}

static int my_write(const char* buf, size_t len)
{
    // Implement write logic
    return bytes_written;
}

static const shell_backend_t my_backend = {
    .read = my_read,
    .write = my_write
};

shell_set_backend(&my_backend);

输出函数¶

// Formatted output
shell_printf("Value: %d\r\n", 42);

// String output
shell_puts("Hello World\r\n");

// Character output
shell_putc('A');

// Print prompt
shell_print_prompt();

// Clear screen
shell_clear_screen();

错误处理¶

shell_status_t status = shell_register_command(&cmd);
if (status != SHELL_OK) {
    const char* msg = shell_get_error_message(status);
    printf("Error: %s\n", msg);
}

状态码：

状态	描述
`SHELL_OK`	成功
`SHELL_ERROR_INVALID_PARAM`	无效参数
`SHELL_ERROR_NOT_INIT`	未初始化
`SHELL_ERROR_ALREADY_INIT`	已初始化
`SHELL_ERROR_NO_BACKEND`	未配置后端
`SHELL_ERROR_CMD_NOT_FOUND`	命令未找到
`SHELL_ERROR_CMD_EXISTS`	命令已存在
`SHELL_ERROR_BUFFER_FULL`	缓冲区满

编译时配置¶

宏定义	默认值	描述
`SHELL_MAX_COMMANDS`	`32`	最大命令数
`SHELL_DEFAULT_CMD_BUFFER_SIZE`	`128`	默认命令缓冲区
`SHELL_DEFAULT_HISTORY_DEPTH`	`8`	默认历史深度
`SHELL_MAX_ARGS`	`16`	最大参数数量
`SHELL_DEFAULT_PROMPT`	`"$ "`	默认提示符

依赖¶

OSAL: 操作系统抽象层（可选，用于线程安全）
HAL: 硬件抽象层（UART 后端）

API 参考¶

完整 API 文档请参阅 Shell 框架 API 参考。

Nexus 嵌入式平台

导航

Related Topics

Shell 框架¶

概述¶

特性¶

快速开始¶

配置¶

命令定义¶

内置命令¶

行编辑快捷键¶

后端¶

UART 后端¶

自定义后端¶

输出函数¶

错误处理¶

编译时配置¶

依赖¶

API 参考¶