92 lines
5.2 KiB
Markdown
92 lines
5.2 KiB
Markdown
# ADR-011: Device-Initiated Update Checks
|
|
|
|
## Context
|
|
|
|
A device needs a way to find out whether an update is available for it. Devices may use different hardware, run different software versions, or belong to different customer groups. An update available to one device may not be suitable for another.
|
|
|
|
The device also knows its current conditions. It can wait for a usable connection, follow a Wi-Fi-only setting, or check when an operator requests it. The server may not know when these conditions are met.
|
|
|
|
## Decision
|
|
|
|
Let the device contact the server and ask which updates are available for it.
|
|
|
|
The request identifies the device, for example by serial number, and includes relevant information such as its current software version. The server uses this information and its device records to return suitable releases.
|
|
|
|
Checking for updates does not automatically start installation. The device can show “Updates available” and wait for an operator, or proceed according to its automatic update settings.
|
|
|
|
For devices with regular power cycles, check once at power-on when a suitable connection is available. Allow a local operator to request a check as well. Devices that run continuously can use scheduled checks. Apply connection preferences, such as Wi-Fi-only access, to the relevant checks and downloads.
|
|
|
|
## Decision Drivers
|
|
|
|
- The device knows when it has a usable connection.
|
|
- Connection preferences and operator requests can be handled locally.
|
|
- The server can offer different releases to individual devices or groups.
|
|
- Devices can make outgoing requests without accepting incoming server connections.
|
|
- Temporary loss of connectivity can be handled by trying again later.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- The basic exchange is simple: the device asks and the server responds.
|
|
- No permanent connection is needed to discover updates.
|
|
- Power-on, scheduled, and operator-triggered checks use the same mechanism.
|
|
- An offline device can check when it reconnects.
|
|
- Finding an update and deciding when to install it remain separate steps.
|
|
|
|
### Negative
|
|
|
|
- For continuously running devices, power-on checks alone are insufficient if updates need to be discovered during operation. Scheduled or manual checks are needed.
|
|
- If frequent scheduled checks are used, they create traffic even when no update is available.
|
|
- Large groups of devices need staggered checks and retry delays to avoid contacting the server at the same time.
|
|
|
|
## Special Considerations
|
|
|
|
### A Simple Exchange
|
|
|
|
```text
|
|
Device -> Server: I am device SN-123, running version 1.
|
|
Are there updates for me?
|
|
|
|
Server -> Device: Version 2 is available for your device.
|
|
Here are its details and download location.
|
|
|
|
Device: Notify the operator or follow automatic update settings.
|
|
```
|
|
|
|
The server may also respond that no update is available. It can use the serial number to look up the device's hardware model, customer group, or release channel. The device still checks compatibility and verifies the downloaded update before using it.
|
|
|
|
A serial number identifies a device; it is not a secret or proof of identity. Where access is restricted, authentication needs its own credentials.
|
|
|
|
### Connection and Operator Preferences
|
|
|
|
For a device that is powered on for each work session, a single check at startup may be enough. If updates are installed only outside normal work, discovering a release during that work may offer little benefit.
|
|
|
|
A device that stays on continuously needs another trigger, such as a scheduled or operator-requested check. Downloading a large image and restarting the device can have their own conditions.
|
|
|
|
For example, the device can discover an update now, download it later over Wi-Fi, and ask the operator before restarting. A request to check does not have to mean permission to perform every later step.
|
|
|
|
### Failed Checks
|
|
|
|
If the server is unreachable, keep the current software running and retry later. An unsuccessful check means the device could not obtain current information; it does not mean that no updates exist.
|
|
|
|
### After Download
|
|
|
|
When an update is approved and all required files and verification information are available, the device can manage installation, activation, and recovery locally. For devices that can check their essential functions locally, these steps need not depend on a continuous server connection. The device saves its progress and reports the result when connectivity returns.
|
|
|
|
## Applicability
|
|
|
|
This approach fits devices that can make outgoing connections and do not need immediate notification of every new release. It provides a straightforward starting point for automatic checks, manual checks, and intermittent connectivity.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Server-Initiated Delivery
|
|
|
|
The server contacts the device when an update becomes available. This can reduce discovery delay, but requires a way to reach the device and handle missed delivery while it is offline. Local conditions still determine whether installation can begin.
|
|
|
|
### Notification Followed by a Device Check
|
|
|
|
A messaging service tells the device that an update may be available. The device then queries the server for current details.
|
|
|
|
This can provide faster notification, but adds a messaging connection and another component to maintain. Periodic checks can still be used to cover missed notifications.
|