diagrams and simulation

diagrams/plantuml/ab-storage-layout.puml

@@ -0,0 +1,43 @@
+@startuml
+title A/B storage: logical areas and access responsibilities
+left to right direction
+skinparam shadowing false
+skinparam monochrome true
+
+actor "Installer" as installer
+actor "Boot control" as boot
+actor "OTA manager /\nconfirmation program" as manager
+actor "Running system\nand applications" as runtime
+
+rectangle "Device storage (logical areas, not a partition table)" {
+  rectangle "Shared boot components\nSeparate update and recovery method" as shared
+  database "Boot state\nNormal slot, trial target, attempts, confirmation" as state
+  rectangle "Slot A: retained system\nKernel + device tree + root filesystem" as A
+  rectangle "Slot B: update target\nKernel + device tree + root filesystem" as B
+  database "Persistent device data" as data {
+    rectangle "Identity and calibration\nRestricted access" as identity
+    rectangle "Configuration and application data\nMust support the retained version" as appdata
+    rectangle "OTA progress, failure blocks\nand pending reports" as progress
+  }
+  rectangle "Download and work area\nDisposable preparation files" as work
+}
+
+installer --> B : replace inactive slot
+installer --> work : use temporary files
+boot --> shared : execute
+boot --> state : read / save before Linux starts
+boot --> A : select matching components
+boot --> B : select matching components
+manager --> state : request trial / confirm\nthrough platform interface
+manager --> progress : read / save
+runtime --> appdata : read / write
+runtime --> identity : authorized access only
+
+legend bottom
+  A is running while B is prepared. Preserve A, boot state and device data.
+  Persistent device data survives replacement of either system slot.
+  Shared data is not rolled back by selecting A.
+  Both system versions must understand the recovery records they read.
+  Separate logical areas do not guarantee safe writes or whole-device recovery.
+endlegend
+@enduml

diagrams/plantuml/ab-trial-boot.puml

@@ -0,0 +1,52 @@
+@startuml
+title A/B trial boot and recovery
+skinparam shadowing false
+skinparam monochrome true
+
+state "A confirmed" as A
+state "Prepare B\nA remains the normal boot choice" as Preparing
+state "B prepared and verified" as Prepared
+state "B trial pending\nSaved target and attempt limit" as Pending
+state "B trial running\nUnconfirmed" as Trial
+state "B confirmed" as Confirmed
+state "Recovery to A pending" as Recovering
+state "A recovery running" as Recovery
+state "A recovery checked" as Recovered
+state "Separate recovery required" as Failed
+
+[*] --> A
+A --> Preparing : begin installation
+Preparing --> Preparing : reset during preparation; boot A\nB is not eligible for trial
+Preparing --> A : abandon incomplete or failed preparation
+Preparing --> Prepared : installation and verification complete
+Prepared --> Pending : save trial request through boot control
+Pending --> Trial : reset [attempts left > 0]; save attempts left - 1\nbefore handing control to B
+Trial --> Confirmed : local checks pass within time limit;\nsave confirmation
+Trial --> Recovering : local checks fail; save recovery request
+Trial --> Pending : reset before confirmation\n(power loss or covered watchdog)
+Pending --> Recovering : reset; no attempts left
+Recovering --> Recovery : boot control selects A on reset
+Recovery --> Recovered : local recovery checks pass;\nsave outcome
+Recovery --> Failed : recovery checks fail or startup fails\n(platform recovery policy)
+Confirmed --> [*]
+Recovered --> [*]
+Failed --> [*]
+
+note right of Pending
+  Boot state is outside A and B.
+  Attempts are consumed before starting B.
+  Invalid records require a platform-defined
+  recovery path, never implicit confirmation.
+end note
+
+note right of Recovery
+  A must still be compatible with shared data.
+  Do not endlessly alternate failed systems.
+end note
+
+legend bottom
+  Preparation interruption assumes the installer preserves A and boot state.
+  State transitions assume valid durable records; torn writes need platform testing.
+  Checks and recovery are local; reports wait for connectivity.
+endlegend
+@enduml

diagrams/plantuml/ota-architecture.puml

@@ -0,0 +1,38 @@
+@startuml
+title OTA roles and device boundary
+left to right direction
+skinparam shadowing false
+skinparam monochrome true
+skinparam packageStyle rectangle
+
+package "Release and deployment services" {
+  component "Build, test and publish" as release
+  component "Artifact storage" as artifacts
+  component "Deployment management" as deployment
+}
+
+package "Device" {
+  component "OTA manager" as manager
+  component "Installer" as installer
+  component "Boot control" as boot
+  component "Local health checks" as checks
+  database "Persistent update progress\nand pending reports" as progress
+}
+
+release --> artifacts : publish artifact and\nverification information
+release --> deployment : register release and compatibility
+manager --> deployment
+manager --> installer : authorize preparation
+installer --> artifacts : download and verify
+manager --> boot : request trial through\nplatform interface
+checks --> boot : confirm after local checks pass\nor request recovery after failure
+manager --> progress : save / resume progress;\nqueue reports while offline
+manager --> checks : arrange checks after activation
+
+legend bottom
+  OTA manager -> deployment management: request releases; report running version and outcome.
+  Boot control runs before the OTA manager and handles exhausted trial attempts.
+  Hangs need a covered reset path. Checks and recovery do not require the server.
+  Roles may be combined in one tool. This view uses a system update with trial boot.
+endlegend
+@enduml