kopia lustrzana https://github.com/espressif/esp-idf
examples: support USB_CDC and USB_SERIAL_JTAG in basic console example
Related to https://github.com/espressif/esp-idf/issues/8738 Related to https://github.com/espressif/esp-idf/issues/8879 Doesn’t implement USB_CDC (over USB_OTG peripheral) for ESP32-S3 yet; this only works on ESP32-S2 for now. On ESP32-S3 it is now possible to use USB_SERIAL_JTAG console.pull/8968/head
rodzic
11c67d175f
commit
3390d2a2d1
|
@ -1,24 +1,48 @@
|
|||
# Console Example
|
||||
# Basic Console Example (`esp_console_repl`)
|
||||
|
||||
(See the README.md file in the upper level 'examples' directory for more information about examples.)
|
||||
|
||||
This 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 ESP chip. The interactive shell running on the ESP chip can then be controlled/interacted with over a serial port (UART).
|
||||
This example illustrates the usage of the REPL (Read-Eval-Print Loop) APIs 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 ESP chip. The interactive shell running on the ESP chip can then be controlled/interacted with over a serial interface. This example supports UART and USB interfaces.
|
||||
|
||||
The 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).
|
||||
|
||||
Compared to the [advanced console example](../advanced), this example requires less code to initialize and run the console. `esp_console_repl` API handles most of the details. If you'd like to customize the way console works (for example, process console commands in an existing task), please check the advanced console example.
|
||||
|
||||
## How to use example
|
||||
|
||||
### Hardware Required
|
||||
This example can be used on boards with UART and USB interfaces. The sections below explain how to set up the board and configure the example.
|
||||
|
||||
This example should be able to run on any commonly available Espressif development board.
|
||||
### Using with UART
|
||||
|
||||
### Configure the project
|
||||
When UART interface is used, this example should run on any commonly available Espressif development board. UART interface is enabled by default (`CONFIG_ESP_CONSOLE_UART_DEFAULT` option in menuconfig). No extra configuration is required.
|
||||
|
||||
```
|
||||
idf.py menuconfig
|
||||
```
|
||||
### Using with USB_SERIAL_JTAG
|
||||
|
||||
* Enable/disable `Example Configuration > Store command history in flash` as necessary
|
||||
On chips with USB_SERIAL_JTAG peripheral, console example can be used over the USB serial port.
|
||||
|
||||
* First, connect the USB cable to the USB_SERIAL_JTAG interface.
|
||||
* Second, run `idf.py menuconfig` and enable `CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG` option.
|
||||
|
||||
For more details about connecting and configuring USB_SERIAL_JTAG (including pin numbers), see the IDF Programming Guide:
|
||||
* [ESP32-C3 USB_SERIAL_JTAG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32c3/api-guides/usb-serial-jtag-console.html)
|
||||
* [ESP32-S3 USB_SERIAL_JTAG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/api-guides/usb-serial-jtag-console.html)
|
||||
|
||||
### Using with USB CDC (USB_OTG peripheral)
|
||||
|
||||
USB_OTG peripheral can also provide a USB serial port which works with this example.
|
||||
|
||||
* First, connect the USB cable to the USB_OTG peripheral interface.
|
||||
* Second, run `idf.py menuconfig` and enable `CONFIG_ESP_CONSOLE_USB_CDC` option.
|
||||
|
||||
For more details about connecting and configuring USB_OTG (including pin numbers), see the IDF Programming Guide:
|
||||
* [ESP32-S2 USB_OTG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s2/api-guides/usb-otg-console.html)
|
||||
* [ESP32-S3 USB_OTG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/api-guides/usb-otg-console.html)
|
||||
|
||||
### Other configuration options
|
||||
|
||||
This example has an option to store the command history in Flash. This option is enabled by default.
|
||||
|
||||
To disable this, run `idf.py menuconfig` and disable `CONFIG_CONSOLE_STORE_HISTORY` option.
|
||||
|
||||
### Build and Flash
|
||||
|
||||
|
@ -36,7 +60,9 @@ See the Getting Started Guide for full steps to configure and use ESP-IDF to bui
|
|||
|
||||
## Example Output
|
||||
|
||||
Enter 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.
|
||||
Enter 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.
|
||||
|
||||
On ESP32, GPIO15 may be connected to GND to remove the boot log output.
|
||||
|
||||
```
|
||||
This is an example of ESP-IDF console component.
|
||||
|
@ -119,33 +145,3 @@ Line editing and history features are disabled.
|
|||
On Windows, try using Putty instead.
|
||||
esp32>
|
||||
```
|
||||
|
||||
## Example Breakdown
|
||||
|
||||
### Configuring UART
|
||||
|
||||
The ``initialize_console()`` function in the example configures some aspects of UART relevant to the operation of the console.
|
||||
|
||||
- **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:
|
||||
- When 'enter' key is pressed on the keyboard, `CR` (0x13) code is sent to the serial device.
|
||||
- To move the cursor to the beginning of the next line, serial device needs to send `CR LF` (0x13 0x10) sequence.
|
||||
|
||||
### Line editing
|
||||
|
||||
The main source file of the example illustrates how to use `linenoise` library, including line completion, hints, and history.
|
||||
|
||||
### Commands
|
||||
|
||||
Several 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.
|
||||
|
||||
### Command handling
|
||||
|
||||
Main loop inside `app_main()` function illustrates how to use `linenoise` and `esp_console_run()` to implement read/eval loop.
|
||||
|
||||
### Argument parsing
|
||||
|
||||
Several commands implemented in `cmd_wifi.c` and `cmd_system.c` use the Argtable3 library to parse and check the arguments.
|
||||
|
||||
### Command history
|
||||
|
||||
Each 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.
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
/* Console example
|
||||
/* Basic console example (esp_console_repl API)
|
||||
|
||||
This example code is in the Public Domain (or CC0 licensed, at your option.)
|
||||
|
||||
|
@ -16,10 +16,6 @@
|
|||
#include "esp_vfs_fat.h"
|
||||
#include "nvs.h"
|
||||
#include "nvs_flash.h"
|
||||
|
||||
#ifdef CONFIG_ESP_CONSOLE_USB_CDC
|
||||
#error This example is incompatible with USB CDC console. Please try "console_usb" example instead.
|
||||
#endif // CONFIG_ESP_CONSOLE_USB_CDC
|
||||
#include "cmd_system.h"
|
||||
#include "cmd_wifi.h"
|
||||
#include "cmd_nvs.h"
|
||||
|
@ -65,7 +61,6 @@ void app_main(void)
|
|||
{
|
||||
esp_console_repl_t *repl = NULL;
|
||||
esp_console_repl_config_t repl_config = ESP_CONSOLE_REPL_CONFIG_DEFAULT();
|
||||
esp_console_dev_uart_config_t uart_config = ESP_CONSOLE_DEV_UART_CONFIG_DEFAULT();
|
||||
/* Prompt to be printed before each line.
|
||||
* This can be customized, made dynamic, etc.
|
||||
*/
|
||||
|
@ -88,7 +83,21 @@ void app_main(void)
|
|||
register_wifi();
|
||||
register_nvs();
|
||||
|
||||
ESP_ERROR_CHECK(esp_console_new_repl_uart(&uart_config, &repl_config, &repl));
|
||||
#if defined(CONFIG_ESP_CONSOLE_UART_DEFAULT) || defined(CONFIG_ESP_CONSOLE_UART_CUSTOM)
|
||||
esp_console_dev_uart_config_t hw_config = ESP_CONSOLE_DEV_UART_CONFIG_DEFAULT();
|
||||
ESP_ERROR_CHECK(esp_console_new_repl_uart(&hw_config, &repl_config, &repl));
|
||||
|
||||
#elif defined(CONFIG_ESP_CONSOLE_USB_CDC)
|
||||
esp_console_dev_usb_cdc_config_t hw_config = ESP_CONSOLE_DEV_CDC_CONFIG_DEFAULT();
|
||||
ESP_ERROR_CHECK(esp_console_new_repl_usb_cdc(&hw_config, &repl_config, &repl));
|
||||
|
||||
#elif defined(CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG)
|
||||
esp_console_dev_usb_serial_jtag_config_t hw_config = ESP_CONSOLE_DEV_USB_SERIAL_JTAG_CONFIG_DEFAULT();
|
||||
ESP_ERROR_CHECK(esp_console_new_repl_usb_serial_jtag(&hw_config, &repl_config, &repl));
|
||||
|
||||
#else
|
||||
#error Unsupported console type
|
||||
#endif
|
||||
|
||||
ESP_ERROR_CHECK(esp_console_start_repl(repl));
|
||||
}
|
||||
|
|
Ładowanie…
Reference in New Issue