From 3390d2a2d18c289b0b1e1cf121bf6670099641db Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Tue, 3 May 2022 19:47:38 +0200 Subject: [PATCH] examples: support USB_CDC and USB_SERIAL_JTAG in basic console example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- examples/system/console/basic/README.md | 76 +++++++++---------- .../console/basic/main/console_example_main.c | 23 ++++-- 2 files changed, 52 insertions(+), 47 deletions(-) diff --git a/examples/system/console/basic/README.md b/examples/system/console/basic/README.md index feb2417cee..67a67be03b 100644 --- a/examples/system/console/basic/README.md +++ b/examples/system/console/basic/README.md @@ -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. diff --git a/examples/system/console/basic/main/console_example_main.c b/examples/system/console/basic/main/console_example_main.c index 12923237d4..26fc3d4d5b 100644 --- a/examples/system/console/basic/main/console_example_main.c +++ b/examples/system/console/basic/main/console_example_main.c @@ -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)); }