Firmware update and recovery
ESP32 DoomsDay uses a main application partition and a small independent recovery updater. This design lets an SD update recover from an interrupted main-image write on a 4 MB flash device.
Ordinary SD update
- Download the main release file named like
esp32-doomsday-vX.Y.Z.bin. - Verify its SHA-256 value against the Firmware Center.
- Put it in
/OTA-Firmware-Update/on the microSD card. - Keep only the intended main update image in that directory.
- On the device, open Settings → Firmware Update → From SD Card.
- Confirm and keep power stable until the system restarts.
Do not rename a factory image to look like a main image.
Online update
If the device has Wi-Fi, Settings → Firmware Update → Online Update does
steps 1–4 for you: it fetches the latest release,
verifies its SHA-256, and places it in /OTA-Firmware-Update/ automatically,
then continues into the exact same confirm-and-install step below. It still
requires the one-time USB recovery install described in this page — there is
no way to reach a device that doesn't have a working recovery partition over
the network. See App Store & online updates for the full
online-update screen and the small public API behind it.
Image types
| Image | Purpose | Normal installation |
|---|---|---|
Main .bin | Routine firmware update | SD updater or wired flash at the documented main offset |
Recovery .bin | Repairs/replaces the independent updater | Wired flashing only |
Factory .bin | Bootloader, partition table, recovery, and main firmware merged | Wired flash at address 0x0 |
If an SD update is interrupted
Restore stable power and boot with the update SD card still inserted. The recovery updater can finish installing a valid main image. Do not repeatedly cycle power while it is writing.
If it immediately returns to the old firmware
An update normally spends noticeable seconds in the independent recovery app while the screen backlight is off. If the device instead watchdog-resets immediately and returns to the unchanged firmware, repair only the recovery slot from the source repository:
powershell -ExecutionPolicy Bypass -File .\tools\repair_sd_ota_recovery.ps1
Close the serial monitor first. The script normally identifies the ESP32-S3 port; when more than one serial device is connected, add -Port COM8 with the correct port.
The repair uses the hash-pinned image in Valuable_Recovery_Bin, validates the ESP32-S3 image and expected 0x260000 recovery partition, flashes only that slot, and verifies it by reading it back. It does not replace the main firmware, bootloader, NVS settings, partition table, or SD files. After it succeeds, retry the same SD update from the device.
The known 2026-08-20 failure was not SD-card corruption. A recovery-only build configuration enabled USB CDC too early; a USB tick interrupt accessed flash while NVS startup had the flash cache disabled. Recovery crashed before its own setup code and the bootloader safely returned to the old main firmware. The corrected recovery environment explicitly excludes ARDUINO_USB_CDC_ON_BOOT and safely deselects the shared expansion SPI device before mounting SD.
Wired factory recovery
Factory recovery erases or replaces the installed flash layout. Back up microSD content separately; microSD files are not stored in internal flash, but removing the card before wired recovery avoids accidental confusion.
Use Espressif-compatible tooling, the correct ESP32-S3 USB device, and the exact address documented with the release. The merged factory image is written at 0x0.
Integrity matters
SHA-256 verifies that a download is byte-for-byte identical to the published artifact. It does not by itself prove who published it. Download only from the official Firmware Center and never install a binary from an untrusted message or file-sharing link.