nRF5 SDK v15.0.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Command Line Interface

Module for unified command line handling. More...

Modules

 BLE UART command line interface transport layer
 
 CDC ACM command line interface transport layer
 
 Command line interface configuration
 
 libUARTE command line interface transport layer.
 
 RTT command line interface transport layer
 
 UART command line interface transport layer
 

Data Structures

struct  nrf_cli_cmd_entry
 CLI command descriptor. More...
 
struct  nrf_cli_static_entry
 CLI static command descriptor. More...
 
struct  nrf_cli_transport_api_t
 Unified CLI transport interface. More...
 
struct  nrf_cli_transport_s
 
struct  nrf_cli_flag_t
 
union  nrf_cli_internal_t
 
struct  nrf_cli_ctx_t
 CLI instance context. More...
 
struct  nrf_cli_log_backend_t
 
struct  nrf_cli
 CLI instance internals. More...
 
struct  nrf_cli_getopt_option
 Option descriptor. More...
 

Macros

#define NRF_CLI_CMD_REGISTER(p_syntax, p_subcmd, p_help, p_handler)
 Macro for defining and adding a root command (level 0). More...
 
#define NRF_CLI_CREATE_STATIC_SUBCMD_SET(name)
 Macro for creating a subcommand set. It must be used outside of any function body. More...
 
#define NRF_CLI_SUBCMD_SET_END   {NULL}
 Define ending subcommands set.
 
#define NRF_CLI_CREATE_DYNAMIC_CMD(name, p_get)
 Macro for creating a dynamic entry. More...
 
#define NRF_CLI_CMD(_p_syntax, _p_subcmd, _p_help, _p_handler)
 Initializes a CLI command (nrf_cli_static_entry). More...
 
#define NRF_LOG_BACKEND_CLI_DEF(_name_, _queue_sz_)
 
#define NRF_CLI_BACKEND_PTR(_name_)   NULL
 
#define NRF_CLI_MEMOBJ_PTR(_name_)   NULL
 
#define NRF_CLI_HISTORY_MEM_OBJ(name)
 
#define NRF_CLI_DEF(name, cli_prefix, p_transport_iface, newline_ch, log_queue_size)
 Macro for defining a command line interface instance. More...
 
#define NRF_CLI_DEFAULT   NRF_CLI_VT100_COLOR_DEFAULT
 CLI colors for nrf_cli_fprintf function. More...
 
#define NRF_CLI_NORMAL   NRF_CLI_VT100_COLOR_WHITE
 
#define NRF_CLI_INFO   NRF_CLI_VT100_COLOR_GREEN
 
#define NRF_CLI_OPTION   NRF_CLI_VT100_COLOR_CYAN
 
#define NRF_CLI_WARNING   NRF_CLI_VT100_COLOR_YELLOW
 
#define NRF_CLI_ERROR   NRF_CLI_VT100_COLOR_RED
 
#define NRF_CLI_OPT(_p_optname, _p_shortname, _p_help)
 Option structure initializer nrf_cli_getopt_option. More...
 

Typedefs

typedef struct nrf_cli nrf_cli_t
 Aliases to: Command Line Interface, nrf_cli_cmd_entry, and nrf_cli_static_entry. Must be created here to satisfy module declaration order dependencies.
 
typedef struct nrf_cli_cmd_entry nrf_cli_cmd_entry_t
 
typedef struct nrf_cli_static_entry nrf_cli_static_entry_t
 
typedef void(* nrf_cli_dynamic_get )(size_t idx, nrf_cli_static_entry_t *p_static)
 CLI dynamic command descriptor. More...
 
typedef void(* nrf_cli_cmd_handler )(nrf_cli_t const *p_cli, size_t argc, char **argv)
 CLI command handler prototype.
 
typedef void(* nrf_cli_transport_handler_t )(nrf_cli_transport_evt_t evt_type, void *p_context)
 
typedef struct nrf_cli_transport_s nrf_cli_transport_t
 
typedef struct
nrf_cli_getopt_option 
nrf_cli_getopt_option_t
 Option descriptor.
 

Enumerations

enum  nrf_cli_receive_t {
  NRF_CLI_RECEIVE_DEFAULT,
  NRF_CLI_RECEIVE_ESC,
  NRF_CLI_RECEIVE_ESC_SEQ
}
 
enum  nrf_cli_state_t {
  NRF_CLI_STATE_UNINITIALIZED,
  NRF_CLI_STATE_INITIALIZED,
  NRF_CLI_STATE_ACTIVE,
  NRF_CLI_STATE_PANIC_MODE_ACTIVE,
  NRF_CLI_STATE_PANIC_MODE_INACTIVE
}
 
enum  nrf_cli_transport_evt_t {
  NRF_CLI_TRANSPORT_EVT_RX_RDY,
  NRF_CLI_TRANSPORT_EVT_TX_RDY
}
 Event type from CLI transport.
 

Functions

 STATIC_ASSERT (sizeof(nrf_cli_flag_t)==sizeof(uint32_t))
 
ret_code_t nrf_cli_init (nrf_cli_t const *p_cli, void const *p_transport_config, bool use_colors, bool log_backend, nrf_log_severity_t init_lvl)
 Function for initializing a transport layer and internal CLI state. More...
 
ret_code_t nrf_cli_task_create (nrf_cli_t const *p_cli)
 
ret_code_t nrf_cli_uninit (nrf_cli_t const *p_cli)
 Function for uninitializing a transport layer and internal CLI state. If function returns NRF_ERROR_BUSY, you must call nrf_cli_process before calling nrf_cli_uninit again. More...
 
ret_code_t nrf_cli_start (nrf_cli_t const *p_cli)
 Function for starting CLI processing. More...
 
ret_code_t nrf_cli_stop (nrf_cli_t const *p_cli)
 Function for stopping CLI processing. More...
 
void nrf_cli_fprintf (nrf_cli_t const *p_cli, nrf_cli_vt100_color_t color, char const *p_fmt,...)
 Printf-like function which sends formatted data stream to the CLI. This function shall not be used outside of the CLI module or CLI command context. More...
 
void nrf_cli_process (nrf_cli_t const *p_cli)
 Process function, which should be executed when data is ready in the transport interface. More...
 
__STATIC_INLINE bool nrf_cli_help_requested (nrf_cli_t const *p_cli)
 Informs that a command has been called with -h or –help option. More...
 
void nrf_cli_help_print (nrf_cli_t const *p_cli, nrf_cli_getopt_option_t const *p_opt, size_t opt_len)
 Prints the current command help. More...
 
void nrf_cli_print_stream (void const *p_user_ctx, char const *p_data, size_t data_len)
 

Variables

const nrf_log_backend_api_t nrf_log_backend_cli_api
 

Detailed Description

Module for unified command line handling.

Macro Definition Documentation

#define NRF_CLI_CMD (   _p_syntax,
  _p_subcmd,
  _p_help,
  _p_handler 
)
Value:
{ \
.p_syntax = (const char *) STRINGIFY(_p_syntax), \
.p_subcmd = _p_subcmd, \
.p_help = (const char *) _p_help, \
.handler = _p_handler \
}

Initializes a CLI command (nrf_cli_static_entry).

Parameters
[in]_p_syntaxCommand syntax (for example: history).
[in]_p_subcmdPointer to a subcommands array.
[in]_p_helpPointer to a command help string.
[in]_p_handlerPointer to a function handler.
#define NRF_CLI_CMD_REGISTER (   p_syntax,
  p_subcmd,
  p_help,
  p_handler 
)
Value:
nrf_cli_static_entry_t const CONCAT_3(nrf_cli_, p_syntax, _raw) = \
NRF_CLI_CMD(p_syntax, p_subcmd, p_help, p_handler); \
NRF_SECTION_ITEM_REGISTER(cli_command, \
nrf_cli_cmd_entry_t const CONCAT_3(nrf_cli_, p_syntax, _const)) = { \
.is_dynamic = false, \
.u.p_static = &CONCAT_3(nrf_cli_, p_syntax, _raw) \
}; \
NRF_SECTION_ITEM_REGISTER(cli_sorted_cmd_ptrs, char const * CONCAT_2(p_syntax, _str_ptr))

Macro for defining and adding a root command (level 0).

Note
Each root command shall have unique syntax.
Parameters
[in]p_syntaxCommand syntax (for example: history).
[in]p_subcmdPointer to a subcommands array.
[in]p_helpPointer to a command help string.
[in]p_handlerPointer to a function handler.
#define NRF_CLI_CREATE_DYNAMIC_CMD (   name,
  p_get 
)
Value:
/*lint -save -e19*/ \
static nrf_cli_cmd_entry_t const name = { \
.is_dynamic = true, \
.u.p_dynamic_get = p_get \
}; /*lint -restore*/

Macro for creating a dynamic entry.

Parameters
[in]nameName of the dynamic entry.
[in]p_getPointer to the function returning dynamic commands array nrf_cli_dynamic_get.
#define NRF_CLI_CREATE_STATIC_SUBCMD_SET (   name)
Value:
/*lint -save -e85 -e31*/ \
static nrf_cli_static_entry_t const CONCAT_2(name, _raw)[]; \
static nrf_cli_cmd_entry_t const name = { \
.is_dynamic = false, \
.u.p_static = CONCAT_2(name, _raw) \
}; \
static nrf_cli_static_entry_t const CONCAT_2(name, _raw)[] = /*lint -restore*/

Macro for creating a subcommand set. It must be used outside of any function body.

Parameters
[in]nameName of the subcommand set.
#define NRF_CLI_DEF (   name,
  cli_prefix,
  p_transport_iface,
  newline_ch,
  log_queue_size 
)
Value:
static nrf_cli_t const name; \
static nrf_cli_ctx_t CONCAT_2(name, _ctx); \
NRF_FPRINTF_DEF(CONCAT_2(name, _fprintf_ctx), \
&name, \
CONCAT_2(name, _ctx).printf_buff, \
false, \
nrf_cli_print_stream); \
NRF_LOG_BACKEND_CLI_DEF(CONCAT_2(name, _log_backend), log_queue_size); \
NRF_CLI_HISTORY_MEM_OBJ(name); \
/*lint -save -e31*/ \
static nrf_cli_t const name = { \
.p_name = cli_prefix, \
.p_iface = p_transport_iface, \
.p_ctx = &CONCAT_2(name, _ctx), \
.p_log_backend = NRF_CLI_BACKEND_PTR(name), \
.p_fprintf_ctx = &CONCAT_2(name, _fprintf_ctx), \
.p_cmd_hist_mempool = NRF_CLI_MEMOBJ_PTR(name), \
.newline_char = newline_ch \
} /*lint -restore*/

Macro for defining a command line interface instance.

Parameters
[in]nameInstance name.
[in]cli_prefixCLI prefix string.
[in]p_transport_ifacePointer to the transport interface.
[in]newline_chNew line character - only allowed values are '\n' or '\r'.
[in]log_queue_sizeLogger processing queue size.
#define NRF_CLI_DEFAULT   NRF_CLI_VT100_COLOR_DEFAULT

CLI colors for nrf_cli_fprintf function.

Turn off character attributes.

#define NRF_CLI_ERROR   NRF_CLI_VT100_COLOR_RED

Error color printf.

#define NRF_CLI_INFO   NRF_CLI_VT100_COLOR_GREEN

Info color printf.

#define NRF_CLI_NORMAL   NRF_CLI_VT100_COLOR_WHITE

Normal color printf.

#define NRF_CLI_OPT (   _p_optname,
  _p_shortname,
  _p_help 
)
Value:
{ \
.p_optname = _p_optname, \
.p_optname_short = _p_shortname, \
.p_optname_help = _p_help, \
}

Option structure initializer nrf_cli_getopt_option.

Parameters
[in]_p_optnameOption name long.
[in]_p_shortnameOption name short.
[in]_p_helpOption help string.
#define NRF_CLI_OPTION   NRF_CLI_VT100_COLOR_CYAN

Option color printf.

#define NRF_CLI_WARNING   NRF_CLI_VT100_COLOR_YELLOW

Warning color printf.

Typedef Documentation

typedef void(* nrf_cli_dynamic_get)(size_t idx, nrf_cli_static_entry_t *p_static)

CLI dynamic command descriptor.

Function shall fill the received nrf_cli_static_entry structure with requested (idx) dynamic subcommand data. If there is more than one dynamic subcommand available, the function shall ensure that the returned commands: p_static->p_syntax are sorted in alphabetical order. If idx exceeds the available dynamic subcommands, the function must write to p_static->p_syntax NULL value. This will indicate to the CLI module that there are no more dynamic commands to read.

Enumeration Type Documentation

Enumerator
NRF_CLI_STATE_UNINITIALIZED 

State uninitialized.

NRF_CLI_STATE_INITIALIZED 

State initialized but not active.

NRF_CLI_STATE_ACTIVE 

State active.

NRF_CLI_STATE_PANIC_MODE_ACTIVE 

State panic mode activated.

NRF_CLI_STATE_PANIC_MODE_INACTIVE 

State panic mode requested but not supported.

Function Documentation

void nrf_cli_fprintf ( nrf_cli_t const *  p_cli,
nrf_cli_vt100_color_t  color,
char const *  p_fmt,
  ... 
)

Printf-like function which sends formatted data stream to the CLI. This function shall not be used outside of the CLI module or CLI command context.

Parameters
[in]p_cliPointer to the CLI instance.
[in]colorPrintf color.
[in]p_fmtFormat string.
[in]...List of parameters to print.
void nrf_cli_help_print ( nrf_cli_t const *  p_cli,
nrf_cli_getopt_option_t const *  p_opt,
size_t  opt_len 
)

Prints the current command help.

Function will print a help string with: the currently entered command, its options, and subcommands (if they exist).

Parameters
[in]p_cliPointer to the CLI instance.
[in]p_optPointer to the optional option array.
[in]opt_lenOption array size.
__STATIC_INLINE bool nrf_cli_help_requested ( nrf_cli_t const *  p_cli)

Informs that a command has been called with -h or –help option.

Parameters
[in]p_cliPointer to the CLI instance.
Returns
True if help has been requested.
ret_code_t nrf_cli_init ( nrf_cli_t const *  p_cli,
void const *  p_transport_config,
bool  use_colors,
bool  log_backend,
nrf_log_severity_t  init_lvl 
)

Function for initializing a transport layer and internal CLI state.

Parameters
[in]p_cliPointer to CLI instance.
[in]p_transport_configConfiguration forwarded to the transport during initialization.
[in]use_colorsEnables colored prints.
[in]log_backendIf true, the console will be used as logger backend.
[in]init_lvlDefault severity level for the logger.
Returns
Standard error code.
void nrf_cli_process ( nrf_cli_t const *  p_cli)

Process function, which should be executed when data is ready in the transport interface.

Parameters
[in]p_cliPointer to the CLI instance.
ret_code_t nrf_cli_start ( nrf_cli_t const *  p_cli)

Function for starting CLI processing.

Parameters
p_cliPointer to the CLI instance.
Returns
Standard error code.
ret_code_t nrf_cli_stop ( nrf_cli_t const *  p_cli)

Function for stopping CLI processing.

Parameters
p_cliPointer to CLI instance.
Returns
Standard error code.
ret_code_t nrf_cli_uninit ( nrf_cli_t const *  p_cli)

Function for uninitializing a transport layer and internal CLI state. If function returns NRF_ERROR_BUSY, you must call nrf_cli_process before calling nrf_cli_uninit again.

Parameters
p_cliPointer to CLI instance.
Returns
Standard error code.

Documentation feedback | Developer Zone | Subscribe | Updated