Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

Shell API . More...

Data Structures

union  shell_cmd_entry
 Shell command descriptor. More...
 
struct  shell_static_args
 
struct  shell_static_entry
 
struct  shell_transport_api
 Unified shell transport interface. More...
 
struct  shell_transport
 
struct  shell_stats
 Shell statistics structure. More...
 
struct  shell_backend_config_flags
 
struct  shell_backend_ctx_flags
 
union  shell_backend_cfg
 
union  shell_backend_ctx
 
struct  shell_ctx
 Shell instance context. More...
 
struct  shell
 Shell instance internals. More...
 

Macros

#define 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.
 
#define SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, mandatory, optional)
 Macro for defining and adding a conditional root command (level 0) with required number of arguments.
 
#define SHELL_CMD_REGISTER(syntax, subcmd, help, handler)
 Macro for defining and adding a root command (level 0) with arguments.
 
#define SHELL_COND_CMD_REGISTER(flag, syntax, subcmd, help, handler)
 Macro for defining and adding a conditional root command (level 0) with arguments.
 
#define SHELL_STATIC_SUBCMD_SET_CREATE(name, ...)
 Macro for creating a subcommand set.
 
#define SHELL_SUBCMD_SET_CREATE(_name, _parent)
 Create set of subcommands.
 
#define SHELL_SUBCMD_COND_ADD(_flag, _parent, _syntax, _subcmd, _help, _handler, _mand, _opt)
 Conditionally add command to the set of subcommands.
 
#define SHELL_SUBCMD_ADD(_parent, _syntax, _subcmd, _help, _handler, _mand, _opt)
 Add command to the set of subcommands.
 
#define SHELL_SUBCMD_SET_END   {NULL}
 Define ending subcommands set.
 
#define SHELL_DYNAMIC_CMD_CREATE(name, get)
 Macro for creating a dynamic entry.
 
#define SHELL_CMD_ARG(syntax, subcmd, help, handler, mand, opt)
 Initializes a shell command with arguments.
 
#define SHELL_COND_CMD_ARG(flag, syntax, subcmd, help, handler, mand, opt)
 Initializes a conditional shell command with arguments.
 
#define SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, _mand, _opt)
 Initializes a conditional shell command with arguments if expression gives non-zero result at compile time.
 
#define SHELL_CMD(_syntax, _subcmd, _help, _handler)
 Initializes a shell command.
 
#define SHELL_COND_CMD(_flag, _syntax, _subcmd, _help, _handler)
 Initializes a conditional shell command.
 
#define SHELL_EXPR_CMD(_expr, _syntax, _subcmd, _help, _handler)
 Initializes shell command if expression gives non-zero result at compile time.
 
#define SHELL_CMD_DICT_CREATE(_data, _handler)
 
#define SHELL_SUBCMD_DICT_SET_CREATE(_name, _handler, ...)
 Initializes shell dictionary commands.
 
#define SHELL_DEFAULT_BACKEND_CONFIG_FLAGS
 
#define SHELL_DEFINE(_name, _prompt, _transport_iface, _log_queue_size, _log_timeout, _shell_flag)
 Macro for defining a shell instance.
 
#define SHELL_NORMAL   SHELL_VT100_COLOR_DEFAULT
 Terminal default text color for shell_fprintf function.
 
#define SHELL_INFO   SHELL_VT100_COLOR_GREEN
 Green text color for shell_fprintf function.
 
#define SHELL_OPTION   SHELL_VT100_COLOR_CYAN
 Cyan text color for shell_fprintf function.
 
#define SHELL_WARNING   SHELL_VT100_COLOR_YELLOW
 Yellow text color for shell_fprintf function.
 
#define SHELL_ERROR   SHELL_VT100_COLOR_RED
 Red text color for shell_fprintf function.
 
#define shell_fprintf(sh, color, fmt, ...)
 
#define shell_info(_sh, _ft, ...)
 Print info message to the shell.
 
#define shell_print(_sh, _ft, ...)
 Print normal message to the shell.
 
#define shell_warn(_sh, _ft, ...)
 Print warning message to the shell.
 
#define shell_error(_sh, _ft, ...)
 Print error message to the shell.
 
#define SHELL_CMD_HELP_PRINTED   (1)
 Command's help has been printed.
 

Typedefs

typedef void(* shell_dynamic_get) (size_t idx, struct shell_static_entry *entry)
 Shell dynamic command descriptor.
 
typedef bool(* shell_device_filter_t) (const struct device *dev)
 Filter callback type, for use with shell_device_lookup_filter.
 
typedef int(* shell_cmd_handler) (const struct shell *sh, size_t argc, char **argv)
 Shell command handler prototype.
 
typedef int(* shell_dict_cmd_handler) (const struct shell *sh, size_t argc, char **argv, void *data)
 Shell dictionary command handler prototype.
 
typedef void(* shell_transport_handler_t) (enum shell_transport_evt evt, void *context)
 
typedef void(* shell_uninit_cb_t) (const struct shell *sh, int res)
 
typedef void(* shell_bypass_cb_t) (const struct shell *sh, uint8_t *data, size_t len)
 Bypass callback.
 

Enumerations

enum  shell_receive_state { SHELL_RECEIVE_DEFAULT , SHELL_RECEIVE_ESC , SHELL_RECEIVE_ESC_SEQ , SHELL_RECEIVE_TILDE_EXP }
 
enum  shell_state {
  SHELL_STATE_UNINITIALIZED , SHELL_STATE_INITIALIZED , SHELL_STATE_ACTIVE , SHELL_STATE_PANIC_MODE_ACTIVE ,
  SHELL_STATE_PANIC_MODE_INACTIVE
}
 
enum  shell_transport_evt { SHELL_TRANSPORT_EVT_RX_RDY , SHELL_TRANSPORT_EVT_TX_RDY }
 Shell transport event. More...
 
enum  shell_signal {
  SHELL_SIGNAL_RXRDY , SHELL_SIGNAL_LOG_MSG , SHELL_SIGNAL_KILL , SHELL_SIGNAL_TXDONE ,
  SHELL_SIGNALS
}
 
enum  shell_flag { SHELL_FLAG_CRLF_DEFAULT = (1<<0) , SHELL_FLAG_OLF_CRLF = (1<<1) }
 Flags for setting shell output newline sequence. More...
 

Functions

const struct deviceshell_device_lookup (size_t idx, const char *prefix)
 Get by index a device that matches .
 
const struct deviceshell_device_filter (size_t idx, shell_device_filter_t filter)
 Get a device by index and filter.
 
int shell_init (const struct shell *sh, const void *transport_config, struct shell_backend_config_flags cfg_flags, bool log_backend, uint32_t init_log_level)
 Function for initializing a transport layer and internal shell state.
 
void shell_uninit (const struct shell *sh, shell_uninit_cb_t cb)
 Uninitializes the transport layer and the internal shell state.
 
int shell_start (const struct shell *sh)
 Function for starting shell processing.
 
int shell_stop (const struct shell *sh)
 Function for stopping shell processing.
 
void shell_fprintf_impl (const struct shell *sh, enum shell_vt100_color color, const char *fmt,...)
 printf-like function which sends formatted data stream to the shell.
 
void shell_vfprintf (const struct shell *sh, enum shell_vt100_color color, const char *fmt, va_list args)
 vprintf-like function which sends formatted data stream to the shell.
 
void shell_hexdump_line (const struct shell *sh, unsigned int offset, const uint8_t *data, size_t len)
 Print a line of data in hexadecimal format.
 
void shell_hexdump (const struct shell *sh, const uint8_t *data, size_t len)
 Print data in hexadecimal format.
 
void shell_fprintf_info (const struct shell *sh, const char *fmt,...)
 
void shell_fprintf_normal (const struct shell *sh, const char *fmt,...)
 
void shell_fprintf_warn (const struct shell *sh, const char *fmt,...)
 
void shell_fprintf_error (const struct shell *sh, const char *fmt,...)
 
void shell_process (const struct shell *sh)
 Process function, which should be executed when data is ready in the transport interface.
 
int shell_prompt_change (const struct shell *sh, const char *prompt)
 Change displayed shell prompt.
 
void shell_help (const struct shell *sh)
 Prints the current command help.
 
int shell_execute_cmd (const struct shell *sh, const char *cmd)
 Execute command.
 
int shell_set_root_cmd (const char *cmd)
 Set root command for all shell instances.
 
void shell_set_bypass (const struct shell *sh, shell_bypass_cb_t bypass)
 Set bypass callback.
 
bool shell_ready (const struct shell *sh)
 Get shell readiness to execute commands.
 
int shell_insert_mode_set (const struct shell *sh, bool val)
 Allow application to control text insert mode.
 
int shell_use_colors_set (const struct shell *sh, bool val)
 Allow application to control whether terminal output uses colored syntax.
 
int shell_use_vt100_set (const struct shell *sh, bool val)
 Allow application to control whether terminal is using vt100 commands.
 
int shell_echo_set (const struct shell *sh, bool val)
 Allow application to control whether user input is echoed back.
 
int shell_obscure_set (const struct shell *sh, bool obscure)
 Allow application to control whether user input is obscured with asterisks – useful for implementing passwords.
 
int shell_mode_delete_set (const struct shell *sh, bool val)
 Allow application to control whether the delete key backspaces or deletes.
 
int shell_get_return_value (const struct shell *sh)
 Retrieve return value of most recently executed shell command.
 

Variables

const struct log_backend_api log_backend_shell_api
 

Detailed Description

Shell API .

Since
1.14
Version
1.0.0

Macro Definition Documentation

◆ SHELL_CMD

#define SHELL_CMD ( _syntax,
_subcmd,
_help,
_handler )

#include <zephyr/shell/shell.h>

Value:
SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)
#define SHELL_CMD_ARG(syntax, subcmd, help, handler, mand, opt)
Initializes a shell command with arguments.
Definition shell.h:441

Initializes a shell command.

Parameters
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.

◆ SHELL_CMD_ARG

#define SHELL_CMD_ARG ( syntax,
subcmd,
help,
handler,
mand,
opt )

#include <zephyr/shell/shell.h>

Value:
SHELL_EXPR_CMD_ARG(1, syntax, subcmd, help, handler, mand, opt)
#define SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, _mand, _opt)
Initializes a conditional shell command with arguments if expression gives non-zero result at compile...
Definition shell.h:486

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
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandNumber of mandatory arguments including command name.
[in]optNumber of optional arguments.

◆ SHELL_CMD_ARG_REGISTER

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

#include <zephyr/shell/shell.h>

Value:
static const struct shell_static_entry UTIL_CAT(_shell_, syntax) = \
SHELL_CMD_ARG(syntax, subcmd, help, handler, mandatory, optional); \
static const TYPE_SECTION_ITERABLE(union shell_cmd_entry, \
UTIL_CAT(shell_cmd_, syntax), shell_root_cmds, \
UTIL_CAT(shell_cmd_, syntax) \
) = { \
.entry = &UTIL_CAT(_shell_, syntax) \
}
#define TYPE_SECTION_ITERABLE(type, varname, secname, section_postfix)
Defines a new element for an iterable section for a generic type.
Definition iterable_sections.h:42
Definition shell.h:206
const union shell_cmd_entry * subcmd
Pointer to subcommand.
Definition shell.h:209
shell_cmd_handler handler
Command handler.
Definition shell.h:210
const char * help
Command help string.
Definition shell.h:208
const char * syntax
Command syntax strings.
Definition shell.h:207
Shell command descriptor.
Definition shell.h:101
#define UTIL_CAT(a,...)
Definition util_internal.h:104

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
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandatoryNumber of mandatory arguments including command name.
[in]optionalNumber of optional arguments.

◆ SHELL_CMD_DICT_CREATE

#define SHELL_CMD_DICT_CREATE ( _data,
_handler )

#include <zephyr/shell/shell.h>

Value:
SHELL_CMD_ARG(GET_ARG_N(1, __DEBRACKET _data), NULL, GET_ARG_N(3, __DEBRACKET _data), \
UTIL_CAT(UTIL_CAT(cmd_dict_, UTIL_CAT(_handler, _)), \
GET_ARG_N(1, __DEBRACKET _data)), 1, 0)
#define GET_ARG_N(N,...)
Get nth argument from argument list.
Definition util_macro.h:371

◆ SHELL_CMD_HELP_PRINTED

#define SHELL_CMD_HELP_PRINTED   (1)

#include <zephyr/shell/shell.h>

Command's help has been printed.

◆ SHELL_CMD_REGISTER

#define SHELL_CMD_REGISTER ( syntax,
subcmd,
help,
handler )

#include <zephyr/shell/shell.h>

Value:
SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, 0, 0)
#define 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.
Definition shell.h:230

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

Note
All root commands must have different name.
Parameters
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.

◆ SHELL_COND_CMD

#define SHELL_COND_CMD ( _flag,
_syntax,
_subcmd,
_help,
_handler )

#include <zephyr/shell/shell.h>

Value:
SHELL_COND_CMD_ARG(_flag, _syntax, _subcmd, _help, _handler, 0, 0)
#define SHELL_COND_CMD_ARG(flag, syntax, subcmd, help, handler, mand, opt)
Initializes a conditional shell command with arguments.
Definition shell.h:463

Initializes a conditional shell command.

See also
SHELL_COND_CMD_ARG.
Parameters
[in]_flagCompile time flag. Command is present only if flag exists and equals 1.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.

◆ SHELL_COND_CMD_ARG

#define SHELL_COND_CMD_ARG ( flag,
syntax,
subcmd,
help,
handler,
mand,
opt )

#include <zephyr/shell/shell.h>

Value:
SHELL_EXPR_CMD_ARG(IS_ENABLED(flag), syntax, subcmd, help, \
handler, mand, opt)
#define IS_ENABLED(config_macro)
Check for macro definition in compiler-visible expressions.
Definition util_macro.h:140

Initializes a conditional shell command with arguments.

See also
SHELL_CMD_ARG. Based on the flag, creates a valid entry or an empty command which is ignored by the shell. It is an alternative to #ifdefs around command registration and command handler. However, empty structure is present in the flash even if command is disabled (subcommands and handler are removed). Macro internally handles case if flag is not defined so flag must be provided without any wrapper, e.g.: SHELL_COND_CMD_ARG(CONFIG_FOO, ...)
Parameters
[in]flagCompile time flag. Command is present only if flag exists and equals 1.
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandNumber of mandatory arguments including command name.
[in]optNumber of optional arguments.

◆ SHELL_COND_CMD_ARG_REGISTER

#define SHELL_COND_CMD_ARG_REGISTER ( flag,
syntax,
subcmd,
help,
handler,
mandatory,
optional )

#include <zephyr/shell/shell.h>

Value:
flag, \
(\
SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, \
mandatory, optional) \
), \
(\
static shell_cmd_handler dummy_##syntax##_handler __unused = \
handler;\
static const union shell_cmd_entry *dummy_subcmd_##syntax \
__unused = subcmd\
) \
)
int(* shell_cmd_handler)(const struct shell *sh, size_t argc, char **argv)
Shell command handler prototype.
Definition shell.h:174
#define COND_CODE_1(_flag, _if_1_code, _else_code)
Insert code depending on whether _flag expands to 1 or not.
Definition util_macro.h:195

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

See also
SHELL_CMD_ARG_REGISTER for details.

Macro can be used to create a command which can be conditionally present. It is and alternative to #ifdefs around command registration and command handler. If command is disabled handler and subcommands are removed from the application.

Parameters
[in]flagCompile time flag. Command is present only if flag exists and equals 1.
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandatoryNumber of mandatory arguments including command name.
[in]optionalNumber of optional arguments.

◆ SHELL_COND_CMD_REGISTER

#define SHELL_COND_CMD_REGISTER ( flag,
syntax,
subcmd,
help,
handler )

#include <zephyr/shell/shell.h>

Value:
SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, 0, 0)
#define SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, mandatory, optional)
Macro for defining and adding a conditional root command (level 0) with required number of arguments.
Definition shell.h:261

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

See also
SHELL_COND_CMD_ARG_REGISTER.
Parameters
[in]flagCompile time flag. Command is present only if flag exists and equals 1.
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.

◆ SHELL_DEFAULT_BACKEND_CONFIG_FLAGS

#define SHELL_DEFAULT_BACKEND_CONFIG_FLAGS

#include <zephyr/shell/shell.h>

Value:
{ \
.insert_mode = 0, \
.echo = 1, \
.obscure = IS_ENABLED(CONFIG_SHELL_START_OBSCURED), \
.mode_delete = 1, \
.use_colors = 1, \
.use_vt100 = 1, \
};

◆ SHELL_DEFINE

#define SHELL_DEFINE ( _name,
_prompt,
_transport_iface,
_log_queue_size,
_log_timeout,
_shell_flag )

#include <zephyr/shell/shell.h>

Value:
static const struct shell _name; \
static struct shell_ctx UTIL_CAT(_name, _ctx); \
static uint8_t _name##_out_buffer[CONFIG_SHELL_PRINTF_BUFF_SIZE]; \
Z_SHELL_LOG_BACKEND_DEFINE(_name, _name##_out_buffer, \
_log_queue_size, _log_timeout); \
Z_SHELL_HISTORY_DEFINE(_name##_history, CONFIG_SHELL_HISTORY_BUFFER); \
Z_SHELL_FPRINTF_DEFINE(_name##_fprintf, &_name, _name##_out_buffer, \
true, z_shell_print_stream); \
LOG_INSTANCE_REGISTER(shell, _name, CONFIG_SHELL_LOG_LEVEL); \
Z_SHELL_STATS_DEFINE(_name); \
static K_KERNEL_STACK_DEFINE(_name##_stack, CONFIG_SHELL_STACK_SIZE); \
static struct k_thread _name##_thread; \
static const STRUCT_SECTION_ITERABLE(shell, _name) = { \
.default_prompt = _prompt, \
.iface = _transport_iface, \
.ctx = &UTIL_CAT(_name, _ctx), \
.history = IS_ENABLED(CONFIG_SHELL_HISTORY) ? \
&_name##_history : NULL, \
.shell_flag = _shell_flag, \
.fprintf_ctx = &_name##_fprintf, \
.stats = Z_SHELL_STATS_PTR(_name), \
.log_backend = Z_SHELL_LOG_BACKEND_PTR(_name), \
LOG_INSTANCE_PTR_INIT(log, shell, _name) \
.name = STRINGIFY(_name), \
.thread = &_name##_thread, \
.stack = _name##_stack \
}
#define STRINGIFY(s)
Definition common.h:134
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition iterable_sections.h:216
#define K_KERNEL_STACK_DEFINE(sym, size)
Define a toplevel kernel stack memory region.
Definition thread_stack.h:214
#define CONFIG_SHELL_HISTORY_BUFFER
Definition shell.h:42
#define CONFIG_SHELL_PRINTF_BUFF_SIZE
Definition shell.h:38
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
Thread Structure.
Definition thread.h:259
Shell instance context.
Definition shell.h:813
Shell instance internals.
Definition shell.h:890

Macro for defining a shell instance.

Parameters
[in]_nameInstance name.
[in]_promptShell default prompt string.
[in]_transport_ifacePointer to the transport interface.
[in]_log_queue_sizeLogger processing queue size.
[in]_log_timeoutLogger 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.
[in]_shell_flagShell output newline sequence.

◆ SHELL_DYNAMIC_CMD_CREATE

#define SHELL_DYNAMIC_CMD_CREATE ( name,
get )

#include <zephyr/shell/shell.h>

Value:
static const TYPE_SECTION_ITERABLE(union shell_cmd_entry, name, \
shell_dynamic_subcmds, name) = \
{ \
.dynamic_get = get \
}

Macro for creating a dynamic entry.

Parameters
[in]nameName of the dynamic entry.
[in]getPointer to the function returning dynamic commands array

◆ SHELL_ERROR

#define SHELL_ERROR   SHELL_VT100_COLOR_RED

#include <zephyr/shell/shell.h>

Red text color for shell_fprintf function.

◆ shell_error

#define shell_error ( _sh,
_ft,
... )

#include <zephyr/shell/shell.h>

Value:
shell_fprintf_error(_sh, _ft "\n", ##__VA_ARGS__)
void shell_fprintf_error(const struct shell *sh, const char *fmt,...)

Print error message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_EXPR_CMD

#define SHELL_EXPR_CMD ( _expr,
_syntax,
_subcmd,
_help,
_handler )

#include <zephyr/shell/shell.h>

Value:
SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, 0, 0)

Initializes shell command if expression gives non-zero result at compile time.

See also
SHELL_EXPR_CMD_ARG.
Parameters
[in]_exprCompile time expression. Command is present only if expression is non-zero.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.

◆ SHELL_EXPR_CMD_ARG

#define SHELL_EXPR_CMD_ARG ( _expr,
_syntax,
_subcmd,
_help,
_handler,
_mand,
_opt )

#include <zephyr/shell/shell.h>

Value:
{ \
.syntax = (_expr) ? (const char *)STRINGIFY(_syntax) : "", \
.help = (_expr) ? (const char *)_help : NULL, \
.subcmd = (const union shell_cmd_entry *)((_expr) ? \
_subcmd : NULL), \
.handler = (shell_cmd_handler)((_expr) ? _handler : NULL), \
.args = { .mandatory = _mand, .optional = _opt} \
}

Initializes a conditional shell command with arguments if expression gives non-zero result at compile time.

See also
SHELL_CMD_ARG. Based on the expression, creates a valid entry or an empty command which is ignored by the shell. It should be used instead of SHELL_COND_CMD_ARG if condition is not a single configuration flag, e.g.: SHELL_EXPR_CMD_ARG(IS_ENABLED(CONFIG_FOO) && IS_ENABLED(CONFIG_FOO_SETTING_1), ...)
Parameters
[in]_exprExpression.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.
[in]_mandNumber of mandatory arguments including command name.
[in]_optNumber of optional arguments.

◆ shell_fprintf

#define shell_fprintf ( sh,
color,
fmt,
... )

#include <zephyr/shell/shell.h>

Value:
shell_fprintf_impl(sh, color, fmt, ##__VA_ARGS__)
void shell_fprintf_impl(const struct shell *sh, enum shell_vt100_color color, const char *fmt,...)
printf-like function which sends formatted data stream to the shell.

◆ SHELL_INFO

#define SHELL_INFO   SHELL_VT100_COLOR_GREEN

#include <zephyr/shell/shell.h>

Green text color for shell_fprintf function.

◆ shell_info

#define shell_info ( _sh,
_ft,
... )

#include <zephyr/shell/shell.h>

Value:
shell_fprintf_info(_sh, _ft "\n", ##__VA_ARGS__)
void shell_fprintf_info(const struct shell *sh, const char *fmt,...)

Print info message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_NORMAL

#define SHELL_NORMAL   SHELL_VT100_COLOR_DEFAULT

#include <zephyr/shell/shell.h>

Terminal default text color for shell_fprintf function.

◆ SHELL_OPTION

#define SHELL_OPTION   SHELL_VT100_COLOR_CYAN

#include <zephyr/shell/shell.h>

Cyan text color for shell_fprintf function.

◆ shell_print

#define shell_print ( _sh,
_ft,
... )

#include <zephyr/shell/shell.h>

Value:
shell_fprintf_normal(_sh, _ft "\n", ##__VA_ARGS__)
void shell_fprintf_normal(const struct shell *sh, const char *fmt,...)

Print normal message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_STATIC_SUBCMD_SET_CREATE

#define SHELL_STATIC_SUBCMD_SET_CREATE ( name,
... )

#include <zephyr/shell/shell.h>

Value:
static const struct shell_static_entry shell_##name[] = { \
__VA_ARGS__ \
}; \
static const union shell_cmd_entry name = { \
.entry = shell_##name \
}

Macro for creating a subcommand set.

It must be used outside of any function body.

Example usage:

foo,
SHELL_CMD(abc, ...),
SHELL_CMD(def, ...),
)
#define SHELL_CMD(_syntax, _subcmd, _help, _handler)
Initializes a shell command.
Definition shell.h:505
#define SHELL_SUBCMD_SET_END
Define ending subcommands set.
Definition shell.h:413
#define SHELL_STATIC_SUBCMD_SET_CREATE(name,...)
Macro for creating a subcommand set.
Definition shell.h:324
Parameters
[in]nameName of the subcommand set.
[in]...List of commands created with SHELL_CMD_ARG or or SHELL_CMD

◆ SHELL_SUBCMD_ADD

#define SHELL_SUBCMD_ADD ( _parent,
_syntax,
_subcmd,
_help,
_handler,
_mand,
_opt )

#include <zephyr/shell/shell.h>

Value:
SHELL_SUBCMD_COND_ADD(1, _parent, _syntax, _subcmd, _help, _handler, _mand, _opt)
#define SHELL_SUBCMD_COND_ADD(_flag, _parent, _syntax, _subcmd, _help, _handler, _mand, _opt)
Conditionally add command to the set of subcommands.
Definition shell.h:377

Add command to the set of subcommands.

Add command to the set created with SHELL_SUBCMD_SET_CREATE.

Parameters
[in]_parentParent command sequence. Comma separated in parenthesis.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.
[in]_mandNumber of mandatory arguments including command name.
[in]_optNumber of optional arguments.

◆ SHELL_SUBCMD_COND_ADD

#define SHELL_SUBCMD_COND_ADD ( _flag,
_parent,
_syntax,
_subcmd,
_help,
_handler,
_mand,
_opt )

#include <zephyr/shell/shell.h>

Value:
COND_CODE_1(_flag, \
(static const TYPE_SECTION_ITERABLE(struct shell_static_entry, \
Z_SHELL_SUBCMD_NAME(__DEBRACKET _parent, _syntax), \
shell_subcmds, \
Z_SHELL_SUBCMD_ADD_SECTION_TAG(_parent, _syntax)) = \
SHELL_EXPR_CMD_ARG(1, _syntax, _subcmd, _help, \
_handler, _mand, _opt)\
), \
(static shell_cmd_handler dummy_handler_##_syntax __unused = _handler;\
static const union shell_cmd_entry dummy_subcmd_##_syntax __unused = { \
.entry = (const struct shell_static_entry *)_subcmd\
} \
) \
)

Conditionally add command to the set of subcommands.

Add command to the set created with SHELL_SUBCMD_SET_CREATE.

Note
The name of the section is formed as concatenation of number of parent commands, names of all parent commands and own syntax. Number of parent commands is added to ensure that section prefix is unique. Without it subcommands of (foo) and (foo, cmd1) would mix.
Parameters
[in]_flagCompile time flag. Command is present only if flag exists and equals 1.
[in]_parentParent command sequence. Comma separated in parenthesis.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.
[in]_mandNumber of mandatory arguments including command name.
[in]_optNumber of optional arguments.

◆ SHELL_SUBCMD_DICT_SET_CREATE

#define SHELL_SUBCMD_DICT_SET_CREATE ( _name,
_handler,
... )

#include <zephyr/shell/shell.h>

Value:
FOR_EACH_FIXED_ARG(Z_SHELL_CMD_DICT_HANDLER_CREATE, (), \
_handler, __VA_ARGS__) \
SHELL_STATIC_SUBCMD_SET_CREATE(_name, \
FOR_EACH_FIXED_ARG(SHELL_CMD_DICT_CREATE, (,), _handler, __VA_ARGS__), \
)
#define SHELL_CMD_DICT_CREATE(_data, _handler)
Definition shell.h:550
#define FOR_EACH_FIXED_ARG(F, sep, fixed_arg,...)
Call macro F on each provided argument, with an additional fixed argument as a parameter.
Definition util_macro.h:601

Initializes shell dictionary commands.

This is a special kind of static commands. Dictionary commands can be used every time you want to use a pair: (string <-> corresponding data) in a command handler. The string is usually a verbal description of a given data. The idea is to use the string as a command syntax that can be prompted by the shell and corresponding data can be used to process the command.

Parameters
[in]_nameName of the dictionary subcommand set
[in]_handlerCommand handler common for all dictionary commands.
See also
shell_dict_cmd_handler
Parameters
[in]...Dictionary triplets: (command_syntax, value, helper). Value will be passed to the _handler as user data.

Example usage:

static int my_handler(const struct shell *sh,
size_t argc, char **argv, void *data)
{
int val = (int)data;
shell_print(sh, "(syntax, value) : (%s, %d)", argv[0], val);
return 0;
}
SHELL_SUBCMD_DICT_SET_CREATE(sub_dict_cmds, my_handler,
(value_0, 0, "value 0"), (value_1, 1, "value 1"),
(value_2, 2, "value 2"), (value_3, 3, "value 3")
);
SHELL_CMD_REGISTER(dictionary, &sub_dict_cmds, NULL, NULL);
#define SHELL_CMD_REGISTER(syntax, subcmd, help, handler)
Macro for defining and adding a root command (level 0) with arguments.
Definition shell.h:287
#define shell_print(_sh, _ft,...)
Print normal message to the shell.
Definition shell.h:1108
#define SHELL_SUBCMD_DICT_SET_CREATE(_name, _handler,...)
Initializes shell dictionary commands.
Definition shell.h:588

◆ SHELL_SUBCMD_SET_CREATE

#define SHELL_SUBCMD_SET_CREATE ( _name,
_parent )

#include <zephyr/shell/shell.h>

Value:
static const TYPE_SECTION_ITERABLE(struct shell_static_entry, _name, shell_subcmds, \
Z_SHELL_SUBCMD_SET_SECTION_TAG(_parent))

Create set of subcommands.

Commands to this set are added using SHELL_SUBCMD_ADD and SHELL_SUBCMD_COND_ADD. Commands can be added from multiple files.

Parameters
[in]_nameName of the set. _name is used to refer the set in the parent command.
[in]_parentSet of comma separated parent commands in parenthesis, e.g. (foo_cmd) if subcommands are for the root command "foo_cmd".

◆ SHELL_SUBCMD_SET_END

#define SHELL_SUBCMD_SET_END   {NULL}

#include <zephyr/shell/shell.h>

Define ending subcommands set.

◆ shell_warn

#define shell_warn ( _sh,
_ft,
... )

#include <zephyr/shell/shell.h>

Value:
shell_fprintf_warn(_sh, _ft "\n", ##__VA_ARGS__)
void shell_fprintf_warn(const struct shell *sh, const char *fmt,...)

Print warning message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_WARNING

#define SHELL_WARNING   SHELL_VT100_COLOR_YELLOW

#include <zephyr/shell/shell.h>

Yellow text color for shell_fprintf function.

Typedef Documentation

◆ shell_bypass_cb_t

typedef void(* shell_bypass_cb_t) (const struct shell *sh, uint8_t *data, size_t len)

#include <zephyr/shell/shell.h>

Bypass callback.

Parameters
shShell instance.
dataRaw data from transport.
lenData length.

◆ shell_cmd_handler

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

#include <zephyr/shell/shell.h>

Shell command handler prototype.

Parameters
shShell instance.
argcArguments count.
argvArguments.
Return values
0Successful command execution.
1Help printed and command not executed.
-EINVALArgument validation failed.
-ENOEXECCommand not executed.

◆ shell_device_filter_t

typedef bool(* shell_device_filter_t) (const struct device *dev)

#include <zephyr/shell/shell.h>

Filter callback type, for use with shell_device_lookup_filter.

This is used as an argument of shell_device_lookup_filter to only return devices that match a specific condition, implemented by the filter.

Parameters
devpointer to a struct device.
Returns
bool, true if the filter matches the device type.

◆ shell_dict_cmd_handler

typedef int(* shell_dict_cmd_handler) (const struct shell *sh, size_t argc, char **argv, void *data)

#include <zephyr/shell/shell.h>

Shell dictionary command handler prototype.

Parameters
shShell instance.
argcArguments count.
argvArguments.
dataPointer to the user data.
Return values
0Successful command execution.
1Help printed and command not executed.
-EINVALArgument validation failed.
-ENOEXECCommand not executed.

◆ shell_dynamic_get

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

#include <zephyr/shell/shell.h>

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.

◆ shell_transport_handler_t

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

◆ shell_uninit_cb_t

typedef void(* shell_uninit_cb_t) (const struct shell *sh, int res)

Enumeration Type Documentation

◆ shell_flag

enum shell_flag

#include <zephyr/shell/shell.h>

Flags for setting shell output newline sequence.

Enumerator
SHELL_FLAG_CRLF_DEFAULT 

Do not map CR or LF.

SHELL_FLAG_OLF_CRLF 

Map LF to CRLF on output.

◆ shell_receive_state

#include <zephyr/shell/shell.h>

Enumerator
SHELL_RECEIVE_DEFAULT 
SHELL_RECEIVE_ESC 
SHELL_RECEIVE_ESC_SEQ 
SHELL_RECEIVE_TILDE_EXP 

◆ shell_signal

#include <zephyr/shell/shell.h>

Enumerator
SHELL_SIGNAL_RXRDY 
SHELL_SIGNAL_LOG_MSG 
SHELL_SIGNAL_KILL 
SHELL_SIGNAL_TXDONE 
SHELL_SIGNALS 

◆ shell_state

#include <zephyr/shell/shell.h>

Enumerator
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.

◆ shell_transport_evt

#include <zephyr/shell/shell.h>

Shell transport event.

Enumerator
SHELL_TRANSPORT_EVT_RX_RDY 
SHELL_TRANSPORT_EVT_TX_RDY 

Function Documentation

◆ shell_device_filter()

const struct device * shell_device_filter ( size_t idx,
shell_device_filter_t filter )

#include <zephyr/shell/shell.h>

Get a device by index and filter.

This can be used to return devices matching a specific type.

Devices that the filter returns false for, failed to initialize or do not have a non-empty name are excluded from the candidates for a match.

Parameters
idxthe device number starting from zero.
filtera pointer to a shell_device_filter_t function that returns true if the device matches the filter.

◆ shell_device_lookup()

const struct device * shell_device_lookup ( size_t idx,
const char * prefix )

#include <zephyr/shell/shell.h>

Get by index a device that matches .

This can be used, for example, to identify I2C_1 as the second I2C device.

Devices that failed to initialize or do not have a non-empty name are excluded from the candidates for a match.

Parameters
idxthe device number starting from zero.
prefixoptional name prefix used to restrict candidate devices. Indexing is done relative to devices with names that start with this text. Pass null if no prefix match is required.

◆ shell_echo_set()

int shell_echo_set ( const struct shell * sh,
bool val )

#include <zephyr/shell/shell.h>

Allow application to control whether user input is echoed back.

Value is modified atomically and the previous value is returned.

Parameters
[in]shPointer to the shell instance.
[in]valEcho mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_execute_cmd()

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

#include <zephyr/shell/shell.h>

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.

This function must not be called from shell command context!

Parameters
[in]shPointer to the shell instance. It can be NULL when the CONFIG_SHELL_BACKEND_DUMMY option is enabled.
[in]cmdCommand to be executed.
Returns
Result of the execution

◆ shell_fprintf_error()

void shell_fprintf_error ( const struct shell * sh,
const char * fmt,
... )

◆ shell_fprintf_impl()

void shell_fprintf_impl ( const struct shell * sh,
enum shell_vt100_color color,
const char * fmt,
... )

#include <zephyr/shell/shell.h>

printf-like function which sends formatted data stream to the shell.

This function can be used from the command handler or from threads, but not from an interrupt context.

Parameters
[in]shPointer to the shell instance.
[in]colorPrinted text color.
[in]fmtFormat string.
[in]...List of parameters to print.

◆ shell_fprintf_info()

void shell_fprintf_info ( const struct shell * sh,
const char * fmt,
... )

◆ shell_fprintf_normal()

void shell_fprintf_normal ( const struct shell * sh,
const char * fmt,
... )

◆ shell_fprintf_warn()

void shell_fprintf_warn ( const struct shell * sh,
const char * fmt,
... )

◆ shell_get_return_value()

int shell_get_return_value ( const struct shell * sh)

#include <zephyr/shell/shell.h>

Retrieve return value of most recently executed shell command.

Parameters
[in]shPointer to the shell instance
Return values
returnvalue of previous command

◆ shell_help()

void shell_help ( const struct shell * sh)

#include <zephyr/shell/shell.h>

Prints the current command help.

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

Parameters
[in]shPointer to the shell instance.

◆ shell_hexdump()

void shell_hexdump ( const struct shell * sh,
const uint8_t * data,
size_t len )

#include <zephyr/shell/shell.h>

Print data in hexadecimal format.

Parameters
[in]shPointer to the shell instance.
[in]dataPointer to data.
[in]lenLength of data.

◆ shell_hexdump_line()

void shell_hexdump_line ( const struct shell * sh,
unsigned int offset,
const uint8_t * data,
size_t len )

#include <zephyr/shell/shell.h>

Print a line of data in hexadecimal format.

Each line shows the offset, bytes and then ASCII representation.

For example:

00008010: 20 25 00 20 2f 48 00 08 80 05 00 20 af 46 00 | %. /H.. ... .F. |

Parameters
[in]shPointer to the shell instance.
[in]offsetOffset to show for this line.
[in]dataPointer to data.
[in]lenLength of data.

◆ shell_init()

int shell_init ( const struct shell * sh,
const void * transport_config,
struct shell_backend_config_flags cfg_flags,
bool log_backend,
uint32_t init_log_level )

#include <zephyr/shell/shell.h>

Function for initializing a transport layer and internal shell state.

Parameters
[in]shPointer to shell instance.
[in]transport_configTransport configuration during initialization.
[in]cfg_flagsInitial backend configuration flags. Shell will copy this data.
[in]log_backendIf true, the console will be used as logger backend.
[in]init_log_levelDefault severity level for the logger.
Returns
Standard error code.

◆ shell_insert_mode_set()

int shell_insert_mode_set ( const struct shell * sh,
bool val )

#include <zephyr/shell/shell.h>

Allow application to control text insert mode.

Value is modified atomically and the previous value is returned.

Parameters
[in]shPointer to the shell instance.
[in]valInsert mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_mode_delete_set()

int shell_mode_delete_set ( const struct shell * sh,
bool val )

#include <zephyr/shell/shell.h>

Allow application to control whether the delete key backspaces or deletes.

Value is modified atomically and the previous value is returned.

Parameters
[in]shPointer to the shell instance.
[in]valDelete mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_obscure_set()

int shell_obscure_set ( const struct shell * sh,
bool obscure )

#include <zephyr/shell/shell.h>

Allow application to control whether user input is obscured with asterisks – useful for implementing passwords.

Value is modified atomically and the previous value is returned.

Parameters
[in]shPointer to the shell instance.
[in]obscureObscure mode.
Return values
0or 1: previous value.
-EINVALif shell is NULL.

◆ shell_process()

void shell_process ( const struct shell * sh)

#include <zephyr/shell/shell.h>

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

To be used if shell thread is disabled.

Parameters
[in]shPointer to the shell instance.

◆ shell_prompt_change()

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

#include <zephyr/shell/shell.h>

Change displayed shell prompt.

Parameters
[in]shPointer to the shell instance.
[in]promptNew shell prompt.
Returns
0 Success.
-EINVAL Pointer to new prompt is not correct.

◆ shell_ready()

bool shell_ready ( const struct shell * sh)

#include <zephyr/shell/shell.h>

Get shell readiness to execute commands.

Parameters
[in]shPointer to the shell instance.
Return values
trueShell backend is ready to execute commands.
falseShell backend is not initialized or not started.

◆ shell_set_bypass()

void shell_set_bypass ( const struct shell * sh,
shell_bypass_cb_t bypass )

#include <zephyr/shell/shell.h>

Set bypass callback.

Bypass callback is called whenever data is received. Shell is bypassed and data is passed directly to the callback. Use null to disable bypass functionality.

Parameters
[in]shPointer to the shell instance.
[in]bypassBypass callback or null to disable.

◆ shell_set_root_cmd()

int shell_set_root_cmd ( const char * cmd)

#include <zephyr/shell/shell.h>

Set root command for all shell instances.

It allows setting from the code the root command. It is an equivalent of calling select command with one of the root commands as the argument (e.g "select log") except it sets command for all shell instances.

Parameters
cmdString with one of the root commands or null pointer to reset.
Return values
0if root command is set.
-EINVALif invalid root command is provided.

◆ shell_start()

int shell_start ( const struct shell * sh)

#include <zephyr/shell/shell.h>

Function for starting shell processing.

Parameters
shPointer to the shell instance.
Returns
Standard error code.

◆ shell_stop()

int shell_stop ( const struct shell * sh)

#include <zephyr/shell/shell.h>

Function for stopping shell processing.

Parameters
shPointer to shell instance.
Returns
Standard error code.

◆ shell_uninit()

void shell_uninit ( const struct shell * sh,
shell_uninit_cb_t cb )

#include <zephyr/shell/shell.h>

Uninitializes the transport layer and the internal shell state.

Parameters
shPointer to shell instance.
cbCallback called when uninitialization is completed.

◆ shell_use_colors_set()

int shell_use_colors_set ( const struct shell * sh,
bool val )

#include <zephyr/shell/shell.h>

Allow application to control whether terminal output uses colored syntax.

Value is modified atomically and the previous value is returned.

Parameters
[in]shPointer to the shell instance.
[in]valColor mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_use_vt100_set()

int shell_use_vt100_set ( const struct shell * sh,
bool val )

#include <zephyr/shell/shell.h>

Allow application to control whether terminal is using vt100 commands.

Value is modified atomically and the previous value is returned.

Parameters
[in]shPointer to the shell instance.
[in]valvt100 mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_vfprintf()

void shell_vfprintf ( const struct shell * sh,
enum shell_vt100_color color,
const char * fmt,
va_list args )

#include <zephyr/shell/shell.h>

vprintf-like function which sends formatted data stream to the shell.

This function can be used from the command handler or from threads, but not from an interrupt context. It is similar to shell_fprintf() but takes a va_list instead of variable arguments.

Parameters
[in]shPointer to the shell instance.
[in]colorPrinted text color.
[in]fmtFormat string.
[in]argsList of parameters to print.

Variable Documentation

◆ log_backend_shell_api

const struct log_backend_api log_backend_shell_api
extern