diff --git a/docs/conf_common.py b/docs/conf_common.py index 9bcfa2ac16..151ba312d7 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -137,7 +137,6 @@ RGB_LCD_DOCS = ['api-reference/peripherals/lcd/rgb_lcd.rst'] DSI_LCD_DOCS = ['api-reference/peripherals/lcd/dsi_lcd.rst'] PARLIO_LCD_DOCS = ['api-reference/peripherals/lcd/parl_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'] @@ -247,7 +246,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, diff --git a/docs/docs_not_updated/esp32p4.txt b/docs/docs_not_updated/esp32p4.txt index dc5c69dde7..f4553fef4d 100644 --- a/docs/docs_not_updated/esp32p4.txt +++ b/docs/docs_not_updated/esp32p4.txt @@ -1,6 +1,5 @@ api-guides/partition-tables.rst api-guides/usb-otg-console.rst -api-guides/dfu.rst api-reference/peripherals/adc_calibration.rst api-reference/peripherals/parlio.rst api-reference/peripherals/sd_pullup_requirements.rst diff --git a/docs/en/api-guides/dfu.rst b/docs/en/api-guides/dfu.rst index 2ad2befb48..e9322781c0 100644 --- a/docs/en/api-guides/dfu.rst +++ b/docs/en/api-guides/dfu.rst @@ -3,7 +3,19 @@ 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 + + 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:: SOC_USB_SERIAL_JTAG_SUPPORTED + + Typically, the firmware of the {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). The {IDF_TARGET_NAME} also contains a USB OTG peripheral making it possible to connect the {IDF_TARGET_NAME} to the host directly via USB Device Firmware Upgrade. + +.. only:: esp32s3 + + By default, the :doc:`USB_SERIAL_JTAG ` 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. 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. @@ -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 + The {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 the {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 ` 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. + The {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 `_ for more information about how to enter bootloader mode. .. _api_guide_dfu_build: diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index e9ad8c6941..4ca6af42b7 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -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 diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index c8eccdc5e2..1bd85bc267 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -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 diff --git a/tools/idf_py_actions/dfu_ext.py b/tools/idf_py_actions/dfu_ext.py index 4f0b36105b..4c72f6db82 100644 --- a/tools/idf_py_actions/dfu_ext.py +++ b/tools/idf_py_actions/dfu_ext.py @@ -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)