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 calling 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 superset 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 explain some of the CLI features.

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

Command Groups#

The CLI supports both stand alone commands and commands that belong to groups. A stand alone command is executed by typing the command name and arguments. If a command belongs 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 are stored in the history buffer when executed. Previous commands can be executed again by pressing the up-arrow key one or more times.

Note: The history buffer is a simple character array, which does not define how many command lines can be stored. The history buffer stores 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 argc, 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.

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, which holds the argument values.

The arguments struct has the following definition:

typedef struct {
  struct sl_cli *handle;        ///< The current CLI handle.
  int argc;                     ///< The total number of input strings (command group names, if any + command + corresponding arguments).
  void **argv;                  ///< A pointer to the input string array.
  int arg_ofs;                  ///< The offset in the input string array where the arguments start (after the command group names, if any and command).
} 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 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 using 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;

Note: Each time a command group is 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". Typically one array element exists 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;        ///< String associated with command/group
  const sl_cli_command_info_t *command;     ///< Pointer to command information
  const bool                  is_shortcut;  ///< Indicating if the entry is a shortcut
} sl_cli_command_entry_t;

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

Finally, "command information" for commands is defined in one data structure for each command. The "command information" structure is defined with the following type:

typedef struct {
  sl_cli_command_func_t function;             ///< Command function
    #if SL_CLI_HELP_DESCRIPTION_ENABLED
  char                   *help;               ///< Info displayed by "help" command
  char                   *arg_help;           ///< Info for arguments.
    #endif // SL_CLI_HELP_DESCRIPTION_ENABLED
  sl_cli_argument_type_t arg_type_list[];     ///< List of argument types
} 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, where all command handlers have the same signature. The command handler function prototype has the following definition:

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. The differences between the two configurations are 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 calls the CLI process-action function.

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 polls the iostream for input data. One task is created for each CLI instance. 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 demonstrate how to create and install a CLI command.

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

Define and implement CLI commands:

#include "sl_cli.h"

// 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 three elements in this example
static sl_cli_command_entry_t a_table[] = {
  { "echo_str", &cmd__echostr, false },
  { "echo_int", &cmd__echoint, false },
  { "echo_intstr",  &cmd__echointstr, false },
  { NULL, NULL, false },
};

// Create command details for the commands. The macro SL_CLI_UNIT_SEPARATOR can be
// used to format the help text for multiple arguments.
static const sl_cli_command_info_t cmd__echostr = \
  SL_CLI_COMMAND(echo_str,
                 "echoes string arguments to the output",
                 "Just a string...",
                 {SL_CLI_ARG_WILDCARD, SL_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...",
                 {SL_CLI_ARG_INT8, SL_CLI_ARG_ADDITIONAL, SL_CLI_ARG_END, });

static const sl_cli_command_info_t cmd__echointstr = \
  SL_CLI_COMMAND(echo_intstr,
                 "echoes integer and string arguments to the output",
                 "Just a number..." SL_CLI_UNIT_SEPARATOR
                 "Just a string..."
                 {SL_CLI_ARG_INT8, SL_CLI_ARG_STRING, SL_CLI_ARG_END, });

// Create command handlers for the 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);
    ...
  }
}

void echo_intstr(sl_cli_command_arg_t *arguments)
{
  int8_t argument_value;
  char *ptr_string;

  argument_value = sl_cli_get_argument_int8(arguments, 0);
  ptr_string = sl_cli_get_argument_string(arguments, 1);
  ...
}

// 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
  echo_str                      echoes string arguments to the output
                                [*] Just a string...
  echo_int                      echoes integer arguments to the output
                                [int8+] Just a number...
  echo_intstr                   echoes integer and string arguments to the output
                                [int8] Just a number...
                                [string] Just a string...

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 integrate with the CLI. Most of the components however do not define the command name. Instead, it must be defined by the application implementer.

Note: The CLI extensions described here 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.

Simple Password Protection#

The cli_simple_password component has been designed to provide functionalities to limit access to the CLI interface. It asks to configure a password at first startup and requires the configured password at the next access. It also includes security mechanisms to limit the number of attempts with invalid passwords. In other words, access is locked when the maximum number of retries is reached. If the retry limit is reached, a Security flag is raised and will be displayed on the login page until cleared. Depending on the device used, the key and the encrypted password are stored in the Secure Element or with NVM3.

The cli_simple_password component defines the following user commands and their associated handlers.

sl_status_t sl_cli_simple_password_logout(sl_cli_handle_t handle);
sl_status_t sl_cli_set_simple_password(char *new_password);
sl_status_t sl_cli_simple_password_destroy_key(void);
sl_status_t sl_cli_reset_security_warning_flag(void);

cli logout
cli set_password <current_password> <new_password> <new_password_confirmation>
cli destroy_key
cli reset_security_flag

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. However, 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, get the number of command lines stored in NVM3 storage by calling the following function:

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 a range with 256 keys.

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

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. However, 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, 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.

Delay#

The cli_delay component may be useful to add delays between commands when running command sequences from 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);