From 5c3306ac04b850a923222ec1e9dcbb877097b8b7 Mon Sep 17 00:00:00 2001 From: Jiang Guang Ming Date: Tue, 9 Jun 2026 15:40:34 +0800 Subject: [PATCH] fix(dfu): retry dfu-util flash on macOS detach failure Co-authored-by: Cursor --- docs/en/api-guides/dfu.rst | 2 +- docs/zh_CN/api-guides/dfu.rst | 2 +- tools/cmake/run_dfu_util.cmake | 7 +++++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/en/api-guides/dfu.rst b/docs/en/api-guides/dfu.rst index d96c62819be..7023c0cd35b 100644 --- a/docs/en/api-guides/dfu.rst +++ b/docs/en/api-guides/dfu.rst @@ -161,7 +161,7 @@ Common Errors and Known Issues - The reason for ``No DFU capable USB device available`` could be that the USB driver was not properly installed on Windows (see :ref:`api_guide_dfu_flash_win`), udev rule was not setup on Linux (see :ref:`api_guide_dfu_flash_udev`) or the device is not in bootloader mode. -- Flashing with ``dfu-util`` on Windows fails on the first attempt with error ``Lost device after RESET?``. Please retry the flashing and it should succeed the next time. +- Flashing with ``dfu-util`` on Windows or macOS may fail on the first attempt with error ``Lost device after RESET?``. ``idf.py dfu-flash`` retries once automatically. If flashing still fails, run ``idf.py dfu-flash`` again manually. .. only:: SOC_SUPPORTS_SECURE_DL_MODE diff --git a/docs/zh_CN/api-guides/dfu.rst b/docs/zh_CN/api-guides/dfu.rst index 09718e91b22..cce679078c7 100644 --- a/docs/zh_CN/api-guides/dfu.rst +++ b/docs/zh_CN/api-guides/dfu.rst @@ -161,7 +161,7 @@ Zadig 工具可能会检测到 {IDF_TARGET_NAME} 的多个 USB 接口。请 ** - 出现 ``No DFU capable USB device available`` 错误的原因可能是在 Windows 上没有正确安装 USB 驱动程序（请参考 :ref:`api_guide_dfu_flash_win`），或是未在 Linux 上设置 Udev 规则（请参考 :ref:`api_guide_dfu_flash_udev`），或是设备未处于引导加载程序模式。 -- 在 Windows 上使用 ``dfu-util`` 第一次烧录失败，并出现 ``Lost device after RESET?`` 错误信息。出现此问题时，请重新烧录一次，再次烧录应该会成功。 +- 在 Windows 或 macOS 上使用 ``dfu-util`` 第一次烧录可能失败，并出现 ``Lost device after RESET?`` 错误信息。``idf.py dfu-flash`` 会自动重试一次。如果仍然失败，请手动再次运行 ``idf.py dfu-flash``。 .. only:: SOC_SUPPORTS_SECURE_DL_MODE diff --git a/tools/cmake/run_dfu_util.cmake b/tools/cmake/run_dfu_util.cmake index 49113030c4b..967ce182580 100644 --- a/tools/cmake/run_dfu_util.cmake +++ b/tools/cmake/run_dfu_util.cmake @@ -23,6 +23,13 @@ endif() message("Command list: ${CMD}") execute_process(COMMAND ${CMD} RESULT_VARIABLE result) +# dfu-util may fail on the first attempt while switching from runtime to DFU mode, +# e.g. with "Lost device after RESET?" on Windows/macOS. Retry once. +if(${result} AND NOT ${ESP_DFU_LIST}) + message(WARNING "${TOOL} failed, retrying once...") + execute_process(COMMAND ${CMD} RESULT_VARIABLE result) +endif() + if(${result}) message(FATAL_ERROR "${TOOL} failed") endif()