mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-19 14:26:01 -04:00
docs: Provide CN Translation for usb-otg-console
This commit is contained in:
shenmengjing
BOT
parent
6b34b6c1fb
commit
29350a2d99
@ -1,10 +1,11 @@
|
||||
***************
|
||||
USB OTG Console
|
||||
***************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
On chips with an integrated USB peripheral, it is possible to use USB Communication Device Class (CDC) to implement the serial console, instead of using UART with an external USB-UART bridge chip. {IDF_TARGET_NAME} ROM code contains a USB CDC implementation, which supports for some basic functionality without requiring the application to include the USB stack:
|
||||
|
||||
* 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``.
|
||||
* :doc:`Device Firmware Update (DFU) <dfu>` interface for flashing the device using ``dfu-util`` and ``idf.py dfu``.
|
||||
|
||||
@ -15,29 +16,33 @@ On chips with an integrated USB peripheral, it is possible to use USB Communicat
|
||||
Hardware Requirements
|
||||
=====================
|
||||
|
||||
Connect {IDF_TARGET_NAME} to the USB port as follows
|
||||
Connect {IDF_TARGET_NAME} to the USB port as follows.
|
||||
|
||||
+------+-------------+
|
||||
| GPIO | USB |
|
||||
+======+=============+
|
||||
| 20 | D+ (green) |
|
||||
+------+-------------+
|
||||
| 19 | D- (white) |
|
||||
+------+-------------+
|
||||
| GND | GND (black) |
|
||||
+------+-------------+
|
||||
| | +5V (red) |
|
||||
+------+-------------+
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 50 50
|
||||
:align: center
|
||||
|
||||
* - GPIO
|
||||
- USB
|
||||
* - 20
|
||||
- D+ (green)
|
||||
* - 19
|
||||
- D- (white)
|
||||
* - GND
|
||||
- GND (black)
|
||||
* -
|
||||
- +5V (red)
|
||||
|
||||
Some development boards may offer a USB connector for the internal USB peripheral — in that case, no extra connections are required.
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
By default, :doc:`USB_SERIAL_JTAG <usb-serial-jtag-console>` module is connected to the internal PHY of the ESP32-S3, while USB_OTG peripheral can be used only if the external USB PHY is connected. Since CDC console is provided via USB_OTG peripheral, it cannot be used through the internal PHY in this configuration.
|
||||
By default, the :doc:`USB_SERIAL_JTAG <usb-serial-jtag-console>` module is connected to the internal PHY of ESP32-S3, while the USB OTG peripheral can be used only if the external USB PHY is connected. Since the CDC console is provided via the USB OTG peripheral, it cannot be used through the internal PHY in this configuration.
|
||||
|
||||
You can permanently switch the internal USB PHY to work with USB_OTG peripheral instead of USB_SERIAL_JTAG by burning ``USB_PHY_SEL`` eFuse. See ESP32-S3 Technical Reference Manual for more details about USB_SERIAL_JTAG and USB_OTG.
|
||||
You can permanently switch the internal USB PHY to work with USB OTG peripheral instead of USB_SERIAL_JTAG by burning ``USB_PHY_SEL`` eFuse. See ESP32-S3 Technical Reference Manual for more details about USB_SERIAL_JTAG and USB OTG.
|
||||
|
||||
Note however that USB_SERIAL_JTAG also provides a CDC console, so enabling the CDC console should not be the primary reason for switching from USB_SERIAL_JTAG to USB_CDC.
|
||||
Note however that USB_SERIAL_JTAG also provides a CDC console, so enabling the CDC console should not be the primary reason for switching from USB_SERIAL_JTAG to USB CDC.
|
||||
|
||||
|
||||
Software Configuration
|
||||
@ -55,7 +60,7 @@ Uploading the Application
|
||||
Initial Upload
|
||||
--------------
|
||||
|
||||
If the {IDF_TARGET_NAME} is not yet flashed with a program that enables a USB console, an initial upload of the program is required. There are 3 alternative options to perform the initial upload.
|
||||
If the {IDF_TARGET_NAME} is not yet flashed with a program that enables a USB console, an initial upload of the program is required. There are three alternative options to perform the initial upload.
|
||||
|
||||
Once the initial upload is done, the application will start up and a USB CDC port will appear in the system.
|
||||
|
||||
@ -68,7 +73,7 @@ Initial Upload Using the ROM Download Mode, over USB CDC
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* Place {IDF_TARGET_NAME} into download mode. To do this, keep GPIO0 low while toggling reset. On many development boards, the "Boot" button is connected to GPIO0, and you can press "Reset" button while holding "Boot".
|
||||
* A serial port will appear in the system. On most operating systems (Windows 8 and later, Linux, macOS) driver installation is not required. Find the port name using Device Manager (Windows) or by listing ``/dev/ttyACM*`` devices on Linux or ``/dev/cu*`` devices on macOS.
|
||||
* A serial port will appear in the system. On most operating systems (Windows 8 and later, Linux, macOS), driver installation is not required. Find the port name using Device Manager (Windows) or by listing ``/dev/ttyACM*`` devices on Linux or ``/dev/cu*`` devices on macOS.
|
||||
* Run ``idf.py flash -p PORT`` to upload the application, with ``PORT`` determined in the previous step.
|
||||
|
||||
Initial Upload Using the ROM Download Mode, over USB DFU
|
||||
@ -98,7 +103,7 @@ There are several limitations to the USB console feature. These may or may not b
|
||||
|
||||
2. If the application accidentally reconfigures the USB peripheral pins, or disables the USB peripheral, USB CDC device will disappear from the system. After fixing the issue in the application, you will need to follow the :ref:`usb_console_initial_upload` process to flash the application again.
|
||||
|
||||
3. If the application enters light sleep (including automatic light sleep) or deep sleep mode, USB CDC device will disappear from the system.
|
||||
3. If the application enters Light-sleep mode (including automatic Light-sleep) or Deep-sleep mode, USB CDC device will disappear from the system.
|
||||
|
||||
4. USB CDC driver reserves some amount of RAM and increases application code size. Keep this in mind if trying to optimize application memory usage.
|
||||
|
||||
@ -111,4 +116,3 @@ There are several limitations to the USB console feature. These may or may not b
|
||||
* When developing applications which use USB peripheral, it is very likely that USB functionality will not work or will not fully work at some moments during development. This can be due to misconfigured USB descriptors, errors in the USB stack usage, or other reasons. In this case, using the UART console for flashing and monitoring provides a much better development experience.
|
||||
|
||||
7. When debugging the application using JTAG, USB CDC may stop working if the CPU is stopped on a breakpoint. USB CDC operation relies on interrupts from the USB peripheral being serviced periodically. If the host computer does not receive valid responses from the USB device side for some time, it may decide to disconnect the device. The actual time depends on the OS and the driver, and ranges from a few hundred milliseconds to a few seconds.
|
||||
|
||||
|
||||
@ -1 +1,118 @@
|
||||
.. include:: ../../en/api-guides/usb-otg-console.rst
|
||||
USB OTG 控制台
|
||||
**************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
在集成了 USB 外设的芯片上，可以使用 USB 通信设备类 (CDC) 来实现串行控制台，而不是使用带有外部 USB-UART 桥接芯片的 UART，{IDF_TARGET_NAME} ROM 中包含 USB CDC 实现，支持一些基本功能，而无需应用程序包含 USB 协议栈：
|
||||
|
||||
* 双向串行控制台，可与 :doc:`IDF 监视器 <tools/idf-monitor>` 或其他串行监视器一起使用。
|
||||
* 使用 ``esptool.py`` 和 ``idf.py flash`` 进行烧录。
|
||||
* :doc:`设备固件更新 (DFU) <dfu>` 接口，可通过 ``dfu-util`` 和 ``dfu-util`` 烧录设备。
|
||||
|
||||
.. note::
|
||||
|
||||
目前，此“USB 控制台”功能与 TinyUSB 协议栈不兼容，但 TinyUSB 可以提供自己的 CDC 实现。
|
||||
|
||||
硬件要求
|
||||
========
|
||||
|
||||
如下所示，将 {IDF_TARGET_NAME} 连接到 USB 端口。
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 50 50
|
||||
:align: center
|
||||
|
||||
* - GPIO
|
||||
- USB
|
||||
* - 20
|
||||
- D+（绿色）
|
||||
* - 19
|
||||
- D-（白色）
|
||||
* - GND
|
||||
- GND（黑色）
|
||||
* -
|
||||
- +5V（红色）
|
||||
|
||||
一些开发板可能会提供用于内部 USB 外设的 USB 连接器，此时无需额外的连接。
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
默认情况下，:doc:`USB_SERIAL_JTAG <usb-serial-jtag-console>` 外设与 ESP32-S3 内部的 USB PHY 相连，USB OTG 外设需要连接外部 USB PHY 才能使用。由于 CDC 控制台由 USB OTG 外设提供，因而在默认情况下无法通过内部 PHY 使用控制台。
|
||||
|
||||
通过烧录 ``USB_PHY_SEL`` eFuse， 永久切换内部 USB PHY 来与 USB OTG 外设配合使用，而不是 USB_SERIAL_JTAG。有关 USB_SERIAL_JTAG 和 USB OTG 的更多详细信息，请参阅 ESP32-S3 技术参考手册。
|
||||
|
||||
请注意，USB_SERIAL_JTAG 也可提供 CDC 控制台，因此不能仅仅为了启用 CDC 控制台而从 USB_SERIAL_JTAG 切换到 USB CDC。
|
||||
|
||||
|
||||
软件配置
|
||||
========
|
||||
|
||||
使用 menuconfig 工具中的 ``CONFIG_ESP_CONSOLE_USB_CDC`` 选项可启用 USB 控制台功能（请参阅 :ref:`CONFIG_ESP_CONSOLE_UART`）。
|
||||
|
||||
启用该选项后，按常规方式构建项目。
|
||||
|
||||
上传应用程序
|
||||
============
|
||||
|
||||
.. _usb_console_initial_upload:
|
||||
|
||||
初始上传
|
||||
--------
|
||||
|
||||
如果 {IDF_TARGET_NAME} 尚未烧录可启用 USB 控制台的程序，则需要初始上传程序。有三种可选方案来执行初始上传。
|
||||
|
||||
应用程序将在完成初始上传后启动，系统界面中将显示 USB CDC 端口。
|
||||
|
||||
.. note::
|
||||
|
||||
完成初始上传后，端口名称可能会更改，请在运行 ``idf.py monitor`` 之前再次检查端口列表。
|
||||
|
||||
|
||||
通过 USB CDC，在 ROM 下载模式下进行初始上传
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* 按照以下步骤将 {IDF_TARGET_NAME} 调为下载模式：保持 GPIO0 低电平，同时打开复位键。许多开发板上的 "Boot" 按键与 GPIO0 相连，可以在按住 "Boot" 键的同时按 "Reset" 键。
|
||||
* 系统界面中将显示串行端口。大多数操作系统（Windows 8 及更高版本、Linux、macOS）无需安装驱动程序，使用设备管理器 (Windows)，或列出 ``/dev/ttyACM*`` 设备 (Linux)， 或列出 ``/dev/cu*`` 设备 (macOS) 以查找端口名称。
|
||||
* 运行 ``idf.py flash -p PORT``，上传应用程序。其中 ``PORT`` 是指在上一步中确定的端口。
|
||||
|
||||
通过 USB DFU，在 ROM 下载模式下进行初始上传
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* 按照以下步骤将 {IDF_TARGET_NAME} 调为下载模式：保持 GPIO0 低电平，同时打开复位键。许多开发板上的 "Boot" 按键与 GPIO0 相连，可以在按住 "Boot" 键的同时按 "Reset" 键。
|
||||
* 运行 ``idf.py dfu-flash``。
|
||||
|
||||
有关烧录 DFU 的详细信息，请参阅 :ref:`api_guide_dfu_flash`。
|
||||
|
||||
通过 UART 进行初始上传
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
在有 USB-UART 桥接器的开发板上，可通过 UART 上传应用程序。运行 ``idf.py flash -p PORT``，其中 ``PORT`` 是 USB-UART 桥接器提供的串行端口的名称。
|
||||
|
||||
后续使用
|
||||
--------
|
||||
|
||||
完成应用程序初始上传后，按常规方式运行 ``idf.py flash`` 和 ``idf.py monitor``。
|
||||
|
||||
限制
|
||||
====
|
||||
|
||||
USB 控制台功能有一些限制。开发中的应用程序类型和工作流程不同，受限制的程度也有所不同。由于 USB CDC 是在软件中实现的，相比通过 UART 启用的控制台，通过 USB CDC 启用的会更加脆弱和复杂，而下面多数限制也因此产生。
|
||||
|
||||
1. 如果应用程序崩溃，某些情况下可能无法通过 USB CDC 发送紧急处理程序的输出。如果 CDC 驱动程序使用的内存已损坏，或者存在其他系统级问题，则 CDC 可能无法通过 USB 发送紧急处理程序的消息。在许多情况下，即便应用程序崩溃，USB CDC 依旧正常运转，但无法保证其输出如 UART 一般可靠。此外，如果应用程序在 USB CDC 驱动程序启动前进入循环启动，控制台同样无法输出。
|
||||
|
||||
2. 如果应用程序意外重置了 USB 外设管脚，或是禁用了 USB 外设，则 USB CDC 设备将从系统中消失。修复应用程序中的问题后，请按照 :ref:`usb_console_initial_upload` 流程重新烧录应用程序。
|
||||
|
||||
3. 如果应用程序进入 Light-sleep 模式（包括自动 Light-sleep 模式）或是 Deep-sleep 模式，则 USB CDC 设备将从系统中消失。
|
||||
|
||||
4. 在试图优化应用程序内存使用时，请牢记：USB CDC 驱动程序保留了一定量的 RAM 并增加了应用程序代码大小。
|
||||
|
||||
5. 默认情况下，当使用 USB CDC 时，低级别的 ``esp_rom_printf`` 功能和 ``ESP_EARLY_LOG`` 功能都被禁用。可以通过 :ref:`CONFIG_ESP_CONSOLE_USB_CDC_SUPPORT_ETS_PRINTF` 选项启用这些功能。启用此选项后，可以使用 ``esp_rom_printf`` 功能，但 IRAM 的使用量也随之增加。请注意，与 UART 相比，通过 USB CDC 使用 ``esp_rom_printf`` 和 ``ESP_EARLY_LOG`` 功能的成本要高得多，因此日志记录机制在中断处理程序中尤其不适用于“printf 调试”。
|
||||
|
||||
6. 如果在开发一个使用 TinyUSB 协议栈的应用程序时，无法使用 USB 控制台功能，其主要原因可能如下：
|
||||
|
||||
* 此功能依赖于 {IDF_TARGET_NAME} ROM 中其他的 USB CDC 软件协议栈。
|
||||
* ROM CDC 协议栈使用的 USB 描述符可能与 TinyUSB 使用的描述符有所不同。
|
||||
* 在开发使用 USB 外设的应用程序时，USB 的功能有时很可能无法工作、或是无法完全工作，这可能是由 USB 描述符配置错误、USB 协议栈使用有误等原因引起的。此时为了更好的开发体验，可使用 UART 控制台进行烧录和监控。
|
||||
|
||||
7. 在使用 JTAG 调试应用程序时，如果 CPU 在断点处停止，则 USB CDC 可能会停止工作。USB CDC 的操作依赖于来自 USB 外设的周期性中断。如果主机在一段时间内未收到来自 USB 设备端的有效响应，则可能会断开连接设备。实际的等待时间取决于操作系统和驱动程序，范围从几百毫秒到几秒不等。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user