An Open Source MCU-Level Command Line Interaction Component

Introduction to nr_micro_shell

During debugging and maintenance, it is often necessary to interact with microcontrollers to retrieve or set certain parameters or execute specific operations. nr_micro_shell is a basic command line tool designed to meet this need for resource-constrained MCUs. Although the finsh command line interaction tool provided in the RT_Thread component is powerful, it can be somewhat bulky for microcontrollers with limited ROM and RAM resources. For these platforms, if you still want to retain basic command line interaction functionality, nr_micro_shell is a good choice.

nr_micro_shell has the following advantages:

1. Low resource usage, simple to use, flexible and convenient. The usage process only involves two functions: shell_init() and shell(). Whether using RTOS or bare metal, this tool can be easily applied without additional coding work.

2. Good interactive experience. It is completely similar to the Linux shell command line. When the serial terminal supports ANSI (such as Hypertrm terminal), it not only supports basic command line interaction but also provides command completion with the Tab key, command history queries, and cursor movement with the arrow keys.

3. Good extensibility. nr_micro_shell provides users with a standard function prototype for custom commands. Users only need to write command functions according to the command and register them to use the commands.

Comparison of resource usage between nr_micro_shell and finsh (finsh not using msh) under the same configuration

Original Project	Increase of Adding nr_micro_shell	Increase of Adding finsh
ROM	63660	+3832	+26908
RAM	4696	+1104	+1304

Both configurations are as follows:

Up to 3 historical commands.
Supports Tab completion.
Maximum command line length is 100.
Up to 10 command parameters.
Command line thread stack is 512 bytes.

The demonstration effect of nr_micro_shell is as follows

1.1 Directory Structure

Name	Description
docs	Documentation directory, contains demonstration GIF images, etc.
examples	Example directory, includes command function examples: *nr_micro_shell_commands.c* and RT_Thread usage examples *nr_micro_shell_thread.c*
inc	Header file directory
src	Source code directory

1.2 License

The nr_micro_shell package follows the MIT license, see LICENSE file for details.

1.3 Dependencies

No dependencies

Using nr_micro_shell in RT_Thread ENV Tool

Using the nr_micro_shell package in RT_Thread requires selecting it in the RT-Thread package manager, the specific path is as follows:

RT-Thread online packages
    tools packages ---&gt; 
        [*] nr_micro_shell: Lightweight command line interaction tool. ---&gt;

Related settings can be configured after pressing the space key to select, then press the enter key for related parameter configuration. Then let the RT-Thread package manager update automatically, or use the pkgs --update command to update the package to the BSP.

If you need to run examples, ensure that the option Using console for kt_printf. in the RT_Thread configuration is enabled, and that Use components automatically initialization. option is checked. You can compile and download or simulate to use nr_micro_shell directly. When the command line is blank, pressing Tab will display all supported commands. Test example commands can be seen in the usage example animations under doc/pic. For the process of custom commands, refer to the method in 3. Using nr_micro_shell package in Bare Metal.

Using nr_micro_shell package in Bare Metal

3.1 Configuration:

All configuration work can be done in nr_micro_shell_config.h. For detailed information, please refer to the comments in the file.

3.2 Usage:

Ensure that all files are added to the project.
Ensure that the macro functions “shell_printf()” and “ansi_show_char()” in nr_micro_shell_config.h can be used normally in the project.
Usage example is as follows

#include "nr_micro_shell.h"

int main(void)
{
    /* Initialization */
    shell_init();

    while(1)
    {
        if(USART GET A CHAR 'c')
        {
            /* nr_micro_shell receives character */
            shell(c);
        }
    }
}

It is recommended to use the following code directly before using hardware input (to ensure you can print information correctly) to verify if nr_micro_shell can run normally

#include "nr_micro_shell.h"

int main(void)
{
    unsigned int i = 0;
    // Match the end character configuration NR_SHELL_END_OF_LINE 0
    char test_line[] = "test 1 2 3\n"
    /* Initialization */
    shell_init();
    
    /* Preliminary test code */
    for(i = 0; i &lt; sizeof(test_line)-1; i++)
    {
        shell(test_line[i]);
    }

    /* Official working code */
    while(1)
    {
        if(USART GET A CHAR 'c')
        {
            /* nr_micro_shell receives character */
            shell(c);
        }
    }
}

3.3 Adding Your Own Commands

STEP1:

You need to implement a command function in nr_micro_shell_commands.c. The prototype of the command function is as follows

void your_command_function(char argc, char *argv)
{
    .....
}

argc is the number of parameters. argv stores the starting addresses and contents of each parameter. If the input string is

test -a 1

Then argc is 3, and the contents of argv are

-------------------------------------------------------------
0x03|0x08|0x0b|'t'|'e'|'s'|'t'|'\0'|'-'|'a'|'\0'|'1'|'\0'|
-------------------------------------------------------------

If you want to know the content of the first or second parameter, you should use

/* "-a" */
printf(argv[argv[1]])
/* "1" */
printf(argv[argv[2]])

STEP2: Before using the command, you need to register it. There are two methods to register commands

1. When the NR_SHELL_USING_EXPORT_CMD is not defined in the configuration file, write into the static_cmd[] table

const static_cmd_st static_cmd[] =
{
   .....
   {"your_command_name",your_command_function},
   .....
   {"\0",NULL}
};

Note: Do not delete {“\0”, NULL}!

2. When NR_SHELL_USING_EXPORT_CMD is defined in the configuration file, and NR_SHELL_CMD_EXPORT() supports the compiler being used, you can register commands using the following method

NR_SHELL_CMD_EXPORT(your_command_name,your_command_function);

Simulating nr_micro_shell under Linux

The nr_micro_shell simulation code is stored in the ./examples/simulator/ directory, and you can still add custom commands in the ./examples/nr_micro_shell_commands.c file as described above. After adding, you can use the make command to compile the source code, and the generated executable file will be ./examples/simulator/out/nr_micro_shell or ./examples/simulator/out/nr_micro_shell_db. The usable make commands are as follows

# Compile the executable file
make
# Compile the simulation executable file
make debug
# Clean up compiled files
make clean

Notes

Choose the command registration method based on your usage habits using NR_SHELL_USING_EXPORT_CMD.

When registering commands using the registry, ensure that your project contains the registry

const static_cmd_st static_cmd[] =
{
   .....
   {"\0",NULL}
};

When using NR_SHELL_CMD_EXPORT(), ensure that NR_SHELL_CMD_EXPORT() is supported by the used compiler, otherwise an error will occur.

nr_micro_shell does not support ESC key or other control keys (control characters).

Original source:Maintainer: Nrusher

An Open Source MCU-Level Command Line Interaction Component

1. None)

2. Why can’t I draw schematics well? These tips are essential

3. How to display IP location on embedded devices?

4. RISC-V faces challenges in MCU/MPU and RTOS…

5. A method for self-updating firmware in microcontrollers!

6. The Xuan Tie Cup RISC-V Application Innovation Competition officially starts, registration is now open!

Disclaimer: This article is a network reprint, and the copyright belongs to the original author. If there are copyright issues, please contact us, and we will confirm the copyright based on the copyright certificate you provide and pay the remuneration or delete the content.