Zephyr OS Shell
Overview
Zephyr OS Shell enables multiple Zephyr OS modules to use and expose their shell interface simultaneously.
Each module can support shell functionality dynamically by its Kconfig file, which enables or disables the shell usage for the module.
Using shell commands
Use one of the following formats:
Specific module’s commands
- MODULE_NAME COMMAND
- One of the available modules is “KERNEL”, for the Kernel module. More information can be found in
SHELL_REGISTER
.
Help commands
- help
- Prints the available modules.
- help MODULE_NAME
- Prints the names of the available commands for the module.
- help MODULE_NAME COMMAND
- Prints help for the module’s command (the help should show function goal and required parameters).
Select module commands
- set_module MODULE_NAME
- Use this command when using the shell only for one module. After entering this command, you will not need to enter module name in further commands. If the selected module has set a default shell prompt during its initialization, the prompt will be changed to that one. Otherwise, the prompt will be changed to the selected module’s name to reflect the current module in use.
- set_module
- Clears selected module. Restores prompt as well.
Shell configuration
There are two levels of configuration: Infrastructure level and Module level.
Infrastructure level
The default value for ENABLE_SHELL flag should be considered per product.
This flag enables shell services.
If it is enabled, kernel shell commands are also available for use.
See the CONFIG_ENABLE_SHELL
Kconfig options for more information.
Module level
Each module using shell service should add a unique flag in its Kconfig file.
Example: CONFIG_SAMPLE_MODULE_USE_SHELL=y
In the module’s code, the shell usage depends on this config parameter. This module-specific flag should also depend on ENABLE_SHELL flag.
Therefore, there is one global flag, in addition to a unique flag per each module. The default value for ENABLE_SHELL flag should be considered per product.
Configuration steps to add shell functionality to a module
- Check that ENABLE_SHELL is set to yes.
- Add the module unique flag to its Kconfig file.
Writing a shell module
In order to support shell in your module, the application must do the following:
- Module configuration flag:
Declare a new flag in your module Kconfig file. It should depend on ENABLE_SHELL flag.
- Module registration to shell:
Add your shell identifier and register its callback functions in the shell database using
SHELL_REGISTER
.
- Optional:
shell_register_default_module()
shell_register_prompt_handler()
- Usage:
In case of a sample applications as well as test environment, user can choose to set a default module in code level. In this case, the function shell_register_default_module should be called after calling SHELL_REGISTER in application level. If the function shell_register_prompt_handler was called as well, the prompt will be changed to that one. Otherwise, the prompt will be changed to the selected module’s name, in order to reflect the current module in use.
- Note:
Even if a default module was set in code level, it can be overwritten by “set_module” shell command.
When to use shell_register_default_module:
- Use this command in case of using the shell only for one module. After entering this command, no need to enter module name in further commands.
- Use this function for shell backward compatibility.
More details on those optional functions can be found in Shell Api Functions.
Shell Api Functions
-
typedef const char *(*
shell_prompt_function_t
)(void) Callback to get the current prompt.
- Return
- Current prompt string.
-
void
shell_init
(const char *prompt) Initialize shell with optional prompt, NULL in case no prompt is needed.
- Parameters
prompt
: Prompt to be printed on serial console.
-
void
shell_register_app_cmd_handler
(shell_cmd_function_t handler) Optionally register an app default cmd handler.
- Parameters
handler
: To be called if no cmd found in cmds registered with shell_init.
-
void
shell_register_prompt_handler
(shell_prompt_function_t handler) Optionally register a custom prompt callback.
- Parameters
handler
: To be called to get the current prompt.
-
void
shell_register_default_module
(const char *name) Optionally register a default module, to eliminate typing it in shell console or for backwards compatibility.
- Parameters
name
: Module name.
-
SHELL_REGISTER
(shell_name, shell_commands) Create shell_module object and set it up for boot time initialization.
This macro defines a shell_module object that is automatically configured by the kernel during system initialization.
- Parameters
shell_name
: Module name to be entered in shell console.shell_commands
: Array of commands to register. Shell array entries must be packed to calculate array size correctly.