121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
# ADR-003: Build a Reference Design, Not a Production Framework
|
|
|
|
* **Status:** Accepted
|
|
* **Date:** 2026-07-29
|
|
|
|
## Context
|
|
|
|
OTA update systems differ significantly between products.
|
|
|
|
Their architecture depends on factors such as:
|
|
|
|
* hardware platform;
|
|
* bootloader;
|
|
* storage layout;
|
|
* operating system;
|
|
* security model;
|
|
* network availability;
|
|
* fleet size;
|
|
* update frequency;
|
|
* bandwidth limitations;
|
|
* safety and regulatory requirements;
|
|
* manufacturing and key-provisioning processes.
|
|
|
|
A generic production-ready OTA framework would need to support many combinations of hardware, bootloaders, update artifacts, deployment systems, security policies, and fleet-management requirements.
|
|
|
|
Building such a framework would significantly increase the project scope and could distract from its primary goal: explaining how reliable and secure OTA systems are designed.
|
|
|
|
The project should demonstrate engineering principles and concrete implementation choices without claiming universal applicability.
|
|
|
|
## Decision
|
|
|
|
The project will be developed as a practical OTA reference design.
|
|
|
|
It will provide:
|
|
|
|
* documented requirements;
|
|
* architecture descriptions;
|
|
* Architecture Decision Records;
|
|
* update-state models;
|
|
* security analysis;
|
|
* reliability analysis;
|
|
* diagrams;
|
|
* example implementations;
|
|
* failure-injection tests;
|
|
* at least one working embedded Linux implementation.
|
|
|
|
The initial implementation may use Raspberry Pi as a practical demonstration platform, but the architecture will not be presented as Raspberry Pi-specific.
|
|
|
|
The project will not claim to be:
|
|
|
|
* a production-ready OTA framework;
|
|
* a complete fleet-management service;
|
|
* a universal update client;
|
|
* a certified safety-critical solution;
|
|
* a replacement for established commercial OTA platforms.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Build a Reusable OTA Framework
|
|
|
|
A reusable framework could provide common APIs, backend services, bootloader integrations, and platform adapters.
|
|
|
|
It was not selected because it would require a much larger scope, long-term compatibility guarantees, extensive platform testing, and a stable public API.
|
|
|
|
It would also shift the project away from architecture and engineering analysis toward product development and maintenance.
|
|
|
|
### Build a Raspberry Pi-Specific OTA Tutorial
|
|
|
|
A platform-specific tutorial would be easier to implement and explain.
|
|
|
|
It was not selected because the main engineering principles—atomicity, rollback, artifact verification, health checks, boot control, and failure recovery—apply to many embedded Linux devices.
|
|
|
|
Tying the project too closely to Raspberry Pi would unnecessarily limit its usefulness.
|
|
|
|
### Publish Documentation Without a Working Implementation
|
|
|
|
A documentation-only project would allow broader architectural discussion without platform-specific complexity.
|
|
|
|
It was not selected because a working implementation is necessary to validate assumptions and demonstrate real failure modes.
|
|
|
|
Without practical experiments, the project could remain too theoretical.
|
|
|
|
### Build Only an OTA Update Client
|
|
|
|
A standalone client would provide a concrete software artifact.
|
|
|
|
It was not selected because OTA reliability depends on the complete system, including the bootloader, storage layout, update metadata, health checking, rollback, signing, and deployment process.
|
|
|
|
The client alone would not demonstrate the full architecture.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
* The project can focus on engineering reasoning and architecture.
|
|
* Design decisions and trade-offs can be documented clearly.
|
|
* The implementation can remain understandable and suitable for learning.
|
|
* Platform-specific details can be isolated from general principles.
|
|
* Additional reference implementations can be added later.
|
|
* The project can evolve without promising a stable production API.
|
|
* Failure scenarios can be explored openly without presenting the design as universally safe.
|
|
|
|
### Negative
|
|
|
|
* Users cannot assume the code is ready for direct production deployment.
|
|
* Some components may be simplified for clarity.
|
|
* Platform integration may require significant additional work.
|
|
* The project may not cover manufacturing, provisioning, compliance, or very large fleet operations.
|
|
* Readers must evaluate whether each design decision applies to their own product.
|
|
* The boundary between a complete reference implementation and a framework must remain clearly documented.
|
|
|
|
## Notes
|
|
|
|
The repository README should contain a visible disclaimer similar to:
|
|
|
|
> This repository contains an educational OTA reference design for embedded Linux. It demonstrates one possible approach to reliable and secure system updates. It is not a production-ready framework and must be adapted, reviewed, tested, and hardened for each target product.
|
|
|
|
The project should prefer explicit architectural decisions over hidden assumptions.
|
|
|
|
When a design choice is platform-specific, it should be documented separately from the general OTA architecture.
|