docs: provide CN translation for 18484

espressif · Aug 9, 2022 · a199f6f · a199f6f
1 parent 1df9480
commit a199f6f
Show file tree

Hide file tree

Showing 9 changed files with 260 additions and 54 deletions.
diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst
@@ -52,12 +52,12 @@ Some development boards have the USB-to-UART bridge installed. If a board does n
 
         }
 
-    Some development boards also includes the USB-to-UART bridge, besides the USB peripheral.
+    Apart from the USB peripheral, some development boards also include the USB-to-UART bridge.
 
 USB-to-UART Bridge on Development Board
 ---------------------------------------
 
-For boards with an installed USB-to-UART bridge the connection between the personal computer and the bridge is USB and between the bridge and {IDF_TARGET_NAME} is UART.
+For boards with an installed USB-to-UART bridge, the connection between the personal computer and the bridge is USB and between the bridge and {IDF_TARGET_NAME} is UART.
 
 .. blockdiag::
     :caption: Development Board with USB-to-UART Bridge
@@ -150,7 +150,7 @@ Sometimes the USB-to-UART bridge is external. This is often used in small develo
 
         .. note:: The {IDF_TARGET_NAME} supports only *USB CDC and JTAG*.
 
-        If you are flashing for the first time, you need to get the {IDF_TARGET_NAME} into the download mode manually. To do so, press and hold the **BOOT** button and then press the **RESET** button once. After that release the **BOOT** button.
+        If you are flashing for the first time, you need to get the {IDF_TARGET_NAME} into the download mode manually. To do so, press and hold the ``BOOT`` button and then press the ``RESET`` button once. After that release the ``BOOT`` button.
 
     .. only:: esp32s2
 
@@ -164,7 +164,7 @@ This section provides guidance on how to establish a serial connection between {
 Connect {IDF_TARGET_NAME} to PC
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them.
+Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB-to-UART bridge on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them.
 
 Below is the list of USB to serial converter chips installed on most of the {IDF_TARGET_NAME} boards produced by Espressif together with links to the drivers:
 
@@ -173,7 +173,6 @@ Below is the list of USB to serial converter chips installed on most of the {IDF
 
 Please check the board user guide for specific USB-to-UART bridge chip used. The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with an operating system and automatically installed upon connecting the board to the PC.
 
-
 For devices downloaded using a USB-to-UART bridge, you can run the following command including the optional argument to define the baud rate.
 
 .. code-block:: bash
@@ -184,8 +183,7 @@ You can change the flasher baud rate by replacing ``BAUD`` with the baud rate yo
 
 .. note::
 
-    If the device does not support the auto download mode, you need to get into the download mode manually.
-    To do so, press and hold the BOOT button and then press the RESET button once. After that release the BOOT button.
+    If the device does not support the auto download mode, you need to get into the download mode manually. To do so, press and hold the ``BOOT`` button and then press the ``RESET`` button once. After that release the ``BOOT`` button.
 
 Check port on Windows
 ---------------------

diff --git a/docs/en/get-started/flashing-troubleshooting.rst b/docs/en/get-started/flashing-troubleshooting.rst
@@ -3,22 +3,22 @@ Flashing Troubleshooting
 
 :link_to_translation:`zh_CN:[中文]`
 
-Failed to connect
+Failed to Connect
 -----------------
 
 {IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
 
-If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset described below, and if it does not help you can find more details about possible issues in the `esptool troubleshooting <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ page.
+If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is to manually reset as described below. If it does not help, you can find more details about possible issues in the `esptool troubleshooting <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ page.
 
-``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
+``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB-to-UART bridge, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
 
 In general, you should have no problems with the `official esp-idf development boards <https://www.espressif.com/en/products/devkits>`_. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
 
-- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``
-- The DTR and RTS lines are configured differently
-- There are no such serial control lines at all
+- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``.
+- The DTR and RTS lines are configured differently.
+- There are no such serial control lines at all.
 
 Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
 
-- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an ESP-IDF development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_GPIO}``) and press the **EN** button (``CHIP_PU``).
+- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an ESP-IDF development board, hold down the ``Boot`` button (``{IDF_TARGET_STRAP_GPIO}``) and press the ``EN`` button (``CHIP_PU``).
 - For other types of hardware, try pulling ``{IDF_TARGET_STRAP_GPIO}`` down.
diff --git a/docs/en/get-started/linux-macos-start-project.rst b/docs/en/get-started/linux-macos-start-project.rst
@@ -84,9 +84,9 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
 
     If you are using the USB for flashing the {IDF_TARGET_NAME}, you need to change the channel for the console output from UART (default) to USB.
 
-    1. Navigate to the option ``Channel for console output``
+    1. Navigate to the option ``Channel for console output``.
 
-        ``Component config  --->  ESP System Settings  ---> Channel for console output``
+        ``Component config`` > ``ESP System Settings`` > ``Channel for console output``
 
     2. Change to the option (the default will be always UART):
 

diff --git a/docs/en/get-started/windows-start-project.rst b/docs/en/get-started/windows-start-project.rst
@@ -81,7 +81,7 @@ You are using this menu to set up project specific variables, e.g., Wi-Fi networ
 
     To use the USB for flashing the {IDF_TARGET_NAME}, you need to change the channel for the console output to USB. For the {IDF_TARGET_NAME}, the default console output channel is the UART.
 
-    1. Navigate to the option ``Channel for console output``
+    1. Navigate to the option ``Channel for console output``.
 
         ``Component config  --->  ESP System Settings  ---> Channel for console output``
 

diff --git a/docs/zh_CN/get-started/establish-serial-connection.rst b/docs/zh_CN/get-started/establish-serial-connection.rst
@@ -3,20 +3,187 @@
 
 :link_to_translation:`en:[English]`
 
-本章节主要介绍如何创建 {IDF_TARGET_NAME} 和 PC 之间的串口连接。
+.. only:: not SOC_USB_OTG_SUPPORTED and not SOC_USB_SERIAL_JTAG_SUPPORTED
 
+    可以使用 USB 至 UART 桥，与 {IDF_TARGET_NAME} 创建串口连接。
+
+.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
+
+    可以使用 USB 至 UART 桥或 {IDF_TARGET_NAME} 支持的 USB 外设，与 {IDF_TARGET_NAME} 创建串口连接。
+
+部分开发板中已经安装有 USB 至 UART 桥。如未安装，可使用外部桥。
+
+.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
+
+    支持的 USB 外设
+    ------------------------
+
+    {IDF_TARGET_NAME} 支持 USB 外设。无需 USB 至 UART 桥，便可直接烧录设备。
+
+    .. blockdiag::
+        :scale: 70%
+        :caption: 支持 USB 的 SoC
+        :align: center
+
+        blockdiag usb_capable_esp {
+
+            node_height = 80;
+            span_width = 160;
+            span_height = 140;
+            default_fontsize = 16
+
+            # labels of diagram nodes
+            PC [label="Personal\n Computer"];  
+            CHIP [label="{IDF_TARGET_NAME}", width=120];
+            DUMMY [shape=none, width=1]
+
+
+                # node connections
+                PC  <- DUMMY [label = "USB", fontsize=14];
+                DUMMY -> CHIP [fontsize=14];
+
+                group {
+                    shape = line;
+                    style = dotted;
+                    color = "#FF0000";
+                    label = "Development Board\n\n\n";
+                    CHIP; DUMMY;
+                }
+
+        }
+
+    部分支持 USB 外设的开发板同时也包含 USB 至 UART 桥。
+
+安装有 USB 至 UART 桥的开发板
+---------------------------------------
+
+在安装有 USB 至 UART 桥的开发板中，PC 和桥之间通过 USB 连接，桥和 {IDF_TARGET_NAME} 之间通过 UART 连接。
+
+.. blockdiag::
+    :caption: 安装有 USB 至 UART 桥的开发板
+    :align: center
+
+    blockdiag esp_dev_board_with_usb_to_uart_bridge {
+
+        node_height = 80;
+        span_width = 160;
+        span_height = 140;
+        default_fontsize = 16
+
+        # labels of diagram nodes
+        PC [label="Personal\nComputer"];  
+        BRIDGE [label="USB-to-UART\n Bridge"];  
+        CHIP [label="{IDF_TARGET_NAME}", width=120];
+
+            # node connections
+            PC <-> BRIDGE [label = "USB", fontsize=14];
+            BRIDGE <-> CHIP [label = "UART", fontsize=14];
+
+            group {
+                shape = line;
+                style = dotted;
+                color = "#FF0000";
+                label = "Developmment Board\n\n\n";
+                BRIDGE; CHIP;
+            }
+    }
+
+
+外部 USB 至 UART 桥
+---------------------------
+
+部分开发板使用外部 USB 至 UART 桥。这种情况通常出现在需要控制空间和成本的产品中，例如一些小型开发板或成品。
+
+.. blockdiag::
+    :caption: 外部 USB 至 UART 桥
+    :align: center
+
+    blockdiag external_usb_to_uart_bridge_to_esp {
+
+        node_height = 80;
+        span_width = 160;
+        span_height = 140;
+        default_fontsize = 16
+
+        # labels of diagram nodes
+        PC [label="Personal\n Computer"];  
+        BRIDGE [label="USB-to-UART\n Bridge", width=180];  
+        CHIP [label="{IDF_TARGET_NAME}", width=120];
+        DUMMY [shape=none, width=1]
+
+
+            # node connections
+            PC <-> BRIDGE [label = "USB", fontsize=14];
+            BRIDGE <- DUMMY [label = "UART", fontsize=14];
+            DUMMY -> CHIP [fontsize=14];
+
+            group {
+                shape = line;
+                style = dotted;
+                color = "#FF0000";
+                label = "Programmmer Board\n\n\n";
+                BRIDGE
+            }
+            group {
+                shape = line;
+                style = dotted;
+                color = "#FF0000";
+                label = "Development Board\n\n\n";
+                CHIP; DUMMY;
+            }
+    }
+
+
+.. only:: SOC_USB_OTG_SUPPORTED or SOC_USB_SERIAL_JTAG_SUPPORTED
+
+    使用 USB 进行烧录
+    ------------------
+
+    {IDF_TARGET_NAME} 支持 USB 外设，无需外部 USB 至 UART 桥，即可烧录二进制文件。
+
+    {IDF_TARGET_USB_PIN_DM:default="尚未更新！", esp32c3="GPIO18", esp32s3="GPIO19", esp32s2="GPIO19"}
+    {IDF_TARGET_USB_PIN_DP:default="尚未更新！", esp32c3="GPIO19", esp32s3="GPIO20", esp32s2="GPIO20"}
+
+    {IDF_TARGET_NAME} 上的 USB 使用 **{IDF_TARGET_USB_PIN_DP}** 作为 **D+**， **{IDF_TARGET_USB_PIN_DM}** 作为 **D-**。
+
+    .. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
+
+        .. note:: {IDF_TARGET_NAME} 仅支持 *USB CDC and JTAG*。
+
+        首次烧录需要手动设置 {IDF_TARGET_NAME} 进入下载模式。请按住 ``BOOT`` 按钮，同时按一下 ``RESET`` 按钮。之后，松开 ``BOOT`` 按钮。
+
+    .. only:: esp32s2
+
+        二进制文件烧录完成后，需要手动进行复位。
+
+使用 UART 进行烧录
+---------------------
+
+本节描述如何使用 USB 至 UART 桥在 {IDF_TARGET_NAME} 和 PC 之间建立串行连接。板上桥与外部桥均适用。
 
 连接 {IDF_TARGET_NAME} 和 PC
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-用 USB 线将 {IDF_TARGET_NAME} 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 {IDF_TARGET_NAME} 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。
+用 USB 线将 {IDF_TARGET_NAME} 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 {IDF_TARGET_NAME} 开发板上的 USB 至 UART 桥（或外部转 UART 适配器）型号，然后在网上搜索驱动程序，并进行手动安装。
 
 以下是乐鑫 {IDF_TARGET_NAME} 开发板驱动程序的链接：
 
 * CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 <https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers>`_
 * FTDI: `FTDI 虚拟 COM 端口驱动程序 <https://ftdichip.com/drivers/vcp-drivers/>`_
 
-以上驱动仅供参考，请参考开发板用户指南，查看开发板具体使用的 USB 转串口芯片。一般情况下，当 {IDF_TARGET_NAME} 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。
+以上驱动仅供参考，请查看开发板用户指南，了解开发板具体使用的 USB 至 UART 桥芯片。一般情况下，当 {IDF_TARGET_NAME} 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。
+
+对于使用 USB 至 UART 桥下载的设备，您可以运行以下命令，包括定义波特率的可选参数。
+
+.. code-block:: bash
+
+    idf.py -p PORT [-b BAUD] flash
+
+如需改变烧录器的波特率，请用需要的波特率代替 ``BAUD``。默认的波特率为 ``460800``。
+
+.. note::
+
+    如果设备不支持自动下载模式，则需要手动进入下载模式。请按住 ``BOOT`` 按钮，同时按一下 ``RESET`` 按钮。之后，松开 ``BOOT`` 按钮。
 
 在 Windows 上查看端口
 ---------------------
@@ -39,7 +206,6 @@
 
     Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
 
-
 在 Linux 和 macOS 上查看端口
 -----------------------------
 
@@ -57,7 +223,6 @@ macOS::
 
     对于 macOS 用户：若没有看到串口，请检查是否安装 USB/串口驱动程序。具体应使用的驱动程序，见章节 `连接 {IDF_TARGET_NAME} 和 PC`_。对于 macOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。
 
-
 .. _linux-dialout-group:
 
 在 Linux 中添加用户到 ``dialout``
@@ -73,7 +238,6 @@ macOS::
 
 请重新登录，确保串口读写权限生效。
 
-
 确认串口连接
 ------------------------
 
@@ -100,7 +264,6 @@ Windows 和 Linux 操作系统
 
     在 Linux 操作系统中使用 PuTTY 设置串口通信参数
 
-
 然后，请检查 {IDF_TARGET_NAME} 是否有打印日志。如有，请在终端打开串口进行查看。这里的日志内容取决于加载到 {IDF_TARGET_NAME} 的应用程序，请参考 `输出示例`_。
 
 .. 注解::
@@ -132,7 +295,6 @@ macOS 提供了 **屏幕** 命令，因此您不用安装串口终端程序。
 
    请在验证完串口通信正常后，关闭 **屏幕** 会话。如果直接关闭终端窗口而没有关闭 **屏幕**，之后上传固件时将无法访问串口。
 
-
 输出示例
 ^^^^^^^^^^^
 
@@ -158,7 +320,6 @@ macOS 提供了 **屏幕** 命令，因此您不用安装串口终端程序。
     entry 0x40080034
     I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
     I (45) boot: compile time 18:48:10
-
     ...
 
 如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，您可以继续进行安装，并最终将应用程序上载到 {IDF_TARGET_NAME}。

diff --git a/docs/zh_CN/get-started/flashing-troubleshooting.rst b/docs/zh_CN/get-started/flashing-troubleshooting.rst
@@ -1,5 +1,24 @@
-Flashing Troubleshooting
+烧录故障排除
 ========================
 
 :link_to_translation:`en:[English]`
 
+连接失败
+-----------------
+
+{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9"}
+
+如果在运行给定命令时出现如“连接失败”这样的错误，造成该错误的原因之一可能是运行 ``esptool.py`` 时出现错误。 ``esptool.py`` 是构建系统调用的程序，用于重置芯片、与 ROM 引导加载器交互以及烧录固件的工具。可以按照以下步骤进行手动复位，轻松解决该问题。如果问题仍未解决，请参考 `esptool 故障排除 <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ 获取更多信息。
+
+``esptool.py`` 通过使 USB 至 UART 桥（如 FTDI 或 CP210x）的 DTR 和 RTS 控制线生效来自动复位 {IDF_TARGET_NAME}（请参考 :doc:`establish-serial-connection` 获取更多详细信息）。DTR 和 RTS 控制线又连接到 {IDF_TARGET_NAME} 的 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CHIP_PU`` (EN) 管脚上，因此 DTR 和 RTS 的电压电平变化会使 {IDF_TARGET_NAME} 进入固件下载模式。相关示例可查看 ESP32 DevKitC 开发板的 `原理图 <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_。
+
+一般来说，使用官方的 ESP-IDF 开发板不会出现问题。但是， ``esptool.py`` 在以下情况下不能自动重置硬件：
+
+- 您的硬件没有连接到 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CIHP_PU`` 的 DTR 和 RTS 控制线。
+- DTR 和 RTS 控制线的配置方式不同。
+- 不存在这样的串行控制线路。
+
+根据硬件的种类，也可以将您的 {IDF_TARGET_NAME} 开发板手动设置为固件下载模式（复位）。
+
+- 对于乐鑫开发板，您可以参考对应开发板的入门指南或用户指南。例如，可以通过按住 ``Boot`` 按钮 (``{IDF_TARGET_STRAP_GPIO}``) 再按住 ``EN`` 按钮 (``CHIP_PU``) 来手动复位 ESP-IDF 开发板。
+- 对于其他类型的硬件，可以尝试将 ``{IDF_TARGET_STRAP_GPIO}`` 拉低。