How firmware gets from a build to classroom devices: the registry, approval, staged deployments, what each device does, rollback, and releasing a new version. References: docs/guides/ota-updates.md, docs/firmware/OTA_ARCHITECTURE.md, docs/firmware/FIRMWARE_VERSIONING.md.

• What can be updated over the air
• The big picture
• The firmware registry
• Uploading an image
• Approve, deprecate, delete
• Deploying
• Strategy: canary, batches, limits
• Who is excluded, and why
• Following a deployment
• The per-device state machine
• What the gateway does during an update
• What the hub does during an update
• Rollback
• Releasing a new version
• Safety properties
• Troubleshooting updates

First v2.1 install on gateways and hubs: over USB, once. v2.1 changed the hub–gateway SPI format, and the gateway's bootloader gained rollback. After that, both update over the air.

flowchart LR
    B["Build<br/>impress_class_c6.bin"] --> U["Upload<br/>(Firmware page)"]
    U --> V{"valid imPress image?<br/>chip · project · X.Y.Z ·<br/>SHA-256 · size · signature"}
    V -- no --> R["refused with the reason"]
    V -- yes --> A["registry: uploaded"]
    A --> AP["Approve"] --> D["Deploy<br/>(devices + strategy)"]
    D --> E["deployment engine<br/>(every 5 s)"]
    E -- "offer + prompt" --> G["gateway"]
    G -- "SPI prompt" --> S3["hub"]
    G -- "check · download · status" --> E
    S3 -- "check · download (Wi-Fi hop)" --> E
    S3 -- "result after reboot (via gateway)" --> E

Every uploaded image is a row in firmware_artifacts, plus a file named by its SHA-256 (backend/firmware_bins/<sha256>.bin):

Firmware → Upload an image: drop build/impress_<project>.bin on the box. The upload is checked:

Every refusal names the problem, for example must be built for esp32c6, image version '1' is not X.Y.Z, or the image is not signed with this server's firmware key.

To check an image before uploading:

scripts/verify_firmware.py firmware/class_c6/build/impress_class_c6.bin [--key site.pub]

The page groups images by device type, newest first, and shows how many devices run each image or have it pending. The highest approved version is marked latest.

Deploy on an approved image opens the rollout dialog:

1. Choose devices (the filters combine):
   • specific devices;
   • every device of the image's type;
   • devices running a given version;
   • a classroom's devices (its gateway and the hub it relays).
2. Set the strategy (below).
3. Allow downgrade only for a deliberate rollback.
4. Click Preview. It lists every device that will be included, with its stage, and every one that won't, with the reason.
5. Click Start. The canary stage begins at once.

Push OTA on the Modules page is the same thing for one device: a one-device deployment with the same checks.

flowchart LR
    C["stage 0: canary"] --> H1{"failures ≤ allowed?"}
    H1 -- yes --> B1["stage 1: next batch"] --> H2{"…"} --> BN["last batch"] --> DONE["completed"]
    H1 -- no --> P["paused<br/>(the note says which stage)"]
    P -- "Resume (accept the failures)" --> B1
    P -- Cancel --> X["cancelled"]

So with the defaults, one device updates first. Only if it succeeds do the others follow, five at a time.

The Deployments list shows each rollout's image, state and counts per state, and refreshes itself while a rollout runs. Details shows every device: its stage, state, attempts, versions before and after, and the error if any.

Durability:

• Restarts: everything is stored in the database. The scheduler runs every 5 s and is idempotent, so after a backend restart running deployments carry on where they were.
• Double submits: an idempotency key makes a double submit return the same deployment instead of starting two.

stateDiagram-v2
    [*] --> waiting: in a later stage
    [*] --> queued: stage active
    waiting --> queued: stage starts (concurrency permitting)
    queued --> precheck: device asks firmware/check
    precheck --> downloading
    downloading --> verifying
    verifying --> installing
    installing --> rebooting
    rebooting --> health_check
    health_check --> success: running the expected version
    queued --> cancelled
    precheck --> cancelled
    waiting --> cancelled
    queued --> unreachable: timeout
    downloading --> timed_out: timeout
    rebooting --> rolled_back: the bootloader reverted
    health_check --> rolled_back
    downloading --> failed
    installing --> failed
    failed --> waiting: retry (attempts left)
    timed_out --> waiting: retry
    unreachable --> waiting: retry

sequenceDiagram
    participant BE as Backend
    participant C6 as Gateway (running v1)
    participant BL as Bootloader
    BE->>C6: WS ota_update {device_type: c6, mac}
    C6->>BE: firmware/check → v2, sha256, size (precheck)
    C6->>BE: GET firmware/download (downloading)
    Note over C6: writes into the inactive slot,<br/>hashing the stream (SHA-256)
    C6->>BE: ota/status verifying
    Note over C6: digest == offered sha256?<br/>esp_ota_end (chip, segments, hash, signature if required)
    C6->>BE: ota/status installing → rebooting
    C6->>BL: reboot (NVS: ota_target = v2)
    BL->>C6: boot v2 (pending verification)
    Note over C6: SPI up, Wi-Fi up, registration answered 200
    C6->>BE: ota/status health_check
    Note over C6: mark the image valid
    C6->>BE: ota/status success (version v2)
    Note over C6,BL: no Wi-Fi or backend within 120 s → reboot →<br/>bootloader reverts → v1 reports rolled_back

The gateway also checks for an update at every boot, so it picks up prompts it missed while offline. It ignores an offer it can't verify: a missing or short SHA-256, a non-semver version, or a zero size. It writes nothing to flash if the download's HTTP status or length is wrong.

1. The backend sends the prompt to the hub's gateway, which forwards it to the hub over SPI.
2. The hub joins Wi-Fi (the mesh keeps running), registers, and asks firmware/check.
3. Nothing pending: it disconnects and goes back to the mesh channel, without rebooting.
4. Update pending: it downloads (checking the HTTP status and size), installs and reboots.
5. The new image marks itself valid once the mesh and SPI are up. A crash before that makes the bootloader revert.
6. After the reboot, the hub reports applied (or rolled_back, or failed with an error code) through the gateway.

1. Bump the version in firmware/<project>/version.txt for each project that changed, and in VERSION for a release. A repository test requires all four to match.
2. Build: idf.py build, or use the CI artifact (each image comes with SHA256SUMS). With signing on: scripts/build_signed.sh (Security).
3. Check it: scripts/verify_firmware.py <image> [--key site.pub].
4. Upload it, and check the version, target and chip the page shows.
5. Approve it.
6. Deploy it with a canary.
7. Write release notes.

What a version number doesn't tell you:

• Bootloader and partitions: two devices on 2.1.0 can have different bootloaders or partition tables, because OTA never changes those.
• Build profile: an image built with the reduced-flash or signed profile reports the same version as a normal build. Deploy such builds only to the devices built the same way.