This section introduces the MiniCLI APIs including terms and acronyms, supported features, details on how to use the MiniCLI, function groups, enums, structures and functions. More...

Overview

This section introduces the MiniCLI APIs including terms and acronyms, supported features, details on how to use the MiniCLI, function groups, enums, structures and functions.

MiniCLI is a CLI engine designed with the footprint in mind for the memory and resource constrained systems. The code size is less than 3kB including command history and line editing.

Terms and acronyms

Terms	Details
CLI	Command line interface.

Supported features

Custom command Enables to add custom-defined commands in addition to default CLI commands. The custom command signature must be consistent with other CLI commands.
Multi-Level command and argument passing The CLI command supports multi-level command and argument passing to a CLI command handler.
Hidden command Add prefix 0x01 to the CLI command help message. This command will not show in "?" the available command list.
Flexiable I/O interface Replace getchar, putchar with custom-defined functions to set user-defined source and destination for getchar and putchar commands.
Security Support custom login function. Authentication can be added to.

How to use MiniCLI

To use MiniCLI, two functions and one control block with configuration are needed: cli_init and cli_task , as shown in the example below.

- Step 1. Apply the configuration settings with the function \link #cli_init \endlink.
- Step 2. Call \link #cli_task \endlink to read the user input characters and then call the corresponding user-defined handler function.
- Step 3. The function \link #cli_task \endlink repeats until the user logs
   out, which may or may not be implemented by the developer.
- Step 4. The control is returned to the caller if log out is requested by
   the user. This step may never be reached if log out is not implemented.
   @code
     cli_t cli_config = { ... <configuration omitted> ... };
     cli_init(&cli_config);
     while (1) {
         cli_task();
     }

Configuration

This section provides a MiniCLI configuration example using the following handler functions:

#cli_setup_ip()
#cli_setup_mac()
#cli_ver()

The command handlers are listed and linked together using a C structure cmd_t. In this example, the array cli_cmds is the root of the commands, that is, there are two commands at the top-level: set and ver. The command set requires a sub-command. ) In this example, the sub-command could be ip or mac.

If "ver" is supplied as an input source (by calling #__io_getchar()), #cli_ver() will be called. The version information will be printed to the output using #__io_putchar().

Whatever is supplied to the CLI engine is parsed into tokens similar to main function. The only difference is, in main() function call, the first parameter is the name of the executable.

In MiniCLI, the parameter len indicates the number of tokens supplied to the handler. The parameters supplied by the user on the CLI are stored in the param array based on the order of input. The array counter starts from 0.

uint8_t cli_setup_ip(uint8_t len, char *param[])
{
    if (len != 1) {
        printf("need an IP address\n");
        return 0;
    }
    // Call this function to process the IP address.
    sys_setup_ip(param[0]);
    return 0;
}
uint8_t cli_setup_mac(uint8_t len, char *param[])
{
    if (len != 1) {
        printf("need a mac address\n");
        return 0;
    }
    // Call this function to process the MAC address.
    sys_setup_mac(param[0]);
    return 0;
}
uint8_t cli_ver(uint8_t len, char *param[])
{
    printf("version: 2016-05-20\n");
    return 0;
}
cmd_t cli_setup[] = {
    { "ip",   "ip address",   cli_setup_ip,  NULL },
    { "mac",  "mac address",  cli_setup_mac, NULL },
    { NULL,   NULL,           NULL,          NULL }
};
cmd_t  cli_cmds[] = {
    { "set", "setup",        NULL,    &cli_setup[0] },
    { "ver", "show version", cli_ver, NULL          },
    { NULL,  NULL,           NULL,    NULL          }
};
static cli_t cli_config = {
    .state  = 1,
    .echo   = 0,
    .get    = __io_getchar,
    .put    = __io_putchar,
    .knock  = cli_hardcode_login,
    .cmd    = cli_cmds
};

In #cli_config(), a member state specifies the initial authentication status. If state is set to 1, the CLI engine skips the login function. If it is set to 0, the CLI engine calls the function cli_hardcode_login() with the user ID and password for an authenticated access.

In #cli_config(), the member echo controls what to display. In this example echo is used when typing a password, to hide or show it. Default value is 0.

This section explains the key fields in the configuration structure. An example source code is provided in the cli_def.c source file.

Note: The return value of the handler function is 0. MiniCLI may be enhanced in the future to support the processing of different return values.

Functions
void	cli_init (cli_t *cli)
	MiniCLI initialization. More...

void	cli_line (char *line)
	Process one line of command in plain text format. More...

void	cli_tokens (uint8_t argc, char *argv[])
	Process a tokenized command in array of string pointers format. More...

void	cli_task (void)
	The top-level function of the actual CLI. More...

uint8_t	cli_logout (uint8_t len, char *param[])
	This function implements the logout function. More...

uint8_t	cli_hardcode_login (char id, char password)
	A sample login function implementation. More...

Modules
	Define

	Struct

	Typedef

Function Documentation

uint8_t cli_hardcode_login	(	char *	id,
		char *	password
	)

A sample login function implementation.

The login ID and password were both hardcoded in source code as '1'.

Parameters

[in]	ID	is not used.
[in]	password	is not used.

Returns: always 1 (for now).

Note: Apply this as a reference implementation for user-defined login API.

void cli_init ( cli_t * cli )

MiniCLI initialization.

This function initializes the MiniCLI, call this function before applying other MiniCLI functions. To initialize, one parameter containing a declared table and the chains of commands is required. See cli_t for more information.

Parameters

[out] cli configuration.

Returns: None

Note: the memory pointed by cli must be writable and allocated solely for the use MiniCLI.

Example: Sample code, please refer to How to use MiniCLI How to start using MiniCLI

void cli_line ( char * line )

Process one line of command in plain text format.

Returns: None

Parameters

[in] line a string with command in it.

uint8_t cli_logout	(	uint8_t	len,
		char *	param[]
	)

This function implements the logout function.

Parameters

[in]	len	is the number of elements in the array pointer param.
[in]	param	is an array of pointers remove to the parameters.

Returns: always zero (for now).

void cli_task ( void )

The top-level function of the actual CLI.

This function will never exit unless the user logged out.

Returns: None

Example: Sample code, please refer to How to use MiniCLI How to use MiniCLI

void cli_tokens	(	uint8_t	argc,
		char *	argv[]
	)

Process a tokenized command in array of string pointers format.

Returns: None

Parameters

[in]	argc	the number of elements in argv[].
[in]	argv	the array of string pointers.

Overview

Terms and acronyms

Supported features

How to use MiniCLI

Configuration

Functions

Modules

Function Documentation