Shell system API

Shell API

group shell_api

Shell API.

Defines

SHELL_ARG(_mandatory, _optional)

Initializes a shell command arguments.

Parameters
  • _mandatory: Number of mandatory arguments.
  • _optional: Number of optional arguments.

SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, mandatory, optional)

Macro for defining and adding a root command (level 0) with required number of arguments.

Note
Each root command shall have unique syntax. If a command will be called with wrong number of arguments shell will print an error message and command handler will not be called.
Parameters
  • syntax: Command syntax (for example: history).
  • subcmd: Pointer to a subcommands array.
  • help: Pointer to a command help string.
  • handler: Pointer to a function handler.
  • mandatory: Number of mandatory arguments.
  • optional: Number of optional arguments.

SHELL_CMD_REGISTER(syntax, subcmd, help, handler)

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

Note
Each root command shall have unique syntax.
Parameters
  • syntax: Command syntax (for example: history).
  • subcmd: Pointer to a subcommands array.
  • help: Pointer to a command help string.
  • handler: Pointer to a function handler.

SHELL_CREATE_STATIC_SUBCMD_SET(name)

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

Parameters
  • name: Name of the subcommand set.

SHELL_SUBCMD_SET_END

Define ending subcommands set.

SHELL_CREATE_DYNAMIC_CMD(name, get)

Macro for creating a dynamic entry.

Parameters
  • name: Name of the dynamic entry.
  • get: Pointer to the function returning dynamic commands array

SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, _mandatory, _optional)

Initializes a shell command with arguments.

Note
If a command will be called with wrong number of arguments shell will print an error message and command handler will not be called.
Parameters
  • _syntax: Command syntax (for example: history).
  • _subcmd: Pointer to a subcommands array.
  • _help: Pointer to a command help string.
  • _handler: Pointer to a function handler.
  • _mandatory: Number of mandatory arguments.
  • _optional: Number of optional arguments.

SHELL_CMD(_syntax, _subcmd, _help, _handler)

Initializes a shell command.

Parameters
  • _syntax: Command syntax (for example: history).
  • _subcmd: Pointer to a subcommands array.
  • _help: Pointer to a command help string.
  • _handler: Pointer to a function handler.

SHELL_STATS_DEFINE(_name)
SHELL_STATS_PTR(_name)
SHELL_DEFINE(_name, _prompt, transport_iface, log_queue_size, _shell_flag)

Macro for defining a shell instance.

Parameters
  • _name: Instance name.
  • _prompt: Shell prompt string.
  • transport_iface: Pointer to the transport interface.
  • log_queue_size: Logger processing queue size.
  • _shell_flag: Shell output newline sequence.

SHELL_NORMAL

Terminal default text color for nrf_shell_fprintf function.

SHELL_INFO

Green text color for nrf_shell_fprintf function.

SHELL_OPTION

Cyan text color for nrf_shell_fprintf function.

SHELL_WARNING

Yellow text color for nrf_shell_fprintf function.

SHELL_ERROR

Red text color for nrf_shell_fprintf function.

shell_info(_sh, _ft, ...)

Print info message to the shell.

This function shall not be used outside of the shell command context.

Parameters
  • _sh: Pointer to the shell instance.
  • _ft: Format string.
  • ...: List of parameters to print.

shell_print(_sh, _ft, ...)

Print normal message to the shell.

This function shall not be used outside of the shell command context.

Parameters
  • _sh: Pointer to the shell instance.
  • _ft: Format string.
  • ...: List of parameters to print.

shell_warn(_sh, _ft, ...)

Print warning message to the shell.

This function shall not be used outside of the shell command context.

Parameters
  • _sh: Pointer to the shell instance.
  • _ft: Format string.
  • ...: List of parameters to print.

shell_error(_sh, _ft, ...)

Print error message to the shell.

This function shall not be used outside of the shell command context.

Parameters
  • _sh: Pointer to the shell instance.
  • _ft: Format string.
  • ...: List of parameters to print.

Typedefs

typedef void (*shell_dynamic_get)(size_t idx, struct shell_static_entry *entry)

Shell dynamic command descriptor.

Function shall fill the received shell_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: entry->syntax are sorted in alphabetical order. If idx exceeds the available dynamic subcommands, the function must write to entry->syntax NULL value. This will indicate to the shell module that there are no more dynamic commands to read.

typedef int (*shell_cmd_handler)(const struct shell *shell, size_t argc, char **argv)

Shell command handler prototype.

typedef void (*shell_transport_handler_t)(enum shell_transport_evt evt, void *context)

Enums

enum shell_receive_state

Values:

SHELL_RECEIVE_DEFAULT
SHELL_RECEIVE_ESC
SHELL_RECEIVE_ESC_SEQ
SHELL_RECEIVE_TILDE_EXP
enum shell_state

Values:

SHELL_STATE_UNINITIALIZED
SHELL_STATE_INITIALIZED
SHELL_STATE_ACTIVE
SHELL_STATE_PANIC_MODE_ACTIVE

Panic activated.

SHELL_STATE_PANIC_MODE_INACTIVE

Panic requested, not supported.

enum shell_transport_evt

Shell transport event.

Values:

SHELL_TRANSPORT_EVT_RX_RDY
SHELL_TRANSPORT_EVT_TX_RDY
enum shell_signal

Values:

SHELL_SIGNAL_RXRDY
SHELL_SIGNAL_TXDONE
SHELL_SIGNAL_LOG_MSG
SHELL_SIGNAL_KILL
SHELL_SIGNALS
enum shell_flag

Flags for setting shell output newline sequence.

Values:

SHELL_FLAG_CRLF_DEFAULT = (1<<0)
SHELL_FLAG_OLF_CRLF = (1<<1)

Functions

void shell_print_stream(const void *user_ctx, const char *data, size_t data_len)
int shell_init(const struct shell *shell, const void *transport_config, bool use_colors, bool log_backend, u32_t init_log_level)

Function for initializing a transport layer and internal shell state.

Return
Standard error code.
Parameters
  • shell: Pointer to shell instance.
  • transport_config: Transport configuration during initialization.
  • use_colors: Enables colored prints.
  • log_backend: If true, the console will be used as logger backend.
  • init_log_level: Default severity level for the logger.

int shell_uninit(const struct shell *shell)

Uninitializes the transport layer and the internal shell state.

Return
Standard error code.
Parameters
  • shell: Pointer to shell instance.

int shell_start(const struct shell *shell)

Function for starting shell processing.

Return
Standard error code.
Parameters
  • shell: Pointer to the shell instance.

int shell_stop(const struct shell *shell)

Function for stopping shell processing.

Return
Standard error code.
Parameters
  • shell: Pointer to shell instance.

void shell_fprintf(const struct shell *shell, enum shell_vt100_color color, const char *p_fmt, ...)

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

Parameters
  • shell: Pointer to the shell instance.
  • color: Printf color.
  • p_fmt: Format string.
  • ...: List of parameters to print.

void shell_process(const struct shell *shell)

Process function, which should be executed when data is ready in the transport interface. To be used if shell thread is disabled.

Parameters
  • shell: Pointer to the shell instance.

int shell_prompt_change(const struct shell *shell, char *prompt)

Change displayed shell prompt.

Return
0 success
Return
-1 new string is too long
Parameters
  • shell: Pointer to the shell instance.
  • prompt: New shell prompt.

void shell_help(const struct shell *shell)

Prints the current command help.

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

Parameters
  • shell: Pointer to the shell instance.

int shell_execute_cmd(const struct shell *shell, const char *cmd)

Execute command.

Pass command line to shell to execute.

Note: This by no means makes any of the commands a stable interface, so this function should only be used for debugging/diagnostic.

Return
Result of the execution
Parameters
  • shell: Pointer to the shell instance. It can be NULL when the :option:CONFIG_SHELL_BACKEND_DUMMY option is enabled.
  • cmd: Command to be executed.

Variables

const struct log_backend_api log_backend_shell_api
struct shell_cmd_entry
#include <shell.h>

Shell command descriptor.

struct shell_transport_api
#include <shell.h>

Unified shell transport interface.

struct shell_stats
#include <shell.h>

Shell statistics structure.

union shell_internal
#include <shell.h>

Public Members

u32_t value
struct shell_flags flags
struct shell_ctx
#include <shell.h>

Shell instance context.

struct shell
#include <shell.h>

Shell instance internals.