cleanup

2026-01-26 12:49:12 +01:00
parent bedcd373f5
commit ff791564e4
243 changed files with 18986 additions and 0 deletions
--- a/system_design/features/[OTA]
+++ b/system_design/features/[OTA]
@@ -0,0 +1,236 @@
+# 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:**
+1. Execute controlled teardown
+2. Persist critical runtime data and calibration data
+3. Flash validated firmware image to inactive OTA partition
+4. Update partition table to boot from new partition
+5. Reboot system into new firmware
+6. Validate: System must boot and send health report
+7. Confirmation: Application must confirm stability within 60-120 seconds
+8. 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:**
+1. Detect failure condition
+2. Mark new firmware as invalid
+3. Update partition table to boot from previous partition
+4. Reboot into previous known-good firmware
+5. 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)