From 3a7dcdf1b2a777248d5f13010b0bd53501e4e015 Mon Sep 17 00:00:00 2001 From: Shen Mengjing Date: Fri, 21 Nov 2025 14:24:04 +0800 Subject: [PATCH] docs: Provide CN translation for wokwisimulator.rst and dfu.rst --- docs/en/additionalfeatures/dfu.rst | 40 +++++++++------- docs/en/additionalfeatures/wokwisimulator.rst | 16 ++++--- docs/zh_CN/additionalfeatures/dfu.rst | 47 ++++++++++++++++++- .../additionalfeatures/wokwisimulator.rst | 16 ++++++- 4 files changed, 92 insertions(+), 27 deletions(-) diff --git a/docs/en/additionalfeatures/dfu.rst b/docs/en/additionalfeatures/dfu.rst index 7d742886d..063c8a594 100644 --- a/docs/en/additionalfeatures/dfu.rst +++ b/docs/en/additionalfeatures/dfu.rst @@ -3,40 +3,44 @@ Device Firmware Upgrade (DFU) through USB ========================================== +:link_to_translation:`zh_CN:[中文]` + Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of devices through Universal Serial Bus (USB). There are a few requirements that need to be met: -- DFU is supported by ESP32-S2 and ESP32-S3 chips. -- You will need to do some electrical connection work. Here is a `guide `_ for the ESP32-S2 board. The necessary connections for the USB peripheral are shown in the following table. - -+------+---------------+ -| GPIO | USB | -+======+===============+ -| 20 | D+ (green) | -+------+---------------+ -| 19 | D- (white) | -+------+---------------+ -| GND | GND (black) | -+------+---------------+ -| +5V | +5V (red) | -+------+---------------+ +- DFU is supported by ESP32-S2 and ESP32-S3 chips. +- Make necessary electrical connections manually. You can follow this `guide `__ for the ESP32-S2 board, and this `guide `__ for the ESP32-S3 board. The necessary connections for the USB peripheral are shown in the following table. + + .. list-table:: + :header-rows: 1 + + * - GPIO + - USB + * - 20 + - D+ (green) + * - 19 + - D- (white) + * - GND + - GND (black) + * - +5 V + - +5 V (red) After meeting the above requirements: 1. The chip needs to be in bootloader mode for detection as a DFU device and flashing. This can be achieved by pulling GPIO0 down (e.g., pressing the BOOT button), pulsing RESET down for a moment, and releasing GPIO0. 2. Install USB drivers (Windows only). The drivers can be installed by the `Zadig tool `_. - - Ensure that the device is in download mode before running the tool and that it detects the device before installing the drivers. + + - Ensure that the device is in download mode before running the tool, and that the tool detects the device before installing the drivers. - The Zadig tool might detect several USB interfaces of the target. Install the WinUSB driver only for the interface without a driver installed (likely Interface 2), and avoid re-installing drivers for other interfaces. - Manual driver installation via Device Manager in Windows is not recommended, as it might cause flashing issues. After meeting the above requirements, you can proceed to build and flash via DFU. To use DFU: 1. Edit the active launch configuration. -2. In the main tab, select the *Flash over DFU* option. +2. In the main tab, select the ``Flash over DFU`` option. 3. Select a suitable IDF target for DFU. 4. When using the build command, an extra file (``dfu.bin``) will be created, which can be used later for flashing. .. image:: https://user-images.githubusercontent.com/24419842/226182180-286099d3-9c1c-4394-abb0-212d43054529.png :alt: DFU actions -Additional information, including common errors and known issues, is available in `this `_. - +Additional information, including common errors and known issues, is available `here `_. diff --git a/docs/en/additionalfeatures/wokwisimulator.rst b/docs/en/additionalfeatures/wokwisimulator.rst index 901d7b593..27f4b9b4f 100644 --- a/docs/en/additionalfeatures/wokwisimulator.rst +++ b/docs/en/additionalfeatures/wokwisimulator.rst @@ -1,13 +1,15 @@ Wokwi Simulator =============== +:link_to_translation:`zh_CN:[中文]` + To use the Wokwi Simulator within the IDE, follow these steps: -1. Install `wokwi-server` as explained in the [wokwi-server installation guide](https://github.com/MabezDev/wokwi-server/). -2. In the Eclipse CDT build environment variables, configure `WOKWI_SERVER_PATH` with the path to the `wokwi-server` executable (*Preferences* > *C/C++* > *Build* > *Environment*). -3. Create a new *Run launch configuration* with the *Wokwi Simulator*. -4. Select a project and add the Wokwi project ID. The ID of a Wokwi project can be found in its URL. For example, the project ID of the Wokwi project [ESP32 Rust Blinky](https://wokwi.com/projects/345932416223806035) is `345932416223806035`. -5. Click *Finish* to save the configuration changes. -6. From the IDE Toolbar, click the *Launch* button to start the Wokwi simulator. +1. Install ``wokwi-server`` as explained in the `wokwi-server installation guide `_. +2. Go to ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment``. In the Eclipse CDT build environment variables, configure ``WOKWI_SERVER_PATH`` with the path to the ``wokwi-server`` executable. +3. Create a new ``Run launch configuration`` with the ``Wokwi Simulator``. +4. Select a project and add the Wokwi project ID. The ID of a Wokwi project can be found in its URL. For example, the project ID of the Wokwi project `ESP32 Rust Blinky `_ is ``345932416223806035``. +5. Click ``Finish`` to save the configuration changes. +6. From the IDE Toolbar, click the ``Launch`` button to start the Wokwi simulator. 7. The Wokwi Simulator will open in an external browser, with serial monitor output displayed in the Eclipse CDT build console. -8. To terminate the Wokwi Simulator, click the *Stop* button in the toolbar. +8. To terminate the Wokwi Simulator, click the ``Stop`` button in the toolbar. diff --git a/docs/zh_CN/additionalfeatures/dfu.rst b/docs/zh_CN/additionalfeatures/dfu.rst index 1d85ea065..478e9c76a 100644 --- a/docs/zh_CN/additionalfeatures/dfu.rst +++ b/docs/zh_CN/additionalfeatures/dfu.rst @@ -1 +1,46 @@ -.. include:: ../../en/additionalfeatures/dfu.rst +.. _dfuflashing: + +通过 USB 进行设备固件升级 (DFU) +========================================== + +:link_to_translation:`en:[English]` + +设备固件升级 (Device Firmware Upgrade, DFU) 是一种通过通用串行总线 (Universal Serial Bus, USB) 为设备升级固件的机制。需要满足以下要求： + +- ESP32-S2 和 ESP32-S3 芯片支持 DFU。 +- 手动进行必要的电气连接。对于 ESP32-S2 开发版，请参考 `ESP32-S2 设备固件升级指南 `__；对于 ESP32-S3，参考 `ESP32-S3 设备固件升级指南 `__。USB 外设所需的连接可参见下表。 + + .. list-table:: + :header-rows: 1 + + * - GPIO + - USB + * - 20 + - D+（绿色） + * - 19 + - D-（白色） + * - GND + - GND（黑色） + * - +5 V + - +5 V（红色） + +满足上述要求后，继续以下步骤： + +1. 芯片需要进入引导加载程序模式，才能被检测为 DFU 设备并进行烧录。可以通过将 GPIO0 拉低（例如，按下 BOOT 按钮），将 RESET 短暂拉低，然后释放 GPIO0 来实现。 +2. 安装 USB 驱动（仅限 Windows 系统）。可以使用 `Zadig 工具 `_ 安装驱动。 + + - 在运行该工具前，确保设备处于下载模式，并且在安装驱动前，工具已检测到该设备。 + - Zadig 工具可能会检测到目标设备的多个 USB 接口。你只需要为还没有驱动程序的接口（通常是 Interface 2）安装 WinUSB 驱动，不要对其他已经安装了驱动的接口重复安装。 + - 不建议通过 Windows 的设备管理器手动安装驱动，因为这可能导致烧录问题。 + +满足上述要求后，即可通过 DFU 进行构建和烧录。参照下列步骤使用 DFU： + +1. 编辑当前启用的启动配置。 +2. 在主选项卡中，选择 ``Flash over DFU`` 选项。 +3. 选择适用于 DFU 的 IDF 目标。 +4. 使用构建命令时会生成一个额外的文件 (``dfu.bin``)，可用于后续烧录。 + +.. image:: https://user-images.githubusercontent.com/24419842/226182180-286099d3-9c1c-4394-abb0-212d43054529.png + :alt: DFU 操作 + +包括常见错误和已知问题在内的更多信息，可参阅 `此处 `_。 diff --git a/docs/zh_CN/additionalfeatures/wokwisimulator.rst b/docs/zh_CN/additionalfeatures/wokwisimulator.rst index 4216a061c..14ab4fbd0 100644 --- a/docs/zh_CN/additionalfeatures/wokwisimulator.rst +++ b/docs/zh_CN/additionalfeatures/wokwisimulator.rst @@ -1 +1,15 @@ -.. include:: ../../en/additionalfeatures/wokwisimulator.rst +Wokwi 模拟器 +=============== + +:link_to_translation:`en:[English]` + +要在 IDE 中使用 Wokwi 模拟器，请按以下步骤操作： + +1. 安装 ``wokwi-server``，具体步骤见 `wokwi-server 安装指南 `_。 +2. 前往 ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment``。在 Eclipse CDT 构建环境变量中，将 ``WOKWI_SERVER_PATH`` 配置为 ``wokwi-server`` 可执行文件的路径。 +3. 使用 ``Wokwi Simulator`` 创建新的 ``Run launch configuration``。 +4. 选择一个项目，添加 Wokwi 项目的 ID。Wokwi 项目的 ID 可以在其 URL 中找到。例如，Wokwi 项目 `ESP32 Rust Blinky `_ 的项目 ID 为 ``345932416223806035``。 +5. 点击 ``Finish`` 以保存配置更改。 +6. 在 IDE 工具栏中，点击 ``Launch`` 按钮以启动 Wokwi 模拟器。 +7. Wokwi 模拟器将会在外部浏览器中打开，串口监视器输出将显示在 Eclipse CDT 构建控制台中。 +8. 如需结束 Wokwi 模拟器，请在工具栏中点击 ``Stop`` 按钮。