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