esptool Guide: ESP32 & ESP8266 Flashing Protocol

This guide explains how esptool (Espressif's flashing tool) works under the hood, the differences between esptool.py and esptool-js, common commands, and how browser-based ESP flashing compares to traditional methods.

What is esptool?

esptool.py is the official open-source Python tool from Espressif that communicates with the ESP32, ESP8266, and related chip ROM bootloaders. It handles the low-level serial protocol: baud rate synchronization, flash write with compression, MD5 verification, chip register access, and memory operations. Every flashing tool — Arduino IDE, PlatformIO, ESPHome, Tasmota web installer — ultimately relies on esptool under the hood.

esptool.py vs esptool-js

How the ESP ROM Bootloader Protocol Works

When you flash firmware to an ESP32, the following sequence happens:

1. Sync: The tool sends synchronization bytes at the configured baud rate. The chip's ROM bootloader responds with an acknowledgment. If no response, the tool retries with different baud rates (auto-baud detection).
2. Handshake: After sync, the tool reads chip information: chip model, MAC address, flash size, and security features.
3. Erase: If erase-before-flash is enabled, the tool sends an erase command for the target flash region (or the entire flash).
4. Write: Firmware data is split into 16 KB blocks. Each block is compressed using a sliding-window algorithm and sent to the chip. The chip decompresses and writes to flash. The tool sends the next block while the chip processes the previous one (pipelining).
5. Verify: After writing all blocks, the tool requests an MD5 checksum of the written data from the chip and compares it to the local MD5 of the source file.
6. Reset: The chip is reset (via DTR/RTS or a serial break signal) to boot the new firmware.

The entire process typically completes in 15-30 seconds for a 1-2 MB firmware at 921,600 baud.

Common esptool Commands

esptool.py --port COM3 flash_id
esptool.py --port COM3 read_mac
esptool.py --port COM3 chip_id
esptool.py --port COM3 erase_flash
esptool.py --port COM3 write_flash 0x0 firmware.bin
esptool.py --port COM3 read_flash 0x0 0x400000 backup.bin
esptool.py --port /dev/ttyUSB0 merge_bin --output merged.bin 0x1000 boot.bin 0x8000 partitions.bin 0x10000 app.bin

ESP32 Flash Addresses

For a single merged/factory .bin file, always use address 0x0 regardless of chip.

Browser-Based Flashing with ESP Flasher App

ESP Flasher App implements the full esptool protocol in the browser using esptool-js. It provides all the essential functionality of esptool.py through a visual interface:

• Write firmware to any address
• Auto-detect chip on connect
• Erase flash before writing
• MD5 verification after write
• Multi-file flashing with reorder
• Flash memory map visualization
• Built-in serial monitor for debugging

Flash Encryption and Secure Boot

ESP32 supports hardware flash encryption (AES-XTS) and secure boot. When these features are enabled, firmware must be encrypted with the chip-specific key before flashing. The encryption is typically done in the build pipeline (esptool.py supports it via the --encrypt flag). ESP Flasher App supports flashing pre-encrypted .bin files at the correct address — the chip handles decryption transparently during boot.

Related Resources

• ESP Flasher App — Free browser-based ESP flashing tool
• ESP32 Flash Addresses Reference
• esptool.py Documentation (Espressif official)
• esptool-js on GitHub

ESP Flasher App — Browser-based ESP32 & ESP8266 firmware flashing tool