cleanup

draft/System Design old/system_design/features/Cross-Feature Constraints.md

@@ -0,0 +1,120 @@
+## 1\. Purpose
+
+This document defines **cross-feature constraints** that apply across multiple system features and components. These constraints ensure consistent behavior, prevent architectural violations, and reduce integration risk.
+
+Cross-feature constraints are **mandatory rules** that all future software design and implementation must comply with.
+
+## 2\. Architectural Constraints
+
+### CFC-ARCH-01: Layered Architecture Enforcement
+
+*   Application logic shall not access hardware directly.
+    
+*   All hardware access shall be performed via Drivers and OSAL layers.
+    
+*   Persistence access shall only be performed through the DP component.
+    
+
+**Impacted Features:**  
+DAQ, DQC, DATA, DIAG, SYS, OTA, SEC
+
+### CFC-ARCH-02: State-Aware Feature Execution
+
+*   All features shall be aware of the current system state.
+    
+*   Features shall not execute actions that are invalid for the current state.
+    
+
+**Examples:**
+
+*   DAQ shall not start sampling during OTA\_UPDATE.
+    
+*   Communication shall be limited during TEARDOWN.
+    
+
+**Impacted Features:**  
+SYS, DAQ, COM, OTA, DATA
+
+## 3\. Concurrency & Timing Constraints
+
+### CFC-TIME-01: Non-Blocking Operation
+
+*   Sensor acquisition, communication, and UI updates shall be non-blocking.
+    
+*   Blocking operations shall be isolated in controlled system services (e.g., persistence task).
+    
+
+**Impacted Features:**  
+DAQ, COM, SYS
+
+### CFC-TIME-02: Deterministic Task Behavior
+
+*   Time-critical tasks (sensor acquisition, watchdog servicing) shall have deterministic execution time.
+    
+*   Dynamic memory allocation during runtime shall be minimized or prohibited in critical paths.
+    
+
+**Impacted Features:**  
+DAQ, SYS, DIAG
+
+## 4\. Data & Persistence Constraints
+
+### CFC-DATA-01: Single Source of Truth
+
+*   Runtime and persistent data shall be owned and managed by the DP component.
+    
+*   No feature shall maintain private persistent copies of shared system data.
+    
+
+**Impacted Features:**  
+DATA, DAQ, DIAG, SYS, OTA
+
+### CFC-DATA-02: Data Consistency During Transitions
+
+*   No data write operations shall occur during teardown unless explicitly authorized by the System Manager.
+    
+*   Persistence completion shall be confirmed before state transitions.
+    
+
+**Impacted Features:**  
+SYS, DATA, OTA
+
+## 5\. Security Constraints
+
+### CFC-SEC-01: Security First Initialization
+
+*   Secure boot and flash protection shall be enabled before any application-level logic executes.
+    
+
+**Impacted Features:**  
+SEC, SYS
+
+### CFC-SEC-02: Encrypted Channels Only
+
+*   OTA, diagnostics, and data transmission shall only occur over encrypted and authenticated channels.
+    
+
+**Impacted Features:**  
+COM, OTA, DIAG, SEC
+
+## 6\. HMI & Debug Constraints
+
+### CFC-HMI-01: Read-Only Local UI
+
+*   The OLED HMI shall not allow configuration changes that affect system safety or security.
+    
+*   Configuration updates shall only be accepted via authenticated communication channels.
+    
+
+**Impacted Features:**  
+SYS, SEC
+
+### CFC-DBG-01: Debug Isolation
+
+*   Debug and engineering sessions shall not interfere with normal system operation.
+    
+*   Debug commands shall respect system state restrictions.
+    
+
+**Impacted Features:**  
+SYS, DIAG, SEC

draft/System Design old/system_design/features/Features.md

@@ -0,0 +1,359 @@
+# **ASF Sensor Hub – Feature Definition Document**
+
+*(Global, Feature-Based, Architecture-Neutral)*
+
+This document defines the **system features** of the ASF Sensor Hub subsystem, organized by functional categories.
+It is intended to be used as:
+
+* A **feature baseline** in ALM
+* Input to **system requirements derivation**
+* Reference for **architecture and software design**
+* Traceability anchor to IEC 61508 / IEC 61499 style decomposition later
+
+> ⚠️ **Important Scope Note**
+> This document covers **ONLY the Sensor Hub (Sub-Hub)** based on **ESP32-S3**.
+> Main Hub, Cloud, Farm Control Logic are **explicitly out of scope**.
+
+---
+
+## **1. System Context Overview**
+
+The ASF Sensor Hub is a **distributed sensing node** deployed inside a poultry house.
+Its primary responsibilities are:
+
+* Acquisition of multiple environmental sensors
+* Local preprocessing and validation of sensor data
+* Persistent storage of data and configuration
+* Secure communication with a Main Hub
+* Support for diagnostics, maintenance, and OTA updates
+* Safe operation under fault conditions
+
+The Sensor Hub operates as an **autonomous embedded system** with defined lifecycle states.
+
+---
+
+## **2. Feature Categorization Overview**
+
+The system features are grouped into the following categories:
+
+1. **Sensor Data Acquisition Features**
+2. **Data Quality & Calibration Features**
+3. **Communication Features**
+4. **Diagnostics & Health Monitoring Features**
+5. **Persistence & Data Management Features**
+6. **Firmware Update (OTA) Features**
+7. **Security & Safety Features**
+8. **System Management Features**
+
+Each feature is described at a **functional level** (WHAT the system does, not HOW).
+
+---
+
+## **3. Sensor Data Acquisition Features**
+
+### **F-DAQ-01: Multi-Sensor Data Acquisition**
+
+The system provides the capability to acquire data from multiple environmental sensors connected to the Sensor Hub hardware.
+
+Supported sensor types include:
+
+* Temperature
+* Humidity
+* Carbon Dioxide (CO₂)
+* Ammonia (NH₃)
+* Volatile Organic Compounds (VOC)
+* Particulate Matter (PM)
+* Light Intensity
+
+---
+
+### **F-DAQ-02: High-Frequency Sampling and Local Filtering**
+
+The system provides local preprocessing of sensor data by:
+
+* Sampling each sensor multiple times per acquisition cycle
+* Applying a fast local filtering mechanism
+* Producing a single validated value per sensor per cycle
+
+Filtering algorithms are **pluggable and configurable**.
+
+---
+
+### **F-DAQ-03: Timestamped Sensor Data Generation**
+
+The system provides timestamped sensor data using a synchronized local time source.
+
+Each sensor record includes:
+
+* Sensor identifier
+* Measured value
+* Timestamp
+* Data validity status
+
+---
+
+## **4. Data Quality & Calibration Features**
+
+### **F-DQC-01: Automatic Sensor Detection**
+
+The system provides automatic detection of sensor presence based on dedicated hardware detection signals.
+
+Key characteristics:
+
+* Each sensor slot is type-specific
+* Sensor presence is detected during initialization and runtime
+* Only detected sensors are initialized and sampled
+
+---
+
+### **F-DQC-02: Sensor Type Enforcement**
+
+The system enforces sensor-slot compatibility to prevent incorrect sensor usage.
+
+Each physical slot:
+
+* Accepts only one sensor type
+* Is mapped to a predefined sensor class in software
+
+---
+
+### **F-DQC-03: Sensor Failure Detection**
+
+The system provides detection of sensor failures, including:
+
+* Communication errors
+* Out-of-range values
+* Non-responsive sensors
+
+Detected failures are classified and reported.
+
+---
+
+### **F-DQC-04: Machine Constants & Calibration Management**
+
+The system provides a Machine Constants (MC) mechanism responsible for:
+
+* Defining installed sensor types
+* Holding sensor calibration parameters
+* Defining communication parameters
+* Defining system identity parameters
+
+MC data is persistent and reloadable.
+
+---
+
+## **5. Communication Features**
+
+### **F-COM-01: Main Hub Communication**
+
+The system provides bidirectional communication with a Main Hub to:
+
+* Send sensor data
+* Send diagnostics information
+* Receive configuration updates
+* Receive firmware updates
+
+---
+
+### **F-COM-02: On-Demand Data Broadcasting**
+
+The system provides on-demand transmission of the most recent sensor dataset upon request from the Main Hub.
+
+---
+
+### **F-COM-03: Peer Sensor Hub Communication**
+
+The system provides limited peer-to-peer communication between Sensor Hubs for:
+
+* Connectivity checks
+* Time synchronization support
+* Basic status exchange
+
+This feature is **on-demand and optional**.
+
+---
+
+## **6. Diagnostics & Health Monitoring Features**
+
+### **F-DIAG-01: Diagnostic Code Management**
+
+The system provides structured diagnostics with:
+
+* Diagnostic codes
+* Severity levels
+* Root cause hierarchy
+* Timestamping
+
+---
+
+### **F-DIAG-02: Diagnostic Data Storage**
+
+The system provides persistent storage of diagnostic events for post-analysis.
+
+---
+
+### **F-DIAG-03: Diagnostic Session**
+
+The system provides a diagnostic session allowing engineers to:
+
+* Retrieve diagnostic data
+* Inspect system health
+* Clear diagnostic records
+
+---
+
+## **7. Persistence & Data Management Features**
+
+### **F-DATA-01: Persistent Sensor Data Storage**
+
+The system provides persistent storage of sensor data in non-volatile memory (SD Card).
+
+---
+
+### **F-DATA-02: Data Persistence Abstraction (DP Component)**
+
+The system provides a Data Persistence (DP) component responsible for:
+
+* Abstracting storage media (SD / NVM)
+* Managing write/read operations
+* Ensuring data integrity
+
+---
+
+### **F-DATA-03: Safe Data Handling During State Transitions**
+
+The system ensures that all critical data is safely stored before:
+
+* Firmware update
+* Configuration update
+* System teardown
+* Reset or restart
+
+---
+
+## **8. Firmware Update (OTA) Features**
+
+### **F-OTA-01: OTA Update Negotiation**
+
+The system provides an OTA handshake mechanism with the Main Hub to:
+
+* Acknowledge update availability
+* Signal readiness for update
+
+---
+
+### **F-OTA-02: Firmware Reception and Storage**
+
+The system provides secure reception of firmware images and temporary storage on SD Card.
+
+---
+
+### **F-OTA-03: Firmware Integrity Validation**
+
+The system validates firmware integrity using checksum or CRC before activation.
+
+---
+
+### **F-OTA-04: Safe Firmware Activation**
+
+The system provides controlled firmware flashing and rollback-safe activation.
+
+---
+
+## **9. Security & Safety Features**
+
+### **F-SEC-01: Secure Boot**
+
+The system provides secure boot functionality to ensure only authenticated firmware is executed.
+
+---
+
+### **F-SEC-02: Secure Flash Storage**
+
+The system provides encrypted flash storage for sensitive assets.
+
+---
+
+### **F-SEC-03: Encrypted Communication**
+
+The system provides encrypted communication channels for all external data exchange.
+
+---
+
+## **10. System Management Features**
+
+### **F-SYS-01: System State Management**
+
+The system provides explicit lifecycle states including:
+
+* Initialization
+* Normal Operation
+* Degraded Operation
+* Update Mode
+* Fault Mode
+* Teardown Mode
+
+---
+
+### **F-SYS-02: Controlled Teardown Mechanism**
+
+The system provides a controlled teardown mechanism that:
+
+* Stops sensor acquisition
+* Flushes all critical data
+* Ensures persistent storage consistency
+* Prepares the system for update or shutdown
+
+---
+
+### **F-SYS-03: Status Indication**
+
+The system provides visual status indicators:
+
+* Green: Normal operation
+* Yellow: Warning state
+* Red: Fatal error state
+
+---
+
+### **F-SYS-04: Debug & Engineering Sessions**
+
+The system provides engineering access sessions allowing:
+
+* Log inspection
+* MC file inspection and update
+* Command execution
+* Controlled debugging
+
+---
+
+## **11. Feature Relationship Overview (High-Level)**
+
+```
+Sensor Acquisition
+        ↓
+Data Quality & Calibration
+        ↓
+Data Persistence
+        ↓
+Communication
+        ↓
+Diagnostics & System Management
+        ↓
+OTA / Security / Safety
+```
+
+* **Machine Constants** affect:
+
+  * Sensor initialization
+  * Calibration
+  * Communication
+* **Diagnostics** span all features
+* **Teardown** is a cross-cutting mechanism triggered by:
+
+  * OTA
+  * MC update
+  * Fatal faults
+
+---
+

draft/System Design old/system_design/features/System Assumptions & Limitations.md

@@ -0,0 +1,83 @@
+## 1\. System Assumptions
+
+### SA-01: Deployment Environment
+
+*   The Sensor Hub operates in an indoor poultry farm environment.
+    
+*   Environmental conditions may include high humidity, dust, and ammonia presence.
+    
+
+### SA-02: Power Availability
+
+*   The Sensor Hub is assumed to have continuous power.
+    
+*   Short power interruptions may occur; system shall recover gracefully.
+    
+
+### SA-03: Network Connectivity
+
+*   Wireless connectivity to the Main Hub may be intermittent.
+    
+*   The Sensor Hub shall operate autonomously when disconnected.
+    
+
+### SA-04: Trusted Provisioning
+
+*   Devices are assumed to be provisioned securely during manufacturing or installation.
+    
+*   Cryptographic keys are assumed to be injected via a secure process.
+    
+
+### SA-05: Time Synchronization
+
+*   System time is assumed to be synchronized periodically by the Main Hub.
+    
+*   Temporary time drift is acceptable.
+    
+
+## 2\. System Limitations
+
+### SL-01: Local Processing Limits
+
+*   The Sensor Hub performs lightweight preprocessing only.
+    
+*   Complex analytics and AI models are out of scope.
+    
+
+### SL-02: User Interface Constraints
+
+*   The OLED display is intended for monitoring and diagnostics only.
+    
+*   It is not a full configuration or management interface.
+    
+
+### SL-03: Physical Security
+
+*   The Sensor Hub does not include physical tamper detection.
+    
+*   Physical access is assumed to be restricted.
+    
+
+### SL-04: Storage Constraints
+
+*   SD card storage capacity is finite.
+    
+*   Data retention policies may result in data overwrite.
+    
+
+### SL-05: Safety Classification
+
+*   The system is not classified as a safety-critical life-support system.
+    
+*   Failures may impact farm performance but not human safety directly.
+    
+
+## 3\. External Dependencies
+
+*   ESP32-S3 hardware platform
+    
+*   ESP-IDF framework
+    
+*   Supported sensors and communication modules
+    
+*   Main Hub availability for OTA and configuration updates

draft/System Design old/system_design/features/System_Requirements_Traceability.csv

@@ -0,0 +1,140 @@
+Feature_ID,Feature_Name,Feature_Group,Sub_Feature_ID,Sub_Feature_Name,System_Requirement_ID,System_Requirement_Description
+F-DAQ-01,Multi-Sensor Data Acquisition,DAQ,F-DAQ-01,Multi-Sensor Data Acquisition,SR-DAQ-001,"The system shall support acquisition of data from multiple environmental sensor types simultaneously."
+F-DAQ-01,Multi-Sensor Data Acquisition,DAQ,F-DAQ-01,Multi-Sensor Data Acquisition,SR-DAQ-002,"The system shall provide a dedicated software driver abstraction for each supported sensor type."
+F-DAQ-01,Multi-Sensor Data Acquisition,DAQ,F-DAQ-01,Multi-Sensor Data Acquisition,SR-DAQ-003,"The system shall acquire sensor data only from sensors detected as present and enabled."
+F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-004,"The system shall sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples)."
+F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-005,"The system shall apply a local filtering mechanism to raw sensor samples to produce a single representative value."
+F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-006,"The system shall allow configuration of sampling count and filtering parameters via system configuration data (Machine Constants)."
+F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-010,"The system shall complete sensor acquisition cycle within a maximum of 100ms per sensor."
+F-DAQ-03,Timestamped Sensor Data Generation,DAQ,F-DAQ-03,Timestamped Sensor Data Generation,SR-DAQ-007,"The system shall associate each processed sensor value with a timestamp."
+F-DAQ-03,Timestamped Sensor Data Generation,DAQ,F-DAQ-03,Timestamped Sensor Data Generation,SR-DAQ-008,"The system shall generate timestamps after completion of filtering."
+F-DAQ-03,Timestamped Sensor Data Generation,DAQ,F-DAQ-03,Timestamped Sensor Data Generation,SR-DAQ-009,"The system shall include sensor identifier, sensor type, value, unit, timestamp, and validity status in each sensor data record."
+F-DAQ-04,Sensor State Management,DAQ,F-DAQ-04,Sensor State Management,SR-DAQ-011,"The system shall track sensor operational states (INIT, WARMUP, STABLE, DEGRADED, FAILED)."
+F-DAQ-04,Sensor State Management,DAQ,F-DAQ-04,Sensor State Management,SR-DAQ-012,"The system shall never publish raw sensor values without an accompanying validity flag indicating the current state."
+F-DAQ-04,Sensor State Management,DAQ,F-DAQ-04,Sensor State Management,SR-DAQ-013,"The system shall enforce sensor warmup durations (CO2: 30 seconds, Temperature: 5 seconds, others: sensor-specific)."
+F-DQC-01,Automatic Sensor Detection,DQC,F-DQC-01,Automatic Sensor Detection,SR-DQC-001,"The system shall detect the presence of each sensor using a dedicated hardware detection mechanism."
+F-DQC-01,Automatic Sensor Detection,DQC,F-DQC-01,Automatic Sensor Detection,SR-DQC-002,"The system shall perform sensor presence detection during system startup and after any reinitialization event."
+F-DQC-01,Automatic Sensor Detection,DQC,F-DQC-01,Automatic Sensor Detection,SR-DQC-003,"The system shall initialize only those sensors that are detected as present."
+F-DQC-02,Sensor Type Enforcement,DQC,F-DQC-02,Sensor Type Enforcement,SR-DQC-004,"The system shall assign each sensor slot to a predefined sensor type."
+F-DQC-02,Sensor Type Enforcement,DQC,F-DQC-02,Sensor Type Enforcement,SR-DQC-005,"The system shall verify that the detected sensor matches the expected sensor type for the slot."
+F-DQC-02,Sensor Type Enforcement,DQC,F-DQC-02,Sensor Type Enforcement,SR-DQC-006,"The system shall reject and report any sensor-slot mismatch as a diagnostic event."
+F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-007,"The system shall continuously monitor sensor responsiveness and signal validity during operation."
+F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-008,"The system shall detect sensor failures including disconnection, non-responsiveness, and invalid measurement ranges."
+F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-009,"The system shall mark a failed sensor as defective and exclude it from data reporting."
+F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-010,"The system shall report detected sensor failures to the Main Hub with timestamps and failure classification."
+F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-011,"The system shall maintain a Machine Constants dataset defining sensor configuration, calibration parameters, and communication identifiers."
+F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-012,"The system shall persist the Machine Constants dataset in non-volatile storage."
+F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-013,"The system shall load and apply Machine Constants during system initialization."
+F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-014,"The system shall support remote updates of the Machine Constants dataset initiated by the Main Hub."
+F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-015,"The system shall apply updated Machine Constants only after executing a controlled teardown and reinitialization sequence."
+F-DQC-05,Redundant Sensor Support,DQC,F-DQC-05,Redundant Sensor Support,SR-DQC-016,"The system shall support redundant sensors for critical parameters (CO2, NH3) using different technologies or interfaces."
+F-DQC-05,Redundant Sensor Support,DQC,F-DQC-05,Redundant Sensor Support,SR-DQC-017,"The system shall implement sensor fusion algorithm to combine redundant sensor data (average, weighted, or voting mechanism)."
+F-DQC-05,Redundant Sensor Support,DQC,F-DQC-05,Redundant Sensor Support,SR-DQC-018,"The system shall ensure that every critical parameter has two qualified sensor options to avoid common-mode failures."
+F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-001,"The system shall support bidirectional communication between the Sensor Hub and the Main Hub using MQTT over TLS 1.2."
+F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-002,"The system shall transmit sensor data, diagnostics, and system status information to the Main Hub via MQTT."
+F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-003,"The system shall receive commands, configuration updates, and firmware update requests from the Main Hub via MQTT."
+F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-004,"The system shall monitor and report the communication link status with the Main Hub."
+F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-011,"The system shall implement a heartbeat mechanism with 10-second interval and 30-second timeout."
+F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-012,"The system shall use CBOR encoding for all MQTT payloads."
+F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-013,"The system shall support automatic reconnection with exponential backoff on connection loss."
+F-COM-02,On-Demand Data Broadcasting,COM,F-COM-02,On-Demand Data Broadcasting,SR-COM-005,"The system shall support on-demand requests from the Main Hub for sensor data."
+F-COM-02,On-Demand Data Broadcasting,COM,F-COM-02,On-Demand Data Broadcasting,SR-COM-006,"The system shall respond to on-demand data requests with the most recent timestamped sensor data within 100ms."
+F-COM-02,On-Demand Data Broadcasting,COM,F-COM-02,On-Demand Data Broadcasting,SR-COM-007,"The system shall include data validity and sensor status information in on-demand responses."
+F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-008,"The system shall support limited peer-to-peer communication between Sensor Hubs using ESP-NOW."
+F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-009,"The system shall allow peer communication for basic coordination functions such as connectivity checks or time synchronization."
+F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-010,"The system shall ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations."
+F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-014,"The system shall encrypt all ESP-NOW peer communication using application-layer encryption (AES-128 minimum)."
+F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-015,"The system shall implement acknowledgment and retry mechanism for ESP-NOW peer communication."
+F-COM-04,Long-Range Fallback Communication,COM,F-COM-04,Long-Range Fallback Communication,SR-COM-016,"The system may support long-range fallback communication using LoRa or cellular (LTE-M/NB-IoT) for farm-scale distances."
+F-COM-04,Long-Range Fallback Communication,COM,F-COM-04,Long-Range Fallback Communication,SR-COM-017,"If implemented, long-range fallback communication shall be used only for emergency alerts and data backup, not for OTA updates."
+F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-001,"The system shall implement a diagnostic code framework for reporting system health, warnings, errors, and fatal faults."
+F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-002,"The system shall assign a unique diagnostic code to each detected fault or abnormal condition."
+F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-003,"The system shall classify diagnostic codes by severity level."
+F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-004,"The system shall associate each diagnostic event with a timestamp and source component."
+F-DIAG-02,Diagnostic Data Storage,DIAG,F-DIAG-02,Diagnostic Data Storage,SR-DIAG-005,"The system shall persist diagnostic events in non-volatile storage."
+F-DIAG-02,Diagnostic Data Storage,DIAG,F-DIAG-02,Diagnostic Data Storage,SR-DIAG-006,"The system shall retain diagnostic data across system resets and power cycles."
+F-DIAG-02,Diagnostic Data Storage,DIAG,F-DIAG-02,Diagnostic Data Storage,SR-DIAG-007,"The system shall implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy."
+F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-008,"The system shall provide a diagnostic session interface for accessing diagnostic data."
+F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-009,"The system shall allow authorized diagnostic sessions to retrieve stored diagnostic events."
+F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-010,"The system shall allow authorized diagnostic sessions to clear diagnostic records."
+F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-011,"The system shall ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations."
+F-DIAG-04,Layered Watchdog System,DIAG,F-DIAG-04,Layered Watchdog System,SR-DIAG-012,"The system shall implement Task Watchdog (Task WDT) to detect deadlocks in FreeRTOS tasks with a baseline timeout of 10 seconds."
+F-DIAG-04,Layered Watchdog System,DIAG,F-DIAG-04,Layered Watchdog System,SR-DIAG-013,"The system shall implement Interrupt Watchdog (Interrupt WDT) to detect hangs within ISRs with a baseline timeout of 3 seconds."
+F-DIAG-04,Layered Watchdog System,DIAG,F-DIAG-04,Layered Watchdog System,SR-DIAG-014,"The system shall implement RTC Watchdog (RTC WDT) as a final safety net for total system freezes with a baseline timeout of 30 seconds."
+F-DATA-01,Persistent Sensor Data Storage,DATA,F-DATA-01,Persistent Sensor Data Storage,SR-DATA-001,"The system shall persist timestamped sensor data in non-volatile storage."
+F-DATA-01,Persistent Sensor Data Storage,DATA,F-DATA-01,Persistent Sensor Data Storage,SR-DATA-002,"The system shall store sensor data together with sensor identifiers, timestamps, and validity status."
+F-DATA-01,Persistent Sensor Data Storage,DATA,F-DATA-01,Persistent Sensor Data Storage,SR-DATA-003,"The system shall support configurable data retention and overwrite policies."
+F-DATA-02,Data Persistence Abstraction (DP Component),DATA,F-DATA-02,Data Persistence Abstraction (DP Component),SR-DATA-004,"The system shall provide a Data Persistence (DP) component as the sole interface for persistent data access."
+F-DATA-02,Data Persistence Abstraction (DP Component),DATA,F-DATA-02,Data Persistence Abstraction (DP Component),SR-DATA-005,"The system shall prevent application and feature modules from directly accessing storage hardware."
+F-DATA-02,Data Persistence Abstraction (DP Component),DATA,F-DATA-02,Data Persistence Abstraction (DP Component),SR-DATA-006,"The DP component shall support serialization and deserialization of structured system data."
+F-DATA-03,Safe Data Handling During State Transitions,DATA,F-DATA-03,Safe Data Handling During State Transitions,SR-DATA-007,"The system shall ensure that all critical runtime data is flushed to non-volatile storage before entering a controlled teardown or reset."
+F-DATA-03,Safe Data Handling During State Transitions,DATA,F-DATA-03,Safe Data Handling During State Transitions,SR-DATA-008,"The system shall protect data integrity during firmware updates and configuration changes."
+F-DATA-03,Safe Data Handling During State Transitions,DATA,F-DATA-03,Safe Data Handling During State Transitions,SR-DATA-009,"The system shall verify successful data persistence before completing a state transition."
+F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-010,"The system shall detect brownout conditions using hardware brownout detector (BOD) at 3.0V threshold."
+F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-011,"The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection."
+F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-012,"The system shall complete data flush operations within supercapacitor runtime (1-2 seconds) during brownout."
+F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-013,"The system shall implement wear-aware batch writing to prevent SD card wear."
+F-OTA-01,OTA Update Negotiation,OTA,F-OTA-01,OTA Update Negotiation,SR-OTA-001,"The system shall support OTA update negotiation initiated by the Main Hub."
+F-OTA-01,OTA Update Negotiation,OTA,F-OTA-01,OTA Update Negotiation,SR-OTA-002,"The system shall verify internal readiness before accepting an OTA update request."
+F-OTA-01,OTA Update Negotiation,OTA,F-OTA-01,OTA Update Negotiation,SR-OTA-003,"The system shall explicitly acknowledge or reject OTA requests."
+F-OTA-02,Firmware Reception and Storage,OTA,F-OTA-02,Firmware Reception and Storage,SR-OTA-004,"The system shall receive firmware images over the established communication channel (HTTPS or MQTT)."
+F-OTA-02,Firmware Reception and Storage,OTA,F-OTA-02,Firmware Reception and Storage,SR-OTA-005,"The system shall store received firmware images in non-volatile storage (SD card) prior to validation."
+F-OTA-02,Firmware Reception and Storage,OTA,F-OTA-02,Firmware Reception and Storage,SR-OTA-006,"The system shall prevent overwriting the active firmware during firmware reception."
+F-OTA-03,Firmware Integrity Validation,OTA,F-OTA-03,Firmware Integrity Validation,SR-OTA-007,"The system shall validate the integrity of the received firmware image before activation using SHA-256 hash."
+F-OTA-03,Firmware Integrity Validation,OTA,F-OTA-03,Firmware Integrity Validation,SR-OTA-008,"The system shall reject firmware images that fail integrity validation."
+F-OTA-03,Firmware Integrity Validation,OTA,F-OTA-03,Firmware Integrity Validation,SR-OTA-009,"The system shall report firmware validation results to the Main Hub."
+F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-010,"The system shall execute a controlled teardown before firmware activation."
+F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-011,"The system shall persist critical runtime data and calibration data prior to firmware flashing."
+F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-012,"The system shall activate new firmware only after successful integrity validation."
+F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-013,"The system shall reboot into the new firmware after successful activation."
+F-OTA-05,A/B Partitioning with Rollback,OTA,F-OTA-05,A/B Partitioning with Rollback,SR-OTA-014,"The system shall implement A/B partitioning for safe firmware updates."
+F-OTA-05,A/B Partitioning with Rollback,OTA,F-OTA-05,A/B Partitioning with Rollback,SR-OTA-015,"The system shall automatically rollback to previous firmware if new firmware fails validation or health check."
+F-OTA-05,A/B Partitioning with Rollback,OTA,F-OTA-05,A/B Partitioning with Rollback,SR-OTA-016,"The system shall report rollback events to the Main Hub."
+F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-001,"The system shall verify the authenticity of the firmware image before execution during every boot cycle using Secure Boot V2."
+F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-002,"The system shall prevent execution of firmware images that fail cryptographic verification."
+F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-003,"The system shall enter BOOT_FAILURE state upon secure boot verification failure."
+F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-004,"The system shall protect the root-of-trust against modification (eFuse protection)."
+F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-005,"The system shall protect sensitive data stored in internal flash memory from unauthorized access using Flash Encryption (AES-256)."
+F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-006,"The system shall support encryption of sensitive data stored in external storage devices (SD card)."
+F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-007,"The system shall restrict access to cryptographic keys to authorized system components only."
+F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-008,"The system shall ensure data integrity for stored configuration and machine constant files."
+F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-009,"The system shall encrypt all communication with the Main Hub using TLS 1.2 with mutual authentication (mTLS)."
+F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-010,"The system shall ensure integrity and authenticity of all received and transmitted messages."
+F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-011,"The system shall use secure communication channels for OTA firmware updates."
+F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-012,"The system shall detect and report communication security violations."
+F-SEC-04,Security Violation Handling,SEC,F-SEC-04,Security Violation Handling,SR-SEC-013,"The system shall report security violations as FATAL diagnostic events."
+F-SEC-04,Security Violation Handling,SEC,F-SEC-04,Security Violation Handling,SR-SEC-014,"The system shall implement eFuse-based anti-rollback to prevent downgrade attacks."
+F-SEC-04,Security Violation Handling,SEC,F-SEC-04,Security Violation Handling,SR-SEC-015,"The system shall protect cryptographic keys during power loss and system resets."
+F-SYS-01,System State Management,SYS,F-SYS-01,System State Management,SR-SYS-001,"The system shall implement a defined finite state machine for operational control."
+F-SYS-01,System State Management,SYS,F-SYS-01,System State Management,SR-SYS-002,"The system shall restrict operations based on the current system state."
+F-SYS-01,System State Management,SYS,F-SYS-01,System State Management,SR-SYS-003,"The system shall notify system components of state transitions."
+F-SYS-02,Controlled Teardown Mechanism,SYS,F-SYS-02,Controlled Teardown Mechanism,SR-SYS-004,"The system shall execute a controlled teardown sequence before firmware or machine constant updates."
+F-SYS-02,Controlled Teardown Mechanism,SYS,F-SYS-02,Controlled Teardown Mechanism,SR-SYS-005,"The system shall persist all critical runtime data before completing teardown."
+F-SYS-02,Controlled Teardown Mechanism,SYS,F-SYS-02,Controlled Teardown Mechanism,SR-SYS-006,"The system shall prevent data corruption during teardown and reset operations."
+F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-007,"The system shall provide a local OLED display using I2C communication."
+F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-008,"The system shall display connectivity status, system state, sensor summary, and time/date."
+F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-009,"The system shall provide menu navigation using Up, Down, and Select buttons."
+F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-010,"The system shall provide diagnostic, sensor, and health information via the local menu."
+F-SYS-04,Debug & Engineering Sessions,SYS,F-SYS-04,Debug & Engineering Sessions,SR-SYS-011,"The system shall support diagnostic sessions for retrieving logs and system status."
+F-SYS-04,Debug & Engineering Sessions,SYS,F-SYS-04,Debug & Engineering Sessions,SR-SYS-012,"The system shall support debug sessions for controlled engineering operations."
+F-SYS-04,Debug & Engineering Sessions,SYS,F-SYS-04,Debug & Engineering Sessions,SR-SYS-013,"The system shall restrict debug actions to authorized sessions only."
+F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-014,"The system shall enforce GPIO discipline by avoiding strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O."
+F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-015,"The system shall ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V)."
+F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-016,"The system shall use ADC1 for all analog sensors when Wi-Fi is active (ADC2 is not available with Wi-Fi)."
+F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-017,"The system shall maintain a canonical GPIO map document as a single source of truth."
+F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-001,"The system shall monitor input voltage and detect brownout conditions below 3.0V."
+F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-002,"The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection."
+F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-003,"The system shall enter graceful shutdown mode during brownout conditions."
+F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-004,"The system shall perform clean reboot after power stabilization."
+F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-005,"The system shall recover gracefully from power interruptions."
+F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-006,"The system shall verify data integrity after power restoration."
+F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-007,"The system shall restore system state from persistent storage after power restoration."
+F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-008,"The system shall report power-loss and recovery events via diagnostics."
+F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-001,"The system shall provide a Sensor Abstraction Layer (SAL) for all sensor access."
+F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-002,"The system shall prevent application layer from directly accessing sensor hardware."
+F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-003,"The system shall track sensor state (INIT, WARMUP, STABLE, DEGRADED, FAILED)."
+F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-004,"The system shall provide sensor validation and health check functions."
+F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-005,"The system shall abstract all hardware interfaces (I2C, SPI, UART, ADC, GPIO) through driver layers."
+F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-006,"The system shall enforce GPIO discipline (no strapping pins, proper pull-ups, ADC1/ADC2 separation)."
+F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-007,"The system shall maintain a canonical GPIO map document."
+F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-008,"The system shall detect and report hardware resource conflicts."

draft/System Design old/system_design/features/[COM] Communication Features.md

@@ -0,0 +1,349 @@
+# Feature Engineering Specification
+
+## Communication Features
+
+**Feature Group ID:** FG-COM  
+**Version:** 2.0  
+**Date:** 2025-01-19  
+**Scope:** Sensor Hub (Sub-Hub only)  
+**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4  
+**Applies To:** Indoor poultry farm sensor hubs  
+**Dependencies:**
+
+*   Sensor Data Acquisition (FG-DAQ)
+*   Data Quality & Calibration (FG-DQC)
+*   Diagnostics & Health Monitoring (FG-DIAG)
+*   Security & Safety Features (FG-SEC)
+
+## 1. Purpose and Objectives
+
+The **Communication Features** define how the Sensor Hub exchanges data and control information with external entities. These features ensure that sensor data, diagnostics, configuration updates, and control requests are transferred in a **reliable, secure, and deterministic manner**.
+
+The communication layer is designed to:
+
+*   Support hierarchical farm architecture (Sensor Hub → Main Hub)
+*   Enable on-demand and event-driven data transfer
+*   Allow limited peer-to-peer communication between Sensor Hubs
+*   Maintain robustness under intermittent connectivity
+
+**Technology Stack:**
+- **Primary Uplink:** Wi-Fi 802.11n (2.4 GHz)
+- **Application Protocol:** MQTT over TLS 1.2
+- **Peer-to-Peer:** ESP-NOW
+- **Payload Encoding:** CBOR (Binary, versioned)
+- **Long-Range Fallback:** LoRa (External Module, optional)
+
+## 2. Feature Overview and Relationships
+
+| Feature ID | Feature Name | Primary Objective | Related Features |
+|------------|--------------|-------------------|------------------|
+| F-COM-01 | Main Hub Communication | Primary uplink/downlink with Main Hub | OTA, Diagnostics, MC Management |
+| F-COM-02 | On-Demand Data Broadcasting | Provide latest data upon request | DAQ, DP Stack |
+| F-COM-03 | Peer Sensor Hub Communication | Limited hub-to-hub coordination | System Management |
+| F-COM-04 | Long-Range Fallback Communication | Farm-scale connectivity resilience | System Management |
+
+## 3. Functional Feature Descriptions
+
+### 3.1 F-COM-01: Main Hub Communication
+
+**Description**  
+The Sensor Hub shall establish and maintain a bidirectional communication channel with the Main Hub using **MQTT over TLS 1.2**.
+
+**Protocol Stack:**
+```
+Application Layer (MQTT)
+    ↓
+Transport Security Layer (TLS 1.2 / mTLS)
+    ↓
+Network Layer (Wi-Fi 802.11n 2.4 GHz)
+    ↓
+Physical Layer
+```
+
+**MQTT Configuration:**
+- **Broker:** Main Hub / Edge Gateway
+- **QoS:** QoS 1 (At least once delivery)
+- **Retain:** Used for configuration topics only
+- **Payload:** CBOR (Binary, versioned for efficiency and compatibility)
+- **Keepalive:** 60 seconds (default)
+- **Maximum Message Size:** 8KB
+
+**Topic Structure:**
+```
+/farm/{site_id}/{house_id}/{node_id}/data/{sensor_id}
+/farm/{site_id}/{house_id}/{node_id}/status/heartbeat
+/farm/{site_id}/{house_id}/{node_id}/status/system
+/farm/{site_id}/{house_id}/{node_id}/cmd/{command_type}
+/farm/{site_id}/{house_id}/{node_id}/diag/{severity}
+/farm/{site_id}/{house_id}/{node_id}/ota/{action}
+```
+
+**Heartbeat Mechanism:**
+- **Interval:** 10 seconds
+- **Timeout:** 3 missed heartbeats (30 seconds) triggers "offline" status
+- **Payload includes:**
+  - Uptime (seconds)
+  - Firmware version (string)
+  - Free heap memory (bytes)
+  - RSSI (signal strength, dBm)
+  - Error bitmap (32-bit)
+  - System state
+
+**Key Capabilities**
+
+*   Bidirectional communication
+*   Command and response handling
+*   Diagnostics and status reporting
+*   Integration with OTA and MC updates
+*   Store-and-forward messaging (handles intermittent connectivity)
+*   Automatic reconnection with exponential backoff
+
+**Wi-Fi Configuration:**
+- **Standard:** 802.11n (2.4 GHz)
+- **Minimum RSSI:** -85 dBm (connection threshold)
+- **Channel Selection:** Automatic (avoid interference)
+- **Power Management:** Active mode (no PSM for real-time requirements)
+
+### 3.2 F-COM-02: On-Demand Data Broadcasting
+
+**Description**  
+The Sensor Hub shall support on-demand transmission of the most recent sensor data upon request from the Main Hub. This allows the Main Hub to query real-time conditions without waiting for periodic reporting cycles.
+
+**Response Time:** Maximum 100ms from request to response transmission.
+
+Data broadcasts include timestamped sensor values and associated validity status.
+
+**Key Capabilities**
+
+*   Request/response data exchange
+*   Latest-value data delivery
+*   Timestamp and validity inclusion
+*   Low-latency response (≤100ms)
+
+### 3.3 F-COM-03: Peer Sensor Hub Communication
+
+**Description**  
+Sensor Hubs shall be capable of limited peer-to-peer communication using **ESP-NOW** for coordination purposes such as connectivity checks, time synchronization assistance, or basic status exchange.
+
+**ESP-NOW Configuration:**
+- **Protocol:** ESP-NOW (deterministic, low-latency)
+- **Range:** ~200m line-of-sight, ~50m through walls
+- **Maximum Peers:** 20
+- **Security:** Application-layer encryption (AES-128 minimum) required
+- **Acknowledgment:** Application-layer acknowledgment and retry mechanism
+
+**Message Types:**
+- `PEER_PING`: Connectivity check
+- `PEER_PONG`: Connectivity response
+- `PEER_TIME_SYNC`: Time synchronization request
+- `PEER_TIME_RESP`: Time synchronization response
+
+**Key Capabilities**
+
+*   Hub-to-hub message exchange
+*   Minimal command set
+*   No dependency on centralized infrastructure
+*   Isolation from control logic
+*   Encrypted communication (application-layer)
+
+**Constraints:**
+- Peer communication SHALL NOT interfere with Main Hub communication
+- Peer communication SHALL be limited to coordination functions only
+- Maximum peer count: 20 (ESP-NOW limitation)
+
+### 3.4 F-COM-04: Long-Range Fallback Communication [NEW]
+
+**Description**  
+The system supports optional long-range fallback communication using **LoRa (External Module)** for farm-scale distances where Wi-Fi may not reach.
+
+**Note:** This feature is **optional** and requires cost-benefit analysis. Alternative: Cellular (LTE-M/NB-IoT) if farm has cellular coverage.
+
+**LoRa Configuration (if implemented):**
+- **Module:** External LoRa module (e.g., SX1276, SX1262)
+- **Protocol:** LoRaWAN or raw LoRa
+- **Use Cases:** Emergency alerts, data backup (not for OTA updates)
+- **Data Rate:** Low (may not support OTA updates)
+
+**Alternative Consideration:**
+- **Cellular (LTE-M/NB-IoT):** Higher data rate, better for OTA updates, more expensive but more reliable in some regions
+
+## 4. System Requirements (Formal SHALL Statements)
+
+### 4.1 Main Hub Communication
+
+**SR-COM-001**  
+The system shall support bidirectional communication between the Sensor Hub and the Main Hub using MQTT over TLS 1.2.
+
+**SR-COM-002**  
+The system shall transmit sensor data, diagnostics, and system status information to the Main Hub via MQTT.
+
+**SR-COM-003**  
+The system shall receive commands, configuration updates, and firmware update requests from the Main Hub via MQTT.
+
+**SR-COM-004**  
+The system shall monitor and report the communication link status with the Main Hub.
+
+**SR-COM-011** [NEW]  
+The system shall implement a heartbeat mechanism with 10-second interval and 30-second timeout.
+
+**SR-COM-012** [NEW]  
+The system shall use CBOR encoding for all MQTT payloads.
+
+**SR-COM-013** [NEW]  
+The system shall support automatic reconnection with exponential backoff on connection loss.
+
+### 4.2 On-Demand Data Broadcasting
+
+**SR-COM-005**  
+The system shall support on-demand requests from the Main Hub for sensor data.
+
+**SR-COM-006**  
+The system shall respond to on-demand data requests with the most recent timestamped sensor data within 100ms.
+
+**SR-COM-007**  
+The system shall include data validity and sensor status information in on-demand responses.
+
+### 4.3 Peer Sensor Hub Communication
+
+**SR-COM-008**  
+The system shall support limited peer-to-peer communication between Sensor Hubs using ESP-NOW.
+
+**SR-COM-009**  
+The system shall allow peer communication for basic coordination functions such as connectivity checks or time synchronization.
+
+**SR-COM-010**  
+The system shall ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations.
+
+**SR-COM-014** [NEW]  
+The system shall encrypt all ESP-NOW peer communication using application-layer encryption (AES-128 minimum).
+
+**SR-COM-015** [NEW]  
+The system shall implement acknowledgment and retry mechanism for ESP-NOW peer communication.
+
+### 4.4 Long-Range Fallback Communication [NEW]
+
+**SR-COM-016** [NEW]  
+The system may support long-range fallback communication using LoRa or cellular (LTE-M/NB-IoT) for farm-scale distances.
+
+**SR-COM-017** [NEW]  
+If implemented, long-range fallback communication shall be used only for emergency alerts and data backup, not for OTA updates.
+
+## 5. Technology Specifications
+
+### 5.1 Wi-Fi 802.11n (2.4 GHz)
+
+**Rationale:**
+- Native ESP32-S3 support
+- Existing farm infrastructure compatibility
+- Mature ESP-IDF drivers
+- High data rate for OTA firmware updates (150 Mbps theoretical, ~20-30 Mbps practical)
+- Good range and penetration for farm structures
+
+**Configuration:**
+- **Standard:** 802.11n
+- **Frequency:** 2.4 GHz
+- **Minimum RSSI:** -85 dBm
+- **Channel Selection:** Automatic
+- **Power Management:** Active mode
+
+### 5.2 MQTT Protocol
+
+**Rationale:**
+- Store-and-forward messaging (handles intermittent connectivity gracefully)
+- Built-in keepalive mechanism (monitors connection health automatically)
+- QoS levels for delivery guarantees
+- Massive industrial adoption (SCADA, IIoT)
+- Native ESP-IDF support (esp_mqtt component)
+
+**Configuration:**
+- **QoS Level:** 1 (At least once delivery)
+- **Retain Flag:** Used for configuration topics only
+- **Keepalive:** 60 seconds
+- **Maximum Message Size:** 8KB
+- **Broker Compatibility:** Mosquitto 2.x, HiveMQ, or compatible
+
+### 5.3 TLS 1.2 / mTLS
+
+**Rationale:**
+- Strong security (mutual authentication)
+- Industry standard
+- ESP-IDF native support (mbedTLS)
+- Prevents man-in-the-middle attacks
+
+**Configuration:**
+- **TLS Version:** 1.2 (minimum)
+- **Authentication:** Mutual TLS (mTLS)
+- **Certificate:** Device-unique X.509 certificate
+- **Private Key:** Stored in eFuse or encrypted flash
+- **Maximum Certificate Size:** <2KB (ESP32-S3 optimization)
+
+### 5.4 ESP-NOW
+
+**Rationale:**
+- Deterministic, low-latency communication
+- No AP dependency
+- Native ESP32-S3 support
+- Low power consumption
+
+**Configuration:**
+- **Maximum Peers:** 20
+- **Security:** Application-layer encryption (AES-128 minimum)
+- **Acknowledgment:** Application-layer implementation required
+
+### 5.5 CBOR Encoding
+
+**Rationale:**
+- Binary format (efficient, ~30-50% smaller than JSON)
+- Versioned payloads (backward compatibility)
+- Standardized (RFC 8949)
+- Good library support (TinyCBOR, QCBOR)
+
+**Configuration:**
+- **Schema Versioning:** Required
+- **Maximum Payload Size:** 8KB per message type
+- **Schema Validation:** On Main Hub side
+
+## 6. Traceability Mapping
+
+### 6.1 Feature → System Requirement Mapping
+
+```mermaid
+graph TD
+    F-COM-01 -->|Main Hub Communication| SR-COM-001
+    F-COM-01 -->|Transmit Data| SR-COM-002
+    F-COM-01 -->|Receive Commands| SR-COM-003
+    F-COM-01 -->|Monitor Link Status| SR-COM-004
+    F-COM-01 -->|Heartbeat| SR-COM-011
+    F-COM-01 -->|CBOR Encoding| SR-COM-012
+    F-COM-01 -->|Auto Reconnect| SR-COM-013
+
+    F-COM-02 -->|On-Demand Requests| SR-COM-005
+    F-COM-02 -->|Respond with Data| SR-COM-006
+    F-COM-02 -->|Include Validity Info| SR-COM-007
+
+    F-COM-03 -->|Peer Communication| SR-COM-008
+    F-COM-03 -->|Peer Coordination| SR-COM-009
+    F-COM-03 -->|Isolate Peer Traffic| SR-COM-010
+    F-COM-03 -->|ESP-NOW Encryption| SR-COM-014
+    F-COM-03 -->|ESP-NOW Acknowledgment| SR-COM-015
+
+    F-COM-04 -->|Long-Range Fallback| SR-COM-016
+    F-COM-04 -->|Fallback Use Cases| SR-COM-017
+```
+
+## 7. Engineering Notes and Constraints
+
+*   **MQTT Broker Compatibility:** Specify broker version (e.g., Mosquitto 2.x, HiveMQ)
+*   **Message Size Limits:** Maximum 8KB per message
+*   **Topic Naming:** Follow hierarchical structure `/farm/{site}/{house}/{node}/...`
+*   **Security:** All communication encrypted via TLS 1.2 / mTLS (defined under Security Features)
+*   **ESP-NOW Security:** Application-layer encryption required (AES-128 minimum)
+*   **Communication failures** shall trigger diagnostics events but shall not block sensor acquisition
+*   **LoRa Fallback:** Optional feature requiring cost-benefit analysis
+
+## 8. Dependencies
+
+*   **Security Features:** TLS/mTLS implementation
+*   **System Management:** State-aware communication restrictions
+*   **Diagnostics:** Communication failure reporting
+*   **Data Acquisition:** Sensor data for transmission

draft/System Design old/system_design/features/[DAQ] Sensor Data Acquisition Features.md

@@ -0,0 +1,339 @@
+# **ASF Sensor Hub**
+
+## **Feature Engineering Specification**
+
+## **Sensor Data Acquisition Features**
+
+## **1\. Feature Overview**
+
+### **Feature Name**
+
+Sensor Data Acquisition Features
+
+### **Feature ID**
+
+FEAT-DAQ
+
+### **Subsystem**
+
+ASF Sensor Hub (Sub-Hub)
+
+### **Target Platform**
+
+ESP32-S3–based embedded system
+
+### **Scope**
+
+This feature defines the capabilities of the Sensor Hub related to:
+
+*   Environmental sensor data acquisition
+    
+*   Local preprocessing and filtering
+    
+*   Timestamping and preparation of sensor data for persistence and communication
+    
+
+This feature **does NOT include**:
+
+*   Main Hub processing
+    
+*   Cloud analytics
+    
+*   Control logic
+    
+*   OTA, diagnostics, or persistence mechanisms (referenced only as dependencies)
+    
+
+## **2\. Purpose and Engineering Rationale**
+
+Modern poultry farm automation systems require **high-resolution, reliable, and time-correlated environmental data** to enable:
+
+*   Accurate environmental control
+    
+*   Early fault detection
+    
+*   Advanced analytics and machine learning
+    
+
+The Sensor Data Acquisition feature ensures:
+
+*   Deterministic sensor sampling
+    
+*   Noise-resilient measurements
+    
+*   Temporal traceability of data
+    
+*   Decoupling of acquisition from communication and control
+    
+
+This aligns with **distributed intelligence principles** used in leading international poultry automation systems.
+
+## **3\. Feature Decomposition**
+
+The Sensor Data Acquisition feature is decomposed into the following sub-features:
+
+<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Sub-Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Name</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Multi-Sensor Data Acquisition</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">High-Frequency Sampling and Local Filtering</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Timestamped Sensor Data Generation</p></td></tr></tbody></table></figure>
+
+## **4\. Functional Description**
+
+### **4.1 F-DAQ-01: Multi-Sensor Data Acquisition**
+
+#### **Description**
+
+The Sensor Hub acquires environmental data from multiple heterogeneous sensors connected to dedicated hardware interfaces.
+
+#### **Supported Sensor Types**
+
+*   Temperature
+    
+*   Relative Humidity
+    
+*   Carbon Dioxide (CO₂)
+    
+*   Ammonia (NH₃)
+    
+*   Volatile Organic Compounds (VOC)
+    
+*   Particulate Matter (PM)
+    
+*   Light Intensity
+    
+
+Each sensor:
+
+*   Is mapped to a predefined hardware slot
+    
+*   Has a dedicated driver abstraction
+    
+*   Can be independently enabled or disabled
+    
+
+#### **Key Characteristics**
+
+*   Concurrent sensor handling
+    
+*   Modular sensor driver architecture
+    
+*   Runtime awareness of sensor presence
+    
+
+### **4.2 F-DAQ-02: High-Frequency Sampling and Local Filtering**
+
+#### **Description**
+
+For each enabled sensor, the system performs multiple raw readings per acquisition cycle and applies a local filtering mechanism to produce a single representative value.
+
+#### **Sampling Behavior**
+
+*   Each sensor is sampled **N times per cycle** (default: 10)
+    
+*   Sampling occurs within a bounded time window
+    
+*   Sampling frequency is configurable via Machine Constants
+    
+
+#### **Filtering Behavior**
+
+*   Filtering is executed locally on the Sensor Hub
+    
+*   Filtering algorithms are abstracted and replaceable
+    
+*   Examples (non-exhaustive):
+    
+    *   Moving average
+        
+    *   Median filter
+        
+    *   Outlier rejection
+        
+
+#### **Objective**
+
+*   Reduce sensor noise
+    
+*   Improve data stability
+    
+*   Avoid propagating raw sensor jitter upstream
+    
+
+### **4.3 F-DAQ-03: Timestamped Sensor Data Generation**
+
+#### **Description**
+
+Each processed sensor value is associated with a timestamp generated by the Sensor Hub.
+
+#### **Timestamp Characteristics**
+
+*   Generated after filtering completion
+    
+*   Represents the effective measurement time
+    
+*   Based on system time (RTC or synchronized clock)
+    
+
+#### **Sensor Data Record**
+
+Each record includes:
+
+*   Sensor ID
+    
+*   Sensor type
+    
+*   Filtered value
+    
+*   Unit of measurement
+    
+*   Timestamp
+    
+*   Data validity status
+    
+
+## **5\. Operational Flow**
+
+### **Normal Acquisition Cycle**
+
+1.  Detect enabled sensors
+    
+2.  Initialize sensor drivers (if not already active)
+    
+3.  Perform high-frequency sampling per sensor
+    
+4.  Apply local filtering
+    
+5.  Generate timestamp
+    
+6.  Create sensor data record
+    
+7.  Forward data to:
+    
+    *   Data Persistence component
+        
+    *   Communication component (on request)
+        
+
+## **6\. Constraints and Assumptions**
+
+### **Constraints**
+
+*   Sensor acquisition must not block system-critical tasks
+    
+*   Sampling and filtering must complete within a bounded cycle time
+    
+*   Memory usage must be deterministic
+    
+
+### **Assumptions**
+
+*   Sensor presence detection is handled by a separate feature
+    
+*   Time synchronization is provided by another system component
+    
+*   Storage and communication are decoupled from acquisition
+    
+
+## **7\. Architecture Diagram (PlantUML)**
+
+### **7.1 Sensor Hub Component Diagram**
+
+```mermaid
+graph TD
+    subgraph "Sensor Hub"
+        SD["Sensor Drivers"] --> SE["Sampling Engine"]
+        SE --> FE["Filtering Engine"]
+        FE --> TS["Timestamp Service"]
+        TS --> DB["Sensor Data Buffer"]
+    end
+    SD -->|"raw samples"| SE
+    SE -->|"sampled data"| FE
+    FE -->|"filtered value"| TS
+    TS -->|"timestamped record"| DB
+```
+
+### **7.2 Acquisition Cycle Sequence Diagram**
+
+```mermaid
+sequenceDiagram
+    participant S as Sensor Driver
+    participant SE as Sampling Engine
+    participant FE as Filtering Engine
+    participant TS as Timestamp Service
+    S ->> SE: read()
+    loop N samples
+        SE ->> S: sample()
+    end
+    SE ->> FE: raw sample set
+    FE ->> TS: filtered value
+    TS ->> FE: timestamp
+```
+
+## **8\. Formal System SHALL Requirements**
+
+### **8.1 Requirement Style**
+
+*   Each requirement uses **“The system shall …”**
+    
+*   Each requirement has a unique ID
+    
+*   Requirements are atomic and testable
+    
+
+### **8.2 Requirements List**
+
+#### **Multi-Sensor Acquisition**
+
+*   **SR-DAQ-001**  
+    The system shall support acquisition of data from multiple environmental sensor types simultaneously.
+    
+*   **SR-DAQ-002**  
+    The system shall provide a dedicated software driver abstraction for each supported sensor type.
+    
+*   **SR-DAQ-003**  
+    The system shall acquire sensor data only from sensors detected as present and enabled.
+    
+
+#### **High-Frequency Sampling &amp; Filtering**
+
+*   **SR-DAQ-004**  
+    The system shall sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples).
+    
+*   **SR-DAQ-005**  
+    The system shall apply a local filtering mechanism to raw sensor samples to produce a single representative value.
+    
+*   **SR-DAQ-006**  
+    The system shall allow configuration of sampling count and filtering parameters via system configuration data (Machine Constants).
+    
+*   **SR-DAQ-010**  
+    The system shall complete sensor acquisition cycle within a maximum of 100ms per sensor.
+    
+
+#### **Timestamped Data Generation**
+
+*   **SR-DAQ-007**  
+    The system shall associate each processed sensor value with a timestamp.
+    
+*   **SR-DAQ-008**  
+    The system shall generate timestamps after completion of filtering.
+    
+*   **SR-DAQ-009**  
+    The system shall include sensor identifier, sensor type, value, unit, timestamp, and validity status in each sensor data record.
+
+#### **Sensor State Management**
+
+*   **SR-DAQ-011**  
+    The system shall track sensor operational states (INIT, WARMUP, STABLE, DEGRADED, FAILED).
+    
+*   **SR-DAQ-012**  
+    The system shall never publish raw sensor values without an accompanying validity flag indicating the current state.
+    
+*   **SR-DAQ-013**  
+    The system shall enforce sensor warmup durations (CO2: 30 seconds, Temperature: 5 seconds, others: sensor-specific).
+    
+
+## **9\. Feature-to-Requirement Traceability**
+
+| Feature ID | System Requirements |
+|------------|---------------------|
+| F-DAQ-01 | SR-DAQ-001, SR-DAQ-002, SR-DAQ-003 |
+| F-DAQ-02 | SR-DAQ-004, SR-DAQ-005, SR-DAQ-006, SR-DAQ-010 |
+| F-DAQ-03 | SR-DAQ-007, SR-DAQ-008, SR-DAQ-009 |
+| F-DAQ-04 | SR-DAQ-011, SR-DAQ-012, SR-DAQ-013 |

draft/System Design old/system_design/features/[DATA] Persistence & Data Management Features.md

@@ -0,0 +1,192 @@
+<macro class="toc op-uc-placeholder op-uc-toc">
+</macro>
+
+# Feature Engineering Specification
+
+## Persistence &amp; Data Management Features
+
+**Feature Group ID:** FG-DATA  
+**Scope:** Sensor Hub (Sub-Hub only)  
+**Target Platform:** ESP32-S3–based Sensor Hub  
+**Applies To:** Indoor poultry farm sensor hubs  
+**Dependencies:**
+
+*   Sensor Data Acquisition (FG-DAQ)
+    
+*   Data Quality &amp; Calibration (FG-DQC)
+    
+*   Diagnostics &amp; Health Monitoring (FG-DIAG)
+    
+*   System State Management / Teardown Mechanism
+    
+
+## 1\. Purpose and Objectives
+
+The **Persistence &amp; Data Management Features** define how the Sensor Hub stores, protects, and manages critical runtime and historical data. These features ensure that:
+
+*   Sensor data and system state are not lost during resets or failures
+    
+*   Data storage is abstracted from application logic
+    
+*   Critical data is safely handled during firmware updates, configuration changes, or fatal faults
+    
+
+The persistence layer is a **foundational system service**, supporting diagnostics, calibration, OTA, and recovery operations.
+
+## 2\. Feature Overview and Relationships
+
+<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Persistent Sensor Data Storage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Store timestamped sensor data</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DAQ, COM</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Data Persistence Abstraction (DP)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Abstract storage access</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Application Layer</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Safe Data Handling During State Transitions</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Protect data during teardown</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OTA, System Mgmt</p></td></tr></tbody></table></figure>
+
+## 3\. Functional Feature Descriptions
+
+### 3.1 F-DATA-01: Persistent Sensor Data Storage
+
+**Description**  
+The system shall persist timestamped sensor data to non-volatile storage to support historical analysis, diagnostics correlation, and recovery scenarios.
+
+Persistence may include:
+
+*   Filtered sensor values
+    
+*   Timestamps
+    
+*   Sensor validity and status metadata
+    
+
+The persistence policy (frequency, retention window, overwrite behavior) is configurable and optimized for storage longevity and performance.
+
+**Key Capabilities**
+
+*   Non-volatile storage (SD card / NVM)
+    
+*   Timestamped records
+    
+*   Configurable retention policy
+    
+*   Integration with DAQ and COM
+    
+
+### 3.2 F-DATA-02: Data Persistence Abstraction (DP Component)
+
+**Description**  
+The system shall provide a **Data Persistence (DP) component** that abstracts storage access for all upper layers. Application and feature modules interact with the DP component rather than directly accessing storage hardware.
+
+The DP component manages:
+
+*   Data model definitions
+    
+*   Serialization and deserialization
+    
+*   Storage backend selection
+    
+*   Consistency and integrity guarantees
+    
+
+**Key Capabilities**
+
+*   Unified persistence API
+    
+*   Storage backend abstraction
+    
+*   Centralized data ownership
+    
+*   Reduced coupling between layers
+    
+
+### 3.3 F-DATA-03: Safe Data Handling During State Transitions
+
+**Description**  
+The system shall ensure safe and deterministic handling of data during critical state transitions, including:
+
+*   Firmware updates (OTA)
+    
+*   Machine Constants updates
+    
+*   System resets
+    
+*   Fatal error handling
+    
+
+Before entering such transitions, the system executes a controlled data finalization process to flush buffers, persist critical state, and verify data integrity.
+
+**Key Capabilities**
+
+*   Controlled data flush
+    
+*   Atomic write operations
+    
+*   Data integrity checks
+    
+*   Coordination with teardown mechanism
+    
+
+## 4\. System Requirements (Formal SHALL Statements)
+
+### 4.1 Persistent Sensor Data Storage
+
+**SR-DATA-001**  
+The system shall persist timestamped sensor data in non-volatile storage.
+
+**SR-DATA-002**  
+The system shall store sensor data together with sensor identifiers, timestamps, and validity status.
+
+**SR-DATA-003**  
+The system shall support configurable data retention and overwrite policies.
+
+### 4.2 Data Persistence Abstraction (DP Component)
+
+**SR-DATA-004**  
+The system shall provide a Data Persistence (DP) component as the sole interface for persistent data access.
+
+**SR-DATA-005**  
+The system shall prevent application and feature modules from directly accessing storage hardware.
+
+**SR-DATA-006**  
+The DP component shall support serialization and deserialization of structured system data.
+
+### 4.3 Safe Data Handling During State Transitions
+
+**SR-DATA-007**  
+The system shall ensure that all critical runtime data is flushed to non-volatile storage before entering a controlled teardown or reset.
+
+**SR-DATA-008**  
+The system shall protect data integrity during firmware updates and configuration changes.
+
+**SR-DATA-009**  
+The system shall verify successful data persistence before completing a state transition.
+
+### 4.4 Power-Loss Data Protection [NEW]
+
+**SR-DATA-010**  
+The system shall detect brownout conditions using hardware brownout detector (BOD) at 3.0V threshold.
+
+**SR-DATA-011**  
+The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection.
+
+**SR-DATA-012**  
+The system shall complete data flush operations within supercapacitor runtime (1-2 seconds) during brownout.
+
+**SR-DATA-013**  
+The system shall implement wear-aware batch writing to prevent SD card wear.
+
+## 5\. Feature ↔ System Requirement Mapping
+
+| Feature ID | System Requirements |
+|------------|---------------------|
+| F-DATA-01 | SR-DATA-001, SR-DATA-002, SR-DATA-003 |
+| F-DATA-02 | SR-DATA-004, SR-DATA-005, SR-DATA-006 |
+| F-DATA-03 | SR-DATA-007, SR-DATA-008, SR-DATA-009 |
+| F-DATA-04 | SR-DATA-010, SR-DATA-011, SR-DATA-012, SR-DATA-013 |
+
+## 6\. Engineering Notes
+
+*   The DP component aligns with your **DP Stack** already defined in the architecture.
+    
+*   Atomic write strategies (e.g., temp file + rename) are recommended.
+    
+*   Diagnostic events should be generated on persistence failures.
+    
+*   Storage wear-leveling considerations apply for SD/NVM.
+    
+
+##

draft/System Design old/system_design/features/[DIAG] Diagnostics & Health Monitoring Features.md

@@ -0,0 +1,183 @@
+<macro class="toc op-uc-placeholder op-uc-toc">
+</macro>
+
+# Feature Engineering Specification
+
+## Diagnostics &amp; Health Monitoring Features
+
+**Feature Group ID:** FG-DIAG  
+**Scope:** Sensor Hub (Sub-Hub only)  
+**Target Platform:** ESP32-S3–based Sensor Hub  
+**Applies To:** Indoor poultry farm sensor hubs  
+**Dependencies:**
+
+*   Sensor Data Acquisition (FG-DAQ)
+    
+*   Data Quality &amp; Calibration (FG-DQC)
+    
+*   Communication Features (FG-COM)
+    
+*   Persistence / DP Stack
+    
+
+## 1\. Purpose and Objectives
+
+The **Diagnostics &amp; Health Monitoring Features** provide a structured and persistent mechanism to detect, classify, record, and expose system faults, warnings, and health states.
+
+These features ensure that:
+
+*   Failures are detectable and explainable
+    
+*   Root causes are traceable
+    
+*   Diagnostic data survives resets and power loss
+    
+*   Engineers can access diagnostic information locally or remotely
+    
+
+The diagnostics subsystem is **non-intrusive**, meaning it shall not block core sensing or communication functions unless the system enters a fatal state.
+
+## 2\. Feature Overview and Relationships
+
+<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Diagnostic Code Management</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Standardize fault and warning identification</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DQC, COM</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Diagnostic Data Storage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Persist diagnostic events</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DP Stack</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Diagnostic Session</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Engineer access to diagnostics</p></td><td class="op-uc-table--cell"><p class="op-uc-p">COM, System Mgmt</p></td></tr></tbody></table></figure>
+
+## 3\. Functional Feature Descriptions
+
+### 3.1 F-DIAG-01: Diagnostic Code Management
+
+**Description**  
+The system shall implement a structured diagnostic code framework to represent system health conditions, warnings, errors, and fatal faults.
+
+Each diagnostic event is associated with:
+
+*   A unique diagnostic code
+    
+*   Severity level (info, warning, error, fatal)
+    
+*   A hierarchical root-cause classification
+    
+*   Timestamp and source component
+    
+
+This framework enables consistent fault handling across all system components.
+
+**Key Capabilities**
+
+*   Unique diagnostic code registry
+    
+*   Severity classification
+    
+*   Root-cause hierarchy
+    
+*   Event-based reporting
+    
+
+### 3.2 F-DIAG-02: Diagnostic Data Storage
+
+**Description**  
+The system shall persist diagnostic events in non-volatile storage to allow post-failure analysis and long-term health monitoring.
+
+Stored diagnostics remain available across system resets and power cycles until explicitly cleared by an authorized diagnostic session or command.
+
+**Key Capabilities**
+
+*   Persistent storage of diagnostic events
+    
+*   Timestamped records
+    
+*   Bounded storage with overwrite policy
+    
+*   Integration with DP / Persistence layer
+    
+
+### 3.3 F-DIAG-03: Diagnostic Session
+
+**Description**  
+The system shall provide a diagnostic session that allows authorized engineers or tools to access diagnostic data, inspect system health, and perform maintenance operations.
+
+The diagnostic session may be accessed locally or remotely via the communication interface and supports read and limited control operations.
+
+**Key Capabilities**
+
+*   Session-based access
+    
+*   Read diagnostics and health data
+    
+*   Clear diagnostic records
+    
+*   Controlled command execution
+    
+
+## 4\. System Requirements (Formal SHALL Statements)
+
+### 4.1 Diagnostic Code Management
+
+**SR-DIAG-001**  
+The system shall implement a diagnostic code framework for reporting system health, warnings, errors, and fatal faults.
+
+**SR-DIAG-002**  
+The system shall assign a unique diagnostic code to each detected fault or abnormal condition.
+
+**SR-DIAG-003**  
+The system shall classify diagnostic codes by severity level.
+
+**SR-DIAG-004**  
+The system shall associate each diagnostic event with a timestamp and source component.
+
+### 4.2 Diagnostic Data Storage
+
+**SR-DIAG-005**  
+The system shall persist diagnostic events in non-volatile storage.
+
+**SR-DIAG-006**  
+The system shall retain diagnostic data across system resets and power cycles.
+
+**SR-DIAG-007**  
+The system shall implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy.
+
+### 4.3 Diagnostic Session
+
+**SR-DIAG-008**  
+The system shall provide a diagnostic session interface for accessing diagnostic data.
+
+**SR-DIAG-009**  
+The system shall allow authorized diagnostic sessions to retrieve stored diagnostic events.
+
+**SR-DIAG-010**  
+The system shall allow authorized diagnostic sessions to clear diagnostic records.
+
+**SR-DIAG-011**  
+The system shall ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations.
+
+### 4.4 Layered Watchdog System [NEW]
+
+**SR-DIAG-012**  
+The system shall implement Task Watchdog (Task WDT) to detect deadlocks in FreeRTOS tasks with a baseline timeout of 10 seconds.
+
+**SR-DIAG-013**  
+The system shall implement Interrupt Watchdog (Interrupt WDT) to detect hangs within ISRs with a baseline timeout of 3 seconds.
+
+**SR-DIAG-014**  
+The system shall implement RTC Watchdog (RTC WDT) as a final safety net for total system freezes with a baseline timeout of 30 seconds.
+
+## 5\. Feature ↔ System Requirement Mapping
+
+| Feature ID | System Requirements |
+|------------|---------------------|
+| F-DIAG-01 | SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004 |
+| F-DIAG-02 | SR-DIAG-005, SR-DIAG-006, SR-DIAG-007 |
+| F-DIAG-03 | SR-DIAG-008, SR-DIAG-009, SR-DIAG-010, SR-DIAG-011 |
+| F-DIAG-04 | SR-DIAG-012, SR-DIAG-013, SR-DIAG-014 |
+
+## 6\. Engineering Notes
+
+*   Diagnostic codes should be versioned to support firmware evolution.
+    
+*   Diagnostic severity may be linked to LED indicators (green/yellow/red).
+    
+*   Fatal diagnostics may trigger the teardown mechanism defined elsewhere.
+    
+*   Security and access control for diagnostic sessions are handled under **Security &amp; Safety Features**.
+    
+
+##

draft/System Design old/system_design/features/[DQC] Data Quality & Calibration Features.md

@@ -0,0 +1,197 @@
+<macro class="toc op-uc-placeholder op-uc-toc">
+</macro>
+
+# Feature Engineering Specification
+
+## Data Quality &amp; Calibration Features
+
+**Feature Group ID:** FG-DQC  
+**Scope:** Sensor Hub (Sub-Hub only)  
+**Target Platform:** ESP32-S3–based Sensor Hub  
+**Applies To:** Indoor poultry farm sensor hubs  
+**Dependencies:** Sensor Data Acquisition Features (FG-DAQ), Diagnostics Features (FG-DIAG), Persistence / DP Stack
+
+## 1\. Purpose and Objectives
+
+The **Data Quality &amp; Calibration Features** ensure that all sensor data generated by the Sensor Hub is **valid, trustworthy, correctly classified, and calibrated** throughout the system lifecycle. These features provide mechanisms for:
+
+*   Automatic identification of connected sensors
+    
+*   Enforcing correct sensor–slot compatibility
+    
+*   Early detection and isolation of faulty sensors
+    
+*   Centralized management of machine constants and calibration parameters
+    
+
+The goal is to maintain **high data integrity**, reduce commissioning errors, support **remote reconfiguration**, and ensure safe operation during updates or failures.
+
+<br>
+
+<macro class="embedded-table op-uc-placeholder op-uc-embedded-table" data-query-props="{&quot;columns[]&quot;:[&quot;id&quot;,&quot;subject&quot;,&quot;type&quot;,&quot;status&quot;,&quot;assignee&quot;,&quot;priority&quot;],&quot;showSums&quot;:false,&quot;timelineVisible&quot;:false,&quot;highlightingMode&quot;:&quot;none&quot;,&quot;includeSubprojects&quot;:true,&quot;showHierarchies&quot;:true,&quot;groupBy&quot;:&quot;&quot;,&quot;filters&quot;:&quot;[{\&quot;search\&quot;:{\&quot;operator\&quot;:\&quot;**\&quot;,\&quot;values\&quot;:[\&quot;DQC\&quot;]}}]&quot;,&quot;sortBy&quot;:&quot;[[\&quot;id\&quot;,\&quot;asc\&quot;]]&quot;,&quot;timestamps&quot;:&quot;PT0S&quot;}">
+</macro>
+
+## 2\. Feature Overview and Relationships
+
+<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Automatic Sensor Detection</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Detect connected sensors dynamically</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-01, F-DIAG-01</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Sensor Type Enforcement</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Prevent incorrect sensor-slot usage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-01</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Sensor Failure Detection</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Identify and isolate faulty sensors</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-02</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-04</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Machine Constants &amp; Calibration Management</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Manage static configuration and calibration</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OTA, Persistence, Teardown</p></td></tr></tbody></table></figure>
+
+## 3\. Functional Feature Descriptions
+
+### 3.1 F-DQC-01: Automatic Sensor Detection
+
+**Description**  
+The Sensor Hub shall automatically detect which sensors are physically connected at runtime. Each sensor slot provides a dedicated detection mechanism (e.g., GPIO presence pin or ID signal) that allows the system to determine whether a sensor is installed.
+
+Detected sensors are dynamically initialized and incorporated into the data acquisition workflow without requiring firmware changes.
+
+**Key Capabilities**
+
+*   Hardware-based presence detection
+    
+*   Runtime sensor enumeration
+    
+*   Dynamic initialization during boot or reconfiguration
+    
+*   Integration with diagnostics and data acquisition
+    
+
+### 3.2 F-DQC-02: Sensor Type Enforcement
+
+**Description**  
+Each physical sensor slot on the Sensor Hub is dedicated to a specific sensor type. The system enforces sensor-slot compatibility to prevent incorrect sensor insertion (e.g., humidity sensor in temperature slot).
+
+This enforcement is achieved via electrical identification, pin mapping, or firmware configuration defined in Machine Constants.
+
+**Key Capabilities**
+
+*   Fixed sensor-to-slot mapping
+    
+*   Sensor identity verification
+    
+*   Rejection of invalid sensor configurations
+    
+*   Diagnostic reporting of configuration violations
+    
+
+### 3.3 F-DQC-03: Sensor Failure Detection
+
+**Description**  
+The Sensor Hub continuously monitors sensor behavior to detect failures such as disconnection, out-of-range values, non-responsive sensors, or abnormal signal patterns.
+
+Detected sensor failures are classified, logged, timestamped, and reported to the Main Hub. Failed sensors are excluded from control and analytics workflows to prevent propagation of invalid data.
+
+**Key Capabilities**
+
+*   Runtime health monitoring
+    
+*   Failure classification
+    
+*   Fault isolation
+    
+*   Diagnostic event generation
+    
+
+### 3.4 F-DQC-04: Machine Constants &amp; Calibration Management
+
+**Description**  
+The system maintains a **Machine Constants (MC)** dataset that defines static and semi-static configuration parameters for the Sensor Hub, including:
+
+*   Installed sensor types and slots
+    
+*   Communication identifiers and addressing
+    
+*   Calibration coefficients and offsets
+    
+*   Sensor-specific limits and scaling
+    
+
+Machine Constants are persisted in non-volatile storage (SD card) and loaded during system initialization. Updates may be received from the Main Hub and applied via a controlled teardown and reinitialization process.
+
+**Key Capabilities**
+
+*   Persistent configuration storage
+    
+*   Runtime loading and validation
+    
+*   Remote update support
+    
+*   Controlled reinitialization sequence
+    
+
+## 4\. System Requirements (Formal SHALL Statements)
+
+### 4.1 Automatic Sensor Detection
+
+**SR-DQC-001**  
+The system shall detect the presence of each sensor using a dedicated hardware detection mechanism.
+
+**SR-DQC-002**  
+The system shall perform sensor presence detection during system startup and after any reinitialization event.
+
+**SR-DQC-003**  
+The system shall initialize only those sensors that are detected as present.
+
+### 4.2 Sensor Type Enforcement
+
+**SR-DQC-004**  
+The system shall assign each sensor slot to a predefined sensor type.
+
+**SR-DQC-005**  
+The system shall verify that the detected sensor matches the expected sensor type for the slot.
+
+**SR-DQC-006**  
+The system shall reject and report any sensor-slot mismatch as a diagnostic event.
+
+### 4.3 Sensor Failure Detection
+
+**SR-DQC-007**  
+The system shall continuously monitor sensor responsiveness and signal validity during operation.
+
+**SR-DQC-008**  
+The system shall detect sensor failures including disconnection, non-responsiveness, and invalid measurement ranges.
+
+**SR-DQC-009**  
+The system shall mark a failed sensor as defective and exclude it from data reporting.
+
+**SR-DQC-010**  
+The system shall report detected sensor failures to the Main Hub with timestamps and failure classification.
+
+### 4.4 Machine Constants &amp; Calibration Management
+
+**SR-DQC-011**  
+The system shall maintain a Machine Constants dataset defining sensor configuration, calibration parameters, and communication identifiers.
+
+**SR-DQC-012**  
+The system shall persist the Machine Constants dataset in non-volatile storage.
+
+**SR-DQC-013**  
+The system shall load and apply Machine Constants during system initialization.
+
+**SR-DQC-014**  
+The system shall support remote updates of the Machine Constants dataset initiated by the Main Hub.
+
+**SR-DQC-015**  
+The system shall apply updated Machine Constants only after executing a controlled teardown and reinitialization sequence.
+
+### 4.5 Redundant Sensor Support [NEW]
+
+**SR-DQC-016**  
+The system shall support redundant sensors for critical parameters (CO2, NH3) using different technologies or interfaces.
+
+**SR-DQC-017**  
+The system shall implement sensor fusion algorithm to combine redundant sensor data (average, weighted, or voting mechanism).
+
+**SR-DQC-018**  
+The system shall ensure that every critical parameter has two qualified sensor options to avoid common-mode failures.
+
+## 5\. Traceability Summary
+
+| Feature ID | System Requirements |
+|------------|---------------------|
+| F-DQC-01 | SR-DQC-001, SR-DQC-002, SR-DQC-003 |
+| F-DQC-02 | SR-DQC-004, SR-DQC-005, SR-DQC-006 |
+| F-DQC-03 | SR-DQC-007, SR-DQC-008, SR-DQC-009, SR-DQC-010 |
+| F-DQC-04 | SR-DQC-011, SR-DQC-012, SR-DQC-013, SR-DQC-014, SR-DQC-015 |
+| F-DQC-05 | SR-DQC-016, SR-DQC-017, SR-DQC-018 |
+
+##

draft/System Design old/system_design/features/[HW] Hardware Abstraction Features.md

@@ -0,0 +1,150 @@
+# Hardware Abstraction Features
+
+**Feature Group ID:** FG-HW  
+**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 **Hardware Abstraction Features** provide a clean separation between application logic and hardware interfaces. These features ensure hardware independence, maintainability, and testability of the system.
+
+**Architecture Principle:** Application layer SHALL NOT access hardware directly (CFC-ARCH-01).
+
+## 2 Scope and Assumptions
+
+**In Scope**
+
+*   Sensor Abstraction Layer (SAL)
+*   Hardware interface abstraction (I2C, SPI, UART, ADC, GPIO)
+*   Storage interface abstraction (SD Card, NVM)
+*   Display interface abstraction (OLED I2C)
+
+**Out of Scope**
+
+*   Hardware driver implementation details (ESP-IDF drivers)
+*   Hardware-specific optimizations (deferred to implementation)
+
+## 3 Sub-Feature Breakdown
+
+### 3.1 F-HW-01: Sensor Abstraction Layer (SAL)
+
+#### Description
+
+The system provides a Sensor Abstraction Layer (SAL) to ensure hardware independence and maintainability.
+
+**Interface Functions:**
+- `sensor_read()`: Retrieve the latest value
+- `sensor_calibrate()`: Perform sensor-specific calibration
+- `sensor_validate()`: Check if the reading is within physical bounds
+- `sensor_health_check()`: Verify the operational status of the hardware
+- `sensor_getMetadata()`: Get sensor capabilities (range, accuracy, etc.)
+- `sensor_reset()`: Recovery from fault states
+
+**Sensor State Management:**
+- **INIT:** Sensor initialization
+- **WARMUP:** Sensor warming up (not yet stable)
+- **STABLE:** Sensor operational and stable
+- **DEGRADED:** Sensor operational but degraded
+- **FAILED:** Sensor failed, not operational
+
+#### Responsibilities
+
+*   Abstract sensor hardware interfaces
+*   Provide uniform sensor API
+*   Manage sensor state
+*   Handle sensor-specific calibration
+*   Validate sensor readings
+
+#### Constraints
+
+*   All sensor access must go through SAL
+*   Application layer must not access sensor hardware directly
+*   Sensor state must be tracked and reported
+
+### 3.2 F-HW-02: Hardware Interface Abstraction
+
+#### Description
+
+The system abstracts all hardware interfaces through driver layers.
+
+**Abstraction Layers:**
+- **I2C Interface:** Abstracted via ESP-IDF I2C driver wrapper
+- **SPI Interface:** Abstracted via ESP-IDF SPI driver wrapper
+- **UART Interface:** Abstracted via ESP-IDF UART driver wrapper
+- **ADC Interface:** Abstracted via ESP-IDF ADC driver wrapper
+- **GPIO Interface:** Abstracted via ESP-IDF GPIO driver wrapper
+- **Storage Interfaces:** SD Card (SDMMC), NVM (NVS)
+- **Display Interface:** OLED I2C
+
+**GPIO Discipline:**
+- **No Strapping Pins:** Avoid using strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O
+- **I2C Pull-up Audit:** Ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V)
+- **No ADC2 with Wi-Fi:** ADC2 unit cannot be used when Wi-Fi is active. All analog sensors must be connected to ADC1 pins
+- **Canonical GPIO Map:** Single authoritative GPIO map document must be maintained
+
+#### Responsibilities
+
+*   Abstract hardware interfaces
+*   Provide uniform API for hardware access
+*   Enforce GPIO discipline
+*   Manage hardware resource conflicts
+
+#### Constraints
+
+*   Application layer must not access hardware directly
+*   GPIO usage must follow canonical GPIO map
+*   Hardware conflicts must be detected and reported
+
+## 4 System Requirements (Formal SHALL Statements)
+
+### Sensor Abstraction Layer Requirements
+
+*   **SR-HW-001**: The system shall provide a Sensor Abstraction Layer (SAL) for all sensor access.
+*   **SR-HW-002**: The system shall prevent application layer from directly accessing sensor hardware.
+*   **SR-HW-003**: The system shall track sensor state (INIT, WARMUP, STABLE, DEGRADED, FAILED).
+*   **SR-HW-004**: The system shall provide sensor validation and health check functions.
+
+### Hardware Interface Abstraction Requirements
+
+*   **SR-HW-005**: The system shall abstract all hardware interfaces (I2C, SPI, UART, ADC, GPIO) through driver layers.
+*   **SR-HW-006**: The system shall enforce GPIO discipline (no strapping pins, proper pull-ups, ADC1/ADC2 separation).
+*   **SR-HW-007**: The system shall maintain a canonical GPIO map document.
+*   **SR-HW-008**: The system shall detect and report hardware resource conflicts.
+
+## 5 Traceability Matrix (Feature → System Requirements)
+
+| Feature ID | Related System Requirements |
+|------------|----------------------------|
+| F-HW-01 | SR-HW-001, SR-HW-002, SR-HW-003, SR-HW-004 |
+| F-HW-02 | SR-HW-005, SR-HW-006, SR-HW-007, SR-HW-008 |
+
+## 6 Design & Implementation Notes (Non-Normative)
+
+*   **SAL Implementation:** Each sensor type implements SAL interface
+*   **Driver Wrappers:** ESP-IDF drivers wrapped in application-specific abstraction layer
+*   **GPIO Map:** Must be maintained as single source of truth
+*   **Hardware Conflicts:** Runtime detection and reporting via diagnostics
+
+## 7 Dependencies
+
+*   **ESP-IDF Drivers:** I2C, SPI, UART, ADC, GPIO, SDMMC, NVS
+*   **System Management Features:** Hardware initialization and teardown
+*   **Diagnostics Features:** Hardware fault reporting
+
+## 8 GPIO Map Guidelines
+
+**Strapping Pins (DO NOT USE):**
+- GPIO 0: Boot mode selection
+- GPIO 3: JTAG
+- GPIO 45: Strapping pin
+- GPIO 46: Strapping pin
+
+**ADC Constraints:**
+- **ADC1:** Available when Wi-Fi is active
+- **ADC2:** NOT available when Wi-Fi is active (use ADC1 for all analog sensors)
+
+**I2C Pull-up Requirements:**
+- **Physical Pull-ups:** 2.2kΩ - 4.7kΩ for 3.3V
+- **Software Pull-ups:** Not recommended for production (use physical pull-ups)

draft/System Design old/system_design/features/[OTA] Firmware Update (OTA) Features.md

@@ -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)

draft/System Design old/system_design/features/[PWR] Power & Fault Handling Features.md

@@ -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 |

draft/System Design old/system_design/features/[SEC] Security & Safety Features.md

@@ -0,0 +1,281 @@
+# Security & Safety Features
+
+**Feature Group ID:** FG-SEC  
+**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 **Security & Safety Features** ensure that the Sensor Hub operates only with trusted firmware, protects sensitive data at rest, and guarantees confidentiality and integrity of all communications. These features are foundational and cross-cutting, supporting all other functional features (DAQ, DQC, COM, DIAG, DATA, OTA).
+
+This feature set is designed to:
+
+*   Prevent execution of unauthorized or malicious firmware
+*   Protect firmware, configuration, and machine constants stored in memory
+*   Secure all communications with cryptographic mechanisms
+*   Provide deterministic and auditable behavior in case of security violations
+
+**Technology Stack:**
+- **Secure Boot:** Secure Boot V2 (hardware-enforced)
+- **Flash Encryption:** AES-256 (hardware-accelerated)
+- **Communication Security:** Mutual TLS (mTLS) with X.509 certificates
+- **Anti-Rollback:** eFuse-based version protection
+
+## 2 Scope and Assumptions
+
+**In Scope**
+
+*   Sensor Hub (ESP32-S3–based)
+*   Boot process security
+*   Flash and external storage protection
+*   Communication security with Main Hub and peer Sensor Hubs
+*   Device identity and authentication
+
+**Out of Scope**
+
+*   Cloud server security policies
+*   User identity management
+*   Physical tamper detection hardware (optional future feature)
+
+## 3 Sub-Feature Breakdown
+
+### 3.1 F-SEC-01: Secure Boot
+
+#### Description
+
+Secure Boot ensures that only authenticated and authorized firmware images are executed on the Sensor Hub using **Secure Boot V2**. During system startup, the bootloader verifies the cryptographic signature of the firmware image before handing over execution.
+
+If verification fails, the system enters **BOOT_FAILURE** state and prevents normal operation.
+
+#### Implementation
+
+**Secure Boot V2 Configuration:**
+- **Signature Algorithm:** RSA-3072 or ECDSA-P256
+- **Verification:** Hardware-enforced (ROM bootloader)
+- **Key Storage:** Root-of-trust key in eFuse (one-time programmable)
+- **Enforcement:** Every boot (cold or warm)
+
+#### Responsibilities
+
+*   Firmware authenticity verification
+*   Root-of-trust enforcement
+*   Prevention of downgrade or rollback attacks (via eFuse anti-rollback)
+
+#### Constraints
+
+*   Must complete before any application code execution
+*   Must be enforced on every boot (cold or warm)
+*   Root-of-trust key is one-time programmable (eFuse)
+
+### 3.2 F-SEC-02: Secure Flash Storage
+
+#### Description
+
+Secure Flash Storage protects sensitive data stored in internal flash and external storage (e.g., SD card) from unauthorized access or modification using **Flash Encryption**.
+
+**Encryption Method:** AES-256 (hardware-accelerated)
+
+Sensitive data includes:
+
+*   Firmware images
+*   Machine constants
+*   Calibration data
+*   Cryptographic material
+*   Persistent diagnostics and logs
+
+#### Implementation
+
+**Flash Encryption Configuration:**
+- **Algorithm:** AES-256
+- **Mode:** Release mode (recommended for production)
+- **Key Derivation:** Hardware-based (eFuse)
+- **Transparency:** Automatic decryption on read (transparent to application)
+
+**External Storage Encryption:**
+- **SD Card:** Optional encryption for sensitive files (SWR-SEC-006)
+- **Encryption Method:** AES-256 (software-based for SD card)
+
+#### Responsibilities
+
+*   Encrypted storage of sensitive regions
+*   Access control enforcement
+*   Prevention of unauthorized read/write operations
+
+#### Constraints
+
+*   Encryption must not compromise system boot reliability
+*   Storage access must be mediated through controlled software components (e.g., DP component)
+
+### 3.3 F-SEC-03: Encrypted Communication
+
+#### Description
+
+Encrypted Communication ensures that all data exchanged between the Sensor Hub and other entities (Main Hub, peer Sensor Hubs) is protected against eavesdropping, tampering, and impersonation using **Mutual TLS (mTLS)**.
+
+This includes:
+
+*   Sensor data transmission
+*   Diagnostics reporting
+*   OTA negotiation and data transfer
+*   Configuration and machine constant updates
+
+#### Implementation
+
+**Device Identity & Authentication:**
+- **Identity:** Device-unique X.509 certificate
+- **Private Key:** Stored securely in eFuse or encrypted flash
+- **Authentication:** Mutual TLS (mTLS) for all broker communications
+- **Provisioning:** Handled via secure factory or onboarding mode
+
+**Key Lifecycle Management:**
+
+| Phase | Mechanism |
+|-------|-----------|
+| **Manufacturing** | Injection of unique device certificate and private key |
+| **Operation** | Use of TLS session keys for encrypted communication |
+| **Rotation** | Certificate rotation managed on broker/server side |
+| **Revocation** | Certificate Revocation Lists (CRL) or broker-side denylists |
+
+**Key Insight:**  
+The ESP32-S3 is optimized to handle a single device certificate efficiently. It is recommended to avoid managing large certificate chains on the device itself to conserve resources.
+
+**Certificate Constraints:**
+- **Maximum Certificate Size:** <2KB
+- **Certificate Format:** X.509 v3
+- **Key Algorithm:** RSA-2048 or ECDSA-P256
+
+#### Responsibilities
+
+*   Confidentiality of transmitted data
+*   Integrity and authenticity verification
+*   Secure session establishment
+
+#### Constraints
+
+*   Must be compatible with ESP32-S3 cryptographic capabilities
+*   Must support reconnection and key renewal mechanisms
+*   Certificate size must be optimized for ESP32-S3
+
+### 3.4 F-SEC-04: Security Violation Handling [NEW]
+
+#### Description
+
+The system detects and reports security violations with appropriate responses.
+
+**Security Violation Types:**
+- Secure boot failures
+- Authentication failures
+- Message tampering
+- Unauthorized access attempts
+- Certificate validation failures
+
+**Response Actions:**
+- Secure boot failure → BOOT_FAILURE state
+- Authentication failure → FATAL diagnostic event, connection rejection
+- Message tampering → ERROR diagnostic event (escalates to FATAL if persistent)
+- Unauthorized access → FATAL diagnostic event, access denial
+
+## 4 Functional Flow Overview
+
+### Secure Boot Flow
+
+```mermaid
+sequenceDiagram
+    participant Power as Power On
+    participant ROM as ROM Bootloader
+    participant SecureBoot as Secure Boot V2
+    participant App as Application
+    
+    Power->>ROM: System Reset
+    ROM->>SecureBoot: Load Firmware
+    SecureBoot->>SecureBoot: Verify Signature
+    alt Signature Valid
+        SecureBoot->>App: Jump to Application
+    else Signature Invalid
+        SecureBoot->>SecureBoot: Enter BOOT_FAILURE State
+    end
+```
+
+### Secure Communication Flow (mTLS)
+
+```mermaid
+sequenceDiagram
+    participant SH as Sensor Hub
+    participant Broker as Main Hub Broker
+    
+    SH->>Broker: TLS Client Hello + Certificate
+    Broker->>SH: TLS Server Hello + Certificate
+    SH->>SH: Verify Server Certificate
+    Broker->>Broker: Verify Client Certificate
+    alt Both Valid
+        SH->>Broker: TLS Session Established
+        SH->>Broker: Encrypted Data Exchange
+    else Invalid Certificate
+        SH->>SH: Reject Connection, Log FATAL
+    end
+```
+
+## 5 System SHALL Requirements (Formal)
+
+### Secure Boot Requirements
+
+*   **SR-SEC-001**: The system shall verify the authenticity of the firmware image before execution during every boot cycle using Secure Boot V2.
+*   **SR-SEC-002**: The system shall prevent execution of firmware images that fail cryptographic verification.
+*   **SR-SEC-003**: The system shall enter BOOT_FAILURE state upon secure boot verification failure.
+*   **SR-SEC-004**: The system shall protect the root-of-trust against modification (eFuse protection).
+
+### Secure Flash Storage Requirements
+
+*   **SR-SEC-005**: The system shall protect sensitive data stored in internal flash memory from unauthorized access using Flash Encryption (AES-256).
+*   **SR-SEC-006**: The system shall support encryption of sensitive data stored in external storage devices (SD card).
+*   **SR-SEC-007**: The system shall restrict access to cryptographic keys to authorized system components only.
+*   **SR-SEC-008**: The system shall ensure data integrity for stored configuration and machine constant files.
+
+### Encrypted Communication Requirements
+
+*   **SR-SEC-009**: The system shall encrypt all communication with the Main Hub using TLS 1.2 with mutual authentication (mTLS).
+*   **SR-SEC-010**: The system shall ensure integrity and authenticity of all received and transmitted messages.
+*   **SR-SEC-011**: The system shall use secure communication channels for OTA firmware updates.
+*   **SR-SEC-012**: The system shall detect and report communication security violations.
+
+### Security Violation Handling Requirements [NEW]
+
+*   **SR-SEC-013**: The system shall report security violations as FATAL diagnostic events.
+*   **SR-SEC-014**: The system shall implement eFuse-based anti-rollback to prevent downgrade attacks.
+*   **SR-SEC-015**: The system shall protect cryptographic keys during power loss and system resets.
+
+## 6 Traceability Matrix (Feature → System Requirements)
+
+| Feature ID | Related System Requirements |
+|------------|----------------------------|
+| F-SEC-01 | SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 |
+| F-SEC-02 | SR-SEC-005, SR-SEC-006, SR-SEC-007, SR-SEC-008 |
+| F-SEC-03 | SR-SEC-009, SR-SEC-010, SR-SEC-011, SR-SEC-012 |
+| F-SEC-04 | SR-SEC-013, SR-SEC-014, SR-SEC-015 |
+
+## 7 Design & Implementation Notes (Non-Normative)
+
+*   **Secure Boot V2:** Mandatory for production deployment. Key management and signing infrastructure must be documented.
+*   **Flash Encryption:** Release mode recommended for production. Development mode available for debugging.
+*   **Key Provisioning:** Should occur during manufacturing or secure onboarding. HSM or secure signing server required.
+*   **Certificate Lifecycle:** Certificate rotation and revocation must be managed on broker/server side.
+*   **eFuse Anti-Rollback:** Version numbering strategy must be carefully defined (eFuse is one-time programmable).
+*   **Security Failures:** Should integrate with the Diagnostics & Health Monitoring feature set.
+*   **Security Features:** Must be active before any sensor data acquisition or communication begins (CFC-SEC-01).
+
+## 8 Dependencies
+
+*   **OTA Features** (for secure firmware updates)
+*   **Communication Features** (transport layer for mTLS)
+*   **Diagnostics Features** (security fault reporting)
+*   **Persistence & DP Component** (secure storage abstraction)
+*   **System Management** (BOOT_FAILURE state handling)
+
+## 9 Industrial Standards Compliance
+
+*   **Secure Boot V2:** Industry standard for production-ready industrial embedded systems
+*   **Flash Encryption:** Hardware-accelerated AES-256 (industry standard)
+*   **mTLS:** Industry standard for device authentication
+*   **X.509 Certificates:** Standard certificate format (RFC 5280)

draft/System Design old/system_design/features/[SYS] System Management Features.md

@@ -0,0 +1,326 @@
+<macro class="toc op-uc-placeholder op-uc-toc">
+</macro>
+
+#   
+System Management Features
+
+## Sensor Hub (Sub-Hub) Scope
+
+## 1 Feature Overview
+
+The **System Management Features** provide deterministic control over the Sensor Hub’s operational lifecycle, runtime state visibility, controlled shutdown behavior, and engineering interaction capabilities.
+
+This feature group is responsible for:
+
+*   Managing system operational states and transitions
+    
+*   Ensuring safe teardown during updates or failures
+    
+*   Providing local human–machine interaction via OLED display and buttons
+    
+*   Supporting engineering/debug sessions for diagnostics and maintenance
+    
+
+These features act as the **supervisory layer** governing all other functional domains (DAQ, DQC, COM, DIAG, DATA, OTA, SEC).
+
+## 2 Scope and Assumptions
+
+**In Scope**
+
+*   ESP32-S3 Sensor Hub
+    
+*   OLED-based local UI (I2C)
+    
+*   Physical input buttons
+    
+*   Controlled state transitions and teardown
+    
+*   Debug and engineering access
+    
+
+**Out of Scope**
+
+*   Main Hub UI
+    
+*   Cloud dashboards
+    
+*   User authentication / role management
+    
+
+## 3 Sub-Feature Breakdown
+
+### 3.1 F-SYS-01: System State Management
+
+#### Description
+
+System State Management defines and controls the operational states of the Sensor Hub and governs all valid transitions between them.
+
+The system operates as a **finite state machine (FSM)** with deterministic behavior.
+
+#### Typical System States
+
+*   **INIT** – Hardware and software initialization
+    
+*   **RUNNING** – Normal sensor acquisition and communication
+    
+*   **WARNING** – Non-fatal fault detected, degraded operation
+    
+*   **FAULT** – Fatal error, core functionality disabled
+    
+*   **OTA\_UPDATE** – Firmware update in progress
+    
+*   **MC\_UPDATE** – Machine constants update in progress
+    
+*   **TEARDOWN** – Controlled shutdown sequence
+    
+*   **IDLE / SERVICE** – Engineering or diagnostic interaction
+    
+
+#### Responsibilities
+
+*   Enforce valid state transitions
+    
+*   Notify dependent components of state changes
+    
+*   Prevent unsafe operations during restricted states
+    
+
+### 3.2 F-SYS-02: Controlled Teardown Mechanism
+
+#### Description
+
+The Controlled Teardown Mechanism ensures that the Sensor Hub transitions safely from an active state into reset, update, or shutdown without data loss or corruption.
+
+Teardown is triggered by:
+
+*   Firmware update
+    
+*   Machine constant update
+    
+*   Fatal system fault
+    
+*   Manual engineering command
+    
+
+#### Teardown Sequence (Mandatory)
+
+1.  Stop sensor acquisition tasks
+    
+2.  Flush pending data via DP component
+    
+3.  Persist calibration, diagnostics, and runtime state
+    
+4.  Close communication sessions
+    
+5.  Release hardware resources
+    
+6.  Enter target state (reset, OTA, idle)
+    
+
+#### Responsibilities
+
+*   Guarantee data consistency
+    
+*   Ensure deterministic shutdown behavior
+    
+*   Prevent flash or SD corruption
+    
+
+### 3.3 F-SYS-03: Status Indication (OLED-Based HMI)
+
+#### Description
+
+The Sensor Hub provides local system visibility using an **OLED display connected via I2C**, replacing LED indicators.
+
+The display, together with **three physical buttons (Up / Down / Select)**, forms a minimal local Human–Machine Interface (HMI).
+
+#### Default Information Displayed (Main Screen)
+
+1.  **Connectivity status**
+    
+    *   Connected / Disconnected
+        
+    *   Signal strength (RSSI) if available
+        
+2.  **System status**
+    
+    *   Current system state (RUNNING, WARNING, FAULT, OTA, etc.)
+        
+3.  **Connected sensors**
+    
+    *   Count and/or summary status
+        
+4.  **Time and date**
+    
+    *   Synchronized system time
+        
+
+#### Menu Navigation Behavior
+
+*   **Select button**
+    
+    *   From main screen → opens menu
+        
+    *   From submenu → returns to main screen
+        
+*   **Up / Down buttons**
+    
+    *   Navigate menu entries
+        
+    *   Scroll within pages if applicable
+        
+
+#### Menu Structure
+
+**Main Menu**
+
+*   **Diagnostics**
+    
+    *   Lists active and stored diagnostic codes
+        
+    *   Displays occurrence count per diagnostic
+        
+*   **Sensors**
+    
+    *   Lists all detected sensors
+        
+    *   Displays sensor type and configuration status
+        
+*   **Health**
+    
+    *   Displays SD card usage
+        
+    *   Displays overall system health indicators
+        
+
+#### Responsibilities
+
+*   Provide real-time system visibility
+    
+*   Support local inspection without external tools
+    
+*   Reflect system state and diagnostics accurately
+    
+
+### 3.4 F-SYS-04: Debug &amp; Engineering Sessions
+
+#### Description
+
+Debug &amp; Engineering Sessions allow authorized engineers to interact with the Sensor Hub for diagnostics, inspection, and controlled operations.
+
+Sessions may be established via:
+
+*   Wired interface (e.g., USB/UART)
+    
+*   Secure communication channel (logical session)
+    
+
+#### Supported Capabilities
+
+*   Retrieve diagnostic logs
+    
+*   Read machine constant files
+    
+*   Inspect system state and health
+    
+*   Trigger controlled actions (e.g., reboot, teardown)
+    
+*   Monitor runtime logs
+    
+
+#### Session Types
+
+*   **Diagnostic Session** – Read-only access for inspection
+    
+*   **Debug Session** – Command execution and deeper inspection
+    
+
+## 4 Functional Interaction Overview
+
+### System State &amp; Teardown Relationship
+
+```text
+RUNNING
+   ↓ (Update / Fault)
+TEARDOWN
+   ↓
+OTA_UPDATE / MC_UPDATE / RESET
+```
+
+### Local HMI Interaction
+
+```text
+OLED Display ← System State Manager
+Buttons → UI Controller → State/Menu Logic
+```
+
+## 5 System SHALL Requirements (Formal)
+
+### System State Management
+
+*   **SR-SYS-001**: The system shall implement a defined finite state machine for operational control.
+    
+*   **SR-SYS-002**: The system shall restrict operations based on the current system state.
+    
+*   **SR-SYS-003**: The system shall notify system components of state transitions.
+    
+
+### Controlled Teardown
+
+*   **SR-SYS-004**: The system shall execute a controlled teardown sequence before firmware or machine constant updates.
+    
+*   **SR-SYS-005**: The system shall persist all critical runtime data before completing teardown.
+    
+*   **SR-SYS-006**: The system shall prevent data corruption during teardown and reset operations.
+    
+
+### Status Indication &amp; HMI
+
+*   **SR-SYS-007**: The system shall provide a local OLED display using I2C communication.
+    
+*   **SR-SYS-008**: The system shall display connectivity status, system state, sensor summary, and time/date.
+    
+*   **SR-SYS-009**: The system shall provide menu navigation using Up, Down, and Select buttons.
+    
+*   **SR-SYS-010**: The system shall provide diagnostic, sensor, and health information via the local menu.
+    
+
+### Debug &amp; Engineering Sessions
+
+*   **SR-SYS-011**: The system shall support diagnostic sessions for retrieving logs and system status.
+    
+*   **SR-SYS-012**: The system shall support debug sessions for controlled engineering operations.
+    
+*   **SR-SYS-013**: The system shall restrict debug actions to authorized sessions only.
+
+### GPIO & Hardware Discipline [NEW]
+
+*   **SR-SYS-014**: The system shall enforce GPIO discipline by avoiding strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O.
+*   **SR-SYS-015**: The system shall ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V).
+*   **SR-SYS-016**: The system shall use ADC1 for all analog sensors when Wi-Fi is active (ADC2 is not available with Wi-Fi).
+*   **SR-SYS-017**: The system shall maintain a canonical GPIO map document as a single source of truth.
+
+## 6 Traceability Matrix
+
+| Feature ID | System Requirements |
+|------------|---------------------|
+| F-SYS-01 | SR-SYS-001, SR-SYS-002, SR-SYS-003 |
+| F-SYS-02 | SR-SYS-004, SR-SYS-005, SR-SYS-006 |
+| F-SYS-03 | SR-SYS-007, SR-SYS-008, SR-SYS-009, SR-SYS-010 |
+| F-SYS-04 | SR-SYS-011, SR-SYS-012, SR-SYS-013 |
+| F-SYS-05 | SR-SYS-014, SR-SYS-015, SR-SYS-016, SR-SYS-017 |
+
+## 7 Dependencies
+
+*   Diagnostics &amp; Health Monitoring Features
+    
+*   Persistence &amp; DP Component
+    
+*   Communication Features
+    
+*   Security &amp; Safety Features
+    
+*   OTA Features
+    
+
+##