9.5 KiB
Firmware Update (OTA) Features
Feature Group ID: FG-OTA
Version: 2.0
Date: 2025-01-19
Scope: Sensor Hub (Sub-Hub only)
Target Platform: ESP32-S3–based Sensor Hub, ESP-IDF v5.4
1 Feature Overview
The Firmware Update (OTA) Features enable the Sensor Hub (Sub-Hub) to safely receive, validate, and activate new firmware images provided by the Main Hub.
These features ensure controlled firmware lifecycle management, data integrity, system availability, and fault containment during firmware update operations.
The OTA process is designed to:
- Prevent unauthorized or corrupted firmware installation
- Preserve critical system data and calibration information
- Ensure recoverability in case of update failure
- Minimize operational disruption
Technology: A/B Partitioning with automatic rollback, SHA-256 integrity verification
This feature set applies only to the Sensor Hub (ESP32-S3 based) and does not include cloud-side or Main Hub OTA logic.
2 Scope and Assumptions
In Scope
- OTA negotiation and readiness handshake with Main Hub
- Firmware image reception over secure communication (MQTT or HTTPS)
- Temporary firmware storage on SD card
- Firmware integrity verification (SHA-256 hash)
- Controlled firmware activation and reboot
- A/B partitioning with automatic rollback
Out of Scope
- Firmware generation and signing
- Cloud-side firmware distribution
- Rollback policy definition (defined in this document)
3 Partition Layout
For a device with 8MB of flash, the following partition layout is recommended:
| Partition | Size | Purpose |
|---|---|---|
| bootloader | ~32KB | Initial boot code |
| partition_table | ~4KB | Defines the flash layout |
| factory | Optional | Minimal rescue firmware |
| ota_0 | 3.5 MB | Primary application slot |
| ota_1 | 3.5 MB | Secondary application slot for updates |
| nvs | 64 KB | Encrypted Non-Volatile Storage for config |
| phy_init | ~4KB | Physical layer initialization data |
| coredump | 64 KB | Storage for crash logs and debugging |
Total Used: ~7.1MB (fits in 8MB flash)
4 Sub-Features
4.1 F-OTA-01: OTA Update Negotiation
Description
This sub-feature governs the initial negotiation phase between the Sensor Hub and the Main Hub prior to any firmware transfer.
The Sensor Hub validates its current operational state and explicitly signals readiness before accepting an OTA update.
Readiness Validation:
- System state check (must be RUNNING, not WARNING/FAULT/SERVICE/SD_DEGRADED)
- Storage availability check (SD card space, NVS space)
- Power stability check
- Communication link stability check
Responsibilities
- Receive OTA availability notification
- Validate system readiness (power, storage, state)
- Acknowledge or reject OTA request
- Transition system into OTA_PREP state
4.2 F-OTA-02: Firmware Reception and Storage
Description
This sub-feature handles the controlled reception of the firmware image from the Main Hub and its storage in non-volatile memory (SD card) without overwriting the currently running firmware.
Download Method:
- Protocol: HTTPS or MQTT
- Chunk Size: 4096 bytes (optimized for flash page size)
- Storage: SD Card (temporary) before flashing to OTA partition
Responsibilities
- Receive firmware in chunks (4096 bytes per chunk)
- Store firmware image on SD card (temporary)
- Monitor transfer completeness
- Prevent execution during download
- Track download progress
4.3 F-OTA-03: Firmware Integrity Validation
Description
This sub-feature validates the integrity and correctness of the received firmware image prior to activation, ensuring that corrupted or incomplete firmware is never flashed.
Validation Method:
- Integrity Check: SHA-256 hash verification
- Size Validation: Firmware size matches metadata
- Metadata Validation: Partition table, version number
Responsibilities
- Perform integrity checks (SHA-256 hash)
- Validate firmware size and metadata
- Reject invalid firmware images
- Report validation status to Main Hub
4.4 F-OTA-04: Safe Firmware Activation
Description
This sub-feature manages the safe transition from the current firmware to the new firmware, ensuring all critical data is preserved and the system is left in a known safe state.
Activation Sequence:
- Execute controlled teardown
- Persist critical runtime data and calibration data
- Flash validated firmware image to inactive OTA partition
- Update partition table to boot from new partition
- Reboot system into new firmware
- Validate: System must boot and send health report
- Confirmation: Application must confirm stability within 60-120 seconds
- Failure: Automatic rollback to previous known-good version
Responsibilities
- Trigger teardown procedure
- Persist runtime and calibration data
- Flash validated firmware image
- Reboot system into updated firmware
4.5 F-OTA-05: A/B Partitioning with Rollback [NEW]
Description
The system implements A/B partitioning to support safe firmware updates with automatic rollback capability.
Rollback Triggers:
- Boot failure after firmware activation
- No health report within confirmation window (60-120 seconds)
- Application crash during confirmation period
- Manual rollback command from Main Hub
Rollback Process:
- Detect failure condition
- Mark new firmware as invalid
- Update partition table to boot from previous partition
- Reboot into previous known-good firmware
- Report rollback to Main Hub
5 OTA Policy
A formal policy ensures that updates are downloaded correctly and that the system can roll back if the new firmware is unstable.
| Step | Rule |
|---|---|
| Download | Conducted via HTTPS or MQTT in chunks |
| Chunk Size | 4096 bytes (optimized for flash page size) |
| Integrity | Verified using a full image SHA-256 hash |
| Validation | System must boot and send a health report |
| Confirmation | The application must confirm stability within 60-120 seconds |
| Failure | Automatic rollback to the previous known-good version |
OTA Duration: Maximum 10 minutes (end-to-end)
6 System Requirements (Formal SHALL Statements)
OTA Negotiation Requirements
- SR-OTA-001: The system shall support OTA update negotiation initiated by the Main Hub.
- SR-OTA-002: The system shall verify internal readiness before accepting an OTA update request.
- SR-OTA-003: The system shall explicitly acknowledge or reject OTA requests.
Firmware Reception & Storage Requirements
- SR-OTA-004: The system shall receive firmware images over the established communication channel (HTTPS or MQTT).
- SR-OTA-005: The system shall store received firmware images in non-volatile storage (SD card) prior to validation.
- SR-OTA-006: The system shall prevent overwriting the active firmware during firmware reception.
Firmware Integrity Requirements
- SR-OTA-007: The system shall validate the integrity of the received firmware image before activation using SHA-256 hash.
- SR-OTA-008: The system shall reject firmware images that fail integrity validation.
- SR-OTA-009: The system shall report firmware validation results to the Main Hub.
Safe Activation Requirements
- SR-OTA-010: The system shall execute a controlled teardown before firmware activation.
- SR-OTA-011: The system shall persist critical runtime data and calibration data prior to firmware flashing.
- SR-OTA-012: The system shall activate new firmware only after successful integrity validation.
- SR-OTA-013: The system shall reboot into the new firmware after successful activation.
Rollback Requirements [NEW]
- SR-OTA-014: The system shall implement A/B partitioning for safe firmware updates.
- SR-OTA-015: The system shall automatically rollback to previous firmware if new firmware fails validation or health check.
- SR-OTA-016: The system shall report rollback events to the Main Hub.
7 Feature-to-Requirement Traceability
| Feature ID | Related System Requirements |
|---|---|
| F-OTA-01 | SR-OTA-001, SR-OTA-002, SR-OTA-003 |
| F-OTA-02 | SR-OTA-004, SR-OTA-005, SR-OTA-006 |
| F-OTA-03 | SR-OTA-007, SR-OTA-008, SR-OTA-009 |
| F-OTA-04 | SR-OTA-010, SR-OTA-011, SR-OTA-012, SR-OTA-013 |
| F-OTA-05 | SR-OTA-014, SR-OTA-015, SR-OTA-016 |
8 Architectural Considerations (Informative)
- OTA logic shall be implemented as a dedicated OTA Manager component
- Firmware storage shall be accessed via the DP (Data Persistence) component
- OTA state transitions shall interact with:
- Diagnostics subsystem
- Machine Constants management
- Teardown mechanism
- OTA execution shall not block critical system diagnostics reporting
- OTA operations SHALL NOT be allowed during WARNING, FAULT, SERVICE, or SD_DEGRADED states
9 Related Features
- Persistence & Data Management Features (F-DATA-03)
- Diagnostics & Health Monitoring Features
- Security & Safety Features (Secure Boot, Secure Flash)
- System Management Features (State Machine, Teardown)
10 Closing the Gaps
This strategy directly addresses the following gaps:
- GAP-OTA-001: Reliable image delivery (chunked download, MQTT/HTTPS)
- GAP-OTA-002: Integrity and authenticity verification (SHA-256, Secure Boot)
- GAP-OTA-003: Safe rollback mechanisms (A/B partitioning, automatic rollback)