software design

2026-01-25 23:48:46 +01:00
parent 2a2fba3473
commit c631110349
305 changed files with 40333 additions and 0 deletions
--- a/system_arch_final/[PWR]
+++ b/system_arch_final/[PWR]
@@ -0,0 +1,138 @@
+# Power & Fault Handling Features
+
+**Feature Group ID:** FG-PWR  
+**Version:** 1.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 **Power & Fault Handling Features** ensure that the Sensor Hub operates reliably under power fluctuations and recovers gracefully from power interruptions. These features protect critical data during brownouts and enable clean recovery after power restoration.
+
+**Technology:**
+- **Brownout Detection:** Hardware brownout detector (BOD)
+- **Power-Loss Protection:** Supercapacitor (optional, recommended)
+- **RTC Backup:** External RTC battery (CR2032, optional)
+
+## 2 Scope and Assumptions
+
+**In Scope**
+
+*   Brownout detection and handling
+*   Power-loss data protection
+*   Graceful shutdown on power loss
+*   Clean recovery after power restoration
+
+**Out of Scope**
+
+*   Battery-powered operation (system assumes continuous power)
+*   Power management for low-power modes (not applicable for real-time requirements)
+
+## 3 Sub-Feature Breakdown
+
+### 3.1 F-PWR-01: Brownout Detection and Handling
+
+#### Description
+
+The system monitors input voltage and takes immediate action if it drops below safe threshold.
+
+**Configuration:**
+- **Brownout Threshold:** 3.0V (hardware-configurable)
+- **Detection:** Hardware brownout detector (BOD) in ESP32-S3
+- **ISR Action:** Set "Power Loss" flag and immediately flush critical buffers to NVS/SD
+- **Recovery:** Perform clean reboot once power is stable
+
+**Hardware Support:**
+- **Supercapacitor (Recommended):** 0.5-1.0F for 1-2s at 3.3V
+  - Provides runtime during brownout to complete data flush
+  - Enables graceful shutdown
+- **External RTC Battery (Optional):** CR2032, 3V, 220mAh
+  - Maintains time accuracy during power loss
+  - Not required for basic operation
+
+#### Responsibilities
+
+*   Monitor input voltage
+*   Detect brownout condition
+*   Trigger immediate data flush
+*   Enter graceful shutdown mode
+
+#### Constraints
+
+*   Brownout detection must be hardware-based (ESP32-S3 BOD)
+*   Data flush must complete within supercapacitor runtime (1-2 seconds)
+*   System must reboot cleanly after power restoration
+
+### 3.2 F-PWR-02: Power-Loss Recovery
+
+#### Description
+
+The system recovers gracefully from power interruptions (< 1 second).
+
+**Recovery Behavior:**
+- Clean reboot after power stabilization
+- Data integrity verification
+- State restoration from persistent storage
+- Diagnostic event generation (if data loss detected)
+
+**Recovery Sequence:**
+1. Power restoration detected
+2. Wait for power stabilization (100ms)
+3. Perform clean reboot
+4. Initialize system from persistent storage
+5. Verify data integrity
+6. Report recovery status via diagnostics
+
+#### Responsibilities
+
+*   Detect power restoration
+*   Perform clean reboot
+*   Restore system state from persistent storage
+*   Verify data integrity
+*   Report recovery status
+
+## 4 System Requirements (Formal SHALL Statements)
+
+### Brownout Detection Requirements
+
+*   **SR-PWR-001**: The system shall monitor input voltage and detect brownout conditions below 3.0V.
+*   **SR-PWR-002**: The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection.
+*   **SR-PWR-003**: The system shall enter graceful shutdown mode during brownout conditions.
+*   **SR-PWR-004**: The system shall perform clean reboot after power stabilization.
+
+### Power-Loss Recovery Requirements
+
+*   **SR-PWR-005**: The system shall recover gracefully from power interruptions.
+*   **SR-PWR-006**: The system shall verify data integrity after power restoration.
+*   **SR-PWR-007**: The system shall restore system state from persistent storage after power restoration.
+*   **SR-PWR-008**: The system shall report power-loss and recovery events via diagnostics.
+
+## 5 Traceability Matrix (Feature → System Requirements)
+
+| Feature ID | Related System Requirements |
+|------------|----------------------------|
+| F-PWR-01 | SR-PWR-001, SR-PWR-002, SR-PWR-003, SR-PWR-004 |
+| F-PWR-02 | SR-PWR-005, SR-PWR-006, SR-PWR-007, SR-PWR-008 |
+
+## 6 Design & Implementation Notes (Non-Normative)
+
+*   **Supercapacitor:** Recommended for production deployment to enable graceful shutdown
+*   **RTC Battery:** Optional, improves time accuracy during power loss
+*   **Brownout Threshold:** 3.0V is conservative; adjust based on power supply characteristics
+*   **Data Flush Priority:** Critical data (calibration, diagnostics) must be flushed first
+*   **Recovery Time:** System should recover within 5 seconds after power restoration
+
+## 7 Dependencies
+
+*   **Persistence & Data Management Features** (data flush mechanism)
+*   **Diagnostics Features** (power-loss event reporting)
+*   **System Management Features** (graceful shutdown, state restoration)
+
+## 8 Hardware Recommendations
+
+| Component | Specification | Purpose |
+|-----------|---------------|---------|
+| **Supercapacitor** | 0.5-1.0F, 3.3V | Provides runtime during brownout for data flush |
+| **RTC Battery** | CR2032, 3V, 220mAh | Maintains time accuracy during power loss |
+| **Power Supply** | 3.3V ±5%, minimum 500mA | Stable power for reliable operation |