Recovery OS

Purpose and design

The Recovery OS occupies the ota_0 partition, which is 0x280000 bytes in the current 16 MB layout. The ESP-IDF bootloader can fall back to it when the main OS in ota_1 is missing or invalid. Its job is simple: make sure there is a working ThistleOS in ota_1. If there is not, it provides a way to install one.

Key design choices:

• Rust + esp-rs — smaller binary than equivalent C code, and memory safety means fewer panic-class bugs in the one piece of code that must always work.
• Catalog-led board selection — Recovery detects the chip variant (ESP32/S3/C3/etc.) and lets the selected board profile drive firmware, driver, and window-manager selection. Generic I2C/SPI/UART probing is deliberately kept out of the minimal recovery path.
• Multi-arch chip detection — a single Recovery binary identifies whether it is running on Xtensa or RISC-V and selects the correct firmware architecture from the catalog.
• Downloadable board list — after WiFi connects, the web UI fetches the latest board catalog from https://wan0net.github.io/thistle-os/catalog.json and keeps the built-in list as the offline fallback.
• Full bundle download — Recovery downloads the firmware binary, matching drivers, board config, and the appropriate window manager in one provisioning flow. Catalog SHA-256 hashes and Ed25519 signatures are checked before executable files are installed or firmware is flashed.
• No LVGL — the recovery UI is a captive portal web page served over WiFi, viewable on any phone or laptop. The e-paper display shows status messages via raw framebuffer writes.
• No SD card required — if the SD card is missing or corrupt, recovery can still download firmware over WiFi.
• Web-first control loop — recovery continuously polls captive-portal requests so WiFi connect and bundle download actions do not depend on serial-console input.

Boot flow

Captive portal web UI

When Recovery OS starts its WiFi AP, any device that connects to ThistleOS-Recovery (open network, no password) is automatically redirected to the captive portal. The portal is a single self-contained HTML page served from flash — no SD card needed.

The portal provides a 3-step guided flow:

1. Step 1 — WiFi Connect — enter SSID and password to connect the ESP32 to your network (WPA2 client mode simultaneously with the AP).
2. Step 2 — Board Select — downloads the latest board list after WiFi connects, filters it by detected chip architecture, and keeps the built-in list available offline.
3. Step 3 — Dry Run & Install — dry-runs the selected board against the bundle catalog, then fetches the firmware binary, matching drivers, board config, and window manager from the official bundle catalog URL (https://wan0net.github.io/thistle-apps/catalog.json). Firmware is verified and flashed directly to ota_1; other bundle files are verified and installed to SD.
4. Step 3 — Reboot — confirms installation; reboots the device into a fully provisioned ThistleOS.

The portal design reuses the same link42 dark theme as these docs:

Recovery control path

The captive portal is the primary control path. Recovery keeps the WiFi AP and HTTP server alive, polls queued web requests, connects STA WiFi, installs the selected bundle, and lets the web UI trigger reboot. The UART console is intentionally not part of the minimal install loop, so web-triggered work cannot stall behind blocking serial input.

REST API endpoints

The captive portal web server also exposes a small REST API for scripted recovery:

Building from source

The Recovery OS is a standard esp-idf-svc Rust project. You need:

• Rust toolchain with the xtensa-esp32s3-espidf target (and/or RISC-V target for C3/C6)
• espup (Espressif's Rust toolchain installer)

# Install espup and the Xtensa Rust toolchain
cargo install espup
espup install

# Activate the toolchain in your shell
. $HOME/export-esp.sh

# Build the recovery firmware
cd recovery
cargo build --release

# Flash to ota_0 partition specifically
espflash flash --partition-table partitions.csv \
    --partition ota_0 \
    target/xtensa-esp32s3-espidf/release/thistle-recovery

Source layout