mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: provide CN translation for api-guides/usb-serial-jtag-console.rst
This commit is contained in:
caixinying-git
parent
a416c12e9d
commit
a876c2d888
@ -2,13 +2,19 @@
|
||||
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:
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Generally, ESP chips implement a serial port using UART and can be connected to a serial console emulator on a host/PC via an external USB-UART bridge chip. However, on ESP chips that contain a USB Serial/JTAG Controller, the CDC-ACM portion of the controller implements a serial port that is connected directly to a host/PC, thus does not require an external USB-UART bridge chip.
|
||||
|
||||
{IDF_TARGET_NAME} contains a USB Serial/JTAG Controller providing the following functions:
|
||||
|
||||
* 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, performed simultaneously with serial operations using tools like OpenOCD.
|
||||
|
||||
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.
|
||||
.. note::
|
||||
|
||||
The USB Serial/JTAG Controller is a fixed-function USB device that is implemented entirely in hardware, meaning that it cannot be reconfigured to perform any function other than a serial port and JTAG debugging functionality. This is in contrast to the USB OTG controllers in some ESP chips that can be configured to perform the function of multiple types of USB devices.
|
||||
|
||||
Hardware Requirements
|
||||
=====================
|
||||
@ -18,59 +24,97 @@ Hardware Requirements
|
||||
|
||||
Connect {IDF_TARGET_NAME} to the USB port as follows:
|
||||
|
||||
+------+-------------+
|
||||
| GPIO | USB |
|
||||
+======+=============+
|
||||
| {IDF_TARGET_USB_DP_GPIO} | D+ (green) |
|
||||
+------+-------------+
|
||||
| {IDF_TARGET_USB_DM_GPIO} | D- (white) |
|
||||
+------+-------------+
|
||||
| GND | GND (black) |
|
||||
+------+-------------+
|
||||
| | +5V (red) |
|
||||
+------+-------------+
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 40 60
|
||||
:align: center
|
||||
|
||||
Some development boards may offer a USB connector for the USB Serial/JTAG Controller — in that case, no extra connections are required.
|
||||
* - GPIO
|
||||
- USB
|
||||
* - {IDF_TARGET_USB_DP_GPIO}
|
||||
- D+ (green)
|
||||
* - {IDF_TARGET_USB_DM_GPIO}
|
||||
- D- (white)
|
||||
* - GND
|
||||
- GND (black)
|
||||
* - 5V (or externally supplied)
|
||||
- +5V (red)
|
||||
|
||||
Some development boards may offer a USB connector for the USB Serial/JTAG Controller. In that case, no extra connections are required.
|
||||
|
||||
Software Configuration
|
||||
======================
|
||||
|
||||
USB console feature can be enabled using ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`` option in menuconfig tool (see :ref:`CONFIG_ESP_CONSOLE_UART`).
|
||||
The USB Serial/JTAG Controller can be used as the serial port by selecting ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`` in the :ref:`CONFIG_ESP_CONSOLE_UART` option. Once selected, building and flashing the project can occur 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.
|
||||
Alternatively, you can access the output through the ``usb_serial_jtag`` port but make sure ``CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG`` is selected in the :ref:`CONFIG_ESP_CONSOLE_SECONDARY`.
|
||||
|
||||
.. warning::
|
||||
|
||||
Besides output, if you also want to input or use REPL with console, please select ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG``.
|
||||
Besides output, if you also want to input or use REPL with the console, please select ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG``.
|
||||
|
||||
Uploading the Application
|
||||
=========================
|
||||
|
||||
The USB Serial/JTAG Controller is able to put the {IDF_TARGET_NAME} into download mode automatically. Simply flash as usual, but specify the USB Serial/JTAG Controller port on your system: ``idf.py flash -p PORT`` where ``PORT`` is the name of the proper port.
|
||||
The USB Serial/JTAG Controller is able to put the {IDF_TARGET_NAME} into download mode automatically. Simply flash as usual, but specify the USB Serial/JTAG Controller port on your system: ``idf.py flash -p PORT``, where ``PORT`` is the name of the proper port.
|
||||
|
||||
.. note::
|
||||
|
||||
The USB Serial/JTAG Controller's serial port usually appears:
|
||||
|
||||
- as ``/dev/ttyACM*`` on Linux
|
||||
- as ``/dev/cu*`` on Mac
|
||||
- as a ``COM*`` port in the Windows Device Manager
|
||||
|
||||
Limitations
|
||||
===========
|
||||
|
||||
There are several limitations to the USB Serial/JTAG console feature. These may or may not be significant, depending on the type of application being developed, and the development workflow.
|
||||
{IDF_TARGET_BOOT_PIN:default = "Not Updated!", esp32c3 = "GPIO9", esp32s3 = "GPIO0", esp32c6 = "GPIO9"}
|
||||
|
||||
There are several limitations to the USB Serial/JTAG console feature. The significance of these limitations depends on the type of application being developed, and the development workflow.
|
||||
|
||||
{IDF_TARGET_BOOT_PIN:default = "Not Updated!", esp32c3 = "GPIO9", esp32s3 = "GPIO0", esp32c6 = "GPIO9"}
|
||||
|
||||
1. If the application accidentally reconfigures the USB peripheral pins, or disables the USB Serial/JTAG Controller, the device will disappear from the system. After fixing the issue in the application, you will need to manually put the {IDF_TARGET_NAME} into download mode by pulling low {IDF_TARGET_BOOT_PIN} and resetting the chip.
|
||||
USB Pin Reconfiguration
|
||||
-----------------------
|
||||
|
||||
2. If the application enters deep sleep mode, the USB Serial/JTAG device will disappear from the system.
|
||||
If the application accidentally reconfigures the USB peripheral pins or disables the USB Serial/JTAG Controller, the device disappears from the system. After fixing the issue in the application, you need to manually put the {IDF_TARGET_NAME} into download mode by pulling low {IDF_TARGET_BOOT_PIN} and resetting the chip.
|
||||
|
||||
3. For data sent in the direction of {IDF_TARGET_NAME} to PC Terminal (e.g. stdout, logs), the {IDF_TARGET_NAME} first writes to a small internal buffer. If this buffer becomes full (for example, if no PC Terminal is connected), the {IDF_TARGET_NAME} will do a one-time wait of 50ms hoping for the PC Terminal to request the data. This can appear as a very brief 'pause' in your application.
|
||||
If the application enters Deep-sleep mode, the USB Serial/JTAG device disappears from the system.
|
||||
|
||||
4. For data sent in the PC Terminal to {IDF_TARGET_NAME} direction (e.g. console commands), many PC Terminals will wait for the {IDF_TARGET_NAME} to ingest the bytes before allowing you to sending more data. This is in contrast to using a USB-to-Serial (UART) bridge chip, which will always ingest the bytes and send them to a (possibly not listening) {IDF_TARGET_NAME}.
|
||||
Data Buffering
|
||||
--------------
|
||||
|
||||
For data transmitted from {IDF_TARGET_NAME} to PC Terminal (e.g., stdout, logs), the {IDF_TARGET_NAME} first writes to a small internal buffer. After this buffer becomes full (for example, if no PC Terminal is connected), the {IDF_TARGET_NAME} does a one-time wait of 50 ms for the PC Terminal to request the data. This can appear as a very brief pause in your application.
|
||||
|
||||
For data transmitted from the PC Terminal to {IDF_TARGET_NAME} (e.g., console commands), many PC Terminals wait for the {IDF_TARGET_NAME} to ingest the bytes before allowing you to send more data. This is in contrast to using a USB-to-Serial (UART) bridge chip, which always ingests the bytes and sends them to a (possibly not listening) {IDF_TARGET_NAME}.
|
||||
|
||||
Sleep Mode Considerations
|
||||
-------------------------
|
||||
|
||||
The USB Serial/JTAG controller and its associated USB PHY are driven by particular clocks (e.g., APB and USB PHY clock) and belong to a particular power domain (e.g., digital power domain). Thus, any change to the clock and power domains associated with the USB Serial/JTAG controller, such as entering different sleep modes, can affect the controller's operation.
|
||||
|
||||
Deep Sleep
|
||||
^^^^^^^^^^
|
||||
|
||||
When entering deep sleep, both the USB Serial/JTAG controller and the USB PHY are powered off, leading to the USB PHY's D+ line no longer being pulled up. As a result:
|
||||
|
||||
- When entering deep sleep, the USB Serial/JTAG device appears disconnected from the host/PC (even if the USB cable is still physically connected).
|
||||
- When exiting deep sleep, the USB Serial/JTAG device reconnects to the host/PC.
|
||||
|
||||
Light Sleep
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. only:: not SOC_USB_SERIAL_JTAG_SUPPORT_LIGHT_SLEEP
|
||||
|
||||
5. The USB Serial/JTAG controller will not work during sleep (both light and deep sleep) due to the lack of an APB and USB PHY clock during sleep. Thus, entering sleep has the following implications on the USB Serial/JTAG controller:
|
||||
When entering light sleep, the APB and USB PHY clock are gated. Thus, the USB Serial/JTAG controller is no longer able to receive or respond to any USB transactions from the connected host (including periodic CDC Data IN transactions). As a result:
|
||||
|
||||
i. Both the APB clock and the USB PHY clock (derived form the main PLL clock) will be disabled during sleep. As a result, the USB Serial/JTAG controller will not be able receive or respond to any USB transactions from the connected host (including periodic CDC Data IN transactions). Thus it may appear to the host that the USB Serial/JTAG controller has disconnected.
|
||||
- when entering light sleep, the USB Serial/JTAG device is unresponsive to the host/PC's USB CDC driver. The host/PC may then report the USB Serial/JTAG device as disconnected or erroneous (even if the USB cable is still physically connected).
|
||||
- when exiting light sleep, it is possible that the host/PC does not re-enumerate (i.e., reconnect) the USB Serial/JTAG device given that the USB PHY's D+ line remains pulled up state during light sleep. Users may need to physically disconnect and then reconnect the USB cable.
|
||||
|
||||
ii. If users enter sleep manually (via :cpp:func:`esp_light_sleep_start` or :cpp:func:`esp_deep_sleep_start`), users should be cognizant of the fact that USB Serial/JTAG controller will not work during sleep. ESP-IDF **does not add any safety check to reject entry to sleep** even if the USB Serial/JTAG controller is connected. In the case where sleep is entered while the USB Serial/JTAG controller is connected, connection can be re-established by unplugging and re-plugging the USB cable.
|
||||
Automatic and Manual Sleep Entry
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
iii. If users enter sleep automatically (via :cpp:func:`esp_pm_configure`), enabling the :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` option will allow the {IDF_TARGET_NAME} to automatically detect whether the USB Serial/JTAG controller is currently connected to a host, and prevent automatic entry to sleep as long as the connection persists. However, note that this option will increase power consumption.
|
||||
If users enter sleep manually (via :cpp:func:`esp_light_sleep_start` or :cpp:func:`esp_deep_sleep_start`), users should be cognizant of the fact that USB Serial/JTAG controller does not work during sleep. ESP-IDF **does not add any safety check to reject entry to sleep** even if the USB Serial/JTAG controller is connected. In the case where sleep is entered while the USB Serial/JTAG controller is connected, the connection can be re-established by unplugging and re-plugging the USB cable.
|
||||
|
||||
If users enter sleep automatically (via :cpp:func:`esp_pm_configure`), enabling the :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` option allows the {IDF_TARGET_NAME} to automatically detect whether the USB Serial/JTAG controller is currently connected to a host, and prevent automatic entry to sleep as long as the connection persists. However, note that this option increases power consumption.
|
||||
|
||||
@ -1 +1,120 @@
|
||||
.. include:: ../../en/api-guides/usb-serial-jtag-console.rst
|
||||
**********************************
|
||||
USB 串行/JTAG 控制器控制台
|
||||
**********************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
ESP 芯片通常使用 UART 实现串口，并可以通过外部 USB-UART 桥接芯片，连接到主机/PC 上的串口控制台仿真器。然而，在具有 USB 串行/JTAG 控制器的 ESP 芯片上，控制器的 CDC-ACM 部分即可实现串口，该串口直接连接到主机/PC，不需要外部 USB-UART 桥接芯片。
|
||||
|
||||
拥有 USB 串行/JTAG 控制器时，{IDF_TARGET_NAME} 支持以下功能：
|
||||
|
||||
* 双向串行控制台，可与 :doc:`IDF 监视器 <tools/idf-monitor>` 或其他串行监视器一起使用。
|
||||
* 使用 ``esptool.py`` 和 ``idf.py flash`` 烧录。
|
||||
* 使用 OpenOCD 等工具进行 JTAG 调试，同时进行串行操作。
|
||||
|
||||
.. note::
|
||||
|
||||
USB 串行/JTAG 控制器是一个 USB 设备，其功能固定，完全由硬件实现。也就是说，即便重新配置，它也只能执行串口和 JTAG 调试功能。这不同于某些 ESP 芯片中的 USB OTG 控制器，后者经配置，可以执行多种 USB 设备功能。
|
||||
|
||||
硬件要求
|
||||
=====================
|
||||
|
||||
{IDF_TARGET_USB_DP_GPIO:default="未更新！",esp32c3="19",esp32s3="20", esp32c6="13", esp32h2="27"}
|
||||
{IDF_TARGET_USB_DM_GPIO:default="未更新！",esp32c3="18",esp32s3="19", esp32c6="12", esp32h2="26"}
|
||||
|
||||
将 {IDF_TARGET_NAME} 连接到 USB 端口，连接方式如下：
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 40 60
|
||||
:align: center
|
||||
|
||||
* - GPIO
|
||||
- USB
|
||||
* - {IDF_TARGET_USB_DP_GPIO}
|
||||
- D+（绿）
|
||||
* - {IDF_TARGET_USB_DM_GPIO}
|
||||
- D-（白）
|
||||
* - GND
|
||||
- GND（黑）
|
||||
* - 5V（或由外部提供）
|
||||
- +5V（红）
|
||||
|
||||
部分开发板可能会为 USB 串行/JTAG 控制器提供 USB 连接器，此时无需额外连接。
|
||||
|
||||
软件配置
|
||||
======================
|
||||
|
||||
在 :ref:`CONFIG_ESP_CONSOLE_UART` 选项中选择 ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG``，可以将 USB 串行/JTAG 控制器用作串口。选择该选项后，即可正常构建和烧录项目。
|
||||
|
||||
另外，也可以通过 ``usb_serial_jtag`` 端口访问输出，但请确保在 :ref:`CONFIG_ESP_CONSOLE_SECONDARY` 选项中选择了 ``CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG``。
|
||||
|
||||
.. warning::
|
||||
|
||||
除输出外，如果还想用控制台输入或使用交互式解释器 (REPL)，请选择 ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`` 选项。
|
||||
|
||||
上传应用程序
|
||||
=========================
|
||||
|
||||
USB 串行/JTAG 控制器可以自动将 {IDF_TARGET_NAME} 置于下载模式。用户只需正常烧录芯片，但需要在系统上指定 USB 串行/JTAG 控制器端口：``idf.py flash -p PORT``，``PORT`` 是正确的端口名称。
|
||||
|
||||
.. note::
|
||||
|
||||
USB 串行/JTAG 控制器的串行端口通常：
|
||||
|
||||
- 在 Linux 系统上显示为 ``/dev/ttyACM*``
|
||||
- 在 MAC 系统上显示为 ``/dev/cu*``
|
||||
- 在 Windows 设备管理器上显示为 ``COM*`` 端口
|
||||
|
||||
限制
|
||||
===========
|
||||
|
||||
{IDF_TARGET_BOOT_PIN:default = "未更新！", esp32c3 = "GPIO9", esp32s3 = "GPIO0", esp32c6 = "GPIO9"}
|
||||
|
||||
USB 串行/JTAG 控制台功能存在一些限制，这些限制的影响程度各不相同，具体取决于开发中的应用程序类型，以及开发的工作流程。
|
||||
|
||||
{IDF_TARGET_BOOT_PIN:default = "未更新！", esp32c3 = "GPIO9", esp32s3 = "GPIO0", esp32c6 = "GPIO9"}
|
||||
|
||||
重新配置 USB 管脚
|
||||
-----------------------
|
||||
|
||||
如果在意外情况下，应用程序重新配置了 USB 外设管脚，或禁用了 USB 串行/JTAG 控制器，设备会从系统消失。应用程序中的问题修复后，需要将 {IDF_TARGET_BOOT_PIN} 拉低，并重置芯片，手动将 {IDF_TARGET_NAME} 置于下载模式。
|
||||
|
||||
如果应用程序进入 Deep-sleep 模式，USB 串行/JTAG 设备会从系统中消失。
|
||||
|
||||
数据缓冲
|
||||
--------------
|
||||
|
||||
对于从 {IDF_TARGET_NAME} 发送到 PC 终端的数据（例如 stdout、日志），{IDF_TARGET_NAME} 会先写入一个小型内部缓冲区。如果该缓冲区达到最大容量（例如没有连接 PC 终端），{IDF_TARGET_NAME} 会进行一次等待，时长约 50 ms。在此期间，PC 终端可以请求数据，但可能会导致应用程序出现非常短暂的暂停。
|
||||
|
||||
对于从 PC 终端发送到 {IDF_TARGET_NAME} 的数据（如控制台命令），许多 PC 终端会等待 {IDF_TARGET_NAME} 接收字节后，再允许发送更多数据。这与使用 USB 转串口 (URAT) 桥接芯片不同，URAT 桥接芯片始终接收字节，并将其发送到（可能未在监听）的 {IDF_TARGET_NAME}。
|
||||
|
||||
睡眠模式考虑因素
|
||||
-------------------------
|
||||
|
||||
USB 串行/JTAG 控制器及其关联的 USB PHY 均由特定时钟控制（如 APB 和 USB PHY 时钟），并属于特定的电源域（如数字电源域）。因此，对 USB 串行/JTAG 控制器关联的时钟和电源域进行任何更改，如进入另一睡眠模式，都可能影响控制器操作。
|
||||
|
||||
Deep-sleep
|
||||
^^^^^^^^^^
|
||||
|
||||
进入 Deep-sleep 模式时，USB 串行/JTAG 控制器及 USB PHY 关闭，导致 USB PHY 的 D+ 线不再变成高电平。因此：
|
||||
|
||||
- 进入 Deep-sleep 模式时，USB 串行/JTAG 设备会对主机/PC 显示为断开连接。即使 USB 电缆在物理层面上处于连接状态，仍会显示为断开连接。
|
||||
- 退出 Deep-sleep 模式时，USB 串行/JTAG 设备会重新连接到主机/PC。
|
||||
|
||||
Light-sleep
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. only:: not SOC_USB_SERIAL_JTAG_SUPPORT_LIGHT_SLEEP
|
||||
|
||||
进入 Light-sleep 模式时，APB 和 USB PHY 时钟关闭。因此，USB 串行/JTAG 控制器将无法接收或响应任何来自相连主机的 USB 事务，包括周期性的 CDC Data IN 事务。因此：
|
||||
|
||||
- 进入 Light-sleep 模式时，USB 串行/JTAG 设备无法响应主机/PC 的 USB CDC 驱动程序。主机/PC 可能会报告 USB 串行/JTAG 设备已断开连接，或连接出错。即使 USB 电缆在物理层面上处于连接状态，仍会显示为断开连接。
|
||||
- 退出 Light-sleep 模式时，由于 USB PHY 的 D+ 线在 Light-sleep 期间始终处于高电平，可能导致主机/PC 不会重新枚举（即重新连接）USB 串行/JTAG 设备。用户可能需要在物理层面上断开 USB 电缆，并重新连接。
|
||||
|
||||
自动与手动进入睡眠模式
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
如果通过 :cpp:func:`esp_light_sleep_start` 或 :cpp:func:`esp_deep_sleep_start` 手动进入睡眠模式，需注意，USB 串行/JTAG 控制器在睡眠期间不工作。ESP-IDF **没有添加任何拒绝进入睡眠的安全检查**，即使 USB 串行/JTAG 控制器已连接，也会进入睡眠模式。如果在连接了 USB 串行/JTAG 控制器的情况下进入睡眠，可以通过拔出并重新插入 USB 电缆来重新建立连接。
|
||||
|
||||
如果通过 :cpp:func:`esp_pm_configure` 自动进入睡眠模式，请启用 :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` 选项，该选项支持 {IDF_TARGET_NAME} 自动检测 USB 串行/JTAG 控制器与主机的连接情况，并在连接持续时，阻止程序自动进入睡眠模式。注意，此选项会增加功耗。
|
||||
Loading…
x
Reference in New Issue
Block a user