Writing · Checklist

ESP32 OTA update checklist: what to settle before devices ship

Before an ESP32 product ships with over-the-air updates, settle twelve things: a frozen partition table, a size limit, a delivery path, integrity and signature checks, rollback, a first-boot self-test, an anti-rollback policy, a battery gate, settings migration, staged cohorts and telemetry. The partition table and bootloader options such as rollback are effectively fixed once a unit ships, and a device in the field cannot gain an update path it never shipped with. The checklist is below, along with an honest account of which items our own firmware has today.

Published 2026-11-21. Written for hardware teams shipping ESP32-based devices, especially battery products that sleep most of the time. Rollback and signing details come from Espressif’s ESP-IDF documentation; firmware details come from our own ESP32-S3 + Spectra 6 code.

The ESP32 OTA checklist

Read it as a list of decisions. A row can be a deliberate “not yet”, as long as someone chose that and knows what it costs.

CheckPass looks likeWhy it matters
Partition tableFinal layout frozen, with room for app growth in both slotsApp OTA does not rewrite it; a wrong layout follows every unit
Image sizeBuild fails if the binary exceeds the slotAn oversized image should stop in CI, not on a device
Delivery pathA named route: cloud pull, LAN push or USBDecides whether a field fix needs a site visit
IntegrityHash checked before the new slot is marked bootableInterrupted downloads are routine on weak Wi-Fi
AuthenticityImage signature verified on the deviceWithout it, anyone who can reach the update path can run code
RollbackNew app must confirm itself on first bootA bad build returns to the last good one without a visit
Self-testConfirms what matters: storage, Wi-Fi, server, panelBooting is a low bar; a build can boot and still be useless
Anti-rollbackDecide whether to burn security versions to eFuseBlocks known-bad old builds, but only 16 steps are available
Power gateBattery above a threshold before download and installA brownout mid-update turns a routine release into a support call
Data migrationNew firmware reads old settings; old firmware survives new onesRollback is only safe if the previous build can still read storage
Staged rolloutCohorts with a stop ruleLimits the damage from a bug the bench missed
TelemetryVersion, reset reason and last boot stage reach the serverOtherwise a failed rollout looks like a quiet fleet

Start with the partition table

This is the one row you cannot fix later without a cable. ESP-IDF OTA needs at least two app slots and an OTA data partition that records which slot to boot. An update writes the inactive slot and switches to it, so the running firmware stays intact until the new one is ready.

We have hit the consequence directly. Our firmware carries a check for devices whose storage is too small to hold one image, described in the code as the symptom of an updated device whose on-flash partition table came from an older, smaller layout. The comment is blunt: the only fix is a full USB reflash, because neither of our over-the-air paths writes the partition table.

Our 16 MB layout gives each app slot 3 MB and leaves about 9.9 MB for stored images. Size the slots for the firmware you expect in two years, including TLS, a larger UI and any new radio stack. Our dev kit to product checklist puts this first for the same reason.

Rollback: make the new build prove itself

App rollback: A bootloader feature that returns a device to its previous firmware when a newly installed build fails to confirm that it works.

With CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE, Espressif says a new app gets a single attempt to boot and confirm itself. The sequence is short:

Note where that option lives. It is a bootloader setting, and a normal app update does not replace the bootloader, so decide on rollback before the first production flash.

What the self-test should check

The power-loss rule shapes the design. A self-test that takes minutes gives a battery device minutes in which a brownout will discard a good update, so Espressif recommends keeping it quick. For a connected e-paper product we would check that storage mounts, stored settings parse, Wi-Fi joins and the server answers. Decide what happens when the network is simply down: a build should not roll back because a router was off for the night, so a failed connection needs a retry policy rather than an instant verdict.

The panel deserves its own decision. A full Spectra 6 refresh takes around 30 seconds on our hardware and is a heavy, sustained load, so running one inside the self-test widens that vulnerable window. Checking that the panel responds without painting is usually the better trade.

Signing and anti-rollback

A hash catches corruption. A signature proves the image came from you. ESP-IDF can verify signed updates without hardware secure boot, which is a reasonable first step because it burns fewer irreversible decisions into the chip. Secure boot goes further by checking what the chip boots at all. Plan key storage and rotation before the first signed release; Memfault’s OTA checklist calls out both.

Anti-rollback stops a device from accepting an older, vulnerable build, using a security version stored in eFuse. Espressif limits that field to 16 steps, so reserve increments for genuine security fixes. If your market requires a security update process, our guide to CE marking with an ESP32 module covers the EU cybersecurity rules that make these choices harder to postpone.

Battery devices need their own rules

Most OTA advice assumes a device that is always on. A sleeping product changes three things.

Our firmware already has the pattern for that last point. On hardware with a battery sense pin, which includes our 13.3-inch build, a supply guard runs before each heavy step such as joining Wi-Fi or painting the panel. It reads the battery rail, gives a sagging rail up to 10 seconds to recover, and otherwise logs it and goes back to sleep rather than brown out in a loop. An update path should sit behind the same guard. Our brownout debugging checklist covers how we found those failures, and the battery life guide shows why wake count dominates runtime.

Roll out in stages, and watch it

Memfault suggests starting with about 5% of a fleet, with hard failure thresholds and a pause when errors climb. Write the stop rule before the release: for example, halt if any device in the first cohort fails to report the new version after two wakes. On a pilot of a few dozen units a percentage means little, so use named groups: bench, one friendly site, then everyone.

You can only stop a rollout you can see. Each device should report its firmware version, why it last reset and how far its last boot got. Ours sends its version on every sync, along with recent lines from a black-box boot log: reset reason, the last stage reached and, where the board can sense it, battery voltage at boot and during refresh. That history survives panics and brownouts and arrives at the next successful sync.

Where our own firmware stands

Checklists are easy to write and harder to pass, so here is ours against the code as of this post.

That is a sensible place for a small consumer run and the wrong place for a commercial fleet across many sites. For a team project, field updates belong in the scope from day one, which is why they appear in our questions to ask a hardware partner. Ask any vendor the same thing, and ask to see it work.

FAQ

How does OTA rollback work on an ESP32?

With CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE set in ESP-IDF, a newly installed app boots in the ESP_OTA_IMG_PENDING_VERIFY state. It must run a self-test and call esp_ota_mark_app_valid_cancel_rollback(). If it calls esp_ota_mark_app_invalid_rollback_and_reboot(), or the device resets before it confirms, the bootloader returns to the previous app.

Can an ESP32 OTA update change the partition table?

Treat the answer as no. A normal app OTA writes only the inactive app slot. Our own firmware documents the failure: a device updated over the air keeps the partition table it was flashed with, and the only fix for an undersized layout is a full USB reflash. Freeze the partition table before the first unit ships.

How many partitions does ESP32 OTA need?

Espressif's documentation calls for at least two OTA app slots (ota_0 and ota_1) and an OTA data partition that records which one to boot. Our 16 MB layout uses two 3 MB app slots, an otadata partition, and about 9.9 MB of LittleFS for stored images.

Do ESP32 OTA updates need secure boot to be signed?

No. ESP-IDF can verify signed updates without hardware secure boot, using CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT and CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT. That checks updates but does not stop someone with physical access from flashing other code, which is what secure boot adds.

What percentage of a fleet should get an OTA update first?

Memfault's checklist suggests starting with about 5% of the fleet, setting hard failure thresholds and pausing if errors climb. On a small fleet, use a named group instead: your own bench units, then one friendly site, then everyone.

Should a battery device check for firmware updates on a separate wake?

Usually not. The Wi-Fi join is the expensive part of a wake, so check the version during a wake that already fetches content. Only download and install when the battery is above your threshold, and retry on a later wake if it is not.