cleanup

2026-01-26 12:49:12 +01:00
parent bedcd373f5
commit ff791564e4
243 changed files with 18986 additions and 0 deletions
--- a/draft/System_State_Machine_Specification.md
+++ b/draft/System_State_Machine_Specification.md
@@ -0,0 +1,314 @@
+# System State Machine Specification
+
+**Document Type:** Normative System Specification  
+**Scope:** Sensor Hub (Sub-Hub) Operational States  
+**Traceability:** SR-SYS-001, SR-SYS-002, SR-SYS-003
+
+## 1. Purpose
+
+This document defines the complete finite state machine (FSM) governing the Sensor Hub's operational lifecycle. All system components SHALL respect state-based operation restrictions as defined herein.
+
+## 2. State Definitions
+
+### 2.1 State Enumeration
+
+| State ID | State Name | Description | Entry Condition |
+|----------|------------|-------------|-----------------|
+| `INIT` | Initialization | Hardware and software initialization phase | Power-on, reset, or post-teardown |
+| `BOOT_FAILURE` | Boot Failure | Secure boot verification failed | Secure boot check failure during INIT |
+| `RUNNING` | Normal Operation | Active sensor acquisition and communication | Successful initialization |
+| `WARNING` | Degraded Operation | Non-fatal fault detected, degraded functionality | Non-critical fault detected during RUNNING |
+| `FAULT` | Fatal Error | Critical fault, core functionality disabled | Fatal error or cascading failures |
+| `OTA_PREP` | OTA Preparation | Preparing for firmware update | OTA request accepted, validation pending |
+| `OTA_UPDATE` | OTA Update Active | Firmware update in progress | Firmware transfer and flashing |
+| `MC_UPDATE` | Machine Constants Update | Machine constants update in progress | MC update request accepted |
+| `TEARDOWN` | Controlled Shutdown | Safe shutdown sequence execution | Update, fault recovery, or manual command |
+| `SERVICE` | Service Mode | Engineering/diagnostic interaction | Debug session active |
+| `SD_DEGRADED` | SD Card Degraded | SD card failure detected, fallback mode | SD card access failure |
+
+### 2.2 State Characteristics
+
+#### INIT
+- **Duration:** Bounded (max 5 seconds)
+- **Allowed Operations:** Hardware initialization, secure boot verification, MC loading
+- **Forbidden Operations:** Sensor acquisition, communication, persistence writes
+- **Exit Conditions:** Success → RUNNING, Secure boot failure → BOOT_FAILURE
+
+#### BOOT_FAILURE
+- **Duration:** Indefinite (requires manual intervention)
+- **Allowed Operations:** Diagnostic reporting, secure boot retry (limited)
+- **Forbidden Operations:** All application features
+- **Exit Conditions:** Manual reset, secure boot success → INIT
+
+#### RUNNING
+- **Duration:** Indefinite (normal operation)
+- **Allowed Operations:** All features (DAQ, DQC, COM, DIAG, DATA, HMI)
+- **Forbidden Operations:** OTA, MC update (must transition via TEARDOWN)
+- **Exit Conditions:** Fault → WARNING/FAULT, OTA request → OTA_PREP, MC update → MC_UPDATE, Debug session → SERVICE
+
+#### WARNING
+- **Duration:** Until fault cleared or escalated
+- **Allowed Operations:** Degraded DAQ, COM, DIAG (limited), DATA (read-only)
+- **Forbidden Operations:** OTA, MC update
+- **Exit Conditions:** Fault cleared → RUNNING, Fault escalated → FAULT
+
+#### FAULT
+- **Duration:** Until recovery attempt or manual intervention
+- **Allowed Operations:** Diagnostic reporting, error logging, controlled teardown
+- **Forbidden Operations:** Sensor acquisition, communication (except diagnostics)
+- **Exit Conditions:** Recovery attempt → TEARDOWN, Manual reset → INIT
+
+#### OTA_PREP
+- **Duration:** Bounded (max 2 seconds)
+- **Allowed Operations:** OTA readiness validation, teardown initiation
+- **Forbidden Operations:** Sensor acquisition, new communication sessions
+- **Exit Conditions:** Ready → TEARDOWN, Rejected → RUNNING
+
+#### OTA_UPDATE
+- **Duration:** Bounded (max 10 minutes)
+- **Allowed Operations:** Firmware reception, validation, flashing
+- **Forbidden Operations:** Sensor acquisition, normal communication, persistence (except OTA data)
+- **Exit Conditions:** Success → RUNNING (after reboot), Failure → FAULT
+
+#### MC_UPDATE
+- **Duration:** Bounded (max 30 seconds)
+- **Allowed Operations:** MC reception, validation, teardown
+- **Forbidden Operations:** Sensor acquisition, normal communication
+- **Exit Conditions:** Success → TEARDOWN, Failure → RUNNING
+
+#### TEARDOWN
+- **Duration:** Bounded (max 500ms)
+- **Allowed Operations:** Data flush, resource release, state persistence
+- **Forbidden Operations:** New sensor acquisition, new communication sessions
+- **Exit Conditions:** Complete → INIT (reset), OTA → OTA_UPDATE, MC → MC_UPDATE
+
+#### SERVICE
+- **Duration:** Until session closed
+- **Allowed Operations:** Diagnostic access, read-only inspection, controlled commands
+- **Forbidden Operations:** Sensor acquisition (may be paused), OTA, MC update
+- **Exit Conditions:** Session closed → RUNNING
+
+#### SD_DEGRADED
+- **Duration:** Until SD recovery or manual intervention
+- **Allowed Operations:** Sensor acquisition (no persistence), communication, diagnostics
+- **Forbidden Operations:** Persistence writes (except critical diagnostics)
+- **Exit Conditions:** SD recovery → RUNNING, Manual intervention → SERVICE
+
+## 3. State Transition Table
+
+| From State | To State | Trigger | Guard Condition | Action | Authorized Caller |
+|------------|----------|---------|-----------------|--------|------------------|
+| `[*]` | `INIT` | Power-on, Reset | None | Initialize hardware, secure boot check | System |
+| `INIT` | `RUNNING` | Init success | Secure boot OK, MC loaded, sensors detected | Start DAQ, COM, DIAG tasks | System Manager |
+| `INIT` | `BOOT_FAILURE` | Secure boot fail | Secure boot verification failed | Log security fault, disable application | Secure Boot |
+| `BOOT_FAILURE` | `INIT` | Manual reset | None | Reset system | User/Engineer |
+| `RUNNING` | `WARNING` | Non-fatal fault | Diagnostic severity = WARNING | Degrade functionality, notify | Error Handler |
+| `RUNNING` | `FAULT` | Fatal fault | Diagnostic severity = FATAL | Stop critical features | Error Handler |
+| `RUNNING` | `OTA_PREP` | OTA request | OTA request received, system ready | Validate readiness | OTA Manager |
+| `RUNNING` | `MC_UPDATE` | MC update request | MC update received, authenticated | Validate MC | MC Manager |
+| `RUNNING` | `SERVICE` | Debug session | Debug session authenticated | Pause non-critical tasks | Debug Manager |
+| `RUNNING` | `SD_DEGRADED` | SD failure | SD card access failure detected | Disable persistence writes | Persistence |
+| `WARNING` | `RUNNING` | Fault cleared | Diagnostic cleared, system healthy | Restore full functionality | Error Handler |
+| `WARNING` | `FAULT` | Fault escalated | Multiple warnings or critical fault | Stop degraded features | Error Handler |
+| `FAULT` | `TEARDOWN` | Recovery attempt | Recovery command received | Initiate controlled shutdown | System Manager |
+| `OTA_PREP` | `TEARDOWN` | OTA ready | Readiness validated | Begin teardown | OTA Manager |
+| `OTA_PREP` | `RUNNING` | OTA rejected | Readiness check failed | Resume normal operation | OTA Manager |
+| `TEARDOWN` | `OTA_UPDATE` | Teardown complete (OTA) | OTA pending, data flushed | Enter OTA state | System Manager |
+| `TEARDOWN` | `MC_UPDATE` | Teardown complete (MC) | MC update pending, data flushed | Enter MC update | System Manager |
+| `TEARDOWN` | `INIT` | Teardown complete (reset) | Reset requested, data flushed | Reset system | System Manager |
+| `OTA_UPDATE` | `RUNNING` | OTA success | Firmware flashed, validated | Reboot into new firmware | OTA Manager |
+| `OTA_UPDATE` | `FAULT` | OTA failure | Firmware validation failed | Log error, enter fault | OTA Manager |
+| `MC_UPDATE` | `TEARDOWN` | MC update complete | MC validated, applied | Reinitialize system | MC Manager |
+| `SERVICE` | `RUNNING` | Session closed | Debug session terminated | Resume normal operation | Debug Manager |
+| `SD_DEGRADED` | `RUNNING` | SD recovered | SD card access restored | Re-enable persistence | Persistence |
+| `SD_DEGRADED` | `SERVICE` | Manual intervention | User intervention required | Enter service mode | User/Engineer |
+
+## 4. Per-State Feature Execution Rules
+
+### 4.1 DAQ (Data Acquisition) Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | None | Sensor initialization only |
+| `RUNNING` | Full acquisition cycle | None |
+| `WARNING` | Degraded acquisition (reduced frequency) | Failed sensors excluded |
+| `FAULT` | None | Acquisition stopped |
+| `OTA_PREP` | None | Acquisition stopped |
+| `OTA_UPDATE` | None | Acquisition stopped |
+| `MC_UPDATE` | None | Acquisition stopped |
+| `TEARDOWN` | None | Acquisition stopped |
+| `SERVICE` | Paused (optional read-only) | No new samples |
+| `SD_DEGRADED` | Full acquisition | Data not persisted |
+| `BOOT_FAILURE` | None | Not applicable |
+
+### 4.2 DQC (Data Quality & Calibration) Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | Sensor detection, MC loading | No calibration |
+| `RUNNING` | Full quality checks, calibration | None |
+| `WARNING` | Degraded quality checks | Reduced validation |
+| `FAULT` | Error reporting only | No quality checks |
+| `OTA_PREP` | None | Quality checks stopped |
+| `OTA_UPDATE` | None | Quality checks stopped |
+| `MC_UPDATE` | MC validation only | No sensor calibration |
+| `TEARDOWN` | None | Quality checks stopped |
+| `SERVICE` | Read-only inspection | No calibration |
+| `SD_DEGRADED` | Full quality checks | Results not persisted |
+| `BOOT_FAILURE` | None | Not applicable |
+
+### 4.3 COM (Communication) Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | None | No communication |
+| `RUNNING` | Full bidirectional communication | None |
+| `WARNING` | Limited communication (diagnostics only) | Reduced bandwidth |
+| `FAULT` | Diagnostic reporting only | No data transmission |
+| `OTA_PREP` | OTA negotiation only | No other communication |
+| `OTA_UPDATE` | OTA data transfer only | No other communication |
+| `MC_UPDATE` | MC transfer only | No other communication |
+| `TEARDOWN` | Session closure only | No new sessions |
+| `SERVICE` | Debug session communication | No Main Hub communication |
+| `SD_DEGRADED` | Full communication | Data not persisted |
+| `BOOT_FAILURE` | Diagnostic reporting only | Limited communication |
+
+### 4.4 DIAG (Diagnostics) Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | Boot diagnostics | Limited logging |
+| `RUNNING` | Full diagnostics | None |
+| `WARNING` | Full diagnostics | None |
+| `FAULT` | Full diagnostics | None |
+| `OTA_PREP` | OTA diagnostics | Limited scope |
+| `OTA_UPDATE` | OTA progress diagnostics | Limited scope |
+| `MC_UPDATE` | MC update diagnostics | Limited scope |
+| `TEARDOWN` | Teardown diagnostics | Limited scope |
+| `SERVICE` | Full diagnostics (read access) | No new diagnostics |
+| `SD_DEGRADED` | Full diagnostics | Persistence limited |
+| `BOOT_FAILURE` | Security diagnostics | Limited scope |
+
+### 4.5 DATA (Persistence) Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | MC loading only | No writes |
+| `RUNNING` | Full persistence | None |
+| `WARNING` | Read-only, critical writes | Limited writes |
+| `FAULT` | Critical diagnostics only | No sensor data writes |
+| `OTA_PREP` | Read-only | No writes |
+| `OTA_UPDATE` | OTA data only | No sensor data writes |
+| `MC_UPDATE` | MC writes only | No sensor data writes |
+| `TEARDOWN` | Critical data flush only | Authorized writes only |
+| `SERVICE` | Read-only | No writes |
+| `SD_DEGRADED` | Read-only (if possible) | No writes |
+| `BOOT_FAILURE` | None | Not applicable |
+
+### 4.6 OTA Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | None | OTA not active |
+| `RUNNING` | OTA negotiation only | No transfer |
+| `WARNING` | None | OTA blocked |
+| `FAULT` | None | OTA blocked |
+| `OTA_PREP` | Readiness validation | No transfer |
+| `OTA_UPDATE` | Full OTA operations | None |
+| `MC_UPDATE` | None | OTA blocked |
+| `TEARDOWN` | None | OTA blocked |
+| `SERVICE` | None | OTA blocked |
+| `SD_DEGRADED` | None | OTA blocked |
+| `BOOT_FAILURE` | None | OTA blocked |
+
+### 4.7 SEC (Security) Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | Secure boot verification | Must complete before app start |
+| `RUNNING` | Full security (encryption, authentication) | None |
+| `WARNING` | Full security | None |
+| `FAULT` | Security diagnostics | Limited operations |
+| `OTA_PREP` | OTA authentication | None |
+| `OTA_UPDATE` | Firmware verification | None |
+| `MC_UPDATE` | MC authentication | None |
+| `TEARDOWN` | Key protection | None |
+| `SERVICE` | Debug authentication | None |
+| `SD_DEGRADED` | Full security | None |
+| `BOOT_FAILURE` | Security fault handling | Limited operations |
+
+### 4.8 SYS (System Management) Feature
+
+| State | Allowed Operations | Restrictions |
+|-------|-------------------|--------------|
+| `INIT` | State management, initialization | Limited operations |
+| `RUNNING` | Full system management | None |
+| `WARNING` | Degraded management | Limited operations |
+| `FAULT` | Fault recovery management | Limited operations |
+| `OTA_PREP` | OTA state management | Limited operations |
+| `OTA_UPDATE` | OTA state management | Limited operations |
+| `MC_UPDATE` | MC state management | Limited operations |
+| `TEARDOWN` | Teardown execution | Limited operations |
+| `SERVICE` | Service mode management | Limited operations |
+| `SD_DEGRADED` | Degraded management | Limited operations |
+| `BOOT_FAILURE` | Boot failure management | Limited operations |
+
+## 5. State Transition Timing Requirements
+
+| Transition | Maximum Duration | Justification |
+|------------|------------------|---------------|
+| `[*]` → `INIT` | 100ms | Power-on initialization |
+| `INIT` → `RUNNING` | 5s | Hardware init, secure boot, MC load |
+| `INIT` → `BOOT_FAILURE` | 2s | Secure boot verification |
+| `RUNNING` → `WARNING` | 50ms | Fault detection and state change |
+| `RUNNING` → `FAULT` | 50ms | Critical fault detection |
+| `RUNNING` → `OTA_PREP` | 100ms | OTA request processing |
+| `OTA_PREP` → `TEARDOWN` | 2s | Readiness validation |
+| `TEARDOWN` → `OTA_UPDATE` | 500ms | Data flush and resource release |
+| `TEARDOWN` → `INIT` | 500ms | Data flush and reset |
+| `OTA_UPDATE` → `RUNNING` | 10 minutes | Firmware transfer and flashing |
+| `RUNNING` → `SERVICE` | 100ms | Debug session establishment |
+| `SERVICE` → `RUNNING` | 50ms | Debug session closure |
+
+## 6. State Notification Mechanism
+
+All state transitions SHALL notify registered components via the Event System:
+- **Event Type:** `SYSTEM_STATE_CHANGED`
+- **Payload:** Previous state, new state, transition reason
+- **Subscribers:** All feature managers (DAQ, DQC, COM, DIAG, DATA, OTA, SEC, SYS)
+
+## 7. Traceability
+
+- **SR-SYS-001:** Implemented via complete FSM definition
+- **SR-SYS-002:** Implemented via per-state feature execution rules
+- **SR-SYS-003:** Implemented via state notification mechanism
+
+## 8. Mermaid State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> INIT
+    INIT --> RUNNING: initSuccess
+    INIT --> BOOT_FAILURE: secureBootFail
+    BOOT_FAILURE --> INIT: manualReset
+    RUNNING --> WARNING: nonFatalFault
+    RUNNING --> FAULT: fatalFault
+    RUNNING --> OTA_PREP: otaRequest
+    RUNNING --> MC_UPDATE: mcUpdateRequest
+    RUNNING --> SERVICE: debugSession
+    RUNNING --> SD_DEGRADED: sdFailure
+    WARNING --> RUNNING: faultCleared
+    WARNING --> FAULT: faultEscalated
+    FAULT --> TEARDOWN: recoveryAttempt
+    OTA_PREP --> TEARDOWN: otaReady
+    OTA_PREP --> RUNNING: otaRejected
+    TEARDOWN --> OTA_UPDATE: otaPending
+    TEARDOWN --> MC_UPDATE: mcPending
+    TEARDOWN --> INIT: resetRequested
+    OTA_UPDATE --> RUNNING: otaSuccess
+    OTA_UPDATE --> FAULT: otaFailure
+    MC_UPDATE --> TEARDOWN: mcComplete
+    SERVICE --> RUNNING: sessionClosed
+    SD_DEGRADED --> RUNNING: sdRecovered
+    SD_DEGRADED --> SERVICE: manualIntervention
+```