Files

mahmamdouh 304371c6b8 cleanup sw req

2026-02-01 19:47:53 +01:00

9.8 KiB

Raw Blame History

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

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

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

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

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

9.8 KiB Raw Blame History