MT7687 API Reference  LinkIt SDK v4
MiniCLI

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

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) {
}

Configuration

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

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,
.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]IDis not used.
[in]passwordis 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]cliconfiguration.
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]linea string with command in it.
uint8_t cli_logout ( uint8_t  len,
char *  param[] 
)

This function implements the logout function.

Parameters
[in]lenis the number of elements in the array pointer param.
[in]paramis 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]argcthe number of elements in argv[].
[in]argvthe array of string pointers.