examples: support USB_CDC and USB_SERIAL_JTAG in basic console example

Related to #8738
Related to #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

@@ -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
+
+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)
 
-* Enable/disable `Example Configuration > Store command history in flash` as necessary
+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.

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));
 }