Shell API

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)    SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, 0, 0)
	Macro for defining and adding a root command (level 0) with arguments.
#define	SHELL_COND_CMD_REGISTER(flag, syntax, subcmd, help, handler)    SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, 0, 0)
	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)    SHELL_SUBCMD_COND_ADD(1, _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)    SHELL_EXPR_CMD_ARG(1, 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)    SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)
	Initializes a shell command.
#define	SHELL_COND_CMD(_flag, _syntax, _subcmd, _help, _handler)    SHELL_COND_CMD_ARG(_flag, _syntax, _subcmd, _help, _handler, 0, 0)
	Initializes a conditional shell command.
#define	SHELL_EXPR_CMD(_expr, _syntax, _subcmd, _help, _handler)    SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, 0, 0)
	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, ...)   shell_fprintf_impl(sh, color, fmt, ##__VA_ARGS__)
#define	shell_info(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_INFO, _ft "\n", ##__VA_ARGS__)
	Print info message to the shell.
#define	shell_print(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_NORMAL, _ft "\n", ##__VA_ARGS__)
	Print normal message to the shell.
#define	shell_warn(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_WARNING, _ft "\n", ##__VA_ARGS__)
	Print warning message to the shell.
#define	shell_error(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_ERROR, _ft "\n", ##__VA_ARGS__)
	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 device *	shell_device_lookup (size_t idx, const char *prefix)
	Get by index a device that matches .
const struct device *	shell_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_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
	)		SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)

#include <zephyr/shell/shell.h>

Initializes a shell command.

Parameters

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

SHELL_CMD_ARG

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

#include <zephyr/shell/shell.h>

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]	syntax	Command syntax (for example: history).
[in]	subcmd	Pointer to a subcommands array.
[in]	help	Pointer to a command help string.
[in]	handler	Pointer to a function handler.
[in]	mand	Number of mandatory arguments including command name.
[in]	opt	Number 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)                        \
        }

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]	syntax	Command syntax (for example: history).
[in]	subcmd	Pointer to a subcommands array.
[in]	help	Pointer to a command help string.
[in]	handler	Pointer to a function handler.
[in]	mandatory	Number of mandatory arguments including command name.
[in]	optional	Number 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)

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
	)		SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, 0, 0)

#include <zephyr/shell/shell.h>

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

Note

All root commands must have different name.

Parameters

[in]	syntax	Command syntax (for example: history).
[in]	subcmd	Pointer to a subcommands array.
[in]	help	Pointer to a command help string.
[in]	handler	Pointer to a function handler.

SHELL_COND_CMD

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

#include <zephyr/shell/shell.h>

Initializes a conditional shell command.

See also

SHELL_COND_CMD_ARG.

Parameters

[in]	_flag	Compile time flag. Command is present only if flag exists and equals 1.
[in]	_syntax	Command syntax (for example: history).
[in]	_subcmd	Pointer to a subcommands array.
[in]	_help	Pointer to a command help string.
[in]	_handler	Pointer 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)

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]	flag	Compile time flag. Command is present only if flag exists and equals 1.
[in]	syntax	Command syntax (for example: history).
[in]	subcmd	Pointer to a subcommands array.
[in]	help	Pointer to a command help string.
[in]	handler	Pointer to a function handler.
[in]	mand	Number of mandatory arguments including command name.
[in]	opt	Number 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:

        COND_CODE_1(\
                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\
                ) \
        )

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]	flag	Compile time flag. Command is present only if flag exists and equals 1.
[in]	syntax	Command syntax (for example: history).
[in]	subcmd	Pointer to a subcommands array.
[in]	help	Pointer to a command help string.
[in]	handler	Pointer to a function handler.
[in]	mandatory	Number of mandatory arguments including command name.
[in]	optional	Number of optional arguments.

SHELL_COND_CMD_REGISTER

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

#include <zephyr/shell/shell.h>

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

See also

SHELL_COND_CMD_ARG_REGISTER.

Parameters

[in]	flag	Compile time flag. Command is present only if flag exists and equals 1.
[in]	syntax	Command syntax (for example: history).
[in]	subcmd	Pointer to a subcommands array.
[in]	help	Pointer to a command help string.
[in]	handler	Pointer 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,                 \
                                 CONFIG_SHELL_PRINTF_BUFF_SIZE,               \
                                 _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,   \
                             CONFIG_SHELL_PRINTF_BUFF_SIZE,                   \
                             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                                        \
        }

Macro for defining a shell instance.

Parameters

[in]	_name	Instance name.
[in]	_prompt	Shell default prompt string.
[in]	_transport_iface	Pointer to the transport interface.
[in]	_log_queue_size	Logger processing queue size.
[in]	_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.
[in]	_shell_flag	Shell 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]	name	Name of the dynamic entry.
[in]	get	Pointer 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,
			...
	)		shell_fprintf(_sh, SHELL_ERROR, _ft "\n", ##__VA_ARGS__)

#include <zephyr/shell/shell.h>

Print error message to the shell.

See shell_fprintf.

Parameters

[in]	_sh	Pointer to the shell instance.
[in]	_ft	Format string.
[in]	...	List of parameters to print.

SHELL_EXPR_CMD

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

#include <zephyr/shell/shell.h>

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

See also

SHELL_EXPR_CMD_ARG.

Parameters

[in]	_expr	Compile time expression. Command is present only if expression is non-zero.
[in]	_syntax	Command syntax (for example: history).
[in]	_subcmd	Pointer to a subcommands array.
[in]	_help	Pointer to a command help string.
[in]	_handler	Pointer 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]	_expr	Expression.
[in]	_syntax	Command syntax (for example: history).
[in]	_subcmd	Pointer to a subcommands array.
[in]	_help	Pointer to a command help string.
[in]	_handler	Pointer to a function handler.
[in]	_mand	Number of mandatory arguments including command name.
[in]	_opt	Number of optional arguments.

shell_fprintf

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

#include <zephyr/shell/shell.h>

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,
			...
	)		shell_fprintf(_sh, SHELL_INFO, _ft "\n", ##__VA_ARGS__)

#include <zephyr/shell/shell.h>

Print info message to the shell.

See shell_fprintf.

Parameters

[in]	_sh	Pointer to the shell instance.
[in]	_ft	Format 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,
			...
	)		shell_fprintf(_sh, SHELL_NORMAL, _ft "\n", ##__VA_ARGS__)

#include <zephyr/shell/shell.h>

Print normal message to the shell.

See shell_fprintf.

Parameters

[in]	_sh	Pointer to the shell instance.
[in]	_ft	Format 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:

SHELL_STATIC_SUBCMD_SET_CREATE(
   foo,
   SHELL_CMD(abc, ...),
   SHELL_CMD(def, ...),
   SHELL_SUBCMD_SET_END
)

Parameters

[in]	name	Name 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
	)		SHELL_SUBCMD_COND_ADD(1, _parent, _syntax, _subcmd, _help, _handler, _mand, _opt)

#include <zephyr/shell/shell.h>

Add command to the set of subcommands.

Add command to the set created with SHELL_SUBCMD_SET_CREATE.

Parameters

[in]	_parent	Parent command sequence. Comma separated in parenthesis.
[in]	_syntax	Command syntax (for example: history).
[in]	_subcmd	Pointer to a subcommands array.
[in]	_help	Pointer to a command help string.
[in]	_handler	Pointer to a function handler.
[in]	_mand	Number of mandatory arguments including command name.
[in]	_opt	Number 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]	_flag	Compile time flag. Command is present only if flag exists and equals 1.
[in]	_parent	Parent command sequence. Comma separated in parenthesis.
[in]	_syntax	Command syntax (for example: history).
[in]	_subcmd	Pointer to a subcommands array.
[in]	_help	Pointer to a command help string.
[in]	_handler	Pointer to a function handler.
[in]	_mand	Number of mandatory arguments including command name.
[in]	_opt	Number 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__),  \
                SHELL_SUBCMD_SET_END                                    \
        )

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]	_name	Name of the dictionary subcommand set
[in]	_handler	Command 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);

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]	_name	Name of the set. _name is used to refer the set in the parent command.
[in]	_parent	Set 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,
			...
	)		shell_fprintf(_sh, SHELL_WARNING, _ft "\n", ##__VA_ARGS__)

#include <zephyr/shell/shell.h>

Print warning message to the shell.

See shell_fprintf.

Parameters

[in]	_sh	Pointer to the shell instance.
[in]	_ft	Format 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

sh	Shell instance.
data	Raw data from transport.
len	Data 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

sh	Shell instance.
argc	Arguments count.
argv	Arguments.

Return values

0	Successful command execution.
1	Help printed and command not executed.
-EINVAL	Argument validation failed.
-ENOEXEC	Command 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

dev	pointer 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

sh	Shell instance.
argc	Arguments count.
argv	Arguments.
data	Pointer to the user data.

Return values

0	Successful command execution.
1	Help printed and command not executed.
-EINVAL	Argument validation failed.
-ENOEXEC	Command 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)

#include <zephyr/shell/shell.h>

shell_uninit_cb_t

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

#include <zephyr/shell/shell.h>

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

enum 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

enum 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

enum 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

enum 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

idx	the device number starting from zero.
filter	a 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

idx	the device number starting from zero.
prefix	optional 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]	sh	Pointer to the shell instance.
[in]	val	Echo mode.

Return values

0	or 1: previous value
-EINVAL	if 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]	sh	Pointer to the shell instance. It can be NULL when the CONFIG_SHELL_BACKEND_DUMMY option is enabled.
[in]	cmd	Command to be executed.

Returns

Result of the execution

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]	sh	Pointer to the shell instance.
[in]	color	Printed text color.
[in]	fmt	Format string.
[in]	...	List of parameters to print.

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]

sh

Pointer to the shell instance

Return values

return

value 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]

sh

Pointer 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]	sh	Pointer to the shell instance.
[in]	data	Pointer to data.
[in]	len	Length 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]	sh	Pointer to the shell instance.
[in]	offset	Offset to show for this line.
[in]	data	Pointer to data.
[in]	len	Length 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]	sh	Pointer to shell instance.
[in]	transport_config	Transport configuration during initialization.
[in]	cfg_flags	Initial backend configuration flags. Shell will copy this data.
[in]	log_backend	If true, the console will be used as logger backend.
[in]	init_log_level	Default 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]	sh	Pointer to the shell instance.
[in]	val	Insert mode.

Return values

0	or 1: previous value
-EINVAL	if 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]	sh	Pointer to the shell instance.
[in]	val	Delete mode.

Return values

0	or 1: previous value
-EINVAL	if 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]	sh	Pointer to the shell instance.
[in]	obscure	Obscure mode.

Return values

0	or 1: previous value.
-EINVAL	if 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]

sh

Pointer 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]	sh	Pointer to the shell instance.
[in]	prompt	New 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]

sh

Pointer to the shell instance.

Return values

true	Shell backend is ready to execute commands.
false	Shell 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]	sh	Pointer to the shell instance.
[in]	bypass	Bypass 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

cmd	String with one of the root commands or null pointer to reset.

Return values

0	if root command is set.
-EINVAL	if 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

sh	Pointer 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

sh	Pointer 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

sh	Pointer to shell instance.
cb	Callback 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]	sh	Pointer to the shell instance.
[in]	val	Color mode.

Return values

0	or 1: previous value
-EINVAL	if 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]	sh	Pointer to the shell instance.
[in]	val	vt100 mode.

Return values

0	or 1: previous value
-EINVAL	if 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]	sh	Pointer to the shell instance.
[in]	color	Printed text color.
[in]	fmt	Format string.
[in]	args	List of parameters to print.

Variable Documentation

log_backend_shell_api

const struct log_backend_api log_backend_shell_api

extern

#include <zephyr/shell/shell.h>