移植指南

本指南将帮助你将 ctsehll 移植到不同的硬件平台。

ESP32

已上线 idf registry.

STM32

参考 stm32 port。

芯片通用移植指南

  1. 准备工程

准备一个可以正常使用 uart 发送和接收数据的工程。

  1. 添加文件

将下载的仓库复制到你的工程目录，并添加到编译构建系统中，推荐使用CMake，直接set需要的功能，并引入仓库中的CMakeLists.txt，添加${ctshell_srcs}、${ctshell_incs}、${CTSHELL_DEFINITIONS}即可。

  1. 实现 IO 接口

你需要定义并填充 ctshell_io_t 结构体。

  • write：串口发送函数。应当是阻塞发送，或者确保数据被拷贝到发送缓冲区。

  • get_tick：（可选的） 获取系统毫秒级时间戳，用于 ctshell_delay。如果没有系统时钟，可以填 NULL，但在 Shell 脚本中延时功能将不可用。

以 stm32 hal 为例：

static void stm32_shell_write(const char *str, uint16_t len, void *p) {
    ctshell_stm32_priv_t *d = (ctshell_stm32_priv_t *) p;
    HAL_UART_Transmit(d->huart, (uint8_t *) str, len, 100);
}

ctshell_io_t io = {
    .write = stm32_shell_write,
    .get_tick = HAL_GetTick,
};

  1. 处理输入

Ctshell 需要手动送入接收到的字节，将单个字节送入 ctshell_input。

stm32 使用中断接收示例：

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    if (huart == &huart1) {
        ctshell_input(&ctx, rx_byte);
        HAL_UART_Receive_IT(&huart1, &rx_byte, 1);
    }
}

  1. 初始化与主循环

裸机环境: 在 main() 函数初始化 uart 后进行 Shell 初始化，并在主循环中轮询。

int main(void) {
    HAL_Init();
    MX_USART1_UART_Init();

    ctshell_stm32_init(&ctx, &huart1);

    while (1) {
        ctshell_poll(&ctx);
    }
}

RTOS 环境: 建议创建一个独立的任务来运行 Shell。

void shell_task(void *argument) {
    ctshell_stm32_init(&ctx, &huart1);

    while (1) {
        ctshell_poll(&ctx);
        osDelay(10);
    }
}

  1. 链接脚本修改

    gcc：无需修改。

    MDK-ARM（v5 and v6）：在scatter file中添加示例如下：

CtshellCmdSection +0 {
  *(ctshell_cmd_section)
}

  1. 测试

连接串口终端软件（如 MobaXterm, SecureCRT, Putty）。输入 help 并回车，如果看到命令列表，说明移植成功。