Ref #03 next ADR templates

adr/ADR-011-device-initiated-update-checks.md

@@ -0,0 +1,91 @@
+# 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.

adr/ADR-012-server-initiated-updates.md

@@ -0,0 +1 @@
+# ADR-012: Server-Initiated Updates

adr/ADR-013-update-notifications-with-device-initiated-checks.md

@@ -0,0 +1 @@
+# ADR-013: Update Notifications with Device-Initiated Checks

docs/03-system-architecture.md

@@ -0,0 +1,65 @@
+# 03. OTA System Architecture: How the Parts Work Together
+
+The previous chapter looked at what we update: a system image, an application, or data. Now let’s look at who does the work.
+
+An OTA update starts with a tested release and ends with a device running it successfully. Several parts of the system help it get there.
+
+## 1. The Big Picture
+
+```text
+Build and test a release
+          |
+          v
+Publish update files
+          |
+          v
+Server offers the release to selected devices
+          |
+          v
+Device downloads and checks the update
+          |
+          v
+Install -> Activate -> Check that it works
+          |
+          v
+Report the result to the server
+```
+
+The server decides which devices should receive a release. The device checks whether it can update now, carries out the work, and reports the result.
+
+Alongside the update files, it needs a few details: which version this is, which devices it supports, and how to verify it. The server also needs feedback. “Update offered” and “new version running” are different things.
+
+## 2. Who Does What?
+
+**Release preparation and storage.** The software is built, tested, given a version, and published for download. The release includes information needed to check that the files are intact and come from an authorized source. Storage can be as simple as a file server.
+
+**Deployment management.** This part chooses which devices receive which release and tracks their progress. For example, an operator might offer a release to a small test group before making it available to everyone.
+
+**OTA manager.** On the device, the manager organizes the update. It checks whether the release fits the device and whether local conditions allow the work. A device might download an update while busy, then wait until its current task finishes before restarting.
+
+**Installer.** This part knows how to install the software: write an image, install a package, or prepare a new set of files. Depending on the tool, it may also handle downloading and verification. The manager decides when to proceed; the installer knows how to do the installation.
+
+**Activation and boot control.** Installed software is not necessarily running yet. A system update may need a reboot into the new version. An application update may need only a service restart. For system updates, boot components must also handle cases where the new system cannot start the OTA manager.
+
+**Health checks.** These check whether the new version can do its job. Linux starting successfully may not be enough: the main application might still fail. The results help the device decide whether to keep the new version or start recovery.
+
+These are roles, not a shopping list of separate services. One tool may cover several of them. What matters is knowing who handles each step.
+
+## 3. One Update, Start to Finish
+
+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 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.
+5. Health checks test the essential functions. If they pass, the device confirms version 2. If they fail, it starts recovery. If the system cannot boot at all, the boot recovery mechanism must handle that earlier failure.
+6. The device reports the outcome, including which version is now running.
+
+What if the network disappears? In this example, once the required files and verification information are available, the device can finish the local steps without the server. It sends its report when the connection returns. A broken connection alone does not mean the new software is broken.
+
+If the update itself is interrupted, the device needs enough saved information to work out what happened before continuing. We will look at storage, boot behavior, and recovery in later chapters.
+
+[ADR-011: Device-Initiated Update Checks](../adr/ADR-011-device-initiated-update-checks.md) explains how a device checks for updates at power-on, on a schedule, or at the operator’s request.
+
+Next, we will follow the boot process and see what happens before Linux and the OTA manager start.