1# Console Example
2
3(See the README.md file in the upper level 'examples' directory for more information about examples.)
4
5This example illustrates the usage of the [Console Component](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/console.html#console) to create an interactive shell on the ESP32. The interactive shell running on the ESP32 can then be controlled/interacted with over a serial port (UART).
6
7The interactive shell implemented in this example contains a wide variety of commands, and can act as a basis for applications that require a command-line interface (CLI).
8
9## How to use example
10
11### Hardware Required
12
13This example should be able to run on any commonly available ESP32 development board.
14
15### Configure the project
16
17```
18idf.py menuconfig
19```
20
21* Enable/disable `Example Configuration > Store command history in flash` as necessary
22
23### Build and Flash
24
25Build the project and flash it to the board, then run monitor tool to view serial output:
26
27```
28idf.py -p PORT flash monitor
29```
30
31(Replace PORT with the name of the serial port to use.)
32
33(To exit the serial monitor, type ``Ctrl-]``.)
34
35See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
36
37## Example Output
38
39Enter the `help` command get a full list of all available commands. The following is a sample session of the Console Example where a variety of commands provided by the Console Example are used. Note that GPIO15 is connected to GND to remove the boot log output.
40
41```
42This is an example of ESP-IDF console component.
43Type 'help' to get the list of commands.
44Use UP/DOWN arrows to navigate through command history.
45Press TAB when typing command name to auto-complete.
46[esp32]> help
47help
48  Print the list of registered commands
49
50free
51  Get the total size of heap memory available
52
53restart
54  Restart the program
55
56deep_sleep  [-t <t>] [--io=<n>] [--io_level=<0|1>]
57  Enter deep sleep mode. Two wakeup modes are supported: timer and GPIO. If no
58  wakeup option is specified, will sleep indefinitely.
59  -t, --time=<t>  Wake up time, ms
60      --io=<n>  If specified, wakeup using GPIO with given number
61  --io_level=<0|1>  GPIO level to trigger wakeup
62
63join  [--timeout=<t>] <ssid> [<pass>]
64  Join WiFi AP as a station
65  --timeout=<t>  Connection timeout, ms
66        <ssid>  SSID of AP
67        <pass>  PSK of AP
68
69[esp32]> free
70257200
71[esp32]> deep_sleep -t 1000
72I (146929) deep_sleep: Enabling timer wakeup, timeout=1000000us
73I (619) heap_init: Initializing. RAM available for dynamic allocation:
74I (620) heap_init: At 3FFAE2A0 len 00001D60 (7 KiB): DRAM
75I (626) heap_init: At 3FFB7EA0 len 00028160 (160 KiB): DRAM
76I (645) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
77I (664) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
78I (684) heap_init: At 40093EA8 len 0000C158 (48 KiB): IRAM
79
80This is an example of ESP-IDF console component.
81Type 'help' to get the list of commands.
82Use UP/DOWN arrows to navigate through command history.
83Press TAB when typing command name to auto-complete.
84[esp32]> join --timeout 10000 test_ap test_password
85I (182639) connect: Connecting to 'test_ap'
86I (184619) connect: Connected
87[esp32]> free
88212328
89[esp32]> restart
90I (205639) restart: Restarting
91I (616) heap_init: Initializing. RAM available for dynamic allocation:
92I (617) heap_init: At 3FFAE2A0 len 00001D60 (7 KiB): DRAM
93I (623) heap_init: At 3FFB7EA0 len 00028160 (160 KiB): DRAM
94I (642) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
95I (661) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
96I (681) heap_init: At 40093EA8 len 0000C158 (48 KiB): IRAM
97
98This is an example of ESP-IDF console component.
99Type 'help' to get the list of commands.
100Use UP/DOWN arrows to navigate through command history.
101Press TAB when typing command name to auto-complete.
102[esp32]>
103
104```
105
106## Troubleshooting
107
108### Line Endings
109
110The line endings in the Console Example are configured to match particular serial monitors. Therefore, if the following log output appears, consider using a different serial monitor (e.g. Putty for Windows) or modify the example's [UART configuration](#Configuring-UART-and-VFS).
111
112```
113This is an example of ESP-IDF console component.
114Type 'help' to get the list of commands.
115Use UP/DOWN arrows to navigate through command history.
116Press TAB when typing command name to auto-complete.
117Your terminal application does not support escape sequences.
118Line editing and history features are disabled.
119On Windows, try using Putty instead.
120esp32>
121```
122
123## Example Breakdown
124
125### Configuring UART
126
127The ``initialize_console()`` function in the example configures some aspects of UART relevant to the operation of the console.
128
129- **Line Endings**: The default line endings are configured to match those expected/generated by common serial monitor programs, such as `screen`, `minicom`, and the `idf_monitor.py` included in the SDK. The default behavior for these commands are:
130    - When 'enter' key is pressed on the keyboard, `CR` (0x13) code is sent to the serial device.
131    - To move the cursor to the beginning of the next line, serial device needs to send `CR LF` (0x13 0x10) sequence.
132
133### Line editing
134
135The main source file of the example illustrates how to use `linenoise` library, including line completion, hints, and history.
136
137### Commands
138
139Several commands are registered using `esp_console_cmd_register()` function. See the `register_wifi()` and `register_system()` functions in `cmd_wifi.c` and `cmd_system.c` files.
140
141### Command handling
142
143Main loop inside `app_main()` function illustrates how to use `linenoise` and `esp_console_run()` to implement read/eval loop.
144
145### Argument parsing
146
147Several commands implemented in `cmd_wifi.c` and `cmd_system.c` use the Argtable3 library to parse and check the arguments.
148
149### Command history
150
151Each time a new command line is obtained from `linenoise`, it is written into history and the history is saved into a file in flash memory. On reset, history is initialized from that file.
152