# 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