Command Line Interface

Description

Command Line Interface (CLI)

Introduction

The Command Line Interface (CLI) software component simplifies creating command line user interfaces for programs. It handles tasks such as receiving keyboard input, parsing the input strings for commands and arguments, and finally call the proper C function with decoded and validated arguments. Functions can use standard output functions such as printf to write information to the console.

Multiple components (parts of an application) may define CLI commands where the running program will typically merge all commands into a super-set of commands with common input and output, I/O. The CLI uses I/O functions provided by the I/O Streams framework, iostream.

The CLI component supports multiple instances where separate CLI instances will use separate iostream instances. Groups of commands can be assigned to specific CLI instances, making it possible for one application to use multiple CLI instances where each is customized for its particular use.

Content

Features Design Configuration Examples Extensions

Features

The CLI has several built in features that will be inherited by all applications using the CLI component. The following sections will explain some of the CLI features.

Please note: Some of the features can be simplified or removed to reduce code size by changing the configuration of the application.

Command Groups

The CLI support both stand alone commands and commands that belong to groups. A stand alone command is executed by typing just the command name and arguments. If a command belong to a group, the group name must be typed before the command name. Groups can be nested, and in that case, all group names must be typed before the command name.

If an application has implemented the commands on and off that are part of the groups green and red in group led , the user can type: led green on or led red off to control the LEDs.

Help

The CLI has a built in help command, which can be used as follows:

By typing help , all commands are listed.

By typing help group , all commands in the group are listed.

By typing help command , help for the command is shown.

The information that is displayed when using the help command must be supplied by the implementer. Details for each command must be placed in command tables. See the Command tables section for more details.

Auto-Complete

The CLI can complete a partially typed command by pressing the TAB key.

Cursor Movement

The up-arrow and down-arrow keys can be used to navigate up and down in the history buffer.

The left-arrow and right-arrow keys are used to move the cursor in the current command line. The BACKSPACE key is used to delete the character to the left of the cursor. The DEL key is used to delete the character under the cursor. Typed characters will be inserted at the cursor position.

Command History

Commands will be stored in the history buffer when executed. Previous commands can be executed again by pressing the up-arrow key one or more times.

Please note: The history buffer is a simple character array, which does not define how many command lines can be stored. The history buffer will store command lines sequentially, making room for more short commands than long.

Dynamic Registration of New Commands

An application using the CLI component can define commands that must be installed either at compile time or at run time. Defining commands at compile time may be sufficient for simple applications, while more advanced applications with several CLI instances, may utilize that the CLI can add command groups at run time.

Central decoding and validation of command arguments

The CLI has built in functions to decode and validate command arguments. The command handler will not be called unless the command is entered with correct arguments.

The CLI argument validation can handle signed and unsigned numeric values with 8, 16 and 32 bit sizes, hexadecimal and string arguments. The command handler will be called with decoded arguments using an arc, argv pattern similar to how C/C++ applications pass command line arguments to the main function.

If none of the built in argument types can be used by the command, it can use string arguments and decode the strings in the command handler.

Please note: For the last argument, it is possible to specify that it is optional, mandatory or can have multiple values.

Input and output

The CLI is using iostreams for input and output. Each CLI instance must have a dedicated iostream instance.

Assigning an iostream instance to a CLI instance is usually done with an application configuration. If the application has only one CLI and one iostream instance, the configuration will automatically assign the iostream instance to the CLI instance.

Requirements not defined by the CLI

Command naming rules or output formats are not defined by the CLI.

Design

To fully understand how to use the CLI, it is crucial to understand the design and some implementation details. The following sections will try to explain the basics and how to create user commands.

Modules

The CLI has been implemented as two independent software modules: input handler and command interpreter . The input handler handles the user input and allows the user to enter command lines. When the user types the ENTER key, the input string is passed to the command interpreter where the string will be interpreted and the appropriate command handler will be called with the command arguments.

Normally both modules are used together, but an application can use the command interpreter directly. In that case, the command interpreter must be called with a command line as input parameter.

Command signature

All command handlers must have the same signature, defined in sl_cli_types.h :

typedef void (*sl_cli_command_func_t)( sl_cli_command_arg_t *arguments);

Command arguments

Command arguments are available via the arguments pointer passed to the command handler function.

The arguments pointer will point to a struct holding the actual argument values.

The arguments struct has the following definition:

typedef struct {
struct sl_cli *handle;
int argc;
void **argv;
int arg_ofs;
const sl_cli_argument_type_t* arg_type_list;
} sl_cli_command_arg_t ;

The handle identifies the CLI instance where the command was issued. By including the instance handle, it is possible to share the same command handler between multiple CLI instances.

By using the argc , argv way of passing argument values, it is possible to have a common command handler signature but support variable number of arguments.

When the command handler is called, the argc , argv arguments will contain all commands and arguments. Because the CLI supports command groups, the command may consist of multiple command groups along with the command itself. The arg_ofs tells the command handler the offset where the command arguments begin.

The 'arg_type_list' points to the array of argument type contained in the sl_cli_command_info_t struct of the command. With this, inside the handler it is possible to call the sl_cli_get_argument_type(a, n) macro and retrieve the type of an argument. Although this should be known at compile time, there are some scenarios when autogenerating commands where knowing their type could be usefull.

The cli.h has defined the following macros that can be used to get argument values. The macros use a for the arguments pointer and n for the argument offset, starting on 0 for the first argument.

sl_cli_get_argument_int8 (a, n)
sl_cli_get_argument_int16 (a, n)
sl_cli_get_argument_int32 (a, n)
sl_cli_get_argument_uint8 (a, n)
sl_cli_get_argument_uint16 (a, n)
sl_cli_get_argument_uint32 (a, n)
sl_cli_get_argument_hex (a, n, l)
sl_cli_get_argument_string (a, n)

Command tables

Adding commands to the CLI requires use of three different data structures. The data structures have a root node referred to as a "command group", where sub-structures defining command details are nested. The "command group" may contain details for one or more commands, and it is possible to install multiple "command groups" in each CLI instance.

The "command group" must be of the type:

typedef struct {
sl_slist_node_t node;
bool in_use;
const sl_cli_command_entry_t *command_table;
} sl_cli_command_group_t ;

Please note: Each time a command group shall be installed in a CLI instance, the application must support one unique command group data structure. Command groups cannot be re-used or shared between CLI instances.

The next level is an array where each of the elements must be a "command entry". There will typically be one array element for each command. If a command has both a long and a short (shortcut) name, it will take two array elements.

Each of the "command entries" must be of the type:

typedef struct {
const char *name;
const sl_cli_command_info_t *command;
const bool is_shortcut;
} sl_cli_command_entry_t ;

A "command entries" array can be re-used and shared between multiple CLI instances.

And finally "command information" for commands are defined in one data structure for each command. The "command information" structure is defined with the type:

typedef struct {
sl_cli_command_func_t function ;
#if SL_CLI_HELP_DESCRIPTION_ENABLED
char *help;
char *arg_help;
#endif // SL_CLI_HELP_DESCRIPTION_ENABLED
sl_cli_argument_type_t arg_type_list[];
} sl_cli_command_info_t ;

A "command information" data structure can be re-used and shared between multiple CLI commands and instances.

Command handler

In addition to the tables described above, each command must have a command handler. The command handler is typically written in C-code, and all command handlers have the same signature. The command handler function prototype has the following defition:

typedef void (*sl_cli_command_func_t)( sl_cli_command_arg_t *arguments);

Differences between bare-metal and kernel configurations

The CLI component can be used in both bare-metal and kernel configurations. There are some differences between the two configurations that is explained in the following sections.

Bare-metal

In a bare-metal configuraton, the input handler has a process-action (tick) function that will poll the iostream for input. When generating a project with uc, the CLI process-action function will be installed into the system framework. Calling the sl_system_process_action function will call the CLI process-action function.

Please note: Cli command handlers that take a long time to execute can (should) return from the process-action function before they are complete to not stall other component process-action functions. Execution will in that case be split into several calls to the process-action function. The application should not make any assumptions about when any of the command handlers have completed execution based on when the sl_system_process_action returns.

Kernel

In a kernel configuration, the CLI will create a task where the input handler will poll the iostream for input data. There will be created one task for each CLI instance, and the task(s) must be started by the application by calling the sl_system_kernel_start function.

Configuration

The CLI has two sets of configurations. One is common for all CLI instances and is placed in the sl_cli_config.h file. The other is a configuration file for each CLI instance with the file name sl_cli_config_<instance-name>.h .

Examples

The following steps demonstrates how to create and install a CLI command.

Please note: To avoid forward definitions in the C-code, the following steps will typically be implemented in reverse order.

Include the cli and iostream components to the project. Both cli and iostream_usart instances must specify instance names. The iostream_usart component has some pre-defined instance names while the cli instance name can be anything.

component:
- id: cli
instance:
- example
- id: iostream_usart
instance:
- vcom

Create the command group at the top level:

static sl_cli_command_group_t a_group_0 = {
{ NULL },
false ,
a_table
};

Create the array of commands, containing two elements in this example:

static sl_cli_command_entry_t a_table[] = {
{ "echo_str" , &cmd__echostr, false },
{ "echo_int" , &cmd__echoint, false },
{ NULL, NULL, false },
};

Create command details for the two commands:

static const sl_cli_command_info_t cmd__echostr = \
SL_CLI_COMMAND(echo_str,
"echoes string arguments to the output" ,
"Just a string..." ,
{SLI_CLI_ARG_WILDCARD, SLI_CLI_ARG_END, });
static const sl_cli_command_info_t cmd__echoint = \
SL_CLI_COMMAND(echo_int,
"echoes integer arguments to the output" ,
"Just a number..." ,
{SLI_CLI_ARG_INT8, SLI_CLI_ARG_ADDITIONAL, SLI_CLI_ARG_END, });

Create command handlers for the two commands:

void echo_str( sl_cli_command_arg_t *arguments)
{
char *ptr_string;
for ( int i = 0; i < sl_cli_get_argument_count (arguments); i++) {
ptr_string = sl_cli_get_argument_string (arguments, i);
...
}
}
void echo_int( sl_cli_command_arg_t *arguments)
{
int8_t argument_value;
for ( int i = 0; i < sl_cli_get_argument_count (arguments); i++) {
argument_value = sl_cli_get_argument_int8 (arguments, i);
...
}
}

And finally call the function to install the commands.

status = sl_cli_command_add_command_group (cli_handle, &a_group_0);

The output from executing help will in this case be:

> help
echostr echoes string arguments to the output
[*] Just a string ...
echoint echoes integer arguments to the output
[int8+] Just a number...

Extensions

The CLI comes with some pre-made components that can be useful for some applications. To take advantage of these components, the user must:

  1. Define the command(s) in the command tables. Use the command handlers supplied with the component(s).
  2. Include the component(s) in the project.

The components come with the command handlers and do all the necessary integration with the CLI. The components do however not define the command name, it must be defined by the application implementer.

Please note: The CLI extensions described here will use the method of splitting some of the command handler operations into multiple process-action calls for bare-metal configuration.

Common properties for the storage components: The storage components share some common properties although data is stored in different locations. The most important are: New commands can be added, existing commands can be deleted and stored commands can be executed.

One benefit of running commands from a storage compared to typing the commands at user input is that the next command in the list will be executed immediately after the previous command has completed. Commands will be executed in the sequence they are added and stored, and there will be zero or little delay between commands.

CLI Storage NVM3

The cli_storage_nvm3 component has been designed to store command lines in NVM3 storage. In addition to letting the user control when the commands are executed, the stored commands will automatically be executed at program start.

The cli_storage_nvm3 component does not define the user commands, but it implements a few functions where the following four are designed to be used as CLI command handlers directly.

void sl_cli_storage_nvm3_clear ( sl_cli_command_arg_t *arguments);
void sl_cli_storage_nvm3_list ( sl_cli_command_arg_t *arguments);
void sl_cli_storage_nvm3_define ( sl_cli_command_arg_t *arguments);
void sl_cli_storage_nvm3_execute ( sl_cli_command_arg_t *arguments);

In addition, it is possible to get the number of command lines stored in NVM3 storage by calling:

size_t sl_cli_storage_nvm3_count (sl_cli_handle_t cli_handle);

The cli_storage_nvm3 depends on the cli_default component that defines the NVM3 storage area. This area is typically shared between different parts of the application, where each has its own range of NVM3 object keys to avoid collisions. The cli_storage_nvm3 component has got a range with 256 keys.

It is possible to configure each CLI instance to use a sub-set of the available 256 keys to separate commands between different CLI instances.

CLI Storage RAM

The cli_storage_ram component has been designed to store command lines in a ram buffer.

The cli_storage_ram component does not define the user commands, but it implements a few functions where the following four are designed to be used as CLI command handlers directly.

void sl_cli_storage_ram_clear ( sl_cli_command_arg_t *arguments);
void sl_cli_storage_ram_list ( sl_cli_command_arg_t *arguments);
void sl_cli_storage_ram_define ( sl_cli_command_arg_t *arguments);
void sl_cli_storage_ram_execute ( sl_cli_command_arg_t *arguments);

In addition, it is possible to get the number of command lines stored in RAM by calling:

size_t sl_cli_storage_ram_count (sl_cli_handle_t cli_handle);

Each instance of the CLI will have its own RAM buffer. Commands defined in one CLI instance will not be available for other instances.

CLI Delay

The cli_delay component may be useful to add delays between commands when running command sequences from a storage. The function will delay for the specified number of milliseconds. During the delay, it will allow other components to run in the background.

The command handler has the following function prototype:

void sl_cli_delay_command ( sl_cli_command_arg_t *arguments);

Modules

CLI Commands in NVM3
Support for CLI commands stored in and executed from NVM3.
CLI Commands in RAM
Support for CLI commands stored in and executed from RAM.
CLI Delay
CLI Delay.

Functions

sl_status_t sl_cli_tokenize (char input[], int *token_c, char *token_v[])
Split a C-string on space, ignoring sections in {} or "".
uint8_t * sl_cli_get_argument_hex ( sl_cli_command_arg_t *a, size_t n, size_t *l)
Get the hex argument length and value.
void sl_cli_clear (sl_cli_handle_t handle)
Clear (reset) a CLI.
void sl_cli_redirect_command (sl_cli_handle_t handle, sl_cli_command_function_t command_function, const char *prompt, void *aux)
Redirect user input.
sl_status_t sl_cli_handle_input (sl_cli_handle_t handle, char *string)
Handle input.
sl_status_t sl_cli_instance_init (sl_cli_handle_t handle, sl_cli_instance_parameters_t *parameters)
Initialize a CLI instance.
bool sl_cli_is_ok_to_sleep (sl_cli_handle_t handle)
Check if the CLI instance can allow sleep.
void sl_cli_tick_instance (sl_cli_handle_t handle)
The bare metal tick function.
bool sl_cli_command_add_command_group (sl_cli_handle_t handle, sl_cli_command_group_t *command_group)
Add a new command group.
bool sl_cli_command_remove_command_group (sl_cli_handle_t handle, sl_cli_command_group_t *command_group)
Remove a command group.
const sl_cli_command_entry_t * sl_cli_command_find (sl_cli_handle_t handle, int *token_c, char *token_v[], int *arg_ofs, bool *single_flag, bool *help_flag)
Find a command given the command groups and input arguments.
sl_status_t sl_cli_command_execute (sl_cli_handle_t handle, char *input)
Find and execute a command given the string input and the command table.
bool sl_cli_input_char (sl_cli_handle_t handle, char c)
Handle new input char from the terminal, both in terms of writing back to terminal and writing to the input buffer.
void sl_cli_input_clear (sl_cli_handle_t handle)
Empty the input buffer.

Macros

#define SL_CLI_ARG_UINT8 (0x00U)
UINT8 argument type.
#define SL_CLI_ARG_UINT16 (0x01U)
UINT16 argument type.
#define SL_CLI_ARG_UINT32 (0x02U)
UINT32 argument type.
#define SL_CLI_ARG_INT8 (0x03U)
INT8 argument type.
#define SL_CLI_ARG_INT16 (0x04U)
INT16 argument type.
#define SL_CLI_ARG_INT32 (0x05U)
INT32 argument type.
#define SL_CLI_ARG_STRING (0x06U)
STRING argument type.
#define SL_CLI_ARG_HEX (0x07U)
HEX argument type.
#define SL_CLI_ARG_UINT8OPT (0x10U)
Optional UINT8 argument type.
#define SL_CLI_ARG_UINT16OPT (0x11U)
Optional UINT16 argument type.
#define SL_CLI_ARG_UINT32OPT (0x12U)
Optional UINT32 argument type.
#define SL_CLI_ARG_INT8OPT (0x13U)
Optional INT8 argument type.
#define SL_CLI_ARG_INT16OPT (0x14U)
Optional INT16 argument type.
#define SL_CLI_ARG_INT32OPT (0x15U)
Optional INT32 argument type.
#define SL_CLI_ARG_STRINGOPT (0x16U)
Optional STRING argument type.
#define SL_CLI_ARG_HEXOPT (0x17U)
Optional HEX argument type.
#define SL_CLI_ARG_ADDITIONAL (0x20U)
ADDITIONAL argument type.
#define SL_CLI_ARG_WILDCARD (0x21U)
WILDCARD argument type.
#define SL_CLI_ARG_GROUP (0xFEU)
GROUP argument type.
#define SL_CLI_ARG_END (0xFFU)
END argument type.
#define sl_cli_get_argument_count (a)   ((int)(a->argc - a->arg_ofs))
Obtain the number of command arguments.
#define sl_cli_get_argument_type (a, n)   ((sl_cli_arg_t)(a->arg_type_list[n]))
Obtain the type of argument.
#define sl_cli_get_argument_int8 (a, n)   (*(int8_t *)(a->argv[a->arg_ofs + n]))
Obtain int8 arguments.
#define sl_cli_get_argument_int16 (a, n)   (*(int16_t *)(a->argv[a->arg_ofs + n]))
Obtain int16 arguments.
#define sl_cli_get_argument_int32 (a, n)   (*(int32_t *)(a->argv[a->arg_ofs + n]))
Obtain int32 arguments.
#define sl_cli_get_argument_uint8 (a, n)   (*(uint8_t *)(a->argv[a->arg_ofs + n]))
Obtain uint8 arguments.
#define sl_cli_get_argument_uint16 (a, n)   (*(uint16_t *)(a->argv[a->arg_ofs + n]))
Obtain uint16 arguments.
#define sl_cli_get_argument_uint32 (a, n)   (*(uint32_t *)(a->argv[a->arg_ofs + n]))
Obtain uint32 arguments.
#define sl_cli_get_argument_string (a, n)   ((char *)(a->argv[a->arg_ofs + n]))
Obtain string arguments.
#define sl_cli_get_command_count (a)   ((int)(a->arg_ofs))
Obtain the number of command strings.
#define sl_cli_get_command_string (a, n)   ((char *)(a->argv[n]))
Obtain the command string(s).
#define SL_CLI_COMMAND (function, help_text, arg_help, ...)
A macro, which is used to create commands.
#define SL_CLI_COMMAND_GROUP (group_table, help_text)
A macro, which is used to create command groups.
#define SL_CLI_INPUT_DIRECTION_UP (1)
MACROS ************************************.
#define SL_CLI_INPUT_DIRECTION_DOWN (-1)
Define the DOWN-direction.

Enumerations

enum sl_cli_arg {
sl_cli_arg_uint8 = SL_CLI_ARG_UINT8,
sl_cli_arg_uint16 = SL_CLI_ARG_UINT16,
sl_cli_arg_uint32 = SL_CLI_ARG_UINT32,
sl_cli_arg_int8 = SL_CLI_ARG_INT8,
sl_cli_arg_int16 = SL_CLI_ARG_INT16,
sl_cli_arg_int32 = SL_CLI_ARG_INT32,
sl_cli_arg_string = SL_CLI_ARG_STRING,
sl_cli_arg_hex = SL_CLI_ARG_HEX,
sl_cli_arg_uint8opt = SL_CLI_ARG_UINT8OPT,
sl_cli_arg_uint16opt = SL_CLI_ARG_UINT16OPT,
sl_cli_arg_uint32opt = SL_CLI_ARG_UINT32OPT,
sl_cli_arg_int8opt = SL_CLI_ARG_INT8OPT,
sl_cli_arg_int16opt = SL_CLI_ARG_INT16OPT,
sl_cli_arg_int32opt = SL_CLI_ARG_INT32OPT,
sl_cli_arg_stringopt = SL_CLI_ARG_STRINGOPT,
sl_cli_arg_hexopt = SL_CLI_ARG_HEXOPT,
sl_cli_arg_additionnal = SL_CLI_ARG_ADDITIONAL,
sl_cli_arg_wildcard = SL_CLI_ARG_WILDCARD,
sl_cli_arg_group = SL_CLI_ARG_GROUP,
sl_cli_arg_end = SL_CLI_ARG_END
}
Enum of all the argument types.

Variables

sl_cli_handle_t sl_cli_default_handle
The default CLI handle.
sl_cli_command_group_t * sl_cli_default_command_group
The default CLI command group.

Function Documentation

◆ sl_cli_tokenize()

sl_status_t sl_cli_tokenize ( char input[],
int * token_c,
char * token_v[]
)

Split a C-string on space, ignoring sections in {} or "".

Note
This function modifies the content of the input string, and points the pointers in tokens to addresses in the input string. In quote strings ("") or curly braces ({}), the string will not be split, The quotes will be removed, but curly braces are kept for validation. To avoid '"' being interpreted as start/end of quote string, it may be escaped using '\"', both within and outside of "...". '{' may be escaped using * '\{'. There is no need for escaping '}', since only hex digits are allowed within {...}. Backslash also needs be be escaped, as '\'.
Parameters
[in,out] input The C-string to be split. Must be '\0'-terminated. Will be modified, even if an error occurs.
[out] token_c The number of tokens put in the token_v array.
[out] token_v An array containing the tokens obtained from splitting.
Returns
Status of the operation.

◆ sl_cli_get_argument_hex()

uint8_t* sl_cli_get_argument_hex ( sl_cli_command_arg_t * a,
size_t n,
size_t * l
)

Get the hex argument length and value.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is number 0, the next 1, etc.
[in] l A pointer to the variable that receives the argument value length. Note: The length is stored in a 2 byte variable. Valid lengths are in the range 0 .. 65535.
Returns
A pointer to the value buffer.

◆ sl_cli_clear()

void sl_cli_clear ( sl_cli_handle_t handle )

Clear (reset) a CLI.

Parameters
[in] handle A handle to the CLI that will be cleared.

◆ sl_cli_redirect_command()

void sl_cli_redirect_command ( sl_cli_handle_t handle,
sl_cli_command_function_t command_function,
const char * prompt,
void * aux
)

Redirect user input.

Normally, an input string is passed to the CLI command handler for execution, but with the redirect function the input string will be passed to the alternative function. If the alternative input function should not to be used, this function can be called with NULL in the command_function, prompt and aux.

Parameters
[in] handle A handle to the CLI.
[in] command_function A pointer to the function that will receive user input when the re-direct is active. NULL to stop the redirect.
[in] prompt A pointer to a string that will be used as command prompt in the redirect function. NULL to stop the redirect.
[in] aux A pointer that will be added to the redirect function arguments. NULL to stop the redirect.

◆ sl_cli_handle_input()

sl_status_t sl_cli_handle_input ( sl_cli_handle_t handle,
char * string
)

Handle input.

Execute a complete command line with command and arguments.

Parameters
[in] handle A handle to the CLI.
[in] string A pointer to the string containing the command line that shall be executed.
Returns
Execution status. Note: If the command is redirected, the function will always return SL_STATUS_OK.

◆ sl_cli_instance_init()

sl_status_t sl_cli_instance_init ( sl_cli_handle_t handle,
sl_cli_instance_parameters_t * parameters
)

Initialize a CLI instance.

Parameters
[in] handle A handle to the CLI.
[in] parameters A pointer to the structure containing instance parameters.
Returns
Initialization status.

◆ sl_cli_is_ok_to_sleep()

bool sl_cli_is_ok_to_sleep ( sl_cli_handle_t handle )

Check if the CLI instance can allow sleep.

This function is available in a bare metal configuration only.

Parameters
[in] handle A handle to the CLI instance.
Returns
A boolean that is true if the CLI allows sleep, else false.

◆ sl_cli_tick_instance()

void sl_cli_tick_instance ( sl_cli_handle_t handle )

The bare metal tick function.

Parameters
[in] handle A handle to the CLI instance.

◆ sl_cli_command_add_command_group()

bool sl_cli_command_add_command_group ( sl_cli_handle_t handle,
sl_cli_command_group_t * command_group
)

Add a new command group.

Parameters
[in,out] handle A handle to a CLI instance.
[in] command_group A pointer to a command group structure. Note that the structure must initially have NULL in all elements except the command_table.
Returns
Returns true if the command_group could be added, false otherwise.

◆ sl_cli_command_remove_command_group()

bool sl_cli_command_remove_command_group ( sl_cli_handle_t handle,
sl_cli_command_group_t * command_group
)

Remove a command group.

Parameters
[in,out] handle A handle to a CLI instance.
[in] command_group A pointer to a command group structure.
Returns
Returns true if the command_group could be removed, false otherwise.

◆ sl_cli_command_find()

const sl_cli_command_entry_t * sl_cli_command_find ( sl_cli_handle_t handle,
int * token_c,
char * token_v[],
int * arg_ofs,
bool * single_flag,
bool * help_flag
)

Find a command given the command groups and input arguments.

Parameters
[in,out] handle A handle to a CLI instance.
[in] token_c A number of arguments given.
[in] token_v An array containing the token_v obtained from tokenization.
[out] arg_ofs An integer that will get the index to the first command argument. Whether the command is in a group or not will affect the arg_ofs value.
[out] single_flag Boolean that is set to true if a specific command is detected. For help, the function may return a pointer to a command entry table or NULL, and in these cases the single_flag is set to false.
[out] help_flag Boolean that is set to true if "help" is detected, else set to false.
Returns
A pointer to a command entry for the given command. If the command is not found, the returned value can be NULL. If a help command is issued, the returned value may point to a command entry table.

◆ sl_cli_command_execute()

sl_status_t sl_cli_command_execute ( sl_cli_handle_t handle,
char * input
)

Find and execute a command given the string input and the command table.

Note
The input string will be modified in-place.
Parameters
[in,out] handle A handle to a CLI instance.
[in,out] input C-string containing the user input. Must be '\0'-terminated.
Returns
Status of the execution.

◆ sl_cli_input_char()

bool sl_cli_input_char ( sl_cli_handle_t handle,
char c
)

Handle new input char from the terminal, both in terms of writing back to terminal and writing to the input buffer.

This function should be called every time new input is detected. The behavior of the function is highly configurable through settings in cli_config.h.

Parameters
[in,out] handle A handle to a CLI instance.
[in] c Input char to be processed by the function.
Returns
Returns true if newline or return is detected, false otherwise.

◆ sl_cli_input_clear()

void sl_cli_input_clear ( sl_cli_handle_t handle )

Empty the input buffer.

This function should be called after newline has been detected and the information in the buffer has been processed.

Parameters
[in,out] handle A handle to a CLI instance.

Macro Definition Documentation

◆ SL_CLI_ARG_UINT8

#define SL_CLI_ARG_UINT8   (0x00U)

UINT8 argument type.

◆ SL_CLI_ARG_UINT16

#define SL_CLI_ARG_UINT16   (0x01U)

UINT16 argument type.

◆ SL_CLI_ARG_UINT32

#define SL_CLI_ARG_UINT32   (0x02U)

UINT32 argument type.

◆ SL_CLI_ARG_INT8

#define SL_CLI_ARG_INT8   (0x03U)

INT8 argument type.

◆ SL_CLI_ARG_INT16

#define SL_CLI_ARG_INT16   (0x04U)

INT16 argument type.

◆ SL_CLI_ARG_INT32

#define SL_CLI_ARG_INT32   (0x05U)

INT32 argument type.

◆ SL_CLI_ARG_STRING

#define SL_CLI_ARG_STRING   (0x06U)

STRING argument type.

◆ SL_CLI_ARG_HEX

#define SL_CLI_ARG_HEX   (0x07U)

HEX argument type.

◆ SL_CLI_ARG_UINT8OPT

#define SL_CLI_ARG_UINT8OPT   (0x10U)

Optional UINT8 argument type.

◆ SL_CLI_ARG_UINT16OPT

#define SL_CLI_ARG_UINT16OPT   (0x11U)

Optional UINT16 argument type.

◆ SL_CLI_ARG_UINT32OPT

#define SL_CLI_ARG_UINT32OPT   (0x12U)

Optional UINT32 argument type.

◆ SL_CLI_ARG_INT8OPT

#define SL_CLI_ARG_INT8OPT   (0x13U)

Optional INT8 argument type.

◆ SL_CLI_ARG_INT16OPT

#define SL_CLI_ARG_INT16OPT   (0x14U)

Optional INT16 argument type.

◆ SL_CLI_ARG_INT32OPT

#define SL_CLI_ARG_INT32OPT   (0x15U)

Optional INT32 argument type.

◆ SL_CLI_ARG_STRINGOPT

#define SL_CLI_ARG_STRINGOPT   (0x16U)

Optional STRING argument type.

◆ SL_CLI_ARG_HEXOPT

#define SL_CLI_ARG_HEXOPT   (0x17U)

Optional HEX argument type.

◆ SL_CLI_ARG_ADDITIONAL

#define SL_CLI_ARG_ADDITIONAL   (0x20U)

ADDITIONAL argument type.

◆ SL_CLI_ARG_WILDCARD

#define SL_CLI_ARG_WILDCARD   (0x21U)

WILDCARD argument type.

◆ SL_CLI_ARG_GROUP

#define SL_CLI_ARG_GROUP   (0xFEU)

GROUP argument type.

◆ SL_CLI_ARG_END

#define SL_CLI_ARG_END   (0xFFU)

END argument type.

◆ sl_cli_get_argument_count

#define sl_cli_get_argument_count ( a ) ((int)(a->argc - a->arg_ofs))

Obtain the number of command arguments.

Users obtain the number of command arguments with this macro.

Parameters
[in] a A pointer to the command arguments.
Returns
The number of command arguments.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the number of arguments (after the command strings).
int arg_count = sl_cli_get_argument_count (args); // arg_count = 4
}

◆ sl_cli_get_argument_type

#define sl_cli_get_argument_type ( a,
n
) ((sl_cli_arg_t)(a->arg_type_list[n]))

Obtain the type of argument.

Users obtain the type of the argument with this macro.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
enum of the argument type.

For auto-generated commands, it could be useful in the handler to know the type of the argument.

◆ sl_cli_get_argument_int8

#define sl_cli_get_argument_int8 ( a,
n
) (*(int8_t *)(a->argv[a->arg_ofs + n]))

Obtain int8 arguments.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
The argument value.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the arguments (after the command strings).
char *text_ptr = sl_cli_get_argument_string (args, 0); // char ptr to
// "hello"
uint8_t num1_u8 = sl_cli_get_argument_uint8 (args, 1); // num1_u8 = 255
int16_t num2_i16 = sl_cli_get_argument_int16 (args, 2); // num2_i16 = -100
size_t hex_array_size;
uint8_t *hex_array_ptr = sl_cli_get_argument_hex (args, 3, &hex_array_size);
// uint8_t ptr to {0xAA, 0xBB, 0xCC}, hex_array_size = 3
}

◆ sl_cli_get_argument_int16

#define sl_cli_get_argument_int16 ( a,
n
) (*(int16_t *)(a->argv[a->arg_ofs + n]))

Obtain int16 arguments.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
The argument value.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the arguments (after the command strings).
char *text_ptr = sl_cli_get_argument_string (args, 0); // char ptr to
// "hello"
uint8_t num1_u8 = sl_cli_get_argument_uint8 (args, 1); // num1_u8 = 255
int16_t num2_i16 = sl_cli_get_argument_int16 (args, 2); // num2_i16 = -100
size_t hex_array_size;
uint8_t *hex_array_ptr = sl_cli_get_argument_hex (args, 3, &hex_array_size);
// uint8_t ptr to {0xAA, 0xBB, 0xCC}, hex_array_size = 3
}

◆ sl_cli_get_argument_int32

#define sl_cli_get_argument_int32 ( a,
n
) (*(int32_t *)(a->argv[a->arg_ofs + n]))

Obtain int32 arguments.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
The argument value.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the arguments (after the command strings).
char *text_ptr = sl_cli_get_argument_string (args, 0); // char ptr to
// "hello"
uint8_t num1_u8 = sl_cli_get_argument_uint8 (args, 1); // num1_u8 = 255
int16_t num2_i16 = sl_cli_get_argument_int16 (args, 2); // num2_i16 = -100
size_t hex_array_size;
uint8_t *hex_array_ptr = sl_cli_get_argument_hex (args, 3, &hex_array_size);
// uint8_t ptr to {0xAA, 0xBB, 0xCC}, hex_array_size = 3
}

◆ sl_cli_get_argument_uint8

#define sl_cli_get_argument_uint8 ( a,
n
) (*(uint8_t *)(a->argv[a->arg_ofs + n]))

Obtain uint8 arguments.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
The argument value.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the arguments (after the command strings).
char *text_ptr = sl_cli_get_argument_string (args, 0); // char ptr to
// "hello"
uint8_t num1_u8 = sl_cli_get_argument_uint8 (args, 1); // num1_u8 = 255
int16_t num2_i16 = sl_cli_get_argument_int16 (args, 2); // num2_i16 = -100
size_t hex_array_size;
uint8_t *hex_array_ptr = sl_cli_get_argument_hex (args, 3, &hex_array_size);
// uint8_t ptr to {0xAA, 0xBB, 0xCC}, hex_array_size = 3
}

◆ sl_cli_get_argument_uint16

#define sl_cli_get_argument_uint16 ( a,
n
) (*(uint16_t *)(a->argv[a->arg_ofs + n]))

Obtain uint16 arguments.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
The argument value.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the arguments (after the command strings).
char *text_ptr = sl_cli_get_argument_string (args, 0); // char ptr to
// "hello"
uint8_t num1_u8 = sl_cli_get_argument_uint8 (args, 1); // num1_u8 = 255
int16_t num2_i16 = sl_cli_get_argument_int16 (args, 2); // num2_i16 = -100
size_t hex_array_size;
uint8_t *hex_array_ptr = sl_cli_get_argument_hex (args, 3, &hex_array_size);
// uint8_t ptr to {0xAA, 0xBB, 0xCC}, hex_array_size = 3
}

◆ sl_cli_get_argument_uint32

#define sl_cli_get_argument_uint32 ( a,
n
) (*(uint32_t *)(a->argv[a->arg_ofs + n]))

Obtain uint32 arguments.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
The argument value.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the arguments (after the command strings).
char *text_ptr = sl_cli_get_argument_string (args, 0); // char ptr to
// "hello"
uint8_t num1_u8 = sl_cli_get_argument_uint8 (args, 1); // num1_u8 = 255
int16_t num2_i16 = sl_cli_get_argument_int16 (args, 2); // num2_i16 = -100
size_t hex_array_size;
uint8_t *hex_array_ptr = sl_cli_get_argument_hex (args, 3, &hex_array_size);
// uint8_t ptr to {0xAA, 0xBB, 0xCC}, hex_array_size = 3
}

◆ sl_cli_get_argument_string

#define sl_cli_get_argument_string ( a,
n
) ((char *)(a->argv[a->arg_ofs + n]))

Obtain string arguments.

Parameters
[in] a A pointer to the command arguments.
[in] n The argument number. The first argument is the number 0, the next 1, etc.
Returns
The argument value. For hex arguments, the return value is a pointer to a buffer containing decoded values. For string arguments, the return value is a pointer to the string.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the arguments (after the command strings).
char *text_ptr = sl_cli_get_argument_string (args, 0); // char ptr to
// "hello"
uint8_t num1_u8 = sl_cli_get_argument_uint8 (args, 1); // num1_u8 = 255
int16_t num2_i16 = sl_cli_get_argument_int16 (args, 2); // num2_i16 = -100
size_t hex_array_size;
uint8_t *hex_array_ptr = sl_cli_get_argument_hex (args, 3, &hex_array_size);
// uint8_t ptr to {0xAA, 0xBB, 0xCC}, hex_array_size = 3
}

◆ sl_cli_get_command_count

#define sl_cli_get_command_count ( a ) ((int)(a->arg_ofs))

Obtain the number of command strings.

Users obtain the number of command strings with this macro.

Parameters
[in] a The number of command strings.
Returns
The number of command strings.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the number of command strings (before the arguments).
int cmd_count = sl_cli_get_command_count (args); // cmd_count = 2
// (first string being "example_sub_menu" and second "example_command")
}

◆ sl_cli_get_command_string

#define sl_cli_get_command_string ( a,
n
) ((char *)(a->argv[n]))

Obtain the command string(s).

Users get the command string with this macro. If the command is used in a group, both the group string(s) and command string can be obtained. The total number of command strings is available in the command argument arg_ofs variable.

Parameters
[in] a A pointer to the command arguments.
[in] n The command string number. The first string is number 0, the next 1, etc.

An example could be the CLI input of example_sub_menu example_command hello 255 -100 {AA BB CC} with corresponding C code of:

void example_command( sl_cli_command_arg_t *args)
{
// Get the command strings (before the arguments).
char *cmd1_ptr = sl_cli_get_command_string (args, 0); // char ptr to
// "example_sub_menu"
char *cmd2_ptr = sl_cli_get_command_string (args, 1); // char ptr to
// "example_command"
}

◆ SL_CLI_COMMAND

#define SL_CLI_COMMAND ( function,
help_text,
arg_help,
...
)
Value:
{ \
( function ), /* Pointer to command function */ \
__VA_ARGS__ /* Argument list*/ \
}

A macro, which is used to create commands.

◆ SL_CLI_COMMAND_GROUP

#define SL_CLI_COMMAND_GROUP ( group_table,
help_text
)
Value:
{ \
((sl_cli_command_func_t)(group_table)), /* Group pointer */ \
{ SL_CLI_ARG_GROUP , } /* Group indicator */ \
}

A macro, which is used to create command groups.

◆ SL_CLI_INPUT_DIRECTION_UP

#define SL_CLI_INPUT_DIRECTION_UP   (1)

MACROS ************************************.

Define the UP-direction.

◆ SL_CLI_INPUT_DIRECTION_DOWN

#define SL_CLI_INPUT_DIRECTION_DOWN   (-1)

Define the DOWN-direction.

Enumeration Type Documentation

◆ sl_cli_arg

enum sl_cli_arg

Enum of all the argument types.

Enumerator
sl_cli_arg_uint8

UINT8 argument type.

sl_cli_arg_uint16

UINT16 argument type.

sl_cli_arg_uint32

UINT32 argument type.

sl_cli_arg_int8

INT8 argument type.

sl_cli_arg_int16

INT16 argument type.

sl_cli_arg_int32

INT32 argument type.

sl_cli_arg_string

STRING argument type.

sl_cli_arg_hex

HEX argument type.

sl_cli_arg_uint8opt

Optional UINT8 argument type.

sl_cli_arg_uint16opt

Optional UINT16 argument type.

sl_cli_arg_uint32opt

Optional UINT32 argument type.

sl_cli_arg_int8opt

Optional INT8 argument type.

sl_cli_arg_int16opt

Optional INT16 argument type.

sl_cli_arg_int32opt

Optional INT32 argument type.

sl_cli_arg_stringopt

Optional STRING argument type.

sl_cli_arg_hexopt

Optional HEX argument type.

sl_cli_arg_additionnal

ADDITIONAL argument type.

sl_cli_arg_wildcard

WILDCARD argument type.

sl_cli_arg_group

GROUP argument type.

sl_cli_arg_end

END argument type.

Variable Documentation

◆ sl_cli_default_handle

sl_cli_handle_t sl_cli_default_handle

The default CLI handle.

◆ sl_cli_default_command_group

sl_cli_command_group_t * sl_cli_default_command_group

The default CLI command group.