- The default
esptool.py write_flash --flash_sizeargument has changed from
keep. This means that if no
--flash_sizeargument is passed when flashing a bootloader, the value in the bootloader .bin file header is kept instead of detecting the actual flash size and updating the header. To keep the old behaviour, add the argument
esptool.py [...] write_flash [...] -fs detect
espefuse.pycommand line arguments for ESP32 have changed:
- The key usage
secure_boothas been replaced with
secure_boot_v2. Secure Boot V2 is the new RSA-based Secure Boot mechanism supported on ESP32 V3.
- Support for ESP32-S2 SoC has been added
- Support for detecting ESP32-PICO-V3-02 and ESP32-U4WDH have been added
- Fixed scrolling problems when output is redirected (for example in Arduino IDE, see discussion at #482)
- Produce a meaningful error if the SoC we connect to doesn't match the
- Support different capitalization and spelling for
-c esp32-s2, etc.
- Added dedicated program
esp_rfc_2217_server.pyfor flashing via RFC2217 (i.e. flashing over the network, #383)
- Added support for Secure Boot V2 (ESP32 V3, ESP32-S2)
- Secure Boot V1: PKCS8 formatted ECDSA keys are now supported via ecdsa library (not including password protected keys)
- Added ESP32 ECO3 efuse
- Added new batch burn mode, support burning more than one eFuse on a single command line
- espefuse.py internals have been refactored to support multiple chips, produce more information about which eFuses are being written to which values.
- "Virtual" mode added for host-based testing, allows updating eFuse values on a "virtual" chip inside the host.
These features are intended for use inside Espressif:
- Support for ESP32-S3beta2 & ESP32-C3 have been added. These SoCs are not currently available outside Espressif, so these SoCs are unsupported in this release. Official support will be added in a later esptool release.
esptool.py --no-stub read_flashis now supported on ESP32 and later. This option is slower than using the default stub option to read flash, so it's generally not useful for production SoCs.
- Added temporary workaround for a pyserial failure on macOS Big Sur Preview (#540)
- Fixed gcc9 warning in the stub (#501)
- Fixed some memory types printed in the memory map output
- Fixed the check for zero bytes before applying an ELF SHA-256 with
elf2image --elf-sha256-offsetoption (#560)
- Fixed displaying some single core ESP32 features incorrectly, i.e. ESP32-S0WD
- Fixed exception on Python 3 if the same flash address was repeated twice (#558)
- Updated miniz to v2.1.0 (#500)
- Moved ESP32 stub loader location to facilitate loading large applications direct to IRAM
- Vendored modules ecdsa, pyaes and optional pycrypto have been removed. Pyaes has been replaced with the pyca-cryptography library
esptool.py image_infonow prints a summary of segment memory types (IRAM, DRAM, etc) based on the address range.
esptool.py write_flashwill warn if it looks like a bootloader binary is built for ESP32-S2 or another newer chip (support for flashing ESP32-S2 will be added in a future version.)
- Removed ESP8266 SDK & ESP-IDF dependencies when building the flasher stub binaries. Previously the SDKs were used to include some register address macros, only. This removes any uncertainty about whether the flasher stub binary is a derived work of either SDK. The flasher stub binary itself is the same as the binary in v2.7.
- Fixed minor issues running esptool automated tests on macOS.
- Minor flake8 fixes including compatibility with newer flake8 versions.
- Support detection of new ESP32 silicon revisions
esptool.py elf2image --min-rev Xoption allows creating a .bin file which only supports a minimum ESP32 silicon revision.
- Fix burning custom MAC with espefuse.py when 3/4 Coding Scheme is set (#447)
- New option
write_flash --flash-size keepwill keep whatever flash size is set in the bootloader header, matching the behaviour of
--flash-speed keep. The default is still
--flash-size detectbut may be changed to
keepin a future major update, to be consistent with the other two options.
write_flashno longer updates the flash header if the file being written to the bootloader offset isn't a valid image file for the chip. This is useful for flashing pre-encrypted data to ESP32s, where the image file contains ciphertext.
- esptool now always prints the detected crystal frequency (26MHz or 40MHz) as part of general chip information, and will warn if the detected frequency deviates by an unexpected amount.
- Passing arguments to
main()from Python is now documented in the README (#408)
elf2image --sha256-offsetwill now only write the ELF SHA-256 to this offset if the existing data is all zeroes. Otherwise a warning is printed.
- Improved the error message if esptool searches all serial ports and finds nothing. (#401)
write_flash --encryptoption that works with the new Development Mode flash encryption that will be the default flash encryption development workflow in ESP-IDF V4.0.
espefuse.py summary --format jsonwill print a JSON dictionary of efuse summary data (#436)
espefuse.pyburn commands now set the efuse timing before burning, in line with recent ESP32 TRM update.
espsecure.pykey operations now support
--keylenargument, allowing 192-bit keys for ESP32s with 3/4 Coding Scheme set.
espsecure.pyencryption and decryption speed substantially improved. (#416)
FLASH_CRYPT_CNTefuse is now defined as 7 bits wide, as eight bit is not used by flash encryption hardware.
- Flasher stub is now built with gcc 5.2.0 toolchain.
write_flash --erase-all ...option to erase all flash before writing (single command). (#344)
- Support patching the SHA256 digest of the ELF file into the binary (available in ESP-IDF via app description APIs)
- Make calling esptool module functions and
esptool.main()more Python-friendly (all functions clean up open files correctly,
main(...)can take an optional argument with a command line formatted as a list.) (#341)
- Fix crash due to unimplemented write timeout on RFC2217 ports
- elf2image no longer adds empty ELF sections (zero length) to the .bin file
- elf2image fails with a proper error if an ELF file contains more than 16 loadable sections
- Improve error message if list_ports is missing from pyserial (#350)
- Fix some write_flash timeouts writing large but highly compressible payloads
- Fix bug where flashing with stub would fail if ESP8266 was in deep sleep immediately beforehand. (#351)
- Support for reading/writing efuses when 3/4 Coding Scheme is set details.
- espefuse.py supports displaying and setting a custom MAC address in BLK3 of efuse
- espsecure.py can now verify signatures with raw binary key file as well as PEM formatted key file (#357)
- Workaround a mapping bug in the ESP-IDF bootloader (if IROM/DROM segment ended less than 0x20 bytes after a page boundary, older ESP-IDF bootloaders would not map the final page correctly).
- Reformat espefuse.py summary output (includes: read-only efuses now display value ? not 0, byte order of keys shown for BLK1,BLK2 are now shown in software order not the reversed byte order used by hardware cryptographical modules.)
- espsecure.py: Fix Python 3 compatibility issues (includes #369 #382)
- Errors during chip detection are now formatted correctly.
- OSError is handled correctly while scanning for a port (#322)
- Update link to flashrom repo for SPI flash chip IDs (#338)
- read_flash command: Error out immediately if an invalid length packet is received (common symptom of bad serial link) (#342)
- espefuse.py: Disable burning key efuses when 3/4 Coding Scheme is set (support for burning keys with 3/4 Coding Scheme will be added in a future update).
Thanks to @orangecms for contributing to this release.
- Set a write timeout in pyserial (prevents hanging in sync process if port is unavailable).
- (ESP32) New option
elf2image --secure-padto pad the output binary so once signed it will align to an flash cache page boundary (64KB). Prevents unsigned data from being mapped into the instruction space via the flash cache.
- Fix exception if no
--portis specified but no serial ports are found in the system.
- (ESP32) espsecure: Fix bug where
digest_secure_bootloadercould produce an incorrect digest.
- --port argument was not correctly handled in v2.4.0
- Corrected pyserial dependency to require pyserial v3.0 or newer
ESP8266 & ESP32 changes
- If no serial port is specified, try all serial ports until an Espressif
- Print device MAC on every command, after connecting.
- New option
--before no_reset_no_syncfor use when immediately reusing the
serial port with an already-running loader.
- Fix spurious load_ram error when executed code immediately resets the UART
- Produce an error if load_ram is going to clobber bootloader stub memory (can use
--no-stub to work around this).
- Display a helpful error if the incompatible 'serial' module was installed
instead of 'pyserial'.
- Explicitly close the serial port at end of main() function (allows calling
esptool.main() from another Python program for basic scripting.)
- Workaround Windows usbser.sys (USB CDC-ACM device) driver bug setting DTR & RTS
- Flasher stub build updates to work with recent ESP-IDF & ESP8266 SDK headers
- Flasher stub now sends correct length field in protocol responses (esptool.py
was ignoring this field, but some other tools were not).
- Move the loader stub to the very end of IRAM (useful when using load_ram command).
elf2image --version=2is now compatible with recent ESP8266 SDK bootloader
and produces the same binary output as ESP8266 SDK gen_app.py.
- Remove unsupported flash size 4MB-c2
- Print chip frequency rating values in Features list, for chips where these are
- Working load_ram command.
- espefuse.py: Support setting the baud rate.
- New --override-vddsdio option allows setting the VDDSDIO regulator to 1.8V,
1.9V or "OFF" when connecting (to override the default value read from efuse).
To avoid hardware damage, forcing VDDSDIO to 3.3V is not supported.
Latest stable release available from PyPi:
New since v2.3
- Fixes a bug where Features line was mis-formatted for ESP8266 and triggered an exception on ESP8285.
Latest stable release available from PyPi:
New since v2.2.1
- 'Hard resetting' status message now mentions the RTS pin
- README additions
- Fix regression if esptool is used as a module and ESPLoader() is passed a Python 2 unicode string.
- When connecting, esptool now prints a summary of chip features based on efuse contents.
- espefuse.py support for displaying ADC calibration data via VRef stored in efuse and BLK3_PART_RESERVE if set.