README.rst
1.. zephyr:code-sample:: shell-module
2 :name: Custom Shell module
3 :relevant-api: shell_api
4
5 Register shell commands using the Shell API
6
7Overview
8********
9
10This is a simple application demonstrating how to write and register commands
11using the :ref:`Shell API <shell_api>`:
12
13Register Static commands
14 ``version`` is a static command that prints the kernel version.
15
16Conditionally Register commands
17 ``login`` and ``logout`` are conditionally registered commands depending
18 on :kconfig:option:`CONFIG_SHELL_START_OBSCURED`.
19
20Register Dynamic commands
21 See ``dynamic`` command and :zephyr_file:`samples/subsys/shell/shell_module/src/dynamic_cmd.c`
22 for details on how dynamic commands are implemented.
23
24Register Dictionary commands
25 ``dictionary`` implements subsect of dictionary commands.
26
27Set a Bypass callback
28 ``bypass`` implements the bypass callback.
29
30Set a Login command
31 ``login`` and ``logout`` implement the login and logout mechanism, respectively.
32
33Obscure user-input with asterisks
34 ``login`` and ``logout`` implement the feature of enabling and disabling
35 this functionality, respectively.
36
37Requirements
38************
39
40* A target configured with the shell interface, exposed through any of
41 its :ref:`backends <backends>`.
42
43Building and Running
44********************
45
46The sample can be built for several platforms.
47
48Emulation Targets
49=================
50
51The sample may run on emulation targets. The following commands build the
52application for the qemu_x86.
53
54.. zephyr-app-commands::
55 :zephyr-app: samples/subsys/shell/shell_module
56 :host-os: unix
57 :board: qemu_x86
58 :goals: run
59 :compact:
60
61After running the application, the console displays the shell interface, and
62shows the shell prompt, at which point the user may start the interaction.
63
64On-Hardware
65===========
66
67.. zephyr-app-commands::
68 :zephyr-app: samples/subsys/shell/shell_module
69 :host-os: unix
70 :board: nrf52840dk/nrf52840
71 :goals: flash
72 :compact:
73
74Sample Output
75*************
76
77.. code-block:: console
78
79 uart:~$
80 bypass clear date
81 demo device devmem
82 dynamic help history
83 kernel log log_test
84 rem resize retval
85 section_cmd shell shell_uart_release
86 stats version
87 uart:~$ demo
88 demo - Demo commands
89 Subcommands:
90 dictionary : Dictionary commands
91 hexdump : Hexdump params command.
92 params : Print params command.
93 ping : Ping command.
94 board : Show board name command.
95 uart:~$ dynamic
96 dynamic - Demonstrate dynamic command usage.
97 Subcommands:
98 add : Add a new dynamic command.
99 Example usage: [ dynamic add test ] will add a dynamic command
100 'test'.
101 In this example, command name length is limited to 32 chars. You can
102 add up to 20 commands. Commands are automatically sorted to ensure
103 correct shell completion.
104 execute : Execute a command.
105 remove : Remove a command.
106 show : Show all added dynamic commands.
107 uart:~$
108
109Details on Shell Subsystem
110==========================
111
112For more details on the Shell subsystem, check the general :ref:`Shell documentation <shell_api>`.
113
