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": "",
  "updateInProgress": false
}

Response (both-slots update, second slot installing):

{
  "version": "1.3.0-def5678",
  "activeSlot": "B",
  "inactiveSlot": "A",
  "inactiveVersion": "",
  "updateInProgress": true,
  "updateProgress": 60,
  "updateMessage": "Updating second slot...",
  "updateMode": "full",
  "updatePhase": "installing_second"
}

Field	Type	Description
`version`	string	Currently running firmware version
`activeSlot`	string	Active firmware slot (`A` or `B`)
`inactiveSlot`	string	Inactive firmware slot
`inactiveVersion`	string	Reserved; currently always empty
`updateInProgress`	boolean	Whether an update is currently running
`updateProgress`	number	Progress percentage (0–100)
`updateMessage`	string	Human-readable status message
`updateMode`	string	`"full"` for a both-slots update; omitted for single-slot
`updatePhase`	string	Current phase of a both-slots update (see below)
`lastError`	string	Error message from the last failed update

updateProgress, updateMessage, updateMode, updatePhase and lastError are omitted when they are zero or empty. After an update finishes, updateProgress stays at 100 and updateMessage keeps the result until the device restarts:

Single slot: "Installation complete. Reboot to activate new firmware." Reboot with POST /api/system/reboot to activate it.
Both slots: "Both slots updated successfully." with updateMode: "full". No reboot is needed.

Full Update Phases

Phase	Description
`installing_first`	Installing firmware to the inactive slot
`rebooting`	First slot done, device is about to reboot
`awaiting_second_upload`	After the reboot, an upload-sourced update is waiting for the bundle at `/api/firmware/update/resume` (`updateInProgress` is `true`, progress 55)
`installing_second`	After reboot, installing firmware to the second slot

updatePhase is omitted once a both-slots update completes. If the update fails, it keeps the phase in which the failure happened.

Errors:

503 — Firmware manager not available

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"
}

With mode=full, the message is "Installing firmware from firmware-1.2.0.raucb (both slots, will reboot automatically)".

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 the device, and 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, file larger than 256 MiB, invalid form data, or a file name not ending in .raucb
409 — Update already in progress
500 — The upload could not be saved on the device
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, and the server must present a valid TLS certificate. The bundle must be no larger than 256 MiB.

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 on its own, so no further client action is required. If the re-download fails, it retries up to 5 times, 10 seconds apart.

Response (202 Accepted):

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

With mode=full, the message is "Downloading and installing firmware from URL (both slots, will reboot automatically)".

Errors:

400 — Invalid request body, missing URL, non-HTTPS URL, or update already in progress
503 — Firmware manager not available

Download failures after the request is accepted are reported in lastError of GET /api/firmware/status.

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 version installed to the first slot.

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

Response (202 Accepted):

{
  "status": "accepted",
  "message": "Finishing second slot..."
}

Errors:

400 — Missing file, file larger than 256 MiB, invalid form data, or a file name not ending in .raucb
409 — Not awaiting a second-slot upload, or bundle version mismatch. On a mismatch the device stays in awaiting_second_upload with the reason in lastError, so the correct bundle can be uploaded.
500 — The upload could not be saved on the device
503 — Firmware manager not available

POST /api/firmware/update/cancel

Abandon an interrupted full update, clearing the pending second-slot marker and the update status. The device stays on the new firmware; the second slot keeps its previous version. Both slots remain bootable. Use it only while updatePhase is awaiting_second_upload; it does not stop an install that is running.

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

Response (200 OK):

{
  "status": "ok",
  "message": "Full update cancelled. Both slots remain bootable."
}

Errors:

503 — Firmware manager not available