Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:ESP-IDF partition table

From ReverseEngineering.wiki
Format
On this wiki Facts · Code · Notes · Topics

The 32-byte-entry partition table that ESP-IDF builds from a CSV and flashes (by default at 0x8000) on ESP32-family chips, with its MD5 entry, type and subtype enums, and the otadata partition that picks the running OTA app.

Overview

On ESP32-family flash the bootloader reads a binary partition table to find apps (factory, ota_0..ota_15), the OTA selection data, NVS, filesystems and so on. gen_esp32part.py converts between the CSV (Name, Type, SubType, Offset, Size, Flags) and the binary. The default table offset in the script is 0x8000; the table occupies one 4 KiB sector but only the first 0xC00 bytes carry entries (96 entries including the MD5 entry), the rest stays 0xFF to leave room for a signature. See Format:ESP32 application image for the images the entries point to.

Entry layout (32 bytes, little endian)

magic 0x50AA (bytes AA 50), type, subtype, 32-bit offset, 32-bit size, 16-byte NUL-padded label, 32-bit flags (bit 0 encrypted, bit 1 readonly). The table ends at the first entry that is 32 bytes of 0xFF.

MD5 entry

When enabled (the default of the tool) a 32-byte entry follows the real entries: bytes EB EB then 14 bytes of 0xFF, then the 16-byte MD5 of all preceding entries. Readers recognise it by the two magic bytes and skip it; it is not a partition.

Types and subtypes

type 0x00 app (subtype 0x00 factory, 0x10-0x1F ota_0..ota_15, 0x20 test, 0x30-0x31 tee_0/tee_1), type 0x01 data (0x00 ota, 0x01 phy, 0x02 nvs, 0x03 coredump, 0x04 nvs_keys, 0x05 efuse, 0x06 undefined, 0x80 esphttpd, 0x81 fat, 0x82 spiffs, 0x83 littlefs, 0x90 tee_ota), type 0x02 bootloader (0 primary, 1 ota, 2 recovery), type 0x03 partition_table (0 primary, 1 ota). App partitions must be 0x10000 aligned (without secure boot v2 the size alignment is 0x1000).

OTA data (otadata)

The data/ota partition holds two 4 KiB sectors, each with a 32-byte esp_ota_select_entry_t at its start: 32-bit ota_seq, 20-byte seq_label, 32-bit ota_state, 32-bit crc (CRC32 of the ota_seq field only). Erased flash is 0xFFFFFFFF. The bootloader picks the valid entry (crc matches, seq not 0xFFFFFFFF) with the higher sequence and boots OTA slot (ota_seq - 1) mod number-of-OTA-app-partitions; with no valid entry it boots the factory app (Unverified: factory fallback was not read in the source). ota_state values: 0 NEW, 1 PENDING_VERIFY, 2 VALID, 3 INVALID, 4 ABORTED, 0xFFFFFFFF UNDEFINED.

Finding the table in a dump

Search a full flash image for AA 50 00 00 or AA 50 01 at 0x8000 (the usual offset; a custom offset is a build option, Unverified).

Code & repositories

  • 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