Version 3.3.2

This bugfix release of an older esptool.py version is intended only for purposes when v3.3 needs to be used. The latest v4 release is recommended and under active development.

New Features

• write_flash: Added the ability to recover from serial errors when flashing, effectively making data transfers more robust (#182)
• Added more memory density definitions to cover known flash chips (#769)
• Added parsing of stub flasher error definitions in esptool messages

espefuse.py

• Added XTS_AES_256 key_purpose on ESP32-S3-beta2
• burn_efuse: Improved error messages when a new data value is incorrect (#760)

Bug Fixes

• load_extended_header: Load the minimum chip revision min_rev field
• Fixed faulty hard_reset() with RTS pin for ESP32-S2/S3 in slower environments
• get_default_connected_device: Fixed closing unused ports

espefuse.py

• Corrected eFuse tables
• Removed XTS_AES_256 key purposes on ESP32-C3
• Fixed location of FAIL_BIT and NUM_BITS on ESP32-C3
• Added a warning to specify the --port/-p argument if connection fails (#744)

espsecure.py

• _microecc_format: Pad zeroes to curve length
• Fixed argparse Secure Boot key generation command to work with both V1 and V2

Thanks to @johnboiles, @hathach, and others for contributing to this release!

Full Changelog: v3.3.1...v3.3.2

Version 4.3

New Features

• image_info: Added image type autodetection, specifying --chip is no longer needed
• image_info: Added the ability to display application info if a valid app image is detected
• write_flash: Added the ability to recover from serial errors when flashing, effectively making data transfers more robust (#182)
• write_flash: Added checks to prevent flashing if an incompatible chip type or chip revision is used, --force can be used to override this restriction
• Added more memory density definitions to cover known flash chips (#769)
• Added parsing of stub flasher error definitions in esptool messages
• Added support for Major.Minor chip revision versioning scheme in the format vX.Y

Bug Fixes

• Listed BLE as an ESP32-C3 feature (#770)
• Included MANIFEST in sdist to fix RPM packaging (#767)
• espefuse.py: Fixed burning of ENABLE_SECURITY_DOWNLOAD eFuse

Internal features

Experimental support for ESP32-C6 has been added (--no-stub only). Burning eFuses is not recommended. This SoC is not generally available, so it is not fully supported in this release. Official support will be added in a later release.

Thanks to @johnboiles, @Jason2866, @Robsteranium, and others for contributing to this release!

Version 4.2.1

Bug Fixes

• Fixed faulty hard_reset() with RTS pin for ESP32-S2/S3 in slower environments
• Fixed stub JSON files not being included in executables built by pyInstaller

Thanks to @hathach and others for contributing to this release!

Version 4.2

New Features

• Added a readable message when a device is not detected on a given port (#751)
• image_info: Print flash settings and extended header fields with --version 2 argument
• Added support for 26 MHz XTAL on ESP32-C2
• Expanded minimum revision field to accept higher chip revisions

espefuse.py

• Added XTS_AES_256 key_purpose on ESP32-S3-beta2
• burn_efuse: Improved error messages when a new data value is incorrect (#760)
• get_pkg_version: Fixed on ESP32-C2 (#759)
• Added major and minor wafer version eFuses

Bug Fixes

• load_extended_header: Load the minimum chip revision min_rev field
• Fixed flasher stub on ESP32-H2

espefuse.py

• Removed XTS_AES_256 key purposes on ESP32-C3
• Fixed location of FAIL_BIT and NUM_BITS on ESP32-C3
• Added a warning to specify the --port/-p argument if connection fails (#744)

espsecure.py

• _microecc_format: Pad zeroes to curve length

Miscellaneous Changes

• Clarified USB-OTG-related functions (#756, #757)
• Stub codes are now included as JSON files with metadata for each target

Thanks to @befeleme and others for contributing to this release!

Version 4.1

New Features

• ESP32-C2: Added flash encryption support
• elf2image: Added argument to disable appending SHA256 digests

Bug Fixes

• espsecure.py: Fixed Secure Boot V1 key generation
• espefuse.py: Corrected eFuse tables

Version 4.0.1

Bug Fixes

• Patched the wrapper scripts to not import themselves to allow running esptool, espefuse, and espsecure in different environments and importing these directly in other Python scripts.

Version 4.0

Starting from v4.0.0, esptool adopts the semantic versioning specification, please read the related "Versions" esptool documentation page when deciding which version to use.

Breaking changes

• Public API has been defined by limiting access to internals that have been refactored into multiple source files. Changing or refactoring these limited internals won't be considered a breaking change in future releases. Migration is easy and self-explanatory (you will get an import error if something has moved) and is required only in projects that import esptool directly.
• If active security features are detected, the default behavior changes to prevent unintentional bricking (#699):
  • If flash encryption is enabled, erase_flash and erase_region cannot be executed.
  • If secure boot is enabled, erase_flash, erase_region and write_flash operations cannot be performed (write_flash is just restricted to protect the bootloader region 0x0000->0x8000).
  • An override flag --force lets the users execute these operations anyways.
• Flash parameters in an image header can now be changed only when no SHA256 digest is appended (espressif/esp-idf#8798).
• Python versions 2.7, 3.4, 3.5, and 3.6 have been deprecated, the code is now Python 3-only compatible. Releases v4 and later can't be installed from PyPI on these deprecated Python versions.
• The ESP8684 alias has been removed, ESP32-C2 has to be used.
• Megabit flash sizes have been deprecated, use megabyte units from now on.

New Features

• Added stub flasher support for ESP32-C2 ECO1, deprecated ECO0 stub (can still be used with ROM).

espefuse.py

• Added a new package - ESP32-D0WDR2-V3

Bug Fixes

• Fixed ESP32-S3 USB-OTG compressed flashing
• Fixed division by zero error when reading flash (#729)

Miscellaneous Changes

• Black code formatting has been adopted in the esptool project. Contributions will be automatically formatted in a compatible way when following the contributions guide.

Thanks to everyone who contributed to this release.

Version 3.3.1

New Features

• Added stub flasher support for ESP32-C2 ECO1, deprecated ECO0 stub (can still be used with ROM)

espefuse.py

• Added a new package - ESP32-D0WDR2-V3

Bug Fixes

• Fixed ESP32-S3 USB-OTG compressed flashing

Version 3.3

New Features

• Added flash size options up to 128MB. (#680)
• Added stub flasher support for ESP32-C2.
• Added --flash-mmu-page-size option to change flash MMU page size on ESP32-C2.
• Added address and dummy cycles configuration to SPI flash commands, allowed reading flash SFDP registers.
• Added target-specific flash frequency options.

espsecure.py

• Added support for ECDSA P192 and P256 signatures in Secure Boot V2.
• Refined Secure Boot V2 ECC support.
• Added support for XTS_AES_128 using 128 bit key FE scheme.

espefuse.py

• Added execute_scripts nesting support, a script can now be called from another script.
• Added ESP32-C2 espefuse.py support.
• Fixed power-out time for VDDQ settings for ESP32-S3.
• Removed dysfunctional JTAG_SEL_ENABLE on ESP32-C3.
• Removed unused eFuse fields on ESP32-C3 and ESP32-H2.
• Added execute_scripts error handling in script files. (espressif/esp-idf#8420)
• Added support for running multiple commands at once.
• Added checks for secure download mode.
• Added a recovery option to fix eFuse blocks after encoding errors.

Internal features

These features are intended for use inside Espressif:

• Preview support for ESP32-H2-beta2 has been added. This SoC is not generally available, so it is unsupported in this release. Official support will be added in a later esptool.py release.

Bug Fixes

• Fixed autodetection on ESP32-S2 in USB-OTG mode. (#685)
• Fixed flash.rodata not being recognized as part of IRAM in the ELF parser.
• Fixed wrong UART_RXFIFO_CNT_M mask values in the stub flasher.
• Added overerase detection and a fix sequence for certain XMC flash chips.
• Allowed USB PID detection for USB-JTAG-Serial mode on lowercase port names.
• Fixed chip autodetection to work in secure download mode.
• Fixed wrong firmware image being returned for beta chips.
• Fixed a wrong bootloader flashing offset on ESP32-S3. (#728)

Miscellaneous Changes

• Launched a new self-hosted esptool.py documentation and heavily updated its contents.
• Renamed the ESP8684 target to ESP32-C2 (added alias for compatibility).
• Added a warning for flash sizes that are not supported by the stub flasher.

Thanks to @ESP32DE, @lucasrangit, @Jason2866, and others for contributing to this release.

Version 3.2

New Features

• Support for ESP32-S3 SoC has been added (removed ESP32-S3-beta3).
• Added USB-JTAG-Serial and USB-CDC support for ESP32-S3.
• Added a check to disable stub when connecting to an unsupported chip.
• Added boot log detection and context of failures logging.
• Improved error messages to cover more cases and provide more information.
• Added get_security_info command stub support.
• Augmented chip autodetection to work even in secure download mode. (ESP32-C3 and later only)
• Added flash chip connection verification check.
• Added ESP8266 version 3 image format support.

espsecure.py

• Added option for 512bit keys for encrypt_flash_data.

espefuse.py

• Added a new command which can execute custom python scripts to burn efuses all at once.
• Added ESP32-S2 flash_ver, psram_ver, and pkg_ver efuses.
• Corrected lenght of soft_dis_jtag efuse.
• Added custom_mac eFuse field for ESP32-C3/-S2/-S3/-H2.
• Added a check for read_protect_efuse. (#640)
• Added support for 512bit XTS_AES flash encryption key.
• Added a step to close the serial port after espefuse operations. (#671)
• Added a security confirmation flag to espefuse tests. (#677)

Internal features

These features are intended for use inside Espressif:

• Preview support for ESP32-H2 and ESP8684 has been added. These SoCs are not generally available, so they are unsupported in this release. Official support will be added in a later esptool release.
• Added automatic delay for boot time after ESP32 reset in FPGA.

Bug Fixes

• Fixed build from sources (require wheel only when installing from pip). (#632)
• Fixed failing flashing process on some supported chips. (#635)
• Fixed ESP32-C3 package detection. (#638, #639)
• Fixed test child processes being blocked waiting for the OS pipe buffer to accept more data. (#637)
• Fixed MacOS USB PID detection on tty and cu ports.
• Fixed erroneous comparison when handling deflated data. (#650)

Miscellaneous Changes

• Changed unnecessarily alarming error to a warning. (#631)
• Removed ESP32 rev0 connection workaround.
• Added a readable error and a use example to merge_bin.

Thanks to @bbilas, @xingrz, @loader-bsd, @alvarolb, and others for contributing to this release.