A firmware update that breaks devices should break few of them. A rollout in waves sends a package first to a small group, checks how it went, waits, and only then goes on to bigger groups. It stops by itself when a wave goes worse than you allow. This page explains how to set one up and follow it. The basics of packages and assignments are in Firmware updates (OTA).
When you can use waves
Waves apply to an assignment to Every device of a profile or Some devices (a device list). An assignment to One device is sent at once. You need the permission to assign firmware (administrators).
Set up a rollout
- Open the package on Firmware and select Assign (or use a profile’s Firmware tab).
- Choose Every device of a profile or Some devices and pick the targets.
- Turn on Send in waves (“A small first wave of online devices, then bigger ones. The rollout stops by itself when a wave goes worse than you allow.”).
- Keep Use the usual plan, or edit the waves (see below).
- Select Check. What happens shows the device counts and “In waves: …” with the size of each wave.
- Select Assign and confirm.
The usual plan
| Wave | Size | Wait after it passed |
|---|---|---|
| 1 | 1 % of the devices, at least 1 and at most 10 (the canary) | 30 minutes |
| 2 | 10 % | 30 minutes |
| 3 | 50 % | 15 minutes |
| 4 | the rest | — |
Each wave of the usual plan needs at least 90 % of its finished devices updated, pauses above 5 % failed, and closes after 240 minutes at the latest.
Your own waves
In Waves, “Sizes are counted over the devices that will be updated. The last wave takes every device left.” For each wave:
| Field | Meaning | Range |
|---|---|---|
| Size as | Number of devices or Share of the devices (%) | A size more than 0; a share at most 100 % |
| Wait after it passed (minutes) | The soak time before the next wave starts | 0 to 10,080 (7 days) |
| At least updated (%) | The success gate over the wave’s finished devices | 0 to 100 |
| At most failed (%) | The failure gate | 0 to 100 |
| At most failed (devices) | Optional absolute cap. “Leave empty to count the share only.” | — |
| Close after (minutes) | How long the wave stays open. “Devices still offline or waiting by then are carried on and do not count as failures.” | 5 to 43,200 |
Add a wave and Remove wave n change the list; The rest marks the last wave. A rollout has at most 20 waves.
How devices are put into waves
- The order of devices is stable for a rollout, so a device does not jump between waves when you look again.
- Online devices go first, so the canary wave gives you results quickly.
- A device of a later wave receives nothing (no
fw_*attributes) until its wave starts. On its page it shows Waits for wave n.
While a rollout runs
The package page shows the Rollout in waves: each wave with its State (Not started, Updating, Passed, waiting, Passed, Paused, Not sent), its Devices and Progress (“updated of planned updated, failed failed”), and the gate now (“Now: … failed (… %), … % of the finished updated.”). “This wave closes … at the latest” and “The next wave starts …” show the times.
The rollout’s status is Running, Paused, Completed or Aborted.
Automatic pause
The rollout pauses by itself when a wave:
| Reason | Shown as |
|---|---|
| has more failures than allowed | too many devices failed |
| closes with fewer updated devices than required | too few devices updated |
| closes with no device finished | no device finished in time |
“Devices that already started finish their update; no other device gets it until someone resumes the rollout.” Your administrators get an in-app notice (“package: the rollout is paused”).
Pause, Resume, Abort
| Action | Effect |
|---|---|
| Pause | “No other device gets the update until you resume. Devices that already started finish their update; an update cannot be stopped safely halfway.” |
| Resume | “The rollout goes on with wave n.” After an automatic pause: “Resuming accepts what happened so far: only new failures count against the gate, and a wave stopped at its end counts as passed.” |
| Abort | “Its assignment is removed. Devices that have not started installing do not get this update; devices covered by another assignment move to that one. This cannot be undone.” |
A rollout also ends when the package is revoked, when its assignment is removed, or when a newer assignment replaces it.
Notices, audit and webhooks
| Event | Webhook | In-app notice |
|---|---|---|
| A wave passed | ota.rollout.wave_completed | “Enough devices of wave n updated. The next wave starts after its waiting time.” |
| Paused | ota.rollout.paused | yes |
| Resumed | ota.rollout.resumed | — |
| Completed | ota.rollout.completed | “All n waves passed. Devices that were offline update when they come back.” |
| Aborted | ota.rollout.aborted | — |
Every pause, resume and abort is written to the audit log with who did it.
Tips
- Before a rollout, test the package on a few devices you can reach physically, with One device assignments.
- Keep the soak time long enough for problems to show: a device that reboots in a loop needs time to fail.
- Devices on metered links may wait (Waiting) instead of updating; they are carried on and do not count as failures when the wave closes.