blackbeard420/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf synced 2025-03-09 17:19:09 -04:00
Code Issues Projects Releases Wiki Activity

Merge branch 'feat/dfu_p4_backport_v5.4' into 'release/v5.4'

Browse Source 
feat(dfu): Enable DFU on ESP32-P4 (backport v5.4)

See merge request espressif/esp-idf!35829
This commit is contained in:
Roland Dobai 2025-01-06 15:41:29 +08:00
commit bbdc6cfe4f
7 changed files with 84 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/conf_common.py
View File

@ -136,7 +136,6 @@ I80_LCD_DOCS = ['api-reference/peripherals/lcd/i80_lcd.rst']
RGB_LCD_DOCS = ['api-reference/peripherals/lcd/rgb_lcd.rst']
DSI_LCD_DOCS = ['api-reference/peripherals/lcd/dsi_lcd.rst']
# TODO: Merge this back with `USB_DOCS` IDF-9919 IDF-9920 IDF-9133
USB_OTG_DFU_DOCS = ['api-guides/dfu.rst']
USB_OTG_CONSOLE_DOCS = ['api-guides/usb-otg-console.rst']
@ -246,7 +245,7 @@ ESP32H2_DOCS = ['api-guides/RF_calibration.rst',
ESP32P4_DOCS = ['api-reference/system/ipc.rst',
'api-reference/peripherals/cap_touch_sens.rst',
'api-reference/peripherals/sd_pullup_requirements.rst']
'api-reference/peripherals/sd_pullup_requirements.rst'] + USB_OTG_DFU_DOCS
# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,

1
docs/docs_not_updated/esp32p4.txt
View File

@ -4,7 +4,6 @@ api-guides/coexist.rst
api-guides/wifi.rst
api-guides/usb-otg-console.rst
api-guides/esp-wifi-mesh.rst
api-guides/dfu.rst
api-guides/wifi-security.rst
api-reference/peripherals/touch_element.rst
api-reference/peripherals/touch_pad.rst

64
docs/en/api-guides/dfu.rst
View File

@ -3,9 +3,21 @@ Device Firmware Upgrade via USB
:link_to_translation:`zh_CN:[中文]`
Typically, the firmware of the {IDF_TARGET_NAME} is flashed via the chip's serial port. However, flashing via the serial port requires a USB to serial converter chip (e.g., CP210x or FTDI) to be connected to the {IDF_TARGET_NAME} (see :doc:`Establish Serial Connection with {IDF_TARGET_NAME} <../get-started/establish-serial-connection>` for more details). The {IDF_TARGET_NAME} contains a USB OTG peripheral making it possible to connect the {IDF_TARGET_NAME} to the host directly via USB (thus not requiring a USB to serial converter chip).
.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED
Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of the {IDF_TARGET_NAME} directly via the Universal Serial Bus (USB). However, enabling Secure Boot or flash encryption disables the USB-OTG USB stack in the ROM, disallowing updates via the serial emulation or DFU on that port.
Typically, the firmware of {IDF_TARGET_NAME} is flashed via the chip's serial port. However, flashing via the serial port requires a USB to serial converter chip (e.g., CP210x or FTDI) to be connected to {IDF_TARGET_NAME}. Please see :doc:`Establish Serial Connection with {IDF_TARGET_NAME} <../get-started/establish-serial-connection>` for more details. {IDF_TARGET_NAME} contains a USB OTG peripheral, making it possible to connect {IDF_TARGET_NAME} to the host directly via USB (thus not requiring a USB to serial converter chip).
.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
Typically, the firmware of {IDF_TARGET_NAME} is flashed via the chip's serial port or USB_SERIAL_JTAG (see :doc:`Establish Serial Connection with {IDF_TARGET_NAME} <../get-started/establish-serial-connection>` for more details). {IDF_TARGET_NAME} also contains a USB OTG peripheral making it possible to connect {IDF_TARGET_NAME} to the host directly via USB Device Firmware Upgrade.
.. only:: esp32s3
By default, the :doc:`USB_SERIAL_JTAG <usb-serial-jtag-console>` module is connected to {IDF_TARGET_NAME}'s internal USB PHY, while the USB OTG peripheral can be used only if an external USB PHY is connected. Since DFU is provided via the USB OTG peripheral, it cannot be used through the internal PHY in this configuration.
However, you can permanently switch the internal USB PHY to work with USB OTG peripheral instead of USB_SERIAL_JTAG by burning the ``USB_PHY_SEL`` eFuse. See *{IDF_TARGET_NAME} Technical Reference Manual* [`PDF <{IDF_TARGET_TRM_EN_URL}>`__] for more details about USB_SERIAL_JTAG and USB OTG.
Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of {IDF_TARGET_NAME} directly via the Universal Serial Bus (USB). However, enabling Secure Boot or flash encryption disables the USB-OTG USB stack in the ROM, disallowing updates via the serial emulation or DFU on that port.
- :ref:`get-started-get-prerequisites` of the Getting Started Guide introduces the software requirements of DFU.
- Section :ref:`api_guide_dfu_build` describes how to build firmware for DFU with ESP-IDF.
@ -15,40 +27,40 @@ Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of the {
USB Connection
--------------
The necessary connections for the {IDF_TARGET_NAME}'s internal USB PHY (transceiver) are shown in the following table:
.. only:: esp32p4
.. list-table::
:header-rows: 1
:widths: 25 20
{IDF_TARGET_NAME} routes the USB D+ and D- signals to their dedicated pins. For USB device functionality, these pins must be connected to the USB bus (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug).
* - GPIO
- USB
.. only:: esp32s2 or esp32s3
* - 20
- D+ (green)
The necessary connections for {IDF_TARGET_NAME}'s internal USB PHY (transceiver) are shown in the following table:
* - 19
- D- (white)
.. list-table::
:header-rows: 1
:widths: 25 20
* - GND
- GND (black)
* - GPIO
- USB
* - +5V
- +5V (red)
* - 20
- D+ (green)
* - 19
- D- (white)
* - GND
- GND (black)
* - +5V
- +5V (red)
.. warning::
Some cables are wired up with non-standard colors and some drivers are able to work with swapped D+ and D- connections. Please try to swap the cables connecting to D+ and D- if your device is not detected.
.. only:: esp32s3
By default, the :doc:`USB_SERIAL_JTAG <usb-serial-jtag-console>` module is connected to the {IDF_TARGET_NAME}'s internal USB PHY, while the USB OTG peripheral can be used only if an external USB PHY is connected. Since DFU is provided via the USB OTG peripheral, it cannot be used through the internal PHY in this configuration.
However, users can permanently switch the internal USB PHY to work with USB OTG peripheral instead of USB_SERIAL_JTAG by burning the ``USB_PHY_SEL`` eFuse. See *{IDF_TARGET_NAME} Technical Reference Manual* [`PDF <{IDF_TARGET_TRM_EN_URL}>`__] for more details about USB_SERIAL_JTAG and USB OTG.
.. note::
The {IDF_TARGET_NAME} chip needs to be in bootloader mode before it can be detected as a DFU device and flash. This can be achieved by pulling GPIO0 down (e.g., pressing the BOOT button), pulling RESET down for a moment, and releasing GPIO0.
{IDF_TARGET_NAME} chip needs to be in bootloader mode before it can be detected as a DFU device and flash. Please refer to `Boot Mode Selection <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/advanced-topics/boot-mode-selection.html#select-bootloader-mode>`_ for more information about how to enter bootloader mode.
.. _api_guide_dfu_build:
@ -70,7 +82,7 @@ The command below will create a DFU image named ``dfu.bin`` that is placed in th
Flashing the DFU Image
----------------------
The command below will download the DFU image into the {IDF_TARGET_NAME}::
The command below will download the DFU image into {IDF_TARGET_NAME}::
idf.py dfu-flash
@ -98,7 +110,7 @@ See :ref:`api_guide_dfu_flash_errors` and their solutions.
Udev Rule (Linux Only)
----------------------
Udev is a device manager for the Linux kernel. It allows us to run ``dfu-util`` (and ``idf.py dfu-flash``) without ``sudo`` for gaining access to the chip.
Udev is a device manager for the Linux kernel. It allows running ``dfu-util`` (and ``idf.py dfu-flash``) without ``sudo`` for gaining access to the chip.
Create file ``/etc/udev/rules.d/40-dfuse.rules`` with the following content::
@ -106,7 +118,7 @@ Create file ``/etc/udev/rules.d/40-dfuse.rules`` with the following content::
.. note::
Please check the output of the command ``groups``. The user has to be a member of the `GROUP` specified above. You may use some other existing groups for this purpose (e.g., `uucp` on some systems instead of `plugdev`) or create a new group for this purpose.
Please check the output of the command ``groups``. You need to be a member of the `GROUP` specified above. You may use some other existing groups for this purpose (e.g., `uucp` on some systems instead of `plugdev`) or create a new group for this purpose.
Restart your computer so the previous setting could take into affect or run ``sudo udevadm trigger`` to force manually udev to trigger your new rule.

2
docs/en/api-guides/index.rst
View File

@ -19,7 +19,7 @@ API Guides
core_dump
current-consumption-measurement-modules
:ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB: deep-sleep-stub
:SOC_USB_OTG_SUPPORTED and not esp32p4: dfu
:SOC_USB_OTG_SUPPORTED: dfu
error-handling
:SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
:SOC_SPIRAM_SUPPORTED: external-ram

62
docs/zh_CN/api-guides/dfu.rst
View File

@ -3,7 +3,19 @@
:link_to_translation:`en:[English]`
一般情况下，{IDF_TARGET_NAME} 的固件是通过芯片的串口烧录。但是，通过串口烧录 {IDF_TARGET_NAME} 需要连接 USB 转串口转换器（如 CP210x 或 FTDI），详细信息可参阅 :doc:`与 {IDF_TARGET_NAME} 创建串口连接<../get-started/establish-serial-connection>`。{IDF_TARGET_NAME} 包含一个 USB OTG 外设，使其可以通过 USB 将 {IDF_TARGET_NAME} 直接连接到主机，即不需要 USB 转串口转换器也可完成烧录。
.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED
一般情况下，{IDF_TARGET_NAME} 的固件是通过芯片的串口烧录。但是，通过串口烧录 {IDF_TARGET_NAME} 需要连接 USB 转串口转换器（如 CP210x 或 FTDI），详细信息可参阅 :doc:`与 {IDF_TARGET_NAME} 创建串口连接 <../get-started/establish-serial-connection>`。{IDF_TARGET_NAME} 包含一个 USB OTG 外设，使其能够通过 USB 将 {IDF_TARGET_NAME} 直接连接到主机，即不需要 USB 转串口转换器也可完成烧录。
.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
一般情况下，{IDF_TARGET_NAME} 的固件是通过芯片的串口或 USB_SERIAL_JTAG 烧录，详细信息可参阅 :doc:`与 {IDF_TARGET_NAME} 创建串口连接 <../get-started/establish-serial-connection>`。{IDF_TARGET_NAME} 还包含一个 USB OTG 外设，使其能够通过 USB 设备固件升级直接连接到主机。
.. only:: esp32s3
默认情况下，:doc:`USB_SERIAL_JTAG<usb-serial-jtag-console>` 模块连接到 {IDF_TARGET_NAME} 的内部 USB PHY，而 USB OTG 外设只有在连接外部 USB PHY 时才能使用。由于 DFU 是通过 USB OTG 外设提供的，因此在默认的设置下，无法通过内部 USB PHY 使用 DFU。
然而，你可以通过烧录 ``USB_PHY_SEL`` eFuse，将内部 USB PHY 永久切换为支持 USB OTG 外设的模式，不再用于 USB_SERIAL_JTAG。有关 USB_SERIAL_JTAG 和 USB OTG 的更多信息，请参阅 *{IDF_TARGET_NAME} 技术参考手册* [`PDF <{IDF_TARGET_TRM_CN_URL}>`__]。
设备固件升级 (DFU) 是一种通过通用串行总线 (USB) 升级设备固件的机制。但是，启用安全启动 (Secure Boot) 或 flash 加密会禁用 ROM 中的 USB-OTG USB 堆栈，则无法通过该端口上的模拟串口或 DFU 进行更新。
@ -15,40 +27,40 @@
USB 连接
--------------
{IDF_TARGET_NAME} 的内部 USB PHY（收发器）与 GPIO 的连接如下表所示：
.. only:: esp32p4
.. list-table::
:header-rows: 1
:widths: 25 20
{IDF_TARGET_NAME} 将 USB D+ 和 D- 信号连接到其专用引脚。为了实现 USB 设备功能，这些引脚必须连接到 USB 总线，如，通过 Micro-B 接口、USB-C 接口进行连接，或直接连接到标准 A 型插头。
* - GPIO
- USB
.. only:: esp32s2 or esp32s3
* - 20
- D+（绿色）
{IDF_TARGET_NAME} 的内部 USB PHY（收发器）与 GPIO 的连接如下表所示：
* - 19
- D-（白色）
.. list-table::
:header-rows: 1
:widths: 25 20
* - GND
- GND（黑色）
* - GPIO
- USB
* - +5V
- +5V（红色）
* - 20
- D+（绿色）
* - 19
- D-（白色）
* - GND
- GND（黑色）
* - +5V
- +5V（红色）
.. warning::
一些连接线采用非标准颜色连接，有时调换下 D+ 和 D- 的连接，驱动程序就能正常工作。如果无法检测到你的设备，请尝试下调换 D+ 和 D- 的连接线。
.. only:: esp32s3
默认情况下，{IDF_TARGET_NAME} 内部 USB PHY 与 :doc:`USB_SERIAL_JTAG<usb-serial-jtag-console>` 模块连接，此时 USB OTG 外设只有在连接外部 USB PHY 时才能使用。DFU 是通过 USB OTG 外设提供，因此在默认的设置下，无法通过内部 USB PHY 使用 DFU。
然而，用户可以烧录 ``USB_PHY_SEL`` eFuse 使得内部 USB PHY 与 USB OTG 连接，而不是连接 USB_SERIAL_JTAG。有关 USB_SERIAL_JTAG 和 USB OTG 的更多详细信息，请参阅 *{IDF_TARGET_NAME} 技术参考手册* [`PDF <{IDF_TARGET_TRM_CN_URL}>`__]。
一些连接线采用非标准颜色连接，且一些驱动程序能够在对调了 D+ 和 D- 连接的情况下正常工作。因此如果无法检测到设备，请尝试下调换 D+ 和 D- 的连接线。
.. note::
{IDF_TARGET_NAME} 芯片需要处于引导加载程序模式才能被检测为 DFU 设备并烧录。可以通过下拉 GPIO0（例如按下 BOOT 按钮）、拉低 RESET 片刻并释放 GPIO0 来实现。
{IDF_TARGET_NAME} 芯片需要处于引导加载程序模式才能被检测为 DFU 设备并烧录。有关如何进入引导加载程序模式的更多信息，请参阅 `Boot Mode Selection <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/advanced-topics/boot-mode-selection.html#select-bootloader-mode>`_。
.. _api_guide_dfu_build:
@ -98,7 +110,7 @@ USB 连接
Udev 规则（仅限 Linux）
--------------------------------
Udev 是 Linux 内核的设备管理器，允许用户在没有 ``sudo`` 的情况下运行 ``dfu-util`` （和 ``idf.py dfu-flash``）从而访问芯片。
Udev 是 Linux 内核的设备管理器，允许在没有 ``sudo`` 的情况下运行 ``dfu-util`` （和 ``idf.py dfu-flash``）从而访问芯片。
创建文件 ``/etc/udev/rules.d/40-dfuse.rules``，并在文件中添加如下内容::
@ -106,7 +118,7 @@ Udev 是 Linux 内核的设备管理器，允许用户在没有 ``sudo`` 的情
.. note::
请检查 ``groups`` 命令的输出。用户必须是上面指定的 `GROUP` 的成员。你可以为此使用其他现有的组（例如，在某些系统上使用 `uucp` 而不是 `plugdev`）或为此创建一个新的组。
请检查 ``groups`` 命令的输出。加入上面指定的 `GROUP` 组获取访问权限。你可以为此使用其他现有的组（例如，在某些系统上使用 `uucp` 而不是 `plugdev`）或为此创建一个新的组。
你可以选择重启计算机使之前的设置生效，或者手动运行 ``sudo udevadm trigger``，强制 Udev 触发新规则。

2
docs/zh_CN/api-guides/index.rst
View File

@ -19,7 +19,7 @@ API 指南
core_dump
current-consumption-measurement-modules
:ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB: deep-sleep-stub
:SOC_USB_OTG_SUPPORTED and not esp32p4: dfu
:SOC_USB_OTG_SUPPORTED: dfu
error-handling
:SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
:SOC_SPIRAM_SUPPORTED: external-ram

9
tools/idf_py_actions/dfu_ext.py
View File

@ -1,15 +1,18 @@
# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
# SPDX-License-Identifier: Apache-2.0
from typing import Dict
from click.core import Context
from idf_py_actions.errors import FatalError
from idf_py_actions.tools import PropertyDict, ensure_build_directory, is_target_supported, run_target
from idf_py_actions.tools import ensure_build_directory
from idf_py_actions.tools import is_target_supported
from idf_py_actions.tools import PropertyDict
from idf_py_actions.tools import run_target
def action_extensions(base_actions: Dict, project_path: str) -> Dict:
SUPPORTED_TARGETS = ['esp32s2', 'esp32s3']
SUPPORTED_TARGETS = ['esp32s2', 'esp32s3', 'esp32p4']
def dfu_target(target_name: str, ctx: Context, args: PropertyDict, part_size: str) -> None:
ensure_build_directory(args, ctx.info_name)