esptool.py

Flash firmware to ESP chips

TLDR

Flash a firmware file to an ESP chip with a given port and baud rate

$ sudo esptool.py --port [port] --baud [baud_rate] write_flash 0x0 [path/to/firmware.bin]

Clear the flash of an ESP chip

$ sudo esptool.py --port [port] --baud [baud_rate] erase_flash

SYNOPSIS

esptool.py [options] command [command_options]

--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 ] [--flash_freq ] [--flash_size ]

[

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