esptool.py

ESP8266 and ESP32 series flashing tool

TLDR

Flash firmware to ESP board

$ esptool.py --port [/dev/ttyUSB0] write_flash 0x0 [firmware.bin]

Read chip info and MAC address

$ esptool.py --port [/dev/ttyUSB0] chip_id

Erase entire flash

$ esptool.py --port [/dev/ttyUSB0] erase_flash

Read flash to file

$ esptool.py --port [/dev/ttyUSB0] read_flash 0x0 0x100000 [backup.bin]

Identify the SPI flash chip

$ esptool.py --port [/dev/ttyUSB0] flash_id

Set baud rate for faster flashing

$ esptool.py --port [/dev/ttyUSB0] --baud [921600] write_flash 0x0 [firmware.bin]

Read the MAC address

$ esptool.py --port [/dev/ttyUSB0] read_mac

SYNOPSIS

esptool.py [options] command [args]

esptool.py is the official flashing tool for Espressif ESP8266, ESP32, ESP32-S2, ESP32-S3, ESP32-C3, and other chips in the ESP series. It communicates over serial to program firmware, read/write flash, and manage the boot process.The tool handles bootloader communication, flash layout, and various chip-specific requirements. It supports multiple flash sizes, frequencies, and modes (qio, qout, dio, dout). By default, data is compressed during transfer for better performance.esptool.py is essential for ESP development, used by Arduino IDE, PlatformIO, and ESP-IDF for firmware deployment.

PARAMETERS

COMMAND

Operation: writeflash, readflash, eraseflash, chipid, flashid, readmac, etc.

--port PORT

Serial port device (e.g., /dev/ttyUSB0, COM3).

--baud RATE

Serial baud rate (default: 115200).

--chip CHIP

Target chip type (auto, esp8266, esp32, esp32s2, esp32s3, esp32c3, etc.).

--before ACTION

Action before connecting: defaultreset, noreset, noresetno_sync.

--after ACTION

Action after operation: hardreset (default), softreset, noreset, noreset_stub.

--no-stub

Disable stub loader; communicate directly with ROM bootloader.

write_flash ADDR FILE [ADDR FILE ...]

Write one or more binaries to flash at specified addresses.

read_flash ADDR SIZE FILE

Read flash contents to file.

erase_flash

Erase entire flash.

erase_region ADDR SIZE

Erase a specific flash region (must be sector-aligned to 4096 bytes).

chip_id

Read chip ID.

flash_id

Read SPI flash manufacturer and device ID.

read_mac

Display the MAC address burned into the chip.

image_info FILE

Display metadata about a binary image file.

merge_bin -o OUTPUT ADDR FILE [ADDR FILE ...]

Merge multiple binaries into a single flashable file.

--help

Display help information.

CAVEATS

Requires serial driver for USB adapter (e.g., CP210x, CH340). Boot mode may need manual GPIO0 control on some boards. Flash addresses are chip-specific. Higher baud rates increase speed but may reduce reliability. The erase_region address and size must be aligned to 4096-byte sector boundaries.

HISTORY

esptool.py was developed by Espressif Systems as the official tool for their ESP8266 and ESP32 series of WiFi/Bluetooth microcontrollers, widely used in IoT projects. It is open-source and available via PyPI (`pip install esptool`).