docs: update using usb_serial_jtag documents

This commit is contained in:
Cao Sen Miao 2021-11-12 14:16:53 +08:00
parent 7e9d90ca22
commit a42a1f85f5
3 changed files with 21 additions and 6 deletions

View File

@ -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: 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 <tools/idf-monitor>` or another serial monitor * Bidirectional serial console, which can be used with :doc:`IDF Monitor <tools/idf-monitor>` or another serial monitor.
* Flashing using ``esptool.py`` and ``idf.py flash``. * 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 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: Connect {IDF_TARGET_NAME} to the USB port as follows:
+------+-------------+ +------+-------------+
| GPIO | USB | | 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) | | 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. 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 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. 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). 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).

View File

@ -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`. 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 Application Example
------------------- -------------------

View File

@ -168,6 +168,9 @@ Linenoise 库不需要显式地初始化,但是在调用行编辑函数之前
之后你可以使用 :cpp:func:`esp_console_cmd_register` 来注册其它命令。REPL 环境在初始化后需要再调用 :cpp:func:`esp_console_start_repl` 函数才能开始运行。 之后你可以使用 :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` 函数进行初始化,然后再照常调用其它函数。
应用程序示例 应用程序示例
------------ ------------