Format:ESP32 application image
| On this wiki | Facts · Code · Notes · Topics |
|---|
Espressif's flash image of the second-stage bootloader and apps (ESP8266, ESP32 family): magic 0xE9, segment count, a 16-byte extended header with the chip id, load-address+size segments, an XOR checksum byte and an optional SHA-256; the app descriptor with magic 0xABCD5432 sits at the start of the first flash-mapped (DROM) segment.
Overview
Everything esptool writes with elf2image or reads with image_info is this format. ESP-IDF's bootloader.bin, partition apps (ota_0), and the chips' ROM loader all use it. A full flash dump is different: it holds a partition table, bootloader, apps and data at offsets; carve the images out by partition.
Header
8-byte common header: magic 0xE9, segment count, flash mode, flash size/frequency byte, 32-bit entry point. Then (ESP32 and later, and ESP8266 v3 images) a 16-byte extended header: wp_pin, three SPI drive bytes, a 16-bit chip id at extended offset 4 (see the enum fact), a 1-byte min chip revision, min_rev_full and max_rev_full (16-bit each), four padding bytes and an append_digest byte (0 or 1). Then each segment: 32-bit load address, 32-bit length, data. After the last segment the file is padded to a 16-byte boundary and the last byte is an XOR checksum seeded with 0xEF; if append_digest is 1, a 32-byte SHA-256 of the whole image follows.
An older ESP8266 format uses magic 0xEA (a flash-mapped 'irom' file); esptool also recognises Intel HEX input starting with ':'.
Segment addresses
Segments whose load address is in the flash-mapped IROM or DROM windows are executed or read through the cache; others are copied to RAM. Examples: ESP32 DROM 0x3F400000, IROM 0x400D0000; ESP32-S3 DROM 0x3C000000, IROM 0x42000000. The bootloader offset in flash is 0x1000 on ESP32, 0x0 on ESP32-S3, C3 and C6, and 0x2000 on ESP32-P4 and C5 (esptool targets).
App descriptor
The first segment mapped through DROM begins with esp_app_desc_t: magic word 0xABCD5432, secure_version, 8 reserved bytes, version[32], project_name[32], time[16], date[16], idf_ver[32], app_elf_sha256[32], efuse block revision min/max, mmu page size and reserved. Searching a dump for bytes 32 54 CD AB finds it and gives project name, build date and ESP-IDF version.
Code & repositories
- https://github.com/espressif/esptool @
af1ed10290e6328416cf8c73076bba15b459cbb2· license: GPL-2.0
esptool: image parsing and writing (bin_image.py), chip ids, app descriptor parser, UF2 writer.
Tested on: source read, not run: read · checked 2026-10-18; last activity 2026-10-15; Note: the latest release ships binaries; the wiki links only the source, never the binaries - https://github.com/espressif/esp-idf @
1c42e514c90ae621af33bde3b6ad3dac22edcbfd· license: Apache-2.0
ESP-IDF: gen_esp32part.py (components/partition_table), esp_flash_partitions.h and bootloader_utility.c (components/bootloader_support).
Tested on: source read, not run: source read only · checked 2026-10-19; last activity 2026-10-16; Note: the latest release ships binaries; the wiki links only the source, never the binaries