From 197e919d74ceab7d0f588618dc87609e32fc596e Mon Sep 17 00:00:00 2001 From: Jakob Hasse Date: Thu, 29 Jun 2023 12:09:23 +0800 Subject: [PATCH] refactor(examples/console): Warn if secondary console is active Having a secondary serial console is not useful when applications use a REPL console type, hence we warn for it in examples. Closes https://github.com/espressif/esp-idf/issues/11731 --- docs/en/api-reference/system/console.rst | 4 ++++ .../console/advanced/main/console_example_main.c | 11 +++++++++++ examples/system/console/advanced/sdkconfig.defaults | 3 +++ .../advanced_usb_cdc/main/console_usb_example_main.c | 11 +++++++++++ .../console/advanced_usb_cdc/sdkconfig.defaults | 3 +++ examples/system/console/basic/README.md | 2 ++ .../system/console/basic/main/console_example_main.c | 11 +++++++++++ examples/system/console/basic/sdkconfig.defaults | 3 +++ 8 files changed, 48 insertions(+) diff --git a/docs/en/api-reference/system/console.rst b/docs/en/api-reference/system/console.rst index 64616ee7ef..cb61883007 100644 --- a/docs/en/api-reference/system/console.rst +++ b/docs/en/api-reference/system/console.rst @@ -14,6 +14,10 @@ ESP-IDF provides ``console`` component, which includes building blocks needed to These features 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. +.. note:: + + When using a console application on a chip that supports a hardware USB serial interface, we suggest to disable the secondary serial console output. The secondary output will be output-only and consequently does not make sense in an interactive application. + Line editing ------------ diff --git a/examples/system/console/advanced/main/console_example_main.c b/examples/system/console/advanced/main/console_example_main.c index 2c9eb8fc79..b83b5ab77f 100644 --- a/examples/system/console/advanced/main/console_example_main.c +++ b/examples/system/console/advanced/main/console_example_main.c @@ -24,6 +24,17 @@ #include "cmd_wifi.h" #include "cmd_nvs.h" +/* + * We warn if a secondary serial console is enabled. A secondary serial console is always output-only and + * hence not very useful for interactive console applications. If you encounter this warning, consider disabling + * the secondary serial console in menuconfig unless you know what you are doing. + */ +#if SOC_USB_SERIAL_JTAG_SUPPORTED +#if !CONFIG_ESP_CONSOLE_SECONDARY_NONE +#warning "A secondary serial console is not useful when using the console component. Please disable it in menuconfig." +#endif +#endif + #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 diff --git a/examples/system/console/advanced/sdkconfig.defaults b/examples/system/console/advanced/sdkconfig.defaults index 2d3564c649..e4dfabc50b 100644 --- a/examples/system/console/advanced/sdkconfig.defaults +++ b/examples/system/console/advanced/sdkconfig.defaults @@ -15,3 +15,6 @@ CONFIG_FREERTOS_USE_TRACE_FACILITY=y CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS=y CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y + +# On chips with USB serial, disable secondary console which does not make sense when using console component +CONFIG_ESP_CONSOLE_SECONDARY_NONE=y diff --git a/examples/system/console/advanced_usb_cdc/main/console_usb_example_main.c b/examples/system/console/advanced_usb_cdc/main/console_usb_example_main.c index 25f1c6beec..b81b2a911c 100644 --- a/examples/system/console/advanced_usb_cdc/main/console_usb_example_main.c +++ b/examples/system/console/advanced_usb_cdc/main/console_usb_example_main.c @@ -27,6 +27,17 @@ #include "cmd_system.h" #include "cmd_wifi.h" +/* + * We warn if a secondary serial console is enabled. A secondary serial console is always output-only and + * hence not very useful for interactive console applications. If you encounter this warning, consider disabling + * the secondary serial console in menuconfig unless you know what you are doing. + */ +#if SOC_USB_SERIAL_JTAG_SUPPORTED +#if !CONFIG_ESP_CONSOLE_SECONDARY_NONE +#warning "A secondary serial console is not useful when using the console component. Please disable it in menuconfig." +#endif +#endif + static void initialize_nvs(void) { esp_err_t err = nvs_flash_init(); diff --git a/examples/system/console/advanced_usb_cdc/sdkconfig.defaults b/examples/system/console/advanced_usb_cdc/sdkconfig.defaults index 4cc7e875b0..7473761a40 100644 --- a/examples/system/console/advanced_usb_cdc/sdkconfig.defaults +++ b/examples/system/console/advanced_usb_cdc/sdkconfig.defaults @@ -1,6 +1,9 @@ # Enable USB console CONFIG_ESP_CONSOLE_USB_CDC=y +# On chips with USB serial, disable secondary console which does not make sense when using console component +CONFIG_ESP_CONSOLE_SECONDARY_NONE=y + # Reduce bootloader log verbosity CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y CONFIG_BOOTLOADER_LOG_LEVEL=2 diff --git a/examples/system/console/basic/README.md b/examples/system/console/basic/README.md index f1ac0d4ba0..f4d5eb110a 100644 --- a/examples/system/console/basic/README.md +++ b/examples/system/console/basic/README.md @@ -21,6 +21,8 @@ When UART interface is used, this example should run on any commonly available E ### Using with USB_SERIAL_JTAG +*NOTE: We recommend to disable the secondary console output on chips with USB_SERIAL_JTAG since the secondary serial is output-only and would not be very useful when using a console application. This is why the secondary console output is deactivated per default (CONFIG_ESP_CONSOLE_SECONDARY_NONE=y)* + 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. diff --git a/examples/system/console/basic/main/console_example_main.c b/examples/system/console/basic/main/console_example_main.c index d62f98b941..2ce8565a15 100644 --- a/examples/system/console/basic/main/console_example_main.c +++ b/examples/system/console/basic/main/console_example_main.c @@ -20,6 +20,17 @@ #include "cmd_wifi.h" #include "cmd_nvs.h" +/* + * We warn if a secondary serial console is enabled. A secondary serial console is always output-only and + * hence not very useful for interactive console applications. If you encounter this warning, consider disabling + * the secondary serial console in menuconfig unless you know what you are doing. + */ +#if SOC_USB_SERIAL_JTAG_SUPPORTED +#if !CONFIG_ESP_CONSOLE_SECONDARY_NONE +#warning "A secondary serial console is not useful when using the console component. Please disable it in menuconfig." +#endif +#endif + static const char* TAG = "example"; #define PROMPT_STR CONFIG_IDF_TARGET diff --git a/examples/system/console/basic/sdkconfig.defaults b/examples/system/console/basic/sdkconfig.defaults index 2d3564c649..e4dfabc50b 100644 --- a/examples/system/console/basic/sdkconfig.defaults +++ b/examples/system/console/basic/sdkconfig.defaults @@ -15,3 +15,6 @@ CONFIG_FREERTOS_USE_TRACE_FACILITY=y CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS=y CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y + +# On chips with USB serial, disable secondary console which does not make sense when using console component +CONFIG_ESP_CONSOLE_SECONDARY_NONE=y