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
46This sample can be found under :zephyr_file:`samples/subsys/shell/shell_module`
47in the Zephyr tree.
48
49The sample can be built for several platforms.
50
51Emulation Targets
52=================
53
54The sample may run on emulation targets. The following commands build the
55application for the qemu_x86.
56
57.. zephyr-app-commands::
58 :zephyr-app: samples/subsys/shell/shell_module
59 :host-os: unix
60 :board: qemu_x86
61 :goals: run
62 :compact:
63
64After running the application, the console displays the shell interface, and
65shows the shell prompt, at which point the user may start the interaction.
66
67On-Hardware
68===========
69
70.. zephyr-app-commands::
71 :zephyr-app: samples/subsys/shell/shell_module
72 :host-os: unix
73 :board: nrf52840dk/nrf52840
74 :goals: flash
75 :compact:
76
77Sample Output
78*************
79
80.. code-block:: console
81
82 uart:~$
83 bypass clear date
84 demo device devmem
85 dynamic help history
86 kernel log log_test
87 rem resize retval
88 section_cmd shell shell_uart_release
89 stats version
90 uart:~$ demo
91 demo - Demo commands
92 Subcommands:
93 dictionary : Dictionary commands
94 hexdump : Hexdump params command.
95 params : Print params command.
96 ping : Ping command.
97 board : Show board name command.
98 uart:~$ dynamic
99 dynamic - Demonstrate dynamic command usage.
100 Subcommands:
101 add : Add a new dynamic command.
102 Example usage: [ dynamic add test ] will add a dynamic command
103 'test'.
104 In this example, command name length is limited to 32 chars. You can
105 add up to 20 commands. Commands are automatically sorted to ensure
106 correct shell completion.
107 execute : Execute a command.
108 remove : Remove a command.
109 show : Show all added dynamic commands.
110 uart:~$
111
112Details on Shell Subsystem
113==========================
114
115For more details on the Shell subsystem, check the general :ref:`Shell documentation <shell_api>`.
116
