update readme

.gitignore

@@ -0,0 +1 @@
+.tmp/

adr/ADR-001-repository-name.md

@@ -0,0 +1,87 @@
+# ADR-001: Use `ota-reference-design` as the Repository Name
+
+* **Status:** Accepted
+* **Date:** 2026-07-29
+
+## Context
+
+The project requires a repository name that communicates its purpose clearly without tying the design to a single hardware platform, implementation language, or update framework.
+
+The repository will contain:
+
+* architectural documentation;
+* OTA design decisions;
+* diagrams;
+* reference implementations;
+* update tooling;
+* failure-injection experiments;
+* security and reliability analysis.
+
+The initial practical implementation may use Raspberry Pi hardware, but the overall design should remain applicable to other embedded Linux platforms.
+
+The repository is not intended to provide a production-ready OTA framework or a reusable software library. Its primary purpose is to demonstrate and explain the architecture of a reliable and secure OTA update system.
+
+## Decision
+
+The repository will be named:
+
+```text
+ota-reference-design
+```
+
+The repository will initially remain a standalone top-level repository rather than being placed under a broader group such as `engineering`, `embedded-systems`, or `systems-engineering`.
+
+## Alternatives Considered
+
+### `embedded-ota-lab`
+
+This name emphasizes experimentation and practical work.
+
+It was not selected because the project will contain more than experiments. It will also document architecture, security, reliability, design decisions, and implementation trade-offs.
+
+### `ota-update-lab`
+
+This name is simple but somewhat redundant because OTA already means over-the-air updating.
+
+It also makes the project sound more like a temporary collection of experiments than a structured reference design.
+
+### `reliable-ota`
+
+This name emphasizes one of the primary goals of the project.
+
+It was not selected because it does not clearly communicate that the repository is educational and architectural rather than a production-ready OTA product.
+
+### A Repository Under an `engineering` Group
+
+A broader parent group could eventually contain several related repositories.
+
+It was not selected at this stage because a group containing only one repository adds unnecessary hierarchy and does not yet provide meaningful organization.
+
+## Consequences
+
+### Positive
+
+* The name clearly communicates that the project is an OTA reference design.
+* The repository is not tied to Raspberry Pi or any other specific platform.
+* The name allows the project to include documentation, code, diagrams, and experiments.
+* Readers are less likely to mistake the project for a production-ready framework.
+* The name remains appropriate if additional hardware platforms are added later.
+
+### Negative
+
+* The name is broader than the initial Raspberry Pi implementation.
+* Readers may still require the README to understand the exact project scope.
+* The term “reference design” may suggest a more complete implementation than exists during the early stages of development.
+
+## Notes
+
+A broader repository group may be introduced later if several related systems-engineering projects are created.
+
+Possible future group names include:
+
+```text
+embedded-systems
+systems-engineering
+```
+
+Moving the repository into such a group would not require changing the repository name.

adr/ADR-002-license.md

@@ -0,0 +1,87 @@
+# ADR-002: Use the MIT License
+
+* **Status:** Accepted
+* **Date:** 2026-07-29
+
+## Context
+
+The project is intended to be an open educational and engineering reference for designing OTA update systems on embedded Linux.
+
+The repository may contain:
+
+* documentation;
+* diagrams;
+* source code;
+* scripts;
+* configuration examples;
+* reference implementations;
+* test utilities;
+* failure-injection experiments.
+
+The license should allow engineers to study, modify, reuse, and adapt the material in both personal and commercial projects.
+
+The license should also be familiar, permissive, and easy to understand. The project does not require derivative works to remain open source.
+
+## Decision
+
+The repository will be licensed under the MIT License.
+
+The license will apply to the repository content unless a specific file or third-party component explicitly states otherwise.
+
+A standard `LICENSE` file containing the MIT License text will be included at the repository root.
+
+## Alternatives Considered
+
+### Apache License 2.0
+
+Apache 2.0 is a permissive license that includes an explicit patent grant and patent retaliation provisions.
+
+It was not selected because the project is currently an educational reference design rather than a large infrastructure framework or commercially governed software platform.
+
+The additional legal complexity does not currently provide enough practical benefit over MIT.
+
+### GNU General Public License
+
+The GPL would require derivative works distributed under certain conditions to remain under the same license.
+
+It was not selected because the project is intended to encourage broad reuse, including adoption of ideas and code in commercial embedded products.
+
+A copyleft requirement could discourage some companies or engineers from using the examples.
+
+### BSD 2-Clause or BSD 3-Clause License
+
+The BSD licenses are permissive and would also be suitable for the project.
+
+They were not selected because MIT is more familiar to many readers, concise, and already consistent with other projects maintained by the author.
+
+### No Explicit License
+
+Without a license, the repository would remain protected by copyright by default and other people would not have clear legal permission to reuse the material.
+
+This would conflict with the educational and open-source goals of the project.
+
+## Consequences
+
+### Positive
+
+* The project can be used in open-source and commercial environments.
+* Engineers can copy, modify, and redistribute examples.
+* The license is short and widely understood.
+* The project remains easy to adopt.
+* The license is consistent with the author’s other open-source repositories.
+* Attribution and preservation of the license notice are still required.
+
+### Negative
+
+* Modified versions are not required to remain open source.
+* Improvements may be used commercially without being contributed back.
+* The license does not include the explicit patent language provided by Apache 2.0.
+* The software is provided without warranty or liability protection beyond the license terms.
+
+## Notes
+
+The repository is a reference design and educational project.
+
+The MIT License permits reuse but does not imply that the implementation is production-ready, certified, secure for every deployment, or suitable for safety-critical systems.
+
+These limitations should also be explained in the repository README.

adr/ADR-003-reference-design.md

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

adr/template.md

@@ -0,0 +1,38 @@
+# ADR-NNNN: Decision Title
+
+* **Status:** Proposed
+* **Date:** YYYY-MM-DD
+
+## Context
+
+Describe the problem or architectural question that requires a decision.
+
+Explain the relevant requirements, constraints, risks, and assumptions. Keep this section focused on why the decision is needed.
+
+## Decision
+
+Describe the selected approach clearly and directly.
+
+## Alternatives Considered
+
+### Alternative 1
+
+Briefly describe the alternative and why it was not selected.
+
+### Alternative 2
+
+Briefly describe the alternative and why it was not selected.
+
+## Consequences
+
+### Positive
+
+* List the main benefits of the decision.
+
+### Negative
+
+* List the costs, limitations, and trade-offs introduced by the decision.
+
+## Notes
+
+Add implementation details, unresolved questions, or links to related documents when necessary.

docs/00-series-overview.md

@@ -0,0 +1,262 @@
+# OTA Reference Design
+
+> A practical guide to designing reliable, secure, and maintainable over-the-air (OTA) update systems for embedded Linux devices.
+
+---
+
+## About This Repository
+
+This repository presents a practical reference design for building over-the-air (OTA) update systems for embedded Linux devices.
+
+Rather than documenting a particular framework or vendor-specific solution, it focuses on the engineering principles that make OTA systems reliable, secure, and maintainable.
+
+The goal is to explain **why** modern OTA systems are designed the way they are, what problems they solve, and what trade-offs different approaches involve.
+
+Although many examples use Raspberry Pi as a demonstration platform, the concepts are applicable to a wide range of embedded Linux systems.
+
+---
+
+## Why This Repository Exists
+
+There is no shortage of documentation for OTA frameworks.
+
+You can easily find documentation for tools such as:
+
+- Mender
+- RAUC
+- SWUpdate
+- OSTree
+- A/B Updates
+
+However, these resources usually explain **how to use a particular tool**, not **why OTA systems are designed this way**.
+
+Questions like these are often left unanswered:
+
+- Why do many devices use A/B partitions?
+- Why are bootloaders involved in the update process?
+- Why is rollback necessary?
+- What happens if power is lost during an update?
+- Why are update images signed?
+- Why are atomic updates important?
+- How do production devices remain recoverable after failures?
+
+This repository attempts to answer those engineering questions.
+
+---
+
+## What You'll Learn
+
+Throughout this series we will explore topics including:
+
+- OTA architecture
+- Boot process
+- Update strategies
+- Full-image vs package updates
+- A/B partition layouts
+- Bootloader interaction
+- Rollback mechanisms
+- Atomic updates
+- Image verification
+- Digital signatures
+- Secure Boot
+- Failure recovery
+- Delta updates
+- Version management
+- Testing strategies
+- Production deployment considerations
+
+The emphasis is always on understanding the underlying design rather than memorizing a particular implementation.
+
+---
+
+## Repository Structure
+
+```text
+ota-reference-design/
+│
+├── docs/
+│   ├── 00-series-overview.md
+│   ├── 01-ota-introduction.md
+│   ├── 02-update-strategies.md
+│   ├── ...
+│
+├── diagrams/
+│   └── plantuml/
+│
+├── examples/
+│   ├── raspberry-pi/
+│   ├── qemu/
+│   └── simulations/
+│
+├── adr/
+│   ├── ADR-001-repository-name.md
+│   ├── ADR-002-license.md
+│   └── ADR-003-reference-design.md
+│
+└── README.md
+```
+
+---
+
+## Learning Path
+
+The chapters are designed to build on each other.
+
+```text
+Introduction
+      │
+      ▼
+Update Strategies
+      │
+      ▼
+System Architecture
+      │
+      ▼
+Boot Process
+      │
+      ▼
+Storage Layout
+      │
+      ▼
+Atomic Updates
+      │
+      ▼
+Rollback
+      │
+      ▼
+Security
+      │
+      ▼
+Testing
+      │
+      ▼
+Production Deployment
+```
+
+While each chapter can be read independently, following the series in order provides a much deeper understanding of the complete system.
+
+---
+
+## Engineering Philosophy
+
+This repository is intentionally different from product documentation.
+
+Instead of presenting a single "correct" solution, every topic discusses:
+
+- why a particular design exists;
+- which problem it solves;
+- what alternatives are available;
+- what trade-offs each approach introduces;
+- when another solution may be more appropriate.
+
+Real-world engineering is rarely about choosing the only correct answer.
+
+It is about understanding constraints and making informed decisions.
+
+---
+
+## The Reference Design
+
+The architecture presented throughout this repository is a coherent reference design.
+
+Real products may use different technologies or frameworks while following the same architectural principles.
+
+For example, one project may use RAUC, another SWUpdate, and another a completely custom implementation.
+
+The implementation details may differ.
+
+The underlying engineering principles usually do not.
+
+---
+
+## Practical Examples
+
+Where possible, theoretical discussions are accompanied by practical material, including:
+
+- architecture diagrams
+- boot sequence walkthroughs
+- storage layout examples
+- failure scenarios
+- Raspberry Pi demonstrations
+- QEMU-based experiments
+- implementation notes
+
+The objective is to connect high-level architecture with practical implementation.
+
+---
+
+## Intended Audience
+
+This repository is intended for:
+
+- Embedded Linux developers
+- Firmware engineers
+- Embedded software engineers
+- System architects
+- Students learning embedded systems
+- Engineers preparing for technical interviews
+- Anyone interested in understanding OTA system design
+
+No prior experience with OTA frameworks is assumed.
+
+---
+
+## How to Read This Repository
+
+If you are new to OTA systems, simply start with Chapter 1 and continue in order.
+
+If you already have embedded Linux experience, feel free to jump directly to topics that interest you.
+
+If you are looking for implementation details, the accompanying examples provide practical demonstrations of the concepts discussed in the documentation.
+
+---
+
+## OTA at a Glance
+
+The following diagram illustrates the overall update lifecycle that will be explored throughout this repository.
+
+```text
+                 OTA Server
+                      │
+               Signed Update
+                      │
+          ┌───────────▼───────────┐
+          │   Download Manager    │
+          └───────────┬───────────┘
+                      │
+              Verify Signature
+                      │
+              Verify Integrity
+                      │
+                Install Update
+                      │
+               Mark Boot Target
+                      │
+                Reboot Device
+                      │
+             Bootloader Decision
+             ┌─────────┴─────────┐
+             │                   │
+        Boot Success        Boot Failure
+             │                   │
+             ▼                   ▼
+         Commit Update      Rollback
+```
+
+Each stage of this process will be examined in detail in the chapters that follow.
+
+---
+
+## Contributing
+
+Contributions, suggestions, and discussions are welcome.
+
+If you have ideas for improvements, additional examples, or alternative approaches, feel free to open an issue or submit a pull request.
+
+---
+
+## License
+
+This repository is released under the MIT License.
+
+See the LICENSE file for details.

docs/01-what-is-an-ota-update.md

@@ -0,0 +1,227 @@
+# What Is an OTA Update?
+
+> **Series:** OTA Reference Design
+>
+> This article is the first chapter of a practical reference design describing how reliable and secure over-the-air software updates are built for embedded Linux devices.
+
+---
+
+# Introduction
+
+Almost every modern connected device receives software updates remotely.
+
+Phones do it.
+
+Cars do it.
+
+Industrial controllers do it.
+
+Medical devices do it.
+
+Consumer electronics quietly update themselves while nobody is watching.
+
+This process is commonly known as an **Over-the-Air (OTA) update**.
+
+At first glance, the idea seems simple:
+
+> Download new software and install it.
+
+In reality, OTA is one of the most challenging reliability problems in embedded systems.
+
+---
+
+# Why OTA Is Different
+
+Updating software on a desktop computer is usually forgiving.
+
+If something goes wrong, the user can often retry the installation, download the package again, or reinstall the operating system.
+
+Embedded devices rarely have that luxury.
+
+Imagine a device installed:
+
+- on the roof of a building;
+- inside industrial equipment;
+- on a remote oil pipeline;
+- in a laboratory instrument;
+- in an autonomous vehicle.
+
+A failed update may leave the device completely unreachable.
+
+Nobody may be available to reconnect a keyboard, attach a monitor, or reflash storage.
+
+For embedded systems, software updates must be designed with failure as an expected condition rather than an exceptional one.
+
+---
+
+# The Real Problem
+
+The primary goal of an OTA system is surprisingly simple:
+
+> **Replace the software while always preserving a path to recovery.**
+
+Everything else exists to support this objective.
+
+Notice that this definition says nothing about how the update is delivered or installed.
+
+The engineering problem remains the same regardless of the implementation.
+
+---
+
+# Many Ways to Solve the Same Problem
+
+Different products solve OTA updates in different ways.
+
+An update may be based on:
+
+- complete system images;
+- software packages;
+- application bundles;
+- containers;
+- custom update formats.
+
+These are implementation choices.
+
+Each approach has its own strengths, weaknesses, and trade-offs.
+
+Throughout this series we will explore these options and discuss where each of them makes sense.
+
+---
+
+# Typical Failure Scenarios
+
+A robust OTA implementation assumes that failures are inevitable.
+
+Examples include:
+
+- power loss during installation;
+- interrupted network connection;
+- corrupted download;
+- damaged storage;
+- software crash during the first boot;
+- incompatible configuration;
+- interrupted filesystem writes;
+- unexpected reboot.
+
+None of these situations is unusual.
+
+If enough devices are deployed, every one of them will eventually happen.
+
+The question is never **if**.
+
+Only **when**.
+
+---
+
+# OTA Is a System, Not a Feature
+
+OTA is often imagined as a single application responsible for installing updates.
+
+In practice, it is an entire system composed of multiple cooperating components.
+
+A typical embedded Linux solution may include:
+
+- bootloader;
+- Linux kernel;
+- root filesystem;
+- update agent;
+- storage layout;
+- cryptographic verification;
+- backend services;
+- device identity;
+- rollback mechanism;
+- health monitoring.
+
+Each component has a specific responsibility.
+
+Only together do they provide a reliable update process.
+
+---
+
+# A Better Mental Model
+
+Instead of thinking:
+
+```
+download
+    ↓
+install
+```
+
+think:
+
+```
+prepare
+    ↓
+verify
+    ↓
+store safely
+    ↓
+activate
+    ↓
+boot
+    ↓
+health check
+    ↓
+commit
+      │
+      └── rollback if necessary
+```
+
+Almost every production OTA solution follows some variation of this workflow.
+
+The individual technologies may differ.
+
+The underlying principles remain remarkably similar.
+
+---
+
+# What This Series Covers
+
+Rather than focusing on a particular framework or vendor, this repository explains the engineering principles behind reliable OTA systems.
+
+Topics include:
+
+- OTA architectures;
+- update strategies;
+- boot process;
+- storage layouts;
+- A/B partitioning;
+- rollback mechanisms;
+- image verification;
+- cryptographic signatures;
+- update servers;
+- recovery strategies;
+- production considerations.
+
+Examples will use embedded Linux running on Raspberry Pi, but the concepts apply to many embedded platforms.
+
+---
+
+# Summary
+
+OTA updates are often described as "remote software updates."
+
+While technically correct, this definition misses the real engineering challenge.
+
+The true objective is ensuring that **the device remains recoverable after every possible failure during the update process.**
+
+Everything else—from storage layouts to cryptographic signatures—exists to support that goal.
+
+---
+
+## Key Takeaways
+
+- OTA is fundamentally a reliability problem.
+- Failures must be expected, not treated as exceptions.
+- Multiple implementation strategies exist for OTA systems.
+- The core objective is always safe recovery.
+- Technologies change, but the engineering principles remain the same.
+
+---
+
+## Next Article
+
+The next chapter explores the first major architectural decision in any OTA system:
+
+> **Update Strategies: Full Images, Packages, or Something Else?**

readme.md

@@ -1,5 +1,28 @@
 # ota-reference-design
 
-A practical reference design for reliable and secure over-the-air updates on embedded Linux
+A practical reference design for reliable and secure over-the-air updates on embedded Linux.
 
-This repository is intended as an educational reference design. It demonstrates one possible approach to building a reliable OTA update system for embedded Linux. It is not intended to be a production-ready framework.
+This repository is intended as an educational reference design. It demonstrates one possible approach to designing and implementing a reliable OTA update system for embedded Linux.
+
+The project focuses on the engineering decisions behind OTA systems, including:
+
+* update strategies;
+* system and storage architecture;
+* bootloader interaction;
+* atomic updates;
+* rollback and recovery;
+* integrity verification and signing;
+* testing and failure handling.
+
+It is not tied to a specific OTA framework, hardware platform, or cloud provider.
+
+Raspberry Pi may be used for practical demonstrations, but the underlying concepts are applicable to a broader range of embedded Linux devices.
+
+This repository is not intended to be a production-ready framework. Instead, it is designed to explain the architectural principles, trade-offs, and failure scenarios that should be considered when building a real OTA system.
+
+The repository is being developed incrementally as a structured series of articles, diagrams, architecture decisions, and practical examples.
+
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.