# 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