4.8 KiB
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.