发新帖本帖赏金 50.00元(功能说明)我要提问
返回列表
[APM32F407]

基于APM32F4移植使用letter-shell命令行终端

[复制链接]
786|5
手机看帖
扫描二维码
随时随地手机跟帖
luobeihai|  楼主 | 2022-12-11 23:42 | 显示全部楼层 |阅读模式
本帖最后由 luobeihai 于 2022-12-11 23:42 编辑

#申请原创#  @21小跑堂
1. letter-shell简介
letter shell是一个C语言编写的,可以嵌入在程序中的嵌入式shell,主要面向嵌入式设备。
说得直白点他就是一个命令行交互软件,可以读取用户输入的命令,找到并执行命令对应的函数。
letter-shell的功能十分强大,目前主要功能有:
  • 命令自动补全
  • 快捷键功能定义
  • 命令权限管理
  • 用户管理
  • 变量支持
  • 代理函数和参数代理解析

下面是letter-shell运行起来的效果图:
image-20221211200222990.png
该项目代码遵循MIT协议,作者的代码仓库如下:
https://github.com/NevermindZZT/letter-shell

2. 获取源码
我们是要把letter-shell,移植到极海APM32F4的MCU上面运行,所以我们需要获取到极海的APM32F4的SDK包,以及letter-shell的源码。
  • 获取 APM32F4 SDK :
    https://geehy.com/support/apm32?id=311

  • letter-shell 开源项目源码:
    可以到简介,给出的作者的github官网下载。如果因为网速的原因,也可以到gitee上面下载,gitee也有很多关于letter-shell的源码,下面给出其中一个仓库地址:
    https://gitee.com/biao22ndg/letter-shell

3. APM32F4上移植letter-shell过程
3.1 准备一份可以通过串口打印信息的工程
我们把官网的APM32F4 SDK下载下来后,然后我们选择一个串口中断的例程,如下:
image-20221211203213382.png
然后,把这个例程不需要的代码去掉,只留下串口相关的初始化代码,还有printf重定向的代码就行了。
编译下载到板子之后,可以看到串口正常输出打印信息,就说明代码正常。

3.2 向工程添加letter-shell源码
letter-shell源码目录如下:
image-20221211205110255.png
我们只需要把src目录下的源码复制到对应工程目录下即可。
我这里就复制到对应工程的 \Middlewares\letter-shell 目录下。

3.3 在keil-MDK中添加源码和文件包含路径
打开keil的项目管理窗口,然后添加我们刚刚复制的letter-shell的源码目录src的所有文件:
image-20221211205606464.png
添加文件之后,再添加letter-shell的文件包含路径:
image-20221211205843867.png
点击OK,退出。这个时候源码相当于添加完成,这是编译是可以通过的,没警告和错误。但是还不能正常使用letter-shell,因为还没有添加移植的接口函数。

3.4 添加shell_port.c文件,提供读写接口函数
我们还需要提供letter-shell的读写接口函数,这样letter-shell才能通过串口输出字符,或者通过串口获取输入字符。
在letter-shell的源码目录下,demo目录中,已经提供了基于stm32 freeRTOS的读写接口,我们可以把该文件复制到我们的工程目录下,然后在该文件基础上进行改写:
image-20221211210955325.png
1、在shell_port.c中,我们主要实现shell的写函数即可,代码如下:
/**
* [url=home.php?mod=space&uid=247401]@brief[/url] 用户shell写
*
* @param data 数据
* @param len 数据长度
*
* [url=home.php?mod=space&uid=266161]@return[/url] short 实际写入的数据长度
*/
short userShellWrite(char *data, unsigned short len)
{
        unsigned short temp = len;
        
        while (temp--)
        {
                /* send a byte of data to the serial port */
                USART_TxData(USART1, *data++);

                /* wait for the data to be send */
                while (USART_ReadStatusFlag(USART1, USART_FLAG_TXBE) == RESET);
        }
        
    return len;
}

2、关于读函数,我们可以不用实现,因为我们使用的是串口中断方式接收字符,不需要实现读函数。我们只需要在串口中断函数中,调用shellHandler即可。串口中断代码如下:
/*!
* [url=home.php?mod=space&uid=247401]@brief[/url]        This function handles USART1 RX interrupt Handler
*
* @param        None
*
* @retval       None
*
* @note
*/
void USART1_IRQHandler(void)
{
        uint8_t ch;
        
        if (USART_ReadIntFlag(USART1, USART_INT_RXBNE) == SET)
        {
                ch = USART_RxData(USART1);
                shellHandler(&shell, ch);
        }
}

3、提供letter-shell的初始化函数,该函数其实主要就是初始化shell结构体。因为我们只用到写函数,所以只提供了写接口。具体代码如下:
Shell shell;
char shellBuffer[512];

/**
* [url=home.php?mod=space&uid=247401]@brief[/url] 用户shell初始化
*
*/
void userShellInit(void)
{
    shell.write = userShellWrite;
    shellInit(&shell, shellBuffer, 512);
}

3.5 main函数初始化letter-shell
当我们把接口函数都提供了之后,就只需要在main函数调用 letter-shell 的初始化函数 userShellInit 即可。main函数代码如下:
/*!
* [url=home.php?mod=space&uid=247401]@brief[/url]       Main program
*
* @param       None
*
* @retval      None
*/
int main(void)
{
    /* USART Initialization */
    USART_Config_T usartConfigStruct;

    usartConfigStruct.baudRate = 115200;
    usartConfigStruct.hardwareFlow = USART_HARDWARE_FLOW_NONE;
    usartConfigStruct.mode = USART_MODE_TX_RX;
    usartConfigStruct.parity = USART_PARITY_NONE;
    usartConfigStruct.stopBits = USART_STOP_BIT_1;
    usartConfigStruct.wordLength = USART_WORD_LEN_8B;
    APM_EVAL_COMInit(COM1, &usartConfigStruct);
    APM_EVAL_COMInit(COM2, &usartConfigStruct);

    /* Enable USART1 RXBNE interrput */
    USART_EnableInterrupt(EVAL_COM1, USART_INT_RXBNE);
    USART_ClearStatusFlag(EVAL_COM1, USART_FLAG_RXBNE);
    NVIC_EnableIRQRequest(EVAL_COM1_IRQn,1,0);
        
        userShellInit();

    while(1)
    {
    }
}

主要就是初始化串口之后,就调用 userShellInit 初始化letter-shell。
到这里,我们就完成了letter-shell的移植了,编译下载可以看到如下效果:
image-20221211213130146.png
可以看到letter-shell支持了一些默认命令。

3.6 letter-shell的配置文件shell_cfg.h
该文件也是在letter-shell的src目录下,shell_cfg.h文件中包含了所有用于配置shell的宏,在使用前,可根据需要进行配置。我们工程是使用的默认配置,基本的功能也有,要想使用其他功能,可能需要先打开某个配置宏,定义的含义如下:
image-20221211214019388.png
4. 自定义自己的命令

4.1 与导出自定义命令相关的宏
letter-shell支持定义自己的命令,并且把该命令导出到shell终端中,以供我们在命令行下使用自定义的命令。
在使用letter-shell自定义命令时,要先检查 shell_cfg.h 文件是否开启了命令导出功能。
/**
* [url=home.php?mod=space&uid=247401]@brief[/url] 是否使用命令导出方式
*        使能此宏后,可以使用`SHELL_EXPORT_CMD()`等导出命令
*        定义shell命令,关闭此宏的情况下,需要使用命令表的方式
*/
#define     SHELL_USING_CMD_EXPORT      1

就是这个宏需要定义为 1 。开启了这个宏,我们就可以编写自己的命令函数,然后导出到shell终端了。
导出自定义命令的宏在 shell.h 文件中定义,其代码如下:
/**
* [url=home.php?mod=space&uid=247401]@brief[/url] shell 命令定义
*
* @param _attr 命令属性
* @param _name 命令名
* @param _func 命令函数
* @param _desc 命令描述
*/
#define SHELL_EXPORT_CMD(_attr, _name, _func, _desc) \
        const char shellCmd##_name[] = #_name; \
        const char shellDesc##_name[] = #_desc; \
        SHELL_USED const ShellCommand \
        shellCommand##_name SHELL_SECTION("shellCommand") =  \
        { \
            .attr.value = _attr, \
            .data.cmd.name = shellCmd##_name, \
            .data.cmd.function = (int (*)())_func, \
            .data.cmd.desc = shellDesc##_name \
        }

这里作者加入了命令属性的参数,主要就是定义该命令的权限,类型,是否使用返回值输出等等(详细的属性定义可以去看源码),其他参数就是命令名,对应的命令函数名,已经该命令的描述。

4.2 编写一个命令测试函数
这里我编写一个测试命令函数,代码如下:
/* 自定义命令测试函数 */
int test_func(int a, char *str)
{
        printf("%d\r\n", a);
        printf("%s\r\n", str);
        
        return 0;
}

/* 导出到命令列表里 */
SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), test_cmd, test_func, test cmd);

然后编译运行,可以看到多了一个test_cmd命令:
image-20221211220949182.png
可以看到我们运行这个命令的时候,输出了我们代码的打印内容。
根据作者的reamme文件,目前 letter shell 3.x 版本,命令函数参数只支持整数,字符,字符串参数,以及在某些情况下的浮点参数直接传递给执行命令的函数。浮点型参数是在哪些情况才支持,可以阅读作者的文档。
另外,参数的个数,是有一个宏配置的:
/**
* [url=home.php?mod=space&uid=247401]@brief[/url] shell命令参数最大数量
*        包含命令名在内,超过16个参数并且使用了参数自动转换的情况下,需要修改源码
*/
#define     SHELL_PARAMETER_MAX_NUMBER  8

默认只支持8个参数,当然我们可以修改支持更多参数个数。

我也把整个工程源码上传了,以供大家参考。
  

      

APM32F4xx_EVAL_SDK_Letter-Shell.zip

567.97 KB

使用特权

评论回复

打赏榜单

21小跑堂 打赏了 50.00 元 2022-12-12
理由:恭喜通过原创审核!期待您更多的原创作品~

评论
21小跑堂 2022-12-12 16:46 回复TA
Letter shell小而美的嵌入式实用shell,作者通过简单的移植,便让这个小工具在APM32 MCU上完美运行,移植过程详细顺利,继续加油。 
kai迪皮| | 2022-12-13 14:15 | 显示全部楼层
好文,点赞

使用特权

评论回复
xu@xupt| | 2022-12-19 10:36 | 显示全部楼层
学习啦,感谢分享

使用特权

评论回复
FBI快开门| | 2022-12-30 11:56 | 显示全部楼层
博主好:
移植之后,使能SHELL_USING_CMD_EXPORT = 1,即便在option target>>Linker中添加--keep shellCommand*
变异后还是报错,看起来是被优化掉了
.\Objects\CreateProject.axf: Warning: L6330W: Undefined symbol shellCommand$$Base (referred from shell.o). Unused section has been removed.
.\Objects\CreateProject.axf: Warning: L6330W: Undefined symbol shellCommand$$Limit (referred from shell.o). Unused section has been removed.

烧录运行结果:
Please input password:123456
123456
123456
123456
123456
123456
123456
123456
123456
123456
1234
Warning: Command is too long

使用特权

评论回复
评论
luobeihai 2022-12-30 20:58 回复TA
你是想要自定义命令吗?直接定义自己的命令函数,然后导出到命令行终端就行了呀。不知道你这为什么会报错的 
发新帖 本帖赏金 50.00元(功能说明)我要提问
您需要登录后才可以回帖 登录 | 注册

本版积分规则