ASF_01_sys_sw_arch/system_design/features/[COM] Communication Features.md

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

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