components

2026-02-01 23:37:00 +01:00
parent 304371c6b8
commit 80236fa840
11 changed files with 5501 additions and 0 deletions
--- a/design/components/ota_manager/COMPONENT.md
+++ b/design/components/ota_manager/COMPONENT.md
@@ -0,0 +1,618 @@
+# OTA Manager Component Specification
+
+**Component ID:** C-OTA-001  
+**Component Name:** OTA Manager  
+**Version:** 1.0  
+**Date:** 2025-02-01  
+
+## 1. Component Overview
+
+### 1.1 Purpose
+The OTA Manager is responsible for managing over-the-air firmware updates with A/B partitioning and automatic rollback capabilities. It provides secure, reliable firmware update functionality while ensuring system availability and data integrity throughout the update process.
+
+### 1.2 Scope
+- OTA update negotiation and readiness validation
+- Secure firmware reception and temporary storage
+- Firmware integrity validation and verification
+- Safe firmware activation with controlled teardown
+- A/B partitioning management with automatic rollback
+- Update status reporting and error handling
+
+### 1.3 Responsibilities
+- Negotiate OTA updates with Main Hub
+- Validate system readiness for firmware updates
+- Receive and store firmware images securely
+- Verify firmware integrity using cryptographic methods
+- Manage A/B partition switching and boot control
+- Implement automatic rollback on update failures
+- Coordinate with system teardown and reinitialization
+- Report update status and results to Main Hub
+
+## 2. Component Architecture
+
+### 2.1 Static View
+
+```mermaid
+graph TB
+    subgraph "OTA Manager"
+        OM[OTA Controller]
+        UN[Update Negotiator]
+        FR[Firmware Receiver]
+        IV[Integrity Validator]
+        FA[Firmware Activator]
+        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]
+        CM[Crypto Manager]
+    end
+    
+    OM --> UN
+    OM --> FR
+    OM --> IV
+    OM --> FA
+    OM --> RM
+    OM --> PM
+    
+    FR --> FS
+    IV --> CV
+    IV --> CM
+    FA --> PS
+    RM --> PM
+    FS --> DP
+    PS --> SB
+    PS --> FE
+```
+
+### 2.2 Internal Components
+
+#### 2.2.1 OTA Controller
+- Central coordination of OTA operations
+- State management for update process
+- Error handling and recovery coordination
+
+#### 2.2.2 Update Negotiator
+- OTA update negotiation with Main Hub
+- System readiness validation
+- Update acceptance/rejection logic
+
+#### 2.2.3 Firmware Receiver
+- Secure firmware image reception
+- Chunked download management
+- Progress tracking and resume capability
+
+#### 2.2.4 Integrity Validator
+- Firmware integrity verification
+- Cryptographic signature validation
+- Metadata and compatibility checking
+
+#### 2.2.5 Firmware Activator
+- Controlled firmware activation process
+- System teardown coordination
+- Boot partition management
+
+#### 2.2.6 Rollback Manager
+- Automatic rollback detection and execution
+- Boot failure recovery
+- Rollback status reporting
+
+#### 2.2.7 Partition Manager
+- A/B partition management
+- Boot partition selection
+- Partition health monitoring
+
+## 3. Interfaces
+
+### 3.1 Provided Interfaces
+
+#### 3.1.1 IOTAManager
+```cpp
+class IOTAManager {
+public:
+    virtual ~IOTAManager() = default;
+    
+    // OTA Lifecycle Management
+    virtual Result<void> initialize() = 0;
+    virtual Result<void> shutdown() = 0;
+    virtual OTAState getCurrentState() const = 0;
+    
+    // Update Negotiation
+    virtual Result<void> receiveUpdateNotification(const UpdateNotification& notification) = 0;
+    virtual Result<bool> validateSystemReadiness() const = 0;
+    virtual Result<void> acceptUpdate(const UpdateAcceptance& acceptance) = 0;
+    virtual Result<void> rejectUpdate(const UpdateRejection& rejection) = 0;
+    
+    // Firmware Reception
+    virtual Result<void> startFirmwareDownload(const FirmwareMetadata& metadata) = 0;
+    virtual Result<void> receiveFirmwareChunk(const FirmwareChunk& chunk) = 0;
+    virtual Result<void> completeFirmwareDownload() = 0;
+    virtual DownloadProgress getDownloadProgress() const = 0;
+    
+    // Firmware Validation and Activation
+    virtual Result<void> validateFirmware() = 0;
+    virtual Result<void> activateFirmware() = 0;
+    virtual Result<void> confirmFirmware() = 0;
+    
+    // Rollback Management
+    virtual Result<void> rollbackFirmware() = 0;
+    virtual bool isRollbackAvailable() const = 0;
+    virtual RollbackInfo getRollbackInfo() const = 0;
+    
+    // Status and Information
+    virtual OTAStatus getOTAStatus() const = 0;
+    virtual FirmwareInfo getCurrentFirmwareInfo() const = 0;
+    virtual FirmwareInfo getPendingFirmwareInfo() const = 0;
+    virtual std::vector<OTAEvent> getOTAHistory() const = 0;
+};
+```
+
+#### 3.1.2 IUpdateController
+```cpp
+class IUpdateController {
+public:
+    virtual ~IUpdateController() = default;
+    virtual Result<void> initiateUpdate(const UpdateRequest& request) = 0;
+    virtual Result<void> cancelUpdate() = 0;
+    virtual Result<void> pauseUpdate() = 0;
+    virtual Result<void> resumeUpdate() = 0;
+    virtual UpdateStatus getUpdateStatus() const = 0;
+};
+```
+
+#### 3.1.3 IFirmwareStatus
+```cpp
+class IFirmwareStatus {
+public:
+    virtual ~IFirmwareStatus() = default;
+    virtual FirmwareVersion getCurrentVersion() const = 0;
+    virtual FirmwareVersion getPendingVersion() const = 0;
+    virtual PartitionInfo getActivePartition() const = 0;
+    virtual PartitionInfo getInactivePartition() const = 0;
+    virtual bool isPendingFirmwareValid() const = 0;
+};
+```
+
+### 3.2 Required Interfaces
+
+#### 3.2.1 ICommunicationManager
+- Reception of OTA notifications and firmware data
+- Transmission of OTA status and acknowledgments
+- Secure communication channel management
+
+#### 3.2.2 ISystemStateManager
+- System state management for OTA operations
+- Controlled teardown initiation
+- System reinitialization coordination
+
+#### 3.2.3 IPersistenceManager
+- Firmware image storage and retrieval
+- OTA metadata persistence
+- Backup and recovery data management
+
+#### 3.2.4 ISecurityManager
+- Firmware signature verification
+- Certificate validation
+- Cryptographic operations
+
+#### 3.2.5 IDiagnosticsManager
+- OTA event logging and reporting
+- Error condition reporting
+- Performance metrics collection
+
+## 4. Dynamic View
+
+### 4.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: receiveUpdateNotification(firmware_info)
+    OM->>UN: negotiateUpdate(firmware_info)
+    UN->>STM: checkSystemReadiness()
+    STM-->>UN: system_status
+    UN->>UN: validateUpdateCompatibility()
+    
+    alt System Ready and Compatible
+        UN-->>OM: negotiation_success
+        OM->>STM: transitionToOTAState()
+        STM-->>OM: state_transition_complete
+        OM->>CM: sendOTAAcceptance()
+        CM->>MH: otaAccepted()
+    else System Not Ready or Incompatible
+        UN-->>OM: negotiation_failed(reason)
+        OM->>CM: sendOTARejection(reason)
+        CM->>MH: otaRejected(reason)
+    end
+```
+
+### 4.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 CM as Crypto Manager
+    
+    MH->>FR: startFirmwareTransfer(metadata)
+    FR->>FS: initializeFirmwareStorage(metadata)
+    FS-->>FR: storage_initialized
+    
+    loop Firmware Chunks
+        MH->>FR: sendFirmwareChunk(chunk_data, chunk_id)
+        FR->>FS: storeFirmwareChunk(chunk_data, chunk_id)
+        FS-->>FR: chunk_stored
+        FR->>FR: updateProgress()
+    end
+    
+    FR->>IV: validateFirmwareIntegrity()
+    IV->>FS: calculateSHA256Hash()
+    FS-->>IV: calculated_hash
+    IV->>IV: compareWithExpectedHash()
+    
+    alt Hash Valid
+        IV->>CV: validateFirmwareSignature()
+        CV->>CM: verifySignature(firmware, signature)
+        CM-->>CV: signature_valid
+        
+        alt Signature Valid
+            CV-->>IV: signature_validation_success
+            IV-->>FR: firmware_validated
+        else Signature Invalid
+            CV-->>IV: signature_validation_failed
+            IV-->>FR: validation_failed
+        end
+    else Hash Invalid
+        IV-->>FR: integrity_check_failed
+    end
+```
+
+### 4.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
+    participant SB as Secure Boot
+    
+    OM->>FA: activateFirmware()
+    FA->>STM: initiateTeardown()
+    STM->>STM: executeTeardown()
+    STM-->>FA: teardown_complete
+    
+    FA->>PM: flashFirmwareToInactivePartition()
+    PM->>PM: writeFirmwareToPartition()
+    PM-->>FA: flash_complete
+    
+    FA->>PM: setBootPartition(inactive_partition)
+    PM->>PM: updatePartitionTable()
+    PM-->>FA: boot_partition_set
+    
+    FA->>FA: rebootSystem()
+    
+    Note over FA: System Reboots
+    
+    alt Boot Success
+        SB->>SB: validateNewFirmware()
+        SB->>FA: firmwareBootSuccessful()
+        FA->>FA: startConfirmationTimer()
+        FA->>OM: sendHealthReport()
+        
+        alt Confirmation Received
+            OM->>RM: confirmFirmwareStability()
+            RM->>PM: markPartitionValid()
+        else Confirmation Timeout
+            RM->>PM: rollbackToPreviousPartition()
+            PM->>PM: setBootPartition(previous_partition)
+            PM->>PM: rebootSystem()
+        end
+    else Boot Failure
+        SB->>RM: bootFailureDetected()
+        RM->>PM: rollbackToPreviousPartition()
+        PM->>PM: setBootPartition(previous_partition)
+        PM->>PM: rebootSystem()
+    end
+```
+
+## 5. OTA State Management
+
+### 5.1 OTA States
+```cpp
+enum class OTAState {
+    IDLE,                    // No OTA operation in progress
+    NEGOTIATING,            // Negotiating update with Main Hub
+    DOWNLOADING,            // Downloading firmware image
+    VALIDATING,             // Validating firmware integrity
+    READY_TO_ACTIVATE,      // Ready for firmware activation
+    ACTIVATING,             // Activating new firmware
+    CONFIRMING,             // Confirming firmware stability
+    ROLLING_BACK,           // Rolling back to previous firmware
+    COMPLETED,              // OTA operation completed successfully
+    FAILED,                 // OTA operation failed
+    CANCELLED               // OTA operation cancelled
+};
+```
+
+### 5.2 State Transitions
+```cpp
+class OTAStateMachine {
+public:
+    bool isValidTransition(OTAState from, OTAState to) const;
+    Result<void> transitionTo(OTAState new_state);
+    OTAState getCurrentState() const;
+    std::vector<OTAState> getValidNextStates() const;
+    
+private:
+    OTAState current_state_;
+    std::map<OTAState, std::vector<OTAState>> valid_transitions_;
+};
+```
+
+## 6. A/B Partitioning
+
+### 6.1 Partition Layout
+```cpp
+struct PartitionLayout {
+    // Boot partitions
+    Partition bootloader;      // ~32KB - Initial boot code
+    Partition partition_table; // ~4KB - Partition table
+    Partition factory;         // Optional - Factory/rescue firmware
+    
+    // Application partitions (A/B)
+    Partition ota_0;          // 3.5MB - Primary application slot
+    Partition ota_1;          // 3.5MB - Secondary application slot
+    
+    // Data partitions
+    Partition nvs;            // 64KB - Non-volatile storage
+    Partition phy_init;       // ~4KB - PHY initialization data
+    Partition coredump;       // 64KB - Core dump storage
+};
+```
+
+### 6.2 Partition Management
+```cpp
+class PartitionManager {
+public:
+    Result<void> initialize();
+    
+    // Partition Information
+    PartitionInfo getActivePartition() const;
+    PartitionInfo getInactivePartition() const;
+    std::vector<PartitionInfo> getAllPartitions() const;
+    
+    // Partition Operations
+    Result<void> setBootPartition(PartitionId partition_id);
+    Result<void> markPartitionValid(PartitionId partition_id);
+    Result<void> markPartitionInvalid(PartitionId partition_id);
+    
+    // Firmware Operations
+    Result<void> writeFirmwareToPartition(PartitionId partition_id, 
+                                         const FirmwareImage& firmware);
+    Result<void> eraseFirmwarePartition(PartitionId partition_id);
+    Result<bool> validatePartitionFirmware(PartitionId partition_id);
+    
+    // Rollback Support
+    Result<void> rollbackToPartition(PartitionId partition_id);
+    bool isRollbackAvailable() const;
+    PartitionId getPreviousValidPartition() const;
+};
+```
+
+## 7. Firmware Validation
+
+### 7.1 Validation Methods
+```cpp
+class FirmwareValidator {
+public:
+    struct ValidationResult {
+        bool is_valid;
+        std::vector<ValidationError> errors;
+        ValidationMetrics metrics;
+    };
+    
+    // Integrity Validation
+    ValidationResult validateIntegrity(const FirmwareImage& firmware) const;
+    ValidationResult validateSHA256Hash(const FirmwareImage& firmware, 
+                                       const std::string& expected_hash) const;
+    
+    // Signature Validation
+    ValidationResult validateSignature(const FirmwareImage& firmware,
+                                      const DigitalSignature& signature) const;
+    ValidationResult validateCertificateChain(const CertificateChain& chain) const;
+    
+    // Compatibility Validation
+    ValidationResult validateCompatibility(const FirmwareMetadata& metadata) const;
+    ValidationResult validateHardwareCompatibility(const HardwareRequirements& requirements) const;
+    ValidationResult validateVersionCompatibility(const VersionInfo& version) const;
+    
+    // Metadata Validation
+    ValidationResult validateMetadata(const FirmwareMetadata& metadata) const;
+    ValidationResult validateSize(const FirmwareImage& firmware, size_t expected_size) const;
+};
+```
+
+### 7.2 Security Validation
+- **SHA-256 Hash**: Firmware integrity verification
+- **RSA-3072/ECDSA-P256**: Digital signature verification
+- **Certificate Chain**: Certificate validation and trust verification
+- **Anti-Rollback**: Version downgrade protection
+- **Secure Boot**: Boot-time firmware validation
+
+## 8. Rollback Management
+
+### 8.1 Rollback Triggers
+```cpp
+enum class RollbackTrigger {
+    BOOT_FAILURE,           // System failed to boot with new firmware
+    HEALTH_CHECK_TIMEOUT,   // No health report within confirmation window
+    APPLICATION_CRASH,      // Application crash during confirmation period
+    MANUAL_ROLLBACK,        // Manual rollback command from Main Hub
+    VALIDATION_FAILURE,     // Post-boot validation failure
+    WATCHDOG_TIMEOUT        // Watchdog timeout indicating system hang
+};
+```
+
+### 8.2 Rollback Process
+1. **Failure Detection**: Detect rollback trigger condition
+2. **Rollback Decision**: Determine if rollback is appropriate
+3. **Partition Switch**: Switch boot partition to previous valid firmware
+4. **System Reboot**: Reboot into previous firmware
+5. **Rollback Verification**: Verify successful rollback
+6. **Status Reporting**: Report rollback event and reason
+
+### 8.3 Rollback Prevention
+- **Confirmation Window**: 60-120 seconds for firmware confirmation
+- **Health Monitoring**: Continuous health checks during confirmation
+- **Graceful Degradation**: Attempt recovery before rollback
+- **Rollback Limits**: Prevent infinite rollback loops
+
+## 9. Configuration
+
+### 9.1 OTA Configuration
+```cpp
+struct OTAConfig {
+    // Download Configuration
+    size_t chunk_size;                    // Default: 4096 bytes
+    std::chrono::seconds download_timeout;
+    uint32_t max_retry_attempts;
+    
+    // Validation Configuration
+    bool signature_validation_required;
+    bool certificate_validation_required;
+    std::vector<std::string> trusted_ca_certificates;
+    
+    // Activation Configuration
+    std::chrono::seconds confirmation_timeout;  // Default: 90 seconds
+    bool automatic_rollback_enabled;
+    uint32_t max_rollback_attempts;
+    
+    // Storage Configuration
+    std::string firmware_storage_path;
+    size_t max_firmware_size;
+    bool cleanup_after_activation;
+    
+    // Security Configuration
+    bool secure_download_required;
+    EncryptionMethod storage_encryption;
+    bool anti_rollback_enabled;
+};
+```
+
+## 10. Error Handling
+
+### 10.1 Error Categories
+- **Network Errors**: Download failures, communication timeouts
+- **Storage Errors**: Insufficient space, write failures
+- **Validation Errors**: Integrity check failures, signature validation failures
+- **Activation Errors**: Partition switching failures, boot failures
+- **Rollback Errors**: Rollback process failures
+
+### 10.2 Error Recovery Strategies
+- **Retry Logic**: Automatic retry with exponential backoff
+- **Graceful Degradation**: Continue operation with current firmware
+- **Automatic Rollback**: Rollback on activation failures
+- **Error Reporting**: Detailed error reporting to Main Hub
+- **Diagnostic Logging**: Comprehensive logging for troubleshooting
+
+## 11. Performance Characteristics
+
+### 11.1 Timing Requirements
+- **OTA Negotiation**: < 30 seconds
+- **Firmware Download**: Variable based on size and network speed
+- **Firmware Validation**: < 60 seconds for typical firmware
+- **Firmware Activation**: < 2 minutes including teardown and reboot
+- **Total OTA Process**: < 10 minutes end-to-end
+
+### 11.2 Resource Usage
+- **Memory**: < 64KB for OTA operations and buffers
+- **Storage**: Temporary storage equal to firmware size
+- **CPU**: < 10% during download, higher during validation
+- **Network**: Adaptive based on available bandwidth
+
+## 12. Security Considerations
+
+### 12.1 Secure Download
+- All firmware downloads over encrypted channels (TLS 1.2)
+- Firmware integrity verification during download
+- Secure temporary storage with encryption
+
+### 12.2 Firmware Validation
+- Mandatory cryptographic signature verification
+- Certificate chain validation with trusted root CAs
+- Anti-rollback protection via eFuse version tracking
+
+### 12.3 Activation Security
+- Secure Boot V2 validation of new firmware
+- Encrypted partition storage
+- Rollback protection against unauthorized downgrades
+
+## 13. Testing Strategy
+
+### 13.1 Unit Tests
+- OTA state machine transitions
+- Firmware validation algorithms
+- Partition management operations
+- Error handling and recovery logic
+
+### 13.2 Integration Tests
+- End-to-end OTA update process
+- Communication with Main Hub
+- System teardown and reinitialization
+- Rollback scenarios and recovery
+
+### 13.3 System Tests
+- OTA updates under various system conditions
+- Network interruption and recovery
+- Power failure during OTA process
+- Security validation and attack resistance
+
+## 14. Dependencies
+
+### 14.1 Internal Dependencies
+- Communication Manager for OTA communication
+- System State Manager for teardown coordination
+- Persistence Manager for firmware storage
+- Security Manager for cryptographic operations
+- Diagnostics Manager for event logging
+
+### 14.2 External Dependencies
+- ESP-IDF OTA APIs and partition management
+- mbedTLS for cryptographic operations
+- File system support for firmware storage
+- Secure Boot and Flash Encryption hardware
+
+## 15. Constraints and Assumptions
+
+### 15.1 Constraints
+- OTA process requires system restart
+- Firmware size limited by partition size (3.5MB)
+- Network connectivity required for firmware download
+- Sufficient storage space required for temporary firmware storage
+
+### 15.2 Assumptions
+- Reliable network connectivity during download
+- Valid firmware signatures and certificates
+- Proper A/B partition configuration
+- Sufficient system resources for OTA operations
+- Main Hub provides valid firmware images and metadata