Skip to content
ThingFace

Migrating the partition table (from before 15/10/2026)

The SDK's partition table changed on 15/10/2026: the current one is ports/esp-idf/devui/partitions.csv, the same in ESP-IDF, Rust, PlatformIO, arduino-cli and the Arduino IDE. It is the Arduino core's "Minimal SPIFFS" with the devui partition (the board's key, the device_id and the pairing) in place of the SPIFFS:

PartitionStartSize
nvs0x900020 KB
otadata0xe0008 KB
ota_00x100001,966,080 B
ota_10x1f00001,966,080 B
devui0x3d000016 KB
coredump0x3f000064 KB (the Arduino core's; the ESP-IDF builds do not use it without a core dump enabled)

It needs a flash of 4 MB or more. The table before had nvs at 0x9000 (24 KB), otadata at 0xf000, phy_init at 0x11000, devui at 0x12000, ota_0 at 0x20000 and ota_1 at 0x200000 (0x1e0000 each).

A board in the field: by OTA, with no erase

A board in the field keeps its table and its identity after an OTA, with nothing erased. The partition table is read from the flash at run time, never from the build: the port opens the key's partition by name (nvs_flash_init_partition("devui")), the Arduino shell looks it up by name too, the app's OTA (esp_ota_*, esp_https_ota) takes the next slot of the table on the flash, and the SDK has no fixed table offset at all (it does no OTA of its own). A firmware built with the new SDK and table therefore runs from the old ota_1 (0x200000) with the old devui (0x12000) and the same device_id. The slots of both tables have the same size, 0x1e0000: an app that fits the new one fits the old one.

Proven on 16/10/2026 on an ESP32-S3: the old table with an app of the old SDK, then the LED example of the new SDK written to the old ota_1 and the otadata switched to it (otatool.py write_ota_partition --slot 1 and switch_ota_partition --slot 1, what an OTA writes). The board booted from 0x200000 with the same device_id, reached the gateway, and the 16 KB at 0x12000 kept the same hash.

What that board does not get: the new table itself (no coredump partition, and the nvs stays at 24 KB). And nothing can write it over USB without erasing: the Arduino core's upload and the new table put the app at 0x10000, over the old devui.

A board flashed over USB: a new identity

Flashed over USB with the new table, the board gets a new identity, because the new table puts the app over the old devui. Erase the whole flash and write with the new table:

  • ESP-IDF: idf.py -p PORT erase-flash flash;
  • Rust: python -m esptool erase-flash before the write-flash of examples/rust/README.md;
  • Arduino: "Erase All Flash Before Sketch Upload" once.

Then give the Wi-Fi and pair again (step 7 of the quickstart shows how), and unlink the old device in the portal (Dispositivos): its device_id does not connect again. Without erasing, the new devui and nvs would start over what the old table left in their place (the end of the old ota_1, the old nvs cut to 20 KB).

What still erases the devui

In any of the tools: erasing the whole flash (the Arduino IDE's "Erase All Flash", EraseFlash=all), an extra image from the board's options (upload.extra_flags, written wherever it says) and, with the core's default table, formatting its SPIFFS or LittleFS, which covers 0x3d0000. tools/arduino_build.py refuses the first two. Flashing with the core's default table does not erase the devui, but the SDK does not see it: DevUI.begin creates a new identity in the common nvs and warns on the serial; flashing again with the SDK's table, without erasing, brings the old one back. The details of each tool are in the SDK's README.md, Arduino section.