diff --git a/adr/ADR-011-device-initiated-update-checks.md b/adr/ADR-011-device-initiated-update-checks.md new file mode 100644 index 0000000..7ec2cfa --- /dev/null +++ b/adr/ADR-011-device-initiated-update-checks.md @@ -0,0 +1,88 @@ +# 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. + +Use scheduled checks and allow a local operator to request a check. 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. +- 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 + +- A device may not discover a release until its next check. +- Frequent checks 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. +- The server cannot make an offline device check immediately. + +## 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 + +A device may check automatically after connecting to Wi-Fi, at a scheduled interval, or when an operator selects “Check for updates.” 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. + +Once an update has been selected, [ADR-012](ADR-012-device-controlled-update-execution.md) describes how the device can manage installation, activation, and recovery without a continuous server connection. + +## 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. diff --git a/adr/ADR-011-device-controlled-update-execution.md b/adr/ADR-012-device-controlled-update-execution.md similarity index 80% rename from adr/ADR-011-device-controlled-update-execution.md rename to adr/ADR-012-device-controlled-update-execution.md index d5369e3..e794d21 100644 --- a/adr/ADR-011-device-controlled-update-execution.md +++ b/adr/ADR-012-device-controlled-update-execution.md @@ -1,11 +1,10 @@ -# ADR-011: Device-Controlled Update Execution - -* **Status:** Proposed -* **Date:** 2026-09-21 +# ADR-012: Device-Controlled Update Execution ## Context -This educational example considers remotely deployed embedded Linux devices with intermittent connectivity. A backend assigns authorized releases, but a device may lose contact after receiving an assignment or preparing an update. +A remotely deployed embedded Linux device may lose its connection after learning about an available update or preparing it for installation. The server controls which releases are available to the device, but cannot always stay in contact throughout the update. + +[ADR-011](ADR-011-device-initiated-update-checks.md) describes how the device checks for updates. Once an update has been selected and approved, a separate question remains: who controls the steps needed to complete it? The device can evaluate local operating conditions and has a locally available activation and recovery mechanism. Its essential post-update health checks can be evaluated without contacting the deployment service. @@ -41,13 +40,13 @@ This provides tighter online coordination, but a communication outage can leave The device installs and boots independently but requires the backend to accept the candidate before confirmation. -This can be appropriate when external service behavior is part of release acceptance. In this example, it would couple an otherwise healthy local update to network availability. Such a design also needs an explicit timeout and recovery policy for unavailable remote acceptance. +This can be appropriate when external service behavior is part of release acceptance. For a device that can check its essential functions locally, this would make acceptance of an otherwise healthy update depend on network availability. Such a design also needs an explicit timeout and recovery policy for unavailable remote acceptance. ### Fully Autonomous Release Selection The device selects any compatible authorized release without a backend assignment. -This can fit simpler products, but does not meet the example's need for centrally controlled release assignment. Local execution autonomy does not imply authority to select arbitrary releases. +This can fit simpler products, but does not provide the server control over release availability assumed here. Local execution autonomy does not imply authority to select arbitrary releases. ## Consequences diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.md index 4045b95..0e7cc60 100644 --- a/docs/03-system-architecture.md +++ b/docs/03-system-architecture.md @@ -49,7 +49,7 @@ These are roles, not a shopping list of separate services. One tool may cover se Imagine a device running version 1. Version 2 is ready. In this example, the device can prepare the new system while keeping the previous one available for recovery. -1. The server offers version 2 to the device. +1. The device checks with the server, which returns version 2 as an available update for this device. 2. The OTA manager checks that it fits this device and that an update is allowed now. 3. The installer downloads, verifies, and prepares version 2. Version 1 is still running. 4. When the device can restart, boot control selects version 2 and the device reboots. @@ -62,7 +62,7 @@ If the update itself is interrupted, the device needs enough saved information t Two ADRs explain the choices behind this example: -- [ADR-011: Device-Controlled Update Execution](../adr/ADR-011-device-controlled-update-execution.md) — why let the device finish the update when the server is unreachable? -- [ADR-012: Separate Update Management from Installation](../adr/ADR-012-update-management-and-installation.md) — why separate deciding when to update from knowing how to install it? +- [ADR-011: Device-Initiated Update Checks](../adr/ADR-011-device-initiated-update-checks.md) — how does a device find updates when its connection and settings allow it? +- [ADR-012: Device-Controlled Update Execution](../adr/ADR-012-device-controlled-update-execution.md) — why let the device finish the update when the server is unreachable? Next, we will follow the boot process and see what happens before Linux and the OTA manager start.