Skip to content

Latest commit

 

History

History
135 lines (95 loc) · 5.78 KB

dfu.rst

File metadata and controls

135 lines (95 loc) · 5.78 KB
Raw

Device Firmware Upgrade through USB

esp32

Note

Device Firmware Upgrade through USB is not supported with ESP32 chips.

Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of devices through Universal Serial Bus (USB). DFU is supported by ESP32-S2 chips. 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)

Note

The ESP32-S2 chip needs to be in bootloader mode for the 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.

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.

The software requirements of DFU are included in get-started-get-prerequisites of the Getting Started Guide.

Section api_guide_dfu_build describes how to build firmware for DFU with ESP-IDF and Section api_guide_dfu_flash deals with flashing the firmware.

Building the DFU Image

The DFU image can be created by running:

idf.py dfu

which creates dfu.bin in the build directory.

Note

Don't forget to set the target chip by idf.py set-target before running idf.py dfu. Otherwise, you might create an image for a different chip or receive an error message something like unknown target 'dfu'.

Flashing the Chip with the DFU Image

The DFU image is downloaded into the chip by running:

idf.py dfu-flash

which relies on dfu-util. Please see get-started-get-prerequisites for installing dfu-util. dfu-util needs additional setup for api_guide_dfu_flash_win or setting up an api_guide_dfu_flash_udev. Mac OS users should be able to use dfu-util without further setup.

If there are more boards with the same chip connected then idf.py dfu-list can be used to list the available devices, for example:

Found Runtime: [303a:0002] ver=0723, devnum=4, cfg=1, intf=2, path="1-10", alt=0, name="UNKNOWN", serial="0"
Found Runtime: [303a:0002] ver=0723, devnum=6, cfg=1, intf=2, path="1-2", alt=0, name="UNKNOWN", serial="0"

Consequently, the desired device can be selected for flashing by the --path argument. For example, the devices listed above can be flashed individually by the following commands:

idf.py dfu-flash --path 1-10
idf.py dfu-flash --path 1-2

Note

The vendor and product identificators are set based on the selected chip target by the idf.py set-target command and it is not selectable during the idf.py dfu-flash call.

See 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.

Create file /etc/udev/rules.d/40-dfuse.rules with the following content:

SUBSYSTEMS=="usb", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="00??", GROUP="plugdev", MODE="0666"

Note

Please check the output of command groups. The user has to be a member of the GROUP specified above. You may use some other existing group 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.

USB drivers (Windows only)

dfu-util uses libusb to access the device. You have to register on Windows the device with the WinUSB driver. Please see the libusb wiki for more details.

The drivers can be installed by the Zadig tool. Please make sure that the device is in download mode before running the tool and that it detects the ESP32-S2 device before installing the drivers. The Zadig tool might detect several USB interfaces of ESP32-S2. Please install the WinUSB driver for only that interface for which there is no driver installed (probably it is Interface 2) and don't re-install the driver for the other interface.

Warning

The manual installation of the driver in Device Manager of Windows is not recommended because the flashing might not work properly.

Common errors and known issues

  • dfu-util: command not found might indicate that the tool hasn't been installed or is not available from the terminal. An easy way of checking the tool is running dfu-util --version. Please see get-started-get-prerequisites for installing dfu-util.
  • The reason for No DFU capable USB device available could be that the USB driver wasn't properly installed on Windows (see api_guide_dfu_flash_win), udev rule was not setup on Linux (see api_guide_dfu_flash_udev) or the device isn't 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.