1Console
2=======
3:link_to_translation:`zh_CN:[中文]`
4
5ESP-IDF provides ``console`` component, which includes building blocks needed to develop an interactive console over serial port. This component includes following facilities:
6
7- Line editing, provided by `linenoise`_ library. This includes handling of backspace and arrow keys, scrolling through command history, command auto-completion, and argument hints.
8- Splitting of command line into arguments.
9- Argument parsing, provided by `argtable3`_ library. This library includes APIs used for parsing GNU style command line arguments.
10- Functions for registration and dispatching of commands.
11- Functions to establish a basic REPL (Read-Evaluate-Print-Loop) environment.
12
13.. note::
14
15  These facilities can be used together or independently. For example, it is possible to use line editing and command registration features, but use ``getopt`` or custom code for argument parsing, instead of `argtable3`_. Likewise, it is possible to use simpler means of command input (such as ``fgets``) together with the rest of the means for command splitting and argument parsing.
16
17Line editing
18------------
19
20Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key.
21
22.. note::
23
24  This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running :example:`system/console` example instead of a command prompt (e.g. ``esp>`` ), it means that the serial monitor does not support escape sequences. Programs which are known to work are  GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
25
26Here is an overview of functions provided by `linenoise`_ library.
27
28Configuration
29^^^^^^^^^^^^^
30
31Linenoise library does not need explicit initialization. However, some configuration defaults may need to be changed before invoking the main line editing function.
32
33:cpp:func:`linenoiseClearScreen`
34  Clear terminal screen using an escape sequence and position the cursor at the top left corner.
35
36:cpp:func:`linenoiseSetMultiLine`
37  Switch between single line and multi line editing modes. In single line mode, if the length of the command exceeds the width of the terminal, the command text is scrolled within the line to show the end of the text. In this case the beginning of the text is hidden. Single line needs less data to be sent to refresh screen on each key press, so exhibits less glitching compared to the multi line mode. On the flip side, editing commands and copying command text from terminal in single line mode is harder. Default is single line mode.
38
39:cpp:func:`linenoiseAllowEmpty`
40  Set whether linenoise library will return a zero-length string (if ``true``) or ``NULL`` (if ``false``) for empty lines. By default, zero-length strings are returned.
41
42:cpp:func:`linenoiseSetMaxLineLen`
43  Set maximum length of the line for linenoise library. Default length is 4096. If you need optimize RAM memory usage, you can do it by this function by setting a value less than default 4kB.
44
45
46Main loop
47^^^^^^^^^
48
49:cpp:func:`linenoise`
50  In most cases, console applications have some form of read/eval loop. :cpp:func:`linenoise` is the single function which handles user's key presses and returns completed line once 'enter' key is pressed. As such, it handles the 'read' part of the loop.
51
52:cpp:func:`linenoiseFree`
53  This function must be called to release the command line buffer obtained from :cpp:func:`linenoise` function.
54
55Hints and completions
56^^^^^^^^^^^^^^^^^^^^^
57
58:cpp:func:`linenoiseSetCompletionCallback`
59  When user presses 'tab' key, linenoise library invokes completion callback. The callback should inspect the contents of the command typed so far and provide a list of possible completions using calls to :cpp:func:`linenoiseAddCompletion` function. :cpp:func:`linenoiseSetCompletionCallback` function should be called to register this completion callback, if completion feature is desired.
60
61  ``console`` component provides a ready made function to provide completions for registered commands, :cpp:func:`esp_console_get_completion` (see below).
62
63:cpp:func:`linenoiseAddCompletion`
64  Function to be called by completion callback to inform the library about possible completions of the currently typed command.
65
66:cpp:func:`linenoiseSetHintsCallback`
67  Whenever user input changes, linenoise invokes hints callback. This callback can inspect the command line typed so far, and provide a string with hints (which can include list of command arguments, for example). The library then displays the hint text on the same line where editing happens, possibly with a different color.
68
69:cpp:func:`linenoiseSetFreeHintsCallback`
70  If hint string returned by hints callback is dynamically allocated or needs to be otherwise recycled, the function which performs such cleanup should be registered via :cpp:func:`linenoiseSetFreeHintsCallback`.
71
72
73History
74^^^^^^^
75
76:cpp:func:`linenoiseHistorySetMaxLen`
77  This function sets the number of most recently typed commands to be kept in memory. Users can navigate the history using up/down arrows.
78
79:cpp:func:`linenoiseHistoryAdd`
80  Linenoise does not automatically add commands to history. Instead, applications need to call this function to add command strings to the history.
81
82:cpp:func:`linenoiseHistorySave`
83  Function saves command history from RAM to a text file, for example on an SD card or on a filesystem in flash memory.
84
85:cpp:func:`linenoiseHistoryLoad`
86  Counterpart to :cpp:func:`linenoiseHistorySave`, loads history from a file.
87
88:cpp:func:`linenoiseHistoryFree`
89  Releases memory used to store command history. Call this function when done working with linenoise library.
90
91Splitting of command line into arguments
92----------------------------------------
93
94``console`` component provides :cpp:func:`esp_console_split_argv` function to split command line string into arguments. The function returns the number of arguments found (``argc``) and fills an array of pointers which can be passed as ``argv`` argument to any function which accepts arguments in ``argc, argv`` format.
95
96The command line is split into arguments according to the following rules:
97
98- Arguments are separated by spaces
99- If spaces within arguments are required, they can be escaped using ``\`` (backslash) character.
100- Other escape sequences which are recognized are ``\\`` (which produces literal backslash) and ``\"``, which produces a double quote.
101- Arguments can be quoted using double quotes. Quotes may appear only in the beginning and at the end of the argument. Quotes within the argument must be escaped as mentioned above. Quotes surrounding the argument are stripped by ``esp_console_split_argv`` function.
102
103Examples:
104
105- ``abc def 1 20 .3`` ⟶ [ ``abc``, ``def``, ``1``, ``20``, ``.3`` ]
106- ``abc "123 456" def`` ⟶ [ ``abc``, ``123 456``, ``def`` ]
107- ```a\ b\\c\"`` ⟶ [ ``a b\c"`` ]
108
109
110Argument parsing
111----------------
112
113For argument parsing, ``console`` component includes `argtable3`_ library. Please see `tutorial`_ for an introduction to `argtable3`_. Github repository also includes `examples`_.
114
115.. _argtable3: http://www.argtable.org/
116.. _linenoise: https://github.com/antirez/linenoise
117.. _tutorial: http://www.argtable.org/tutorial/
118.. _examples: https://github.com/argtable/argtable3/tree/master/examples
119
120
121Command registration and dispatching
122------------------------------------
123
124``console`` component includes utility functions which handle registration of commands, matching commands typed by the user to registered ones, and calling these commands with the arguments given on the command line.
125
126Application first initializes command registration module using a call to :cpp:func:`esp_console_init`, and calls :cpp:func:`esp_console_cmd_register` function to register command handlers.
127
128For each command, application provides the following information (in the form of ``esp_console_cmd_t`` structure):
129
130- Command name (string without spaces)
131- Help text explaining what the command does
132- Optional hint text listing the arguments of the command. If application uses Argtable3 for argument parsing, hint text can be generated automatically by providing a pointer to argtable argument definitions structure instead.
133- The command handler function.
134
135A few other functions are provided by the command registration module:
136
137:cpp:func:`esp_console_run`
138  This function takes the command line string, splits it into argc/argv argument list using :cpp:func:`esp_console_split_argv`, looks up the command in the list of registered components, and if it is found, executes its handler.
139
140:cpp:func:`esp_console_register_help_command`
141  Adds ``help`` command to the list of registered commands. This command prints the list of all the registered commands, along with their arguments and help texts.
142
143:cpp:func:`esp_console_get_completion`
144  Callback function to be used with :cpp:func:`linenoiseSetCompletionCallback` from linenoise library. Provides completions to linenoise based on the list of registered commands.
145
146:cpp:func:`esp_console_get_hint`
147  Callback function to be used with :cpp:func:`linenoiseSetHintsCallback` from linenoise library. Provides argument hints for registered commands to linenoise.
148
149Initialize console REPL environment
150-----------------------------------
151
152To establish a basic REPL environment, ``console`` component provides several useful APIs, combining those functions described above.
153
154In a typical application, you only need to call :cpp:func:`esp_console_new_repl_uart` to initialize the REPL environment based on UART device, including driver install, basic console configuration, spawning a thread to do REPL task and register several useful commands (e.g. `help`).
155
156After that, you can register your own commands with :cpp:func:`esp_console_cmd_register`. The REPL environment keeps in init state until you call :cpp:func:`esp_console_start_repl`.
157
158Application Example
159-------------------
160
161Example application illustrating usage of the ``console`` component is available in :example:`system/console` directory. This example shows how to initialize UART and VFS functions, set up linenoise library, read and handle commands from UART, and store command history in Flash. See README.md in the example directory for more details.
162
163Besides that, ESP-IDF contains several useful examples which based on `console` component and can be treated as "tools" when developing applications. For example, :example:`peripherals/i2c/i2c_tools`, :example:`wifi/iperf`.
164
165API Reference
166-------------
167
168.. include-build-file:: inc/esp_console.inc
169