cleanup sw req

2026-02-01 19:47:53 +01:00
parent 0bdbcb1657
commit 304371c6b8
608 changed files with 47798 additions and 0 deletions
--- a/design/features/SF-OTA_Firmware_Update.md
+++ b/design/features/SF-OTA_Firmware_Update.md
@@ -0,0 +1,289 @@
+# Software Feature Specification
+
+## SF-OTA: Firmware Update (OTA)
+
+**Software Feature ID:** SF-OTA  
+**Mapped System Feature:** F-OTA (Firmware Update Features)  
+**Version:** 1.0  
+**Date:** 2025-02-01  
+
+## 1. Feature Overview
+
+The Firmware Update (OTA) software feature implements secure, reliable over-the-air firmware update capabilities with A/B partitioning and automatic rollback mechanisms. This feature provides the software implementation of OTA update negotiation, firmware reception and storage, integrity validation, safe firmware activation, and rollback protection.
+
+### 1.1 Mapped System Features
+
+- **F-OTA-01**: OTA Update Negotiation
+- **F-OTA-02**: Firmware Reception and Storage
+- **F-OTA-03**: Firmware Integrity Validation
+- **F-OTA-04**: Safe Firmware Activation
+- **F-OTA-05**: A/B Partitioning with Rollback
+
+## 2. Static View - Component Architecture
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        OM[OTA Manager]
+        UN[Update Negotiator]
+        FA[Firmware Activator]
+    end
+    
+    subgraph "OTA Services"
+        FR[Firmware Receiver]
+        IV[Integrity Validator]
+        RM[Rollback Manager]
+        PM[Partition Manager]
+    end
+    
+    subgraph "Storage Layer"
+        FS[Firmware Storage]
+        PS[Partition Service]
+        DP[Data Pool]
+    end
+    
+    subgraph "Security Layer"
+        SB[Secure Boot]
+        FE[Flash Encryption]
+        CV[Certificate Validator]
+    end
+    
+    OM --> UN
+    OM --> FR
+    OM --> IV
+    OM --> FA
+    OM --> RM
+    UN --> PM
+    FR --> FS
+    IV --> CV
+    FA --> PS
+    RM --> PM
+    FS --> DP
+    PS --> SB
+    PS --> FE
+```
+
+### 2.1 Component Interfaces
+
+#### 2.1.1 OTA Manager Interfaces
+
+**Provided Interfaces:**
+- `IOTAManager`: Main OTA management interface
+- `IUpdateController`: Update process control interface
+- `IFirmwareStatus`: Firmware status reporting interface
+
+**Required Interfaces:**
+- `IUpdateNegotiator`: Update negotiation interface
+- `IFirmwareReceiver`: Firmware reception interface
+- `IIntegrityValidator`: Firmware validation interface
+- `ISystemStateManager`: System state control interface
+
+#### 2.1.2 Partition Manager Interfaces
+
+**Provided Interfaces:**
+- `IPartitionManager`: Partition management interface
+- `IBootController`: Boot partition control interface
+- `IRollbackController`: Rollback control interface
+
+**Required Interfaces:**
+- `IPartitionService`: Low-level partition interface
+- `ISecureBoot`: Secure boot interface
+- `IDiagnosticsManager`: Diagnostic reporting interface
+
+## 3. Dynamic View - OTA Update Sequences
+
+### 3.1 OTA Negotiation Sequence
+
+```mermaid
+sequenceDiagram
+    participant MH as Main Hub
+    participant CM as Communication Manager
+    participant OM as OTA Manager
+    participant UN as Update Negotiator
+    participant STM as System State Manager
+    
+    MH->>CM: otaUpdateAvailable(firmware_info)
+    CM->>OM: receiveOTARequest(firmware_info)
+    OM->>UN: negotiateUpdate(firmware_info)
+    UN->>STM: checkSystemReadiness()
+    STM-->>UN: system_status
+    
+    alt System Ready
+        UN->>UN: validateUpdateRequest(firmware_info)
+        UN-->>OM: negotiation_success
+        OM->>STM: transitionToOTAState()
+        OM->>CM: sendOTAAcceptance()
+    else System Not Ready
+        UN-->>OM: negotiation_failed
+        OM->>CM: sendOTARejection(reason)
+    end
+```
+
+### 3.2 Firmware Download and Validation Sequence
+
+```mermaid
+sequenceDiagram
+    participant MH as Main Hub
+    participant FR as Firmware Receiver
+    participant FS as Firmware Storage
+    participant IV as Integrity Validator
+    participant CV as Certificate Validator
+    participant OM as OTA Manager
+    
+    MH->>FR: sendFirmwareChunk(chunk_data, chunk_id)
+    FR->>FS: storeFirmwareChunk(chunk_data, chunk_id)
+    FS-->>FR: storage_result
+    
+    loop Until all chunks received
+        MH->>FR: sendFirmwareChunk(chunk_data, chunk_id)
+        FR->>FS: storeFirmwareChunk(chunk_data, chunk_id)
+    end
+    
+    FR->>IV: validateFirmwareIntegrity()
+    IV->>FS: calculateSHA256Hash()
+    FS-->>IV: calculated_hash
+    IV->>IV: compareWithExpectedHash()
+    IV->>CV: validateFirmwareSignature()
+    CV-->>IV: signature_valid
+    
+    alt Validation Success
+        IV-->>OM: firmware_validated
+    else Validation Failed
+        IV-->>OM: validation_failed
+        OM->>FS: deleteFirmwareImage()
+    end
+```
+
+### 3.3 Firmware Activation and Rollback Sequence
+
+```mermaid
+sequenceDiagram
+    participant OM as OTA Manager
+    participant FA as Firmware Activator
+    participant PM as Partition Manager
+    participant STM as System State Manager
+    participant RM as Rollback Manager
+    
+    OM->>FA: activateFirmware()
+    FA->>STM: initiateTeardown()
+    STM-->>FA: teardown_complete
+    FA->>PM: flashFirmwareToInactivePartition()
+    PM-->>FA: flash_complete
+    FA->>PM: setBootPartition(inactive_partition)
+    PM-->>FA: boot_partition_set
+    FA->>FA: rebootSystem()
+    
+    Note over FA: System Reboots
+    
+    alt Boot Success
+        FA->>FA: sendHealthReport()
+        FA->>RM: confirmFirmwareStability()
+        RM->>PM: markPartitionValid()
+    else Boot Failure or No Health Report
+        RM->>PM: rollbackToPreviousPartition()
+        PM->>PM: setBootPartition(previous_partition)
+        PM->>PM: rebootSystem()
+        Note over PM: System Reboots to Previous Firmware
+    end
+```
+
+## 4. Software Constraints
+
+### 4.1 Performance Constraints
+- **SWC-OTA-001**: OTA negotiation must complete within 30 seconds
+- **SWC-OTA-002**: Firmware download must support minimum 10KB/s transfer rate
+- **SWC-OTA-003**: Firmware validation must complete within 60 seconds
+- **SWC-OTA-004**: Total OTA process must complete within 10 minutes
+
+### 4.2 Resource Constraints
+- **SWC-OTA-005**: Firmware storage limited to available SD card space (minimum 4MB)
+- **SWC-OTA-006**: OTA process memory usage limited to 64KB
+- **SWC-OTA-007**: Chunk size optimized at 4KB for flash page alignment
+
+### 4.3 Security Constraints
+- **SWC-OTA-008**: All firmware images must be cryptographically signed
+- **SWC-OTA-009**: SHA-256 integrity verification required for all firmware
+- **SWC-OTA-010**: Secure boot verification must be enforced after activation
+
+### 4.4 Reliability Constraints
+- **SWC-OTA-011**: OTA process must not corrupt existing firmware
+- **SWC-OTA-012**: Automatic rollback required on boot failure
+- **SWC-OTA-013**: Critical data must be preserved during OTA process
+
+## 5. Traceability Matrix - Software Requirements
+
+| Software Requirement ID | Feature Mapping | Component | Verification Method |
+|-------------------------|-----------------|-----------|-------------------|
+| SWR-OTA-001 | F-OTA-01 | Update Negotiator | Integration Test |
+| SWR-OTA-002 | F-OTA-01 | Update Negotiator | Unit Test |
+| SWR-OTA-003 | F-OTA-01 | OTA Manager | Unit Test |
+| SWR-OTA-004 | F-OTA-02 | Firmware Receiver | Integration Test |
+| SWR-OTA-005 | F-OTA-02 | Firmware Storage | Unit Test |
+| SWR-OTA-006 | F-OTA-02 | Partition Manager | Unit Test |
+| SWR-OTA-007 | F-OTA-03 | Integrity Validator | Unit Test |
+| SWR-OTA-008 | F-OTA-03 | Integrity Validator | Security Test |
+| SWR-OTA-009 | F-OTA-03 | OTA Manager | Integration Test |
+| SWR-OTA-010 | F-OTA-04 | Firmware Activator | Integration Test |
+| SWR-OTA-011 | F-OTA-04 | Firmware Activator | Unit Test |
+| SWR-OTA-012 | F-OTA-04 | Firmware Activator | Unit Test |
+| SWR-OTA-013 | F-OTA-04 | Firmware Activator | Integration Test |
+| SWR-OTA-014 | F-OTA-05 | Partition Manager | Hardware Test |
+| SWR-OTA-015 | F-OTA-05 | Rollback Manager | Integration Test |
+| SWR-OTA-016 | F-OTA-05 | Rollback Manager | Unit Test |
+
+## 6. Implementation Notes
+
+### 6.1 A/B Partitioning Architecture
+- Two OTA partitions: ota_0 (3.5MB) and ota_1 (3.5MB)
+- Active partition runs current firmware
+- Inactive partition receives new firmware
+- Boot partition selection via partition table update
+- Automatic rollback on boot failure or health check timeout
+
+### 6.2 OTA Negotiation Process
+- System readiness validation: power, storage, communication, state
+- Firmware compatibility verification: hardware, version, dependencies
+- Resource availability check: storage space, memory, processing capacity
+- Security validation: certificate chain, signature verification
+
+### 6.3 Firmware Reception and Storage
+- Chunked download with 4KB chunks for optimal flash performance
+- Temporary storage on SD card before flashing to partition
+- Progress tracking and resume capability for interrupted downloads
+- Integrity verification during download process
+
+### 6.4 Security Implementation
+- RSA-3072 or ECDSA-P256 signature verification
+- SHA-256 hash validation for firmware integrity
+- Secure Boot V2 enforcement after activation
+- Certificate chain validation for firmware authenticity
+- Anti-rollback protection via eFuse version tracking
+
+### 6.5 Rollback Mechanisms
+- Automatic rollback triggers:
+  - Boot failure after firmware activation
+  - No health report within 60-120 seconds
+  - Application crash during confirmation period
+  - Manual rollback command from Main Hub
+- Rollback process preserves user data and configuration
+- Rollback events logged for analysis and debugging
+
+### 6.6 Data Preservation
+- Controlled teardown before firmware activation
+- Critical data persistence: Machine Constants, calibration, diagnostics
+- Configuration migration between firmware versions
+- User data protection during OTA process
+
+### 6.7 Error Handling
+- OTA negotiation failures logged and reported
+- Download interruption recovery with resume capability
+- Validation failures trigger cleanup and rejection
+- Activation failures trigger automatic rollback
+- Rollback failures escalated as critical system errors
+
+### 6.8 Monitoring and Diagnostics
+- OTA process progress reporting to Main Hub
+- Detailed logging of all OTA operations
+- Performance metrics collection: download speed, validation time
+- Error classification and root cause analysis
+- Health monitoring during firmware confirmation period