diff --git a/docs/en/additionalfeatures/dfu.rst b/docs/en/additionalfeatures/dfu.rst index 7d742886d..d120907be 100644 --- a/docs/en/additionalfeatures/dfu.rst +++ b/docs/en/additionalfeatures/dfu.rst @@ -3,27 +3,32 @@ 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. +- You will need to do some electrical connection work. 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) + * - +5V + - +5V (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. - 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. @@ -31,12 +36,11 @@ After meeting the above requirements: 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..0dd4c918f 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-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`` 按钮。