esptool.py
Flash firmware to ESP chips
TLDR
Flash a firmware file to an ESP chip with a given port and baud rate
Clear the flash of an ESP chip
SYNOPSIS
esptool.py [options] command [command_options]
PARAMETERS
--port
Serial port device. Defaults to $ESPTOOL_PORT, or tries to auto-detect.
--baud
Serial port baud rate. Defaults to 115200.
--before
How to reset the chip before running commands. Options are 'default_reset', 'no_reset', 'hw_reset'. Defaults to 'default_reset'.
--after
How to reset the chip after running commands. Options are 'hard_reset', 'soft_reset', 'no_reset', 'default_reset'. Defaults to 'default_reset'.
--chip
Target chip type. Usually auto-detected. Overrides default behavior. Supported values are esp8266, esp32, esp32s2, esp32s3, esp32c3, esp32h2.
--no-stub
Disable the flasher stub upload. Disabling the stub makes flashing faster but requires more memory in the bootloader.
erase_flash
Erase the entire flash memory.
write_flash [--flash_mode
Write one or more binary files to flash. Requires address-filename pairs. Flash mode, frequency & size can be specified.
read_flash
Read flash memory to a file.
verify_flash
Verify flash memory against a file.
run
Start running the application code.
image_info
Read image file's load address(es).
make_image
Generate an image suitable for OTA updates from provided elf file(s).
DESCRIPTION
esptool.py is a command-line tool for communicating with the ROM bootloader in Espressif ESP32 and ESP8266 SoCs. It is primarily used for flashing firmware images to these chips over a serial connection. It supports a wide range of operations, including erasing flash memory, reading flash memory, writing flash memory, and verifying flash contents. The tool is written in Python and is designed to be portable and easy to use.
It is the tool of choice when you wish to interact at a low level with the Espressif chips and don't want to use higher-level SDK's or frameworks. It provides precise control over the flashing process. It can also be used for tasks like reading the chip's MAC address or changing flash mode/frequency settings. esptool.py is indispensable for developers working with ESP32 and ESP8266 microcontrollers.
CAVEATS
Certain operations, especially writing to flash, can potentially brick the device if not done carefully. Always double-check the addresses and files being used. Use appropriate serial port settings.
DEPENDENCIES
esptool.py requires Python (versions 2.7 or 3.4 and newer) and the pyserial library. These can be installed using pip: `pip install esptool pyserial`
FLASH MODES & FREQUENCIES
The flash mode (qio, qout, dio, dout) and frequency (e.g., 40MHz) need to match the settings used when the firmware was built. Incorrect settings can lead to boot failures. Incorrect flash size will cause errors when flashing and potentially boot failures.
RESET BEHAVIOR
Pay attention to the '--before' and '--after' options as they control how the ESP chip is reset before and after flash operations. Wrong reset behavior can prevent the chip from entering flashing mode or running the newly flashed code.
HISTORY
esptool.py was originally developed as an open-source project for flashing the ESP8266. It was subsequently extended to support the ESP32 family of chips. It's actively maintained and has become the standard tool for interacting with Espressif chips' ROM bootloaders. Development is ongoing, with new features and chip support being added regularly.