cleanup

2026-01-26 12:49:12 +01:00
parent bedcd373f5
commit ff791564e4
243 changed files with 18986 additions and 0 deletions
--- a/system_design/features/[COM]
+++ b/system_design/features/[COM]
@@ -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