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

  1. Check that ENABLE_SHELL is set to yes.
  2. 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:

  1. Module configuration flag:

    Declare a new flag in your module Kconfig file. It should depend on ENABLE_SHELL flag.

  2. Module registration to shell:

    Add your shell identifier and register its callback functions in the shell database using SHELL_REGISTER.

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