nRF5 SDK v15.2.0
Command Line Interface library

This module allows to create and handle a command line interface (CLI) with a user-defined command set. You can use it in examples where more than button/LED user interaction is required. This module can be considered a Unix-like command line interface with these features:

The module can be connected to any transport. At this point, the following transport layers are implemented:

For API documentation of this library, refer to Command Line Interface.

Usage

Use the NRF_CLI_DEF macro to create an instance of the CLI. It is important to pass correct newline character to this macro, otherwise the CLI will not respond correctly to the Enter button.

Settings for PuTTY
Transport
Newline character
Bluetooth
'\n'
USB CDC ACM
'\r'
UART
'\r'
RTT
'\n'


The following code shows a simple use case of this library:

/* Creating subcommands (level 2 command) array for command "counter start".
Subcommands must be added in alphabetical order */
{
NRF_CLI_CMD(with_delay_ms, NULL, "help string", cmd_counter_start_delay_ms),
NRF_CLI_CMD(with_delay_s, NULL, "help string", cmd_counter_start_delay_s),
NRF_CLI_CMD(with_delay_us, NULL, "help string", cmd_counter_start_delay_us),
};
/* Creating subcommands (level 1 command) array for command "counter".
Subcommands must be added in alphabetical order */
{
NRF_CLI_CMD(reset, NULL, "help string", cmd_counter_reset),
NRF_CLI_CMD(start, &m_sub_counter_start, "help string", cmd_counter_start),
NRF_CLI_CMD(stop, NULL, "help string", cmd_counter_stop),
};
/* Creating root (level 0) command "counter" */
NRF_CLI_CMD_REGISTER(counter, &m_sub_counter, "display counter on terminal screen", cmd_counter);
NRF_CLI_RTT_DEF(m_cli_rtt_transport);
NRF_CLI_DEF(m_cli_rtt, "rtt_cli:~$ ", &m_cli_rtt_transport.transport, '\n', 4);
int main(void)
{
/* CLI configured as NRF_LOG backend */
ret = nrf_cli_init(&m_cli_rtt, NULL, true, true, NRF_LOG_SEVERITY_INFO);
ret_code_t ret = nrf_cli_start(&m_cli_rtt);
/* Below text will be printed on the CLI */
NRF_LOG_RAW_INFO("Hello word.\r\n");
while (true)
{
nrf_cli_process(&m_cli_rtt);
}
}

Users may use the Tab key to complete a command/subcommand or to see the available subcommands for the currently entered command level. For example, when the cursor is positioned at the beginning of the command line and the Tab key is pressed, the user will see all root (level 0) commands:

clear cli counter history log resize
Note
To view the subcommands that are available for a specific command, you must first type a space after this command and then hit Tab.

These commands are registered by various modules:

Then, if a user types a counter command and presses the Tab key, the console will only print the subcommands registered for this command:

reset start stop
Note
When using the CLI module along with the Logger module, make sure that another backend using the same physical transport is disabled (e.g. NRF_LOG_BACKEND_UART_ENABLED if CLI over UART is used), or not initialized Raw backends are enabled in NRF_LOG_DEFAULT_BACKENDS_INIT.

Commands

CLI commands are organized in a tree structure and grouped into the following types:

Creating commands

Use the following macros for adding CLI commands:

Commands execution

Each command or subcommand on each level can either have or not have a handler. The CLI executes the handler that is found deepest in the command tree and further subcommands (without a handler) are passed as arguments. Characters within parentheses are treated as one argument. Each command or subcommand without a handler can be treated as an argument, or it can still have a subcommand with a handler and there is no problem for the user to execute it.

Built-in commands

Commands help

Every user-defined command, subcommand, or option can have its own help description. The help for commands and subcommands can be created with respective macros: NRF_CLI_CMD_REGISTER, NRF_CLI_CMD. In addition, you can define options for commands or subcommands using the macro NRF_CLI_OPT. By default, each and every command or subcommand has these two options implemented: "-h" and "--help".

In order to add help functionality to a command or subcommand, you must implement the help handler nrf_cli_help_print inside of a function.

The following code is an example of how commands can be processed:

static void cmd_counter(nrf_cli_t const * p_cli, size_t argc, char **argv)
{
ASSERT(p_cli);
ASSERT(p_cli->p_ctx && p_cli->p_iface && p_cli->p_name);
/* Extra defined dummy option */
static nrf_cli_getopt_option_t const opt[] = {
"--test",
"-t",
"dummy option help string"
)
};
/* Printing help if needed */
if ((argc == 1) || nrf_cli_help_requested(p_cli))
{
nrf_cli_help_print(p_cli, opt, ARRAY_SIZE(opt));
return;
}
/* Expected command length for this handler, for example: counter -t or counter --test */
if (argc != 2)
{
nrf_cli_fprintf(p_cli, NRF_CLI_ERROR, "%s: bad parameter count\r\n", argv[0]);
return;
}
/* Options must be handled with strcmp function */
if (!strcmp(argv[1], "-t") || !strcmp(argv[1], "--test"))
{
nrf_cli_fprintf(p_cli, NRF_CLI_NORMAL, "Dummy test option.\r\n");
return;
}
/* subcommands have their own handlers and they are not processed here */
nrf_cli_fprintf(p_cli, NRF_CLI_ERROR, "%s: unknown parameter: %s\r\n", argv[0], argv[1]);
}

It is recommended to use subcommands. Options apply mainly in the case when an argument with '-' or "--" is requested. The main benefit of using subcommands is that they can be prompted or completed with the Tab key. In addition, subcommands can have their own handler, which limits the usage of "if - else if" statements combination with the strcmp function.

Warning
Do not use function nrf_cli_fprintf outside of the command handler because this might lead to incorrect text display on the console. If any text should be displayed outside of the command context, then use the Logger module.

Wildcards

The CLI module can handle wildcards. This option can be activated in the sdk_config.h file by setting option NRF_CLI_WILDCARD_ENABLED.

Wildcards are interpreted correctly if they are used in commands without handlers. What is more, when commands are run with wildcards, going deeper in the command tree is not possible.

For example, if you want to set logging level to 'error' for the app module and all queue and balloc instances, you can execute the following command:

log enable error queue* balloc* app
lib_cli_wildcards.PNG
Wildcard example
Note
It is important to ensure that the command buffer is large enough to store all expanded commands.

Meta keys

The CLI module supports the following meta keys:

Implemented meta keys
Meta key
Action
ctrl + a Moves the cursor to the beginning of the line.
ctrl + c Preserves the last command on the screen and starts a new command in a new line.
ctrl + e Moves the cursor to the end of the line.
ctrl + l Clears the screen and leaves the currently typed command at the top of the screen.
ctrl + u Clears the currently typed command.
ctrl + w Removes the word or part of the word to the left of the cursor.
Words separated by period instead of space are treated as one word.

Terminal settings

A strongly recommended terminal to use with the CLI module is PuTTY. It can be easily configured to send escape codes interpreted by the console. If other terminal is used, configure it according to the following PuTTY settings. See the below figures.

lib_cli_putty_cfg1.PNG
Mandatory PuTTY settings
lib_cli_putty_cfg2.PNG
Window size settings

If window width is set to a value different than 80, the user must execute the resize command to ensure correct text display.

UART and USB settings

Apply these settings when using UART or USB as the transport layer for the CLI module.

lib_cli_putty_uart_cfg_1.PNG
Serial settings
lib_cli_putty_uart_cfg_2.PNG
Terminal settings

RTT settings

Apply these settings when using RTT as the transport layer for the CLI module.

lib_cli_putty_rtt_cfg_1.PNG
Connection settings
lib_cli_putty_rtt_cfg_2.PNG
Terminal settings
Warning
Do not use J-Link Viewer to start an RTT session because PuTTY will not display characters correctly.

When debugging under Segger Embedded Studio with RTT configured as CLI transport, some characters might be directed to Segger Debug Window, instead of to PuTTY. To solve this problem, you need to deactivate RTT in SES:
Project settings->Debug->Debugger->RTT Enable-> Set to No.

Do not use the SES debug window to operate the console, because it significantly limits CLI capability. Use PuTTY or a similar terminal instead.

Usage examples

For usage examples of this library, see: Experimental: ATT_MTU Throughput Example, Experimental: Console over Bluetooth Application, Command Line Interface (CLI) Example, Capacitive Sensor Low-level Example, Flash Write Example, and TWIS Slave and TWI Master Mode Drivers Example.


Documentation feedback | Developer Zone | Subscribe | Updated