system update

2026-02-01 12:52:10 +01:00
parent ff791564e4
commit f51adeecca
31 changed files with 7984 additions and 0 deletions
--- a/system_design/features/[DAQ]
+++ b/system_design/features/[DAQ]
@@ -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 |