ota-reference-design/adr/ADR-011-device-controlled-update-execution.md

ADR-011: Device-Controlled Update Execution

• Status: Proposed
• Date: 2026-09-21

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.

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.

The architectural question is which participant controls execution once the device has accepted an update assignment. Requiring a remote command for every step would make progress and recovery depend on continued connectivity.

Decision

Let the backend manage release assignment and fleet deployment policy. Let the device coordinate the local execution of an accepted update within that authorization and its local operating policy.

After the required content and verification information are available, local activation, health acceptance, and recovery must not require a live connection to the deployment service.

Keep enough durable local state to reconcile an interrupted operation with installation and boot state. Report progress and the resulting software state when connectivity permits. Treat backend knowledge as a potentially delayed observation of the device.

This decision assigns responsibility to the device as a whole. It does not require the userspace update manager to handle failures that occur before it can run.

Decision Drivers

• Connectivity may disappear during an update.
• Local conditions determine when disruptive operations are permissible.
• A candidate that fails to boot cannot rely on its own update agent for recovery.
• Loss of reporting connectivity should not alone invalidate a locally healthy release.
• Operators need to distinguish intended deployment state from observed device state.

Alternatives Considered

Server-Controlled Execution of Every Step

The server authorizes each transition separately, including activation and confirmation.

This provides tighter online coordination, but a communication outage can leave an operation waiting for a command. It does not remove the need for local handling of boot failures or interrupted writes. It is less suitable for the assumed connectivity model.

Local Execution with Mandatory Remote Acceptance

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.

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.

Consequences

Positive

• Prepared updates can complete or recover during a backend outage.
• Local operational constraints can delay activation without a remote command round trip.
• Boot failure handling remains available independently of the deployment service.
• Requested and observed software states have explicit meanings.

Negative

• The device needs durable execution state and interruption handling.
• Backend status may remain uncertain until the device reconnects.
• Remote cancellation cannot take effect immediately on an offline device.
• Backend and device policies need clear precedence and reconciliation rules.

Notes

The implementation must define when an assignment is accepted, any expiry or cancellation rules, and the points at which an operation may safely be stopped. A backend cancellation cannot undo an activation that already occurred while the device was offline.

Repeated assignments and repeated reports must be reconciled with the operation identity and actual device state. They must not blindly repeat destructive installation steps.

This decision does not choose polling, push notifications, storage layout, or the boot failure detection mechanism. It assumes those mechanisms can support the stated local responsibilities; later chapters must establish how.

Applicability

This choice fits devices whose local health can be assessed offline and whose recovery must remain available during communication failures.

Consider external acceptance when successful operation fundamentally depends on a remote system. Specify how to distinguish failure of the candidate from failure of that system or the network.