Firmware Endpoints

GET /api/firmware/status

Returns current firmware version, slot information, and update progress.

Response (idle):

{
  "version": "1.2.0-abc1234",
  "activeSlot": "A",
  "inactiveSlot": "B",
  "inactiveVersion": "1.1.0",
  "updateInProgress": false
}

Field	Type	Description
`version`	string	Currently running firmware version
`activeSlot`	string	Active firmware slot (`A` or `B`)
`inactiveSlot`	string	Inactive firmware slot
`inactiveVersion`	string	Firmware version on the inactive slot
`updateInProgress`	boolean	Whether an update is currently running
`updateProgress`	number	Progress percentage (0–100), present during updates
`updateMessage`	string	Human-readable status message, present during updates
`updateMode`	string	Empty for single-slot updates, `"full"` for both-slots updates
`updatePhase`	string	Current phase during a full update (see below)
`lastError`	string	Error message from the last failed update, if any

Full Update Phases

Phase	Description
`installing_first`	Installing firmware to the inactive slot
`rebooting`	First slot done, device is about to reboot
`installing_second`	After reboot, installing firmware to the second slot

POST /api/firmware/update

Upload a .raucb firmware bundle for installation. Uses multipart/form-data encoding.

Parameter	Description
Form field: `firmware`	The `.raucb` file (max 256 MiB)
Query: `mode`	Empty (default) for single slot, `full` for both slots

Example — single slot:

curl -X POST -F "firmware=@firmware-1.2.0.raucb" \
  http://<device-ip>/api/firmware/update

Example — both slots:

curl -X POST -F "firmware=@firmware-1.2.0.raucb" \
  "http://<device-ip>/api/firmware/update?mode=full"

Response (202 Accepted):

{
  "status": "accepted",
  "message": "Installing firmware from firmware-1.2.0.raucb"
}

Installation runs asynchronously. Poll GET /api/firmware/status for progress.

In mode=full, the device reboots automatically after the first slot. The bundle is not staged on /data — only a small marker is kept across the reboot. After the reboot the status reports updatePhase: "awaiting_second_upload", and the caller must re-upload the same bundle to POST /api/firmware/update/resume to finish the second slot. (URL-sourced full updates skip this — see below.)

Errors:

400 — Missing file, invalid form data, or non-.raucb file
409 — Update already in progress
503 — Firmware manager not available

POST /api/firmware/update/url

Download and install a firmware bundle from a URL.

Request:

{
  "url": "https://example.com/firmware-1.2.0.raucb"
}

Only HTTPS URLs are accepted.

Parameter	Description
Query: `mode`	Empty (default) for single slot, `full` for both slots

With mode=full, the device re-downloads the bundle from the URL after the reboot and finishes the second slot autonomously — no further client action required.

Response (202 Accepted):

{
  "status": "accepted",
  "message": "Downloading and installing firmware from URL"
}

Errors:

400 — Invalid URL, missing URL, or non-HTTPS URL
409 — Update already in progress

POST /api/firmware/update/resume

Finish the second slot of an interrupted upload-sourced full update by re-uploading the bundle. Uses multipart/form-data with a firmware field, like /api/firmware/update. Valid only while updatePhase is awaiting_second_upload; the bundle version must match the first slot.

curl -X POST -F "firmware=@firmware-1.2.0.raucb" \
  http://<device-ip>/api/firmware/update/resume

Errors:

400 — Missing file, invalid form data, or non-.raucb file
409 — Not awaiting a second-slot upload, or bundle version mismatch

POST /api/firmware/update/cancel

Abandon an interrupted full update, clearing the pending second-slot marker. The device stays on the new firmware; the second slot keeps its previous version. Both slots remain bootable.

curl -X POST http://<device-ip>/api/firmware/update/cancel