.. zephyr:code-sample:: shell-module
:name: Custom Shell module
:relevant-api: shell_api
Register shell commands using the Shell API
Overview
********
This is a simple application demonstrating how to write and register commands
using the :ref:`Shell API <shell_api>`:
Register Static commands
``version`` is a static command that prints the kernel version.
Conditionally Register commands
``login`` and ``logout`` are conditionally registered commands depending
on :kconfig:option:`CONFIG_SHELL_START_OBSCURED`.
Register Dynamic commands
See ``dynamic`` command and :zephyr_file:`samples/subsys/shell/shell_module/src/dynamic_cmd.c`
for details on how dynamic commands are implemented.
Register Dictionary commands
``dictionary`` implements subsect of dictionary commands.
Set a Bypass callback
``bypass`` implements the bypass callback.
Set a Login command
``login`` and ``logout`` implement the login and logout mechanism, respectively.
Obscure user-input with asterisks
``login`` and ``logout`` implement the feature of enabling and disabling
this functionality, respectively.
Requirements
************
* A target configured with the shell interface, exposed through any of
its :ref:`backends <backends>`.
Building and Running
********************
This sample can be found under :zephyr_file:`samples/subsys/shell/shell_module`
in the Zephyr tree.
The sample can be built for several platforms.
Emulation Targets
=================
The sample may run on emulation targets. The following commands build the
application for the qemu_x86.
.. zephyr-app-commands::
:zephyr-app: samples/subsys/shell/shell_module
:host-os: unix
:board: qemu_x86
:goals: run
:compact:
After running the application, the console displays the shell interface, and
shows the shell prompt, at which point the user may start the interaction.
On-Hardware
===========
.. zephyr-app-commands::
:zephyr-app: samples/subsys/shell/shell_module
:host-os: unix
:board: nrf52840dk/nrf52840
:goals: flash
:compact:
Sample Output
*************
.. code-block:: console
uart:~$
bypass clear date
demo device devmem
dynamic help history
kernel log log_test
rem resize retval
section_cmd shell shell_uart_release
stats version
uart:~$ demo
demo - Demo commands
Subcommands:
dictionary : Dictionary commands
hexdump : Hexdump params command.
params : Print params command.
ping : Ping command.
board : Show board name command.
uart:~$ dynamic
dynamic - Demonstrate dynamic command usage.
Subcommands:
add : Add a new dynamic command.
Example usage: [ dynamic add test ] will add a dynamic command
'test'.
In this example, command name length is limited to 32 chars. You can
add up to 20 commands. Commands are automatically sorted to ensure
correct shell completion.
execute : Execute a command.
remove : Remove a command.
show : Show all added dynamic commands.
uart:~$
Details on Shell Subsystem
==========================
For more details on the Shell subsystem, check the general :ref:`Shell documentation <shell_api>`.
8cacbe693d