This page helps when a firmware update does not reach a device, does not finish, or when a rollout in waves stops. Start on the package’s page (Firmware > the package): its Devices list shows each device’s State, Progress, Tries and Problem. The device’s Firmware tab shows what it Runs, its Update and its History.
The device is not offered the image
Before you assign, select Check: What happens lists the devices that will not take the package, with the reason.
| Reason | Fix |
|---|---|
| Updates are off for its profile | On the profile’s Firmware tab turn on Allow firmware updates for this profile (off for a new profile) |
| Another hardware model | The package lists Hardware models; the device reports another one |
| Made for another profile | The package is limited to one profile (Only for devices of this profile) |
| Unsigned not allowed | The package is Not signed and the profile does not Allow unsigned images (use that only for test devices) |
| Current version too old | The device is older than Lowest version it can update from |
| Current version not known yet | The device has not reported current_fw_version. It must send it after every connect. |
| A more specific assignment wins | A device assignment wins over a device list, and a list over a profile |
| It waits for its wave | In a rollout, a device of a later wave receives nothing until its wave starts: Waits for wave n |
The package is not ready
| State | Meaning |
|---|---|
| Being checked | The file is scanned for viruses; it becomes Ready when the scan is clean |
| Rejected | The checksum, the signature or the scan failed; the file was deleted. Upload again. |
| After Retire | It is no longer offered for new assignments; running updates go on |
| After Revoke | It must not be installed: updates that have not started installing were stopped |
A signature is checked against your registered Signing keys. Revoking a key revokes every package signed with it.
Read the update state
| State | Meaning | What to do |
|---|---|---|
| Queued | Assigned; sent when the device is online | Bring the device online |
| Sent to the device | Told; it should start downloading | If it stays, the device does not handle the fw_* shared attributes on v1/attributes/set |
| Downloading, Downloaded, Checked, Installing | Progress the device reports | Wait |
| Waiting | The device holds the update: on a metered link, out of mobile data, or waiting for approval on the device itself | Not an error. See below. |
| Failed | The device reported FAILED with an fw_error code | Read Problem; Try again after fixing the cause |
| No answer in time | The device stopped reporting within Download may take (minutes) (60 by default) or Installing may take (minutes) (20 by default) | Check the link and the device; raise the times on the profile for slow links or large images |
| Went back to the old version | The new version did not start properly, and the device came back on the old one | Test the image on a device you can reach; check the boot logs |
| Not for this device | The package does not fit it | See the first table |
| Cancelled | Stopped before it was installed |
Tries per update (3 by default, 1 to 10 on the profile’s Firmware tab) sets how many attempts an update gets. For failed, timed-out or gone-back devices, the package page offers Try again.
Waiting on a metered link
A device on a mobile (LTE) link reports fw_wait: metered and waits, because Allow updates over LTE (mobile data) is off by default. To let it update:
- turn the setting on for the profile, or
- set Updates over LTE to Allowed for this device on the device’s Firmware tab.
fw_wait: quota_exhausted means the device’s mobile data allowance is used up; approval means someone must approve on the device. Waiting devices do not count as failures when a wave closes.
Download and install problems
| Symptom | Cause |
|---|---|
| The download fails after 15 minutes | fw_url is valid for 15 minutes. The device must ask for fw_url again and resume with an HTTP Range request. |
| The checksum matches but the device refuses the image | The signature does not verify. The device is right to refuse it: re-sign the image with a registered key. |
| The device reports Updated but the state does not change | UPDATED without the new current_fw_version is not accepted on its own. Report the running version after the reboot. |
| Firmware is never offered | Firmware is never offered over plain MQTT: the device must use TLS |
See Firmware updates (OTA) for what the device receives and reports.
A rollout paused itself
A rollout in waves pauses on its own when a wave:
| Reason shown | Meaning | What to do |
|---|---|---|
| too many devices failed | More failures than the wave’s At most failed (%) | Look at the failed devices’ Problem, fix the cause, then Resume or Abort |
| too few devices updated | The wave closed with fewer updated devices than required | Often offline devices. Check them, then resume. |
| no device finished in time | The wave closed with no device finished | The devices may be offline or cannot download |
“Devices that already started finish their update; no other device gets it until someone resumes the rollout.” Administrators get an in-app notice. Resume accepts what happened so far: only new failures count against the gate. Abort removes the assignment and cannot be undone.
The usual plan: 1 % canary (1 to 10 devices), then 10 %, 50 % and the rest; each wave needs 90 % of its finished devices updated, pauses above 5 % failed, and closes after 240 minutes at the latest. See Rolling out firmware in waves.
Who may do what
| Action | Default role |
|---|---|
| View packages and update states | User |
| Upload, retire, revoke, delete packages; assign; change OTA settings; retry | Admin |
| Register and revoke signing keys | Owner |