ESP32 OTA Rollback: A Production Readiness Guide

ESP32 OTA rollback is the recovery path that keeps a failed firmware release from becoming a field visit. Downloading a binary over Wi-Fi is only one part of the job. The device also needs to decide whether the new application works, keep a usable previous application, and recover when power disappears halfway through the process. Espressif provides application rollback for this purpose, but it must be enabled and the new application must confirm that it works. Source

This guide is for teams building connected devices, including ESP32 devices that send sensor data to an AI service. It focuses on ESP-IDF application updates, not a universal recipe for every Arduino framework or ESP32 family. The technical behavior comes from Espressif's documentation. The release checklist and suggested health gates are our engineering synthesis, not a claim that Codesprint has tested a particular fleet.

Start with the partition layout

For application OTA, Espressif requires at least two OTA application slots, usually ota_0 and ota_1, plus an OTA data partition. The new image is written to the slot that is not currently selected for boot. Only after verification does the update process change the OTA data to select the new image for the next boot. This separation is the basis of the application update's power-loss resilience. Source

The OTA data partition is not another firmware image. It records which application the bootloader should select. It occupies two flash sectors, or 0x2000 bytes. Espressif explains that the sectors are written independently and a counter resolves disagreements if a power failure interrupts the operation. Do not replace this mechanism with an application flag that merely says "latest version downloaded." Source

A factory partition is optional in the broader OTA design. With erased OTA data, the bootloader selects the factory application if present, otherwise the first available OTA slot. Espressif's partition guide includes both a single-factory layout without OTA and a factory-plus-two-OTA layout. Check the actual partition table in the build, not what a board description or old prototype says it contains. Source

Our recommendation is to treat slot capacity as a release constraint. Record the built image size and available slot size for every hardware variant. Leave room for expected growth, configuration storage and other data. A firmware release that works on the development board is not evidence that it fits every shipped flash layout.

Enable rollback before you need it

Application rollback is controlled by CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE. It is not enabled by default. Without it, the NEW and PENDING_VERIFY states are not used, and calling the confirmation functions is optional. Two firmware slots alone therefore do not prove that a device will automatically reject a bad first boot. Source

With rollback enabled, the update selects the new application and marks it ESP_OTA_IMG_NEW. On the first boot, the bootloader changes that state to ESP_OTA_IMG_PENDING_VERIFY. The application now has a trial boot in which to run diagnostics and confirm itself. If it reboots without confirmation, the bootloader changes the pending image to ABORTED and selects a previous usable application. Source

The important states are easy to confuse, so keep them separate in device reports:

• NEW: selected for a first boot with rollback enabled.

• PENDING_VERIFY: running on trial and awaiting confirmation.

• VALID: confirmed by the application.

• INVALID: explicitly rejected by the application.

• ABORTED: a trial application restarted without confirmation.

These states live in OTA data, not inside the application binary itself. The bootloader's handling depends on the rollback configuration, so check both the state and the build settings when debugging. Source

Make confirmation a health decision

Espressif's documented flow reads the running partition's state using esp_ota_get_state_partition(). When it is pending verification, the application runs diagnostics. On success it calls esp_ota_mark_app_valid_cancel_rollback(). On failure it calls esp_ota_mark_app_invalid_rollback_and_reboot(). A boot message or successful download is not the confirmation step. Source

Our suggested health gate asks whether the device can perform its minimum useful job. For a sensor device, that might mean reading configuration, initializing the required sensor, producing a plausible sample and starting the local communication task. For an actuator, safe output behavior matters more than a successful log line. Define the checks per product instead of copying a generic five-second delay.

Keep local health distinct from temporary cloud availability. Our view is that an otherwise working device should not necessarily reject firmware because the update server or AI endpoint is briefly offline. If connectivity is essential to the product, give that check a bounded time and an explicit failure policy. Do not leave the firmware pending forever while waiting for an external service.

Espressif recommends performing the self-test as quickly as possible to reduce rollback caused by power loss. That creates a real design tradeoff: enough checks to catch a broken application, but no long unbounded startup sequence before confirmation. Test a power cut during the trial boot as well as during the download. Source

HTTPS and image trust are different checks

The esp_https_ota component provides simplified firmware-upgrade APIs over HTTPS. Server verification uses a root certificate through cert_pem, or the ESP certificate bundle through crt_bundle_attach. Espressif recommends the endpoint's root certificate rather than an intermediate certificate because roots generally remain valid longer. Shipping an update path requires planning for transport trust, not disabling certificate verification when a test fails. Source

Image-signature verification is a separate control. Espressif documents verification of signed OTA applications even without enabling hardware secure boot, using the relevant signed-app configuration options. These controls should not be described as equivalent to a hardware secure-boot chain. Choose the design for the actual threat model and hardware, and test its rejected-image path. Source

Our release recommendation is to record hardware compatibility, image identity, release approval and the intended target group before transfer starts. A valid connection does not tell your backend which product variant should receive a binary. Keep secrets out of update URLs and logs, and separate an operator's permission to schedule a rollout from the authority to sign firmware.

Rollback and anti-rollback solve opposite problems

Application rollback restores an earlier working application when the new one fails. Anti-rollback prevents booting an application whose security version is below the value stored in the chip's eFuse. With both features enabled, recovery is possible only to an image whose security version is equal to or above that stored value. A previous binary can still be present in flash and no longer be an eligible recovery target. Source

Espressif's anti-rollback flow updates the chip's security version when the new application is marked valid. Its documentation warns that a rollback attempt can fail if no bootable application remains. For the classic ESP32, the security-version field also has a finite eFuse budget, and the documented scheme does not support factory or test partitions. These are target-specific design constraints, not details to defer until deployment day. Source

Our recommendation is to treat a security-version increase as its own release decision, not an automatic increment for every build. Before advancing it, establish which recovery image remains eligible and how an operator will recover a device that cannot boot it. Rehearse that decision on the same chip and configuration used in the product.

An application rollback does not restore all data

The application-slot safety model must not be applied to every partition. Espressif labels bootloader, partition-table and other data-partition updates as unsafe in its OTA overview because a power interruption during the final copy can leave the device unable to load the current application. Ordinary application OTA and those update paths have different failure guarantees. Source

Our practical warning is about configuration migrations. If new firmware changes persistent data and then rolls back, the older application still has to understand what remains. Prefer backward-compatible migrations where possible. Test the old image against data written by the new image. A working bootloader fallback cannot repair an incompatible settings schema by itself.

Handle interrupted downloads deliberately

Espressif's HTTPS OTA documentation describes resumption using HTTP range requests. Enabling ota_resumption is part of the setup, and ota_image_bytes_written identifies the point from which to continue. The advanced HTTPS OTA example persists intermediate state in NVS. This is distinct from merely retrying the entire download after a connection failure. Check that the deployed ESP-IDF version supports the feature you plan to use. Source

For rollout operations, our suggested starting point is a small representative cohort, followed by wider groups only after results are reviewed. Report download failure, trial boot, confirmation and rollback separately. Pause the rollout on unexpected resets or rising recovery rates. A backend counter marked "download complete" should never stand in for a confirmed working release.

A pre-release failure-test checklist

This is our synthesis, not an Espressif certification checklist. On representative hardware, test a transfer interruption, a power cut during trial boot, an explicit failed diagnostic, an oversized image, an incompatible hardware target, a rejected signature, unavailable cloud services and an older recovery application reading newly written data. Where anti-rollback is enabled, test the eligibility of the fallback image before advancing security version.

Keep the results with the release record: build configuration, partition table, firmware identities, health-gate outcome and recovery result. For the security foundations around stored firmware and boot verification, read our ESP32 flash encryption and secure boot guide. To discuss a device-to-cloud implementation, use our contact page. We do not claim that this checklist alone makes a fleet production-ready.