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
All root commands must have different name.
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, _log_timeout, _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.
  • _log_timeout: Logger thread timeout in milliseconds on full log queue. If queue is full logger thread is blocked for given amount of time before log message is dropped.
  • _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.

See shell_fprintf.

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.

See shell_fprintf.

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.

See shell_fprintf.

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.

See shell_fprintf.

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

SHELL_CMD_HELP_PRINTED

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.

Parameters
  • shell: Shell instance.
  • argc: Arguments count.
  • argv: Arguments.
Return Value
  • 0: Successful command execution.
  • 1: Help printed and command not executed.
  • -EINVAL: Argument validation failed.
  • -ENOEXEC: Command not executed.

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_COMMAND
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_LOG_MSG
SHELL_SIGNAL_KILL
SHELL_SIGNAL_COMMAND_EXIT
SHELL_SIGNAL_TXDONE
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 unless command requested to stay in the foreground (see shell_command_enter). In that case, function can be called from any thread context until command is terminated with CTRL+C or shell_command_exit call.

Parameters
  • shell: Pointer to the shell instance.
  • color: Printed text 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.

void shell_command_enter(const struct shell *shell)

Indicate to shell that command stay in foreground, blocking the shell.

Command in foreground is terminated by shell_command_exit or CTRL+C.

Parameters
  • shell: Pointer to the shell instance.

void shell_command_exit(const struct shell *shell)

Exit command in foreground state.

See shell_command_enter.

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
-ENOMEM New prompt 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.