253de6c7a2
With basic description of registering different types of Shell commands. Signed-off-by: Luis Ubieda <luisf@croxel.com>
116 lines
3.4 KiB
ReStructuredText
116 lines
3.4 KiB
ReStructuredText
.. 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>`.
|