Device Lifecycle

A device moves through a set of status values from the moment you install the agent until you decommission it. Understanding each status helps you interpret the console, diagnose stale devices, and know when a deployment can be safely targeted.

Status values

OTA-Pulse tracks six status values on every device record.

unknown

The device has been created in the console but has not yet sent a heartbeat. This is the initial state after you register a device manually or after you re-activate a deactivated device. The server has no connectivity information yet.

online

The device sent a heartbeat within the last two minutes. The agent is running, the network is up, and the backend can reach telemetry from this device. New deployments can be targeted here.

degraded

The last heartbeat arrived between two and ten minutes ago. The device is not confirmed down, but it has missed at least one expected check-in. This may indicate intermittent network issues or a slow poll interval. Deployments queued for this device remain pending until contact resumes.

offline

No heartbeat has been received in more than ten minutes. The backend considers the device unreachable. Any in-flight deployment stays in its current status until the agent reconnects and reports progress.

updating

The device is actively applying a firmware update. The agent has started downloading or installing an artifact. The backend reflects this while the device reports downloading or installing deployment status back via the OTA status endpoint.

error

An unrecoverable error was recorded. This can be set by the agent when a deployment fails and the device cannot recover on its own, or by an operator marking the device faulted.

State transitions

[unknown] ──heartbeat──────────────────────────> [online]
[online]  ──>2 min no heartbeat──────────────── [degraded]
[degraded]──>10 min no heartbeat─────────────── [offline]
[offline] ──heartbeat resumes──────────────────> [online]
[online]  ──deployment starts───────────────────> [updating]
[updating]──install complete or failed──────────> [online] or [error]
[online]  ──operator deactivates────────────────> [offline] (is_active = false)

Registration and provisioning

Manual registration — an operator creates a device record in the console or API. The device starts in unknown and moves to online on the first heartbeat.

Self-provisioning — a provisioning token is baked into the image. On first boot the agent calls POST /api/v1/provision, the server creates the device record and issues a unique per-device API key, and the device is immediately online.

Heartbeat

The agent sends a heartbeat to POST /api/v1/heartbeat, updating last_seen and optionally reporting the current firmware version. The online / degraded / offline thresholds (2 min and 10 min) are evaluated server-side against last_seen each time the status is computed.

Caution

If a device misses heartbeats — for example during a network partition or a long firmware install — its status transitions to degraded and eventually offline. Deployments do not abort automatically when a device goes offline; they resume from their last reported state when the agent reconnects.

Decommissioning

Calling POST /devices/{id}/deactivate sets is_active = false and status to offline. Future heartbeats from that device are still accepted (they re-set last_seen) but the device is excluded from deployment targeting by convention. To permanently remove a device and its history, use the DELETE endpoint.