Deployments

A deployment is the record that pairs a specific firmware artifact with a specific device and tracks the update from the moment the server queues it until the device confirms success or failure. Every time you push a firmware version to one or more devices, the server creates one FirmwareDeployment row per device.

Targeting devices

POST /firmware/{id}/deploy accepts two targeting modes:

• Explicit list — pass device_ids to choose a named subset.
• Hardware version match — omit device_ids; the server selects devices whose hardware_version matches the artifact’s embedded device types.

If the firmware has min_version set, devices below that version are skipped unless the caller passes force: true (requires owner role or above).

Phased rollout

Pass rollout_percentage (0–100) in the deploy request to limit the rollout to a random sample of eligible devices. For example, rollout_percentage: 10 creates deployments for 10% of the matching fleet. Run the same call again with a higher percentage to widen the rollout. This is a one-shot sampling — it does not automatically expand over time.

Status states

Each deployment record carries a status field. The device’s OTA agent reports transitions back via POST /v1/ota/status/{deployment_id}.

Status	Meaning
pending	Server created the deployment; device has not started yet. The heartbeat response will advertise an available update.
downloading	Device acknowledged the update and is transferring the artifact.
downloaded	Artifact transfer complete; device has the file locally but has not started writing yet.
installing	Device is writing the artifact to the inactive partition.
installed	Device successfully applied the update and rebooted into the new firmware. The device’s firmware_version is updated to the new version.
failed	The update did not complete successfully. The error_message field contains a description.
rolled_back	An operator triggered a rollback after the update reached installing, installed, or failed.

Pause, resume, and cancel

Operators with at least member role can intervene while a deployment is in flight.

Pause — available from pending or downloading. The server inserts a pause control directive; the paused_at timestamp is recorded. The deployment does not resume automatically.

Resume — clears the pause directive and paused_at. The agent receives a continue directive on its next poll.

Cancel — available at any status. Sets deployment to failed (“Cancelled by operator”) and inserts force_cancel. Cancelling an already-failed deployment is a no-op.

Retry

Only allowed from failed. The deployment resets to pending, retry_count increments, and the error is cleared. Maximum five retries; further attempts return 422.

Rollback

Allowed from installing, installed, or failed. The server sets status = rolled_back and inserts a force_cancel directive. The agent receives the directive on its next poll and uses the bootloader to revert to the previously active partition. Already-rolled-back deployments are a no-op.

Every pause, resume, cancel, retry, and rollback action is written to the audit log with the operator’s user ID and a timestamp.

Every deployment ships an artifact — see Artifacts for the file format and signing requirements.