From a42a1f85f5236e6904fe042330b8560ae1b1743e Mon Sep 17 00:00:00 2001 From: Cao Sen Miao Date: Fri, 12 Nov 2021 14:16:53 +0800 Subject: [PATCH] docs: update using usb_serial_jtag documents --- .../en/api-guides/usb-serial-jtag-console.rst | 21 +++++++++++++------ docs/en/api-reference/system/console.rst | 3 +++ docs/zh_CN/api-reference/system/console.rst | 3 +++ 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/en/api-guides/usb-serial-jtag-console.rst b/docs/en/api-guides/usb-serial-jtag-console.rst index 5808c86c50..6d64aa4547 100644 --- a/docs/en/api-guides/usb-serial-jtag-console.rst +++ b/docs/en/api-guides/usb-serial-jtag-console.rst @@ -4,23 +4,26 @@ USB Serial/JTAG Controller Console On chips with an integrated USB Serial/JTAG Controller, it is possible to use the part of this controller that implements a serial port (CDC) to implement the serial console, instead of using UART with an external USB-UART bridge chip. {IDF_TARGET_NAME} contains this controller, providing the following functions: -* Bidirectional serial console, which can be used with :doc:`IDF Monitor ` or another serial monitor +* Bidirectional serial console, which can be used with :doc:`IDF Monitor ` or another serial monitor. * Flashing using ``esptool.py`` and ``idf.py flash``. -* JTAG debugging using e.g. OpenOCD, simultaneous with serial operations +* JTAG debugging using e.g. OpenOCD, simultaneous with serial operations. -Note that, in contrast with the USB OTG peripheral found in some Espressif chips, the USB Serial/JTAG Controller is a fixed function device, implemented entirely in hardware. This means it cannot be reconfigured to perform any function other than to provide a serial channel and JTAG debugging functionality. +Note that, in contrast with the USB OTG peripheral in some Espressif chips, the USB Serial/JTAG Controller is a fixed function device, implemented entirely in hardware. This means it cannot be reconfigured to perform any function other than to provide a serial channel and JTAG debugging functionality. Hardware Requirements ===================== +{IDF_TARGET_USB_DP_GPIO:default="Not Updated!",esp32c3="19",esp32s3="20"} +{IDF_TARGET_USB_DM_GPIO:default="Not Updated!",esp32c3="18",esp32s3="19"} + Connect {IDF_TARGET_NAME} to the USB port as follows: +------+-------------+ | GPIO | USB | +======+=============+ -| 19 | D+ (green) | +| {IDF_TARGET_USB_DP_GPIO} | D+ (green) | +------+-------------+ -| 18 | D- (white) | +| {IDF_TARGET_USB_DM_GPIO} | D- (white) | +------+-------------+ | GND | GND (black) | +------+-------------+ @@ -36,6 +39,12 @@ USB console feature can be enabled using ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`` Once the option is enabled, build the project as usual. +Alternatively, you can access the output through usb_serial_jtag port but make sure the option ``CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG`` in choice ``ESP_CONSOLE_SECONDARY`` is selected. + +.. warning:: + + Besides output, if you also want to input or use REPL with console, please select ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG``. + Uploading the Application ========================= @@ -52,7 +61,7 @@ There are several limitations to the USB console feature. These may or may not b 2. If the application enters deep sleep mode, USB CDC device will disappear from the system. -3. The behaviour between an actual USB-to-serial bridge chip and the USB Serial/JTAG Controller is slightly different if the ESP-IDF application does not listen for incoming bytes. An USB-to-serial bridge chip will just send the bytes to a (not listening) chip, while the USB Serial/JTAG Controller will block until the application reads the bytes. This can lead to a non-responsive looking terminal program. +3. The behavior between an actual USB-to-serial bridge chip and the USB Serial/JTAG Controller is slightly different if the ESP-IDF application does not listen for incoming bytes. An USB-to-serial bridge chip will just send the bytes to a (not listening) chip, while the USB Serial/JTAG Controller will block until the application reads the bytes. This can lead to a non-responsive looking terminal program. 4. The USB CDC device won't work in sleep modes as normal due to the lack of APB clock in sleep modes. This includes deep-sleep, light-sleep (automataic light-sleep as well). diff --git a/docs/en/api-reference/system/console.rst b/docs/en/api-reference/system/console.rst index 72a7bd7bbd..142a42c260 100644 --- a/docs/en/api-reference/system/console.rst +++ b/docs/en/api-reference/system/console.rst @@ -168,6 +168,9 @@ In a typical application, you only need to call :cpp:func:`esp_console_new_repl_ After that, you can register your own commands with :cpp:func:`esp_console_cmd_register`. The REPL environment keeps in init state until you call :cpp:func:`esp_console_start_repl`. +.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED + + Likewise, if your REPL environment is based on USB_SERIAL_JTAG device, you only need to call :cpp:func:`esp_console_new_repl_usb_serial_jtag` at first step. And call other functions as usual. Application Example ------------------- diff --git a/docs/zh_CN/api-reference/system/console.rst b/docs/zh_CN/api-reference/system/console.rst index b183ef316e..1bd7c323b9 100644 --- a/docs/zh_CN/api-reference/system/console.rst +++ b/docs/zh_CN/api-reference/system/console.rst @@ -168,6 +168,9 @@ Linenoise 库不需要显式地初始化，但是在调用行编辑函数之前 之后你可以使用 :cpp:func:`esp_console_cmd_register` 来注册其它命令。REPL 环境在初始化后需要再调用 :cpp:func:`esp_console_start_repl` 函数才能开始运行。 +.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED + + 同样，如果 REPL 环境是构建在 USB_SERIAL_JTAG 设备基础上，你只需要先调用 :cpp:func:`esp_console_new_repl_usb_serial_jtag` 函数进行初始化，然后再照常调用其它函数。 应用程序示例 ------------