OTA Updates, Provisioning, and Security Basics
A device you cannot update is a device whose bugs you have promised to keep.
🎯 By the end you'll understand
How ESP-IDF's over-the-air update works — two application partitions, a small ledger partition that survives a power cut mid-write, and a boot that is provisional until the new firmware proves itself. What rollback protects you from and, precisely, what it does not. Why an unsigned update mechanism is a remote code execution feature with a friendly name, and what image signing costs when you are not ready for secure boot. What secure boot and flash encryption actually cost — irreversible fuses, no more UART reflashing, and a debugging story that gets much worse — and how to decide whether a 25-unit pilot needs them. And how to run a rollout that fails safely rather than one that fails at scale.
KEY INSIGHTThe update is easy; the recovery is the product
The image passed on all four bench units. It shipped to the fleet on a Friday. Three units came back on the new firmware. The rest went quiet, permanently, because a supplier had substituted a compatible flash part on a later production run and the new build's timing did not suit it. There was no way back. Every one of them had to be opened.
Writing new firmware into flash over a radio is a solved, unremarkable engineering problem. What is not solved by default, and what separates a fleet you can maintain from a fleet you can destroy, is everything around it: where the new image goes while the old one is still running, how the device decides which one to boot, what happens when the power fails halfway, how the device knows the new firmware actually works, and who is allowed to send an image in the first place. Those five questions have well-understood answers, they are all cheap, and skipping any one of them is a decision you only get to make once per fleet.
Two defences, two entirely different threats, and neither substitutes for the other. Rollback protects you from yourself — a build that crashes, a build that fails on the one unit with a different flash chip, a regression nobody caught. Signing protects you from everyone else — an attacker who can reach your update endpoint, or sit between it and the device. Rollback does nothing against a hostile image, because a hostile image passes its own self-test happily. Signing does nothing against your own broken build, because you signed it. A fleet needs both, and the widget below will let you watch what happens when it has one.
HOW IT WORKSTwo partitions and a ledger that survives a power cut
The ESP-IDF scheme is deliberately boring, which is the correct property for this part of a system. Flash is divided by a partition table into, among other things, two application partitions — ota_0 and ota_1 — and a small data partition called otadata. Exactly one application partition is running at any time; the other is scratch space.
# Name, Type, SubType, Offset, Size, Notes nvs, data, nvs, 0x9000, 0x6000 # Wi-Fi credentials, calibration, seq base otadata, data, ota, 0xf000, 0x2000 # TWO 4 KB sectors — this is the whole trick phy_init, data, phy, 0x11000, 0x1000 ota_0, app, ota_0, 0x20000, 0x1B0000 # 1.69 MB — the app can only be half the flash ota_1, app, ota_1, 0x1D0000, 0x1B0000 storage, data, spiffs, 0x380000, 0x80000 # 512 KB for logs and the CA certificate
Read the size column before anything else, because it is the constraint people meet late. Two application partitions means your application can never exceed half the flash, minus the data partitions. On a 4 MB module that is about 1.7 MB, which is generous for Beacon and not generous at all for a product that wants TLS, a filesystem, and a graphics library. If you discover at integration time that the image is 2.1 MB, you are choosing between a bigger module, a smaller feature set, and giving up OTA — and the last of those is not a real option.
The update sequence itself:
Write into the partition that is not running
esp_ota_get_next_update_partition() hands you the inactive one; esp_ota_begin() erases it, esp_ota_write() streams the image in. The running application is never touched. Lose power at any point here and the device reboots into exactly the firmware it had before, because nothing has told the bootloader otherwise.
Validate before committing
esp_ota_end() checks the image header and its checksum, and — if signature verification is configured — the signature. A corrupted download fails here and the update is simply abandoned. This is why "the image got corrupted in transit" is the fault everyone worries about and the one that has been handled since before you started.
Flip the pointer, atomically
esp_ota_set_boot_partition() writes a new select record into otadata. That partition is two sectors, each holding a record with a sequence number and a CRC, and a write goes to the older of the two. If power fails mid-write, the other sector still holds a valid, older record, and the bootloader uses it. There is no window in which the device has no valid answer to "which partition do I boot?"
Boot provisionally, and make the new firmware earn it
With rollback enabled, the new application boots in the state ESP_OTA_IMG_PENDING_VERIFY. It must call esp_ota_mark_app_valid_cancel_rollback() to make the change permanent. If it instead calls esp_ota_mark_app_invalid_rollback_and_reboot(), or simply crashes and reboots without marking itself valid, the bootloader reverts to the previous partition. This is the single most valuable line of code in the entire update path, and its value depends entirely on where you call it.
One related feature worth knowing before you need it: anti-rollback. Enabled with CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK, it stores a monotonically increasing security version in eFuse and refuses to boot an image with a lower one, which stops an attacker from downgrading a device to a version with a known vulnerability. It is genuinely valuable and it is irreversible: once you burn a security version, no older image will ever run on that unit again, including the one you need for debugging. It belongs on a shipping product with a security history, not on a pilot whose firmware changes weekly.
CORE CONCEPTSigning: deciding who is allowed to run code on your hardware
Strip the update mechanism down to what it is: a feature that downloads a binary from the network and executes it with full privileges. If nothing authenticates that binary, you have shipped remote code execution and called it maintainability. The question is not whether to authenticate; it is where the trust lives.
| Approach | What it proves | What it does not | Cost |
|---|---|---|---|
| TLS to a known server | You are talking to the server whose certificate you pinned, and nobody is modifying the stream. | Nothing about the image itself. If the server is compromised, or a build machine pushes a bad artefact, the device happily runs it. | Flash for the certificate, RAM for the session, an OTA when the certificate rotates. |
| Signed image, verified at update and boot | The image was produced by whoever holds the signing key. | That the key holder is trustworthy, or that the build is correct. A signed broken build is still broken. | A key you must protect for the life of the product; a build step; a Kconfig option. |
| Both | Transport integrity and image provenance, independently. | Compromise of the signing key itself, which is why that key belongs in a hardware token or a locked-down CI secret, not in the repository. | The union of the above, which is small. |
ESP-IDF gives you a middle path that is often overlooked and is exactly right for a pilot: signed application verification without hardware secure boot. The Kconfig option is in the CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT family — check the exact symbol for your IDF version, as this area is revised. The build signs images with your private key; the bootloader and the OTA path verify against the embedded public key. No eFuses are burned, nothing is irreversible, and you can still flash a development build over UART. What you get is a device that refuses an image it did not receive from your build system. What you do not get is protection against someone who can rewrite the bootloader itself over the wire — which requires physical access, and which is a different threat.
COMPARISONSecure boot and flash encryption: what they really cost
These are the two heavyweight features, and they are heavyweight in a specific way: they are enforced by eFuses, which are one-time-programmable bits. Burning them is permanent for that chip. There is no undo, no development mode you can switch back to, and no recovery from a mistake other than replacing the part.
| Secure Boot v2 | Flash encryption | |
|---|---|---|
| What it stops | Running any bootloader or application not signed by your key — including one flashed over UART with physical access. | Reading your firmware, keys, and NVS contents off the flash chip, whether in circuit or desoldered. |
| Mechanism | A digest of your public key burned into eFuse; the ROM verifies the bootloader, which verifies the app. | AES-XTS with a key in eFuse that software cannot read; the flash controller decrypts transparently on read. |
| The irreversible part | The key digest and the enable bit. Lose the private key and every unit ever built is permanently unupdatable. | Release mode disables UART re-flashing of plaintext for good. Development mode allows a limited number of reflashes and is not a security posture. |
| What it costs you daily | Every debug build must be signed. Bricking a unit with a bad bootloader is now unrecoverable. | JTAG debugging and plain idf.py flash stop working. Reading a crash dump becomes much harder. |
| Needed when | The device controls something dangerous, or firmware theft is a business risk. | The flash holds a secret worth extracting: a per-device key, a customer credential, licensed IP. |
The natural middle ground is "I do not need the whole flash encrypted, I just want the Wi-Fi credentials in NVS protected". ESP-IDF supports encrypted NVS — and the key it uses lives in a separate nvs_keys partition. Which is in the same flash chip. Which is readable. So NVS encryption is only meaningful when flash encryption is protecting the key partition (or, on parts with the relevant peripheral, when the scheme is anchored to an HMAC key in eFuse). Enabling NVS encryption on its own moves the key next to the lock and produces a document you can show an auditor rather than a secret an attacker cannot read. If credentials genuinely need protecting, the answer is the full mechanism and its costs; if they do not, be honest that they are stored in the clear and say why that is acceptable.
The honest position for a 25-unit pilot: signed OTA, yes; secure boot and flash encryption, not yet. Signing costs a build step and protects against the realistic threat, which is a compromised or spoofed update path. Secure boot protects against an attacker with the device in their hands, and the pilot's assets — a temperature reading and a shared Wi-Fi password on a workshop network — do not justify making 25 units permanently undebuggable while the design is still changing weekly. Write that reasoning down. A security decision that is recorded with its rationale can be revisited when the product's context changes; one that was never made cannot.
SEE ITOTA failure drill: 25 units, one update, one thing goes wrong
Beacon's pilot is exactly 25 units. Push an update to them with whatever defences you choose, inject one fault, and see how many survive. The fleet strip below is coloured per unit. The point of the drill is not to reach twenty-five green squares — it is to notice which defence caught which fault, and to find the combination where the fault gets through.
Four drills. One: inject "crashes before app start" with no defences. Twenty-five bricks, every one needing a cable and a screwdriver. Now enable rollback alone: twenty-five rollbacks, zero bricks, and the fleet is exactly where it started. That one checkbox is the difference between a bad Friday and a recall. Two: inject the hostile update server with rollback enabled and nothing else. Rollback does not help at all — the attacker's image runs, reports itself healthy, and marks itself valid. Add signing: every unit refuses. Three: take the self-test fault with three quirky units and turn on staged rollout. Watch which cohort exposes them; sometimes the canary catches it, sometimes it does not, because a canary is a sample and a sample can miss. Four: corrupt image and power loss, with no defences at all. Both are harmless. The faults people design against are the ones the architecture already handles; the faults that hurt are the ones where your own build is wrong or somebody else's build is running.
IN PRACTICEThe self-test gate, and where to call it
Rollback is only as good as the test that decides whether to cancel it, and the most common way to lose all of its value is to call esp_ota_mark_app_valid_cancel_rollback() at the top of app_main() because that is where the example put it. At that point the new firmware has proved that it can reach the first line of your code — which is exactly the thing that was never in doubt. Put the call after a test that could actually fail.
static esp_err_t beacon_self_test(void) { uint8_t who = 0; if (i2c_read_reg(LIS2DH12_ADDR, LIS2DH12_WHO_AM_I, &who) != ESP_OK) return ESP_FAIL; if (who != 0x33) return ESP_FAIL; // accelerometer alive if (sht40_measure(&t_c100, &rh) != ESP_OK) return ESP_FAIL; // 0x44 responds and converts if (t_c100 < -4000 || t_c100 > 8500) return ESP_FAIL; // …with a plausible value // Reads the sample taken at THIS wake from a divider enabled before the last sleep. // The divider is 500 kΩ Thevenin into 100 nF: τ = 50 ms, so a fresh reading needs // >=250 ms (5τ) to settle. Never busy-wait for that inside a 45 ms wake window. if (batt_read_mv() < 2800) return ESP_FAIL; // ADC path + divider switch work if (nvs_flash_init() != ESP_OK) return ESP_FAIL; if (ble_controller_start() != ESP_OK) return ESP_FAIL; // the radio actually comes up return ESP_OK; } void app_main(void) { const esp_partition_t *run = esp_ota_get_running_partition(); esp_ota_img_states_t st; if (esp_ota_get_state_partition(run, &st) == ESP_OK && st == ESP_OTA_IMG_PENDING_VERIFY) { /* This boot is on trial. Do the work FIRST, then decide. */ if (beacon_self_test() == ESP_OK) { esp_ota_mark_app_valid_cancel_rollback(); // commit — only now } else { ESP_LOGE(TAG, "self-test failed on new image; reverting"); esp_ota_mark_app_invalid_rollback_and_reboot(); // never returns } } beacon_run_state_machine(); // SLEEP ⇄ WAKE → SAMPLE → ADVERTISE (3.7) }
Three properties that test needs, and they pull against each other. It must be fast, because it runs inside a 45 ms wake window that the entire Lesson 4.3 budget depends on — a self-test that takes two seconds turns a three-year battery life into a three-month one. The battery reading is the concrete instance of that trap: the sense divider presents 500 kΩ into a 100 nF capacitor, so its time constant is 50 ms and a settled sample needs at least 250 ms. That is five and a half times the whole wake window, so the divider is enabled before entering sleep and the ADC is read at the next wake, by which point the node has had a minute to settle. A self-test that instead switches the divider on and waits for it has quietly made every report six times more expensive. It must be discriminating, exercising the things a bad build actually breaks: the I²C bus, both sensors returning plausible values, the ADC path, NVS, and the radio starting. And it must be robust to its own failure: a self-test that hangs rather than returning an error never reaches either branch, and a hung device with rollback enabled is saved only by the watchdog rebooting it, which then does roll back — so make sure the task watchdog is enabled, because it is the backstop for the backstop.
On provisioning: something must give each unit its Wi-Fi credentials. ESP-IDF's provisioning manager runs over SoftAP or BLE with an encrypted session so the password is not broadcast in clear, and it is the right answer for a product a customer sets up. For 25 pilot units that never leave one building, flashing credentials at assembly time is simpler and equally honest. What to avoid is the third option — one SSID and password compiled into the image — because it gives the whole fleet one shared secret, puts it in the git history, and makes rotating it an OTA to every unit. Beacon stores credentials in NVS, which is the decision that made the NVS encryption caveat above worth stating.
BEACONBeacon: opt-in OTA, and the GPIO9 trap that bites it
Per the canon, Beacon updates over Wi-Fi only when the button is held at wake. That is a deliberate design, and it is worth spelling out what each part of it buys.
| Decision | Why |
|---|---|
| Wi-Fi is used for OTA and nothing else | Lesson 4.7's arithmetic: an association costs ~264 mC, which is fatal once a minute and negligible as a rare event. One complete OTA is about 0.62 C, roughly 0.017 % of the cell. |
| Entered by holding the button, not triggered remotely | A remotely triggerable Wi-Fi association is a battery-drain attack on 25 units at once. A physical button is the cheapest possible authentication and is proportionate to this threat. |
| Two OTA partitions plus rollback | The pilot's firmware changes weekly. The cost of a bad build must be a rollback, not a site visit to 25 assets in a working warehouse. |
| The self-test gates the commit | The Stage 3 boot self-test already existed. Wiring it to the rollback decision is a dozen lines and converts it from a log message into a safety mechanism. |
| Signed images, no secure boot | Protects the realistic threat — a spoofed or compromised update path — without burning irreversible eFuses on hardware that is still changing. |
| The firmware version byte in the BLE payload | Lesson 4.6 spent one of fourteen bytes on it. During a staged rollout it is how you see which units took the update, which rolled back, and which never got it — from the gateway, without touching anything. |
The canon records a known Rev A defect: the user button is on GPIO9, which is a boot-strapping pin, and holding it at power-up puts the ESP32-C3 into serial download mode instead of running the application. Lesson 3.3 taught the trap; here is where it costs something concrete.
"Hold the button at wake" works perfectly from a timer or motion wake, because the chip is coming out of deep sleep rather than powering up, and the strapping pins are only sampled at power-on reset. It does not work from a cold start — connect the battery with the button held and you get the ROM downloader, not the OTA mode. So the documented procedure for the pilot has to be "let the unit run, then hold the button and wait for the next wake", which is a worse user experience than it should be and is exactly the kind of thing that gets discovered by the person doing the twentieth unit rather than the first.
Two mitigations, both honest. Near term, document it and put it in the bring-up checklist. Rev B moves the button to a non-strapping pin, which is the actual fix and is already on the change list. What you should not do is add a firmware workaround that reads the strapping state after boot: by then the ROM has already decided, and there is nothing left to work around.
The Stage 4 milestone is now complete: the power budget is measured and matches the canon, the buck is chosen and justified, the BLE payload is live and decoded at a gateway, and OTA with rollback works. What remains is to turn all of it into copper.
WEAKNESSWhere this bites
app_main()This is the single most common way to have rollback enabled and get nothing from it. The vendor example calls esp_ota_mark_app_valid_cancel_rollback() early because the example is demonstrating the API, not gating on anything. Copied into a product, it means the new image commits itself the instant it reaches your first line of code — so the only build it can ever roll back from is one that fails inside the bootloader. Every interesting failure, from a broken sensor driver to a peripheral that behaves differently on one hardware revision, sails straight through. Put the call after a self-test that touches the things a bad build breaks, and confirm the mechanism works by deliberately shipping a build that fails the test.
An update path with no image authentication is a documented, supported way for anyone on the network path to run code of their choosing on every unit you have shipped. It is not a hardening task for a later sprint; it is the difference between a maintainable product and a botnet with a temperature sensor. And note the ordering trap: TLS alone still trusts your server forever, and signing alone still lets an attacker serve an old signed image unless you also handle versioning. Do both, put the signing key somewhere a laptop compromise does not reach, and be aware that "we will add it before we ship" has a poor historical record against "the pilot went well, let us do a hundred more".
Two different mistakes with the same shape: an irreversible decision made on incomplete information. Enabling secure boot or flash encryption on 25 units whose design changes weekly buys a threat model you have not written down and costs you JTAG, UART reflashing, and any hope of a quick crash dump — and it cannot be undone. Similarly, a staged rollout is a sampling procedure, and its value depends entirely on whether the sample can contain the problem: a canary chosen because it is the unit on your desk shares your desk's flash chip, your desk's temperature, and your desk's Wi-Fi. Choose canaries across production batches and deployment sites, and treat "the first cohort was clean" as weak evidence rather than a green light.
KEY INSIGHTHow this connects
- Toolchain and Build: From Source to Flash (3.2) — where the partition table and the image layout came from, and the reason an application can only ever be half the flash once you add a second app partition.
- Wi-Fi, MQTT, and When Not to Use Wi-Fi (4.7) — the association cost that makes OTA affordable as a rare event and fatal as a routine one, and the credentials in NVS that this lesson had to talk about protecting.
- BLE: Advertising, Connections, and Data Design (4.6) — the firmware-version byte that makes a staged rollout observable from the gateway without touching a single unit.
- Capstone: Beacon Pilot Deployment and Post-Mortem (6.9) — where the GPIO9 button, the leaky divider, and the rotated LED footprint are finally paid for.
That closes Stage 4. Beacon now has a power system that lasts, a radio that reaches, and a way to fix itself in the field. Stage 5 turns all of it into a four-layer board.
GLOSSARYKey terms introduced
- OTA partitions
- The two application partitions,
ota_0andota_1. One runs while the other is written, which is why a power loss during download is harmless — and why an application can never exceed half the flash. - otadata
- A two-sector data partition holding sequence-numbered, CRC-protected records that say which application partition to boot. Writing to the older sector means there is never a moment with no valid answer.
- Pending verify
- The state a newly booted OTA image is in when rollback is enabled. It becomes permanent only when the application calls
esp_ota_mark_app_valid_cancel_rollback(); a reboot without that call reverts to the previous partition. - Self-test gate
- The check that decides whether to commit or revert. Must be fast enough for the wake budget, discriminating enough to catch a broken build, and unable to hang.
- Anti-rollback
- A monotonic security version in eFuse that prevents booting older images, closing the downgrade attack. Irreversible, and therefore not a pilot feature.
- Secure Boot v2
- Signature verification anchored in a public-key digest burned into eFuse, so only images signed with your key will run at all. Permanent per chip; losing the key permanently ends updates for every unit built with it.
- Flash encryption
- Transparent AES-XTS encryption of flash with a key in eFuse. Release mode ends UART reflashing and JTAG debugging for good. Required for NVS encryption to mean anything.
- Staged rollout
- Deploying to a small cohort, verifying, and expanding. A sampling procedure whose value depends on whether the canaries can actually contain the fault — different batches, different sites, not the unit on your desk.
ACTIVE RECALLCheck your understanding
Answer in your own words first, then reveal.
1Your fleet has rollback enabled and a signed update path. An attacker gains control of your build server. Which defence helps, and what would have?›
Neither helps. Rollback protects against a build that fails its own self-test; an attacker's image will pass a self-test cheerfully, because passing it is trivially easy and the attacker wants the device running. Signing proves an image came from whoever holds the key — and the build server holds the key, so the malicious image is validly signed. Both defences do exactly what they promise and neither covers this threat.
What would have helped is defence around the key and the release process rather than around the device: the signing key held in a hardware token or an isolated signing service rather than on the build machine, so a compromised builder can produce artefacts but not sign them; two-person review of what gets signed; reproducible builds so a signed artefact can be checked against source. Beyond that, staged rollout limits the blast radius of anything that does get through, and anti-rollback prevents the attacker from serving an old vulnerable-but-genuinely-signed image. The general lesson: at some point the trust chain terminates in a human process, and that is where the remaining risk lives.
2Explain why a power cut during an OTA is a non-event, in enough detail that you could implement the same guarantee on a platform that did not provide it.›
Two mechanisms, both about never having an invalid state. First, the new image is written to a partition that is not running, so throughout the download the currently-executing firmware is untouched. A power cut here leaves a half-written inactive partition that nothing points at; the device reboots into the old image and can simply retry.
Second, the pointer that says which partition to boot is itself power-fail safe. otadata is two sectors, each holding a record with a sequence number and a CRC. A write always targets the older sector, so the newer valid record is never the one being erased. On boot, the bootloader reads both, discards any with a failing CRC, and takes the highest sequence number that remains. There is no instant at which both copies are invalid.
To rebuild this elsewhere: reserve two erase blocks for the selector; write a record containing a monotonically increasing counter, the target, and a checksum; always write to the block holding the lower counter; on boot pick the valid record with the higher counter. The property you are buying is that the commit is a single atomic transition between two states that are each individually valid, which is the same idea as a journalled filesystem's commit record.
3A colleague enables NVS encryption to protect the Wi-Fi password and closes the ticket. What is wrong, and what are the two honest options?›
NVS encryption encrypts the namespace with a key that lives in a separate nvs_keys partition — in the same flash chip, unencrypted, readable by anyone who can dump the flash either in circuit or after desoldering it. The lock and the key are in the same box. Enabling NVS encryption alone produces an artefact you can point at in a review rather than a secret an attacker cannot obtain.
The two honest options. Do it properly: enable flash encryption so the key partition is itself protected (or, on parts with the relevant peripheral, anchor the scheme to an HMAC key in eFuse). That means accepting release-mode flash encryption's costs — no more UART reflashing, JTAG effectively gone, harder crash analysis — and burning irreversible fuses. Or accept the risk explicitly: write down that the credentials are recoverable by anyone with physical possession of a unit, and manage it another way — a dedicated, segregated network for the pilot devices, credentials that are rotated when a unit is lost, and no reuse of that password anywhere else. Both are defensible. What is not defensible is the ticket being closed with the risk unchanged and the documentation implying otherwise.
4You are shipping a firmware change to Beacon's 25 pilot units. Describe the rollout you would actually run, and what you would watch.›
Before anything leaves the building: confirm the image is signed, confirm rollback is enabled, and confirm the self-test gate is wired to the commit — ideally by deliberately building a version that fails the self-test and watching a bench unit revert. A rollback mechanism you have never seen fire is a mechanism you are assuming.
Cohorts, chosen to be representative rather than convenient: one unit first, from a different production batch than the ones on my desk and deployed in the real environment rather than the lab, because the failure mode in the opening quote was a substituted flash part that a desk unit would never have shown. Then five, spread across sites and batches. Then the remaining nineteen.
What I watch, and it is already in the payload: the firmware-version byte in the fourteen-byte advertisement (Lesson 4.6) tells the gateway which image each unit is running, so "took the update", "rolled back", and "never received it" are three distinguishable states visible from the dashboard without touching a unit. The flags byte carries the self-test result. And the sequence number shows whether reporting continued at the expected rate — a unit that updated and then went quiet is the signal that matters most.
What I decide in advance: what count of rollbacks halts the rollout (for 25 units, one), and how long each cohort soaks before the next. At least one full night, because a fault that only appears after a few hundred wake cycles or a temperature swing will not show in twenty minutes.