esptool.py

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]

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

esptool.py [OPTIONS] COMMAND [ARGS]

--chip CHIP
    Target chip (auto, esp8266, esp32, esp32s2/s3/c3/c6/h2). Default: auto

--port PORT, -p PORT
    Serial port (/dev/ttyUSB0)

--baud BAUD, -b BAUD
    Flash baudrate (115200). Use --baud-download for separate read/write speed

--before {default_reset,usb_reset,...}
    Command before connecting (default_reset)

--after {no_reset,hard_reset}
    Command after flashing (default_reset)

--no-stub
    Disable ROM stub loader

--stub IMAGE
    Path to custom stub firmware

--compress / --no-compress
    Enable/disable LZMA compression (enabled)

--verify / --no-verify
    Verify written data (enabled)

--diff {none,auto,force}
    Diff mode for verification (auto)

--flash_mode {keep,dio,qio,...}
    Flash mode (keep)

--flash_freq {keep,40m,80m,...}
    Flash frequency (keep)

--flash_size {keep,4MB,16MB,...}
    Flash size (detect)

--erase-all / --erase-block
    Erase all flash / by blocks

--trace
    Enable trace output

--keep
    Keep loader for reuse

esptool.py is a versatile Python-based command-line tool for Espressif ESP microcontrollers like ESP8266, ESP32, ESP32-S2/S3/C3/C6/H2. It interfaces via serial port with the ROM bootloader to handle flash operations, chip detection, and configuration.

Key uses include:
• Flashing firmware: Upload binaries with compression, verification, and custom flash parameters (mode: DIO/QIO, freq: 40MHz/80MHz, size: 4MB).
• Erasing flash: Full or block erase before updates.
• Reading/writing flash: Dump contents or program specific addresses.
• Diagnostics: Read MAC, chip/flash ID, eFuses.

Supports advanced features like stub loaders for secure boot chips, encryption, trace mode. Cross-platform (Linux/macOS/Windows), requires pyserial. Install via pip install esptool. Ideal for IoT firmware deployment, Arduino IDE integration, and ESP-IDF workflows. Auto-detects many params but specify --port /dev/ttyUSB0 --baud 115200 for reliability.

Requires bootloader mode (hold BOOT/EN+RESET). Linux needs udev rules for USB access (e.g., esp32.rules). High baud (>460800) demands quality FTDI/CP210x adapters. No GUI; serial conflicts with monitors like screen(1).

erase_flash - Erase all flash.
write_flash [-z] ADDR FILENAME - Write with pad/null-fill.
read_flash ADDR SIZE OUTFILE - Dump flash.
flash_id - Chip/flash info.
read_mac - MAC address.

pip install esptool (Python 3.7+). Or apt: python3-esptool on Debian.

esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash -z 0x1000 bootloader.bin 0x8000 partitions.bin 0x10000 firmware.bin

Originated 2013-2014 for ESP8266 by community (themadinventor/esptool). Espressif adopted/enhanced for ESP32 (2016+), now v4.x in ESP-IDF. Active on GitHub/espressif/esptool.

screen(1), minicom(1), stty(1), avrdude(1)