# OTA — Firmware Updates over Wi-Fi and from the SD card

**Goal:** install new firmware without a USB cable. Push it from the PC over Wi-Fi, or drop it on the SD card. Unsigned images are refused, and a broken update rolls back by itself.

## Decisions (design round 2026-10-03)

| # | Decision |
|---|---|
| Q52 | Two sources: **push over Wi-Fi** from the PC, and **from the SD card**. Pulling from Gitea releases is deferred. |
| Q53 | **Signed Update Files** (ECDSA P-256 over SHA-256). The private key stays in `~/.config/roro9stack/`, and the firmware embeds the public key (ADR 0003). |
| Q54 | The device **always listens** for pushes on the LAN while Wi-Fi is Connected, announced as `roro9stack-<id>.local`. |
| Q55 | New firmware runs on **Probation**. It's confirmed once booted, UI drawn, Services started, 30 s without a crash, and Wi-Fi connected (if configured). Otherwise **Rollback**. A Toast reports either outcome. |
| Q56 | **Downgrades are allowed**, with "older than the installed version" shown. |
| Q57 | A valid push **installs right away**: progress screen, then reboot. The reboot waits for Text Entry to end, 60 s at most. |

## Done when

- `scripts/ota_keygen.sh` creates the key pair once. The public key is committed; the private key never is.
- `scripts/flash.sh --ota` builds, signs and pushes to `roro9stack-<id>.local`. The device shows progress, reboots, and a Toast confirms the new version.
- An Update File with a bad signature, a truncated or corrupted image, or no signature is refused, and the device keeps running.
- Settings → About → **Update from SD** lists the `.ota` files in `/updates` and installs one.
- A firmware that crashes during Probation rolls back to the previous version, and says so after the reboot.

## Work breakdown

1. **Update File format** (host-tested): header (magic, format, version, image size, SHA-256), signature, image. A streaming parser that hashes as it goes and decides accept / refuse / downgrade. The signature verifier sits behind an interface, so tests can inject one.
2. **PC side:** key generation, `make_ota.py` (wraps `firmware.bin` into a signed `.ota`), and the push client. `flash.sh --ota` ties them together.
3. **Device:** the Update Service.
   - A listener on TCP 3232 plus mDNS.
   - Writes the image to the inactive app slot, with the ECDSA check through mbedTLS.
   - A progress screen, and a reboot that waits out Text Entry.
4. **Probation and Rollback:** the health checks, confirming the image, and detecting a rollback after reboot to report it.
5. **Update from SD:** the same parser, fed from the Storage Service's task (all card access stays there).