Merge branch 'refactor/secondary_console_usb_serial_improvement' into 'master'

refactor(console): Warn if secondary console is active

Closes IDFGH-10484

See merge request espressif/esp-idf!24494

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
 ------------
 

docs/zh_CN/api-reference/system/console.rst

@@ -14,6 +14,10 @@ ESP-IDF 提供了 ``console`` 组件，它包含了开发基于串口的交互
 
   这些功能模块可以一起使用也可以独立使用，例如仅使用行编辑和命令注册的功能，然后使用 ``getopt`` 函数或者自定义的函数来实现参数解析，而不是直接使用 `argtable3 <https://www.argtable.org/>`_ 库。同样地，还可以使用更简单的命令输入方法（比如 ``fgets`` 函数）和其他用于命令分割和参数解析的方法。
 
+.. note::
+
+  当在支持硬件 USB 串行接口的芯片上使用控制台应用程序时，建议禁用次级串口控制台输出。次级输出仅用于显示，对于交互式应用程序没有任何作用。
+
 行编辑
 ------
 

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

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

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

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

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.

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
 

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