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:
* 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``.
* 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).

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

View File

@ -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` 函数进行初始化,然后再照常调用其它函数。
应用程序示例
------------