11 KiB
11 KiB
Communication Manager Component Specification
Component ID: C-COM-001
Component Name: Communication Manager
Version: 1.0
Date: 2025-02-01
1. Component Overview
1.1 Purpose
The Communication Manager is responsible for managing all external communication interfaces including MQTT-based Main Hub communication, ESP-NOW peer communication, and long-range fallback communication. It provides a unified interface for all communication protocols and handles connection management, message routing, and protocol-specific operations.
1.2 Scope
- MQTT over TLS communication with Main Hub
- ESP-NOW peer-to-peer communication
- Message formatting and encoding (CBOR)
- Connection management and health monitoring
- Communication protocol abstraction
1.3 Responsibilities
- Establish and maintain secure connections with Main Hub
- Handle MQTT message publishing and subscription
- Manage ESP-NOW peer communication
- Implement heartbeat and keepalive mechanisms
- Provide communication status monitoring
- Handle automatic reconnection with exponential backoff
- Route messages between internal components and external entities
2. Component Architecture
2.1 Static View
graph TB
subgraph "Communication Manager"
CM[Communication Controller]
MH[MQTT Handler]
EN[ESP-NOW Handler]
MF[Message Formatter]
CS[Connection Supervisor]
end
subgraph "External Interfaces"
MQTT[MQTT Broker]
PEER[Peer Hubs]
end
subgraph "Internal Components"
SM[Sensor Manager]
DP[Data Pool]
DIAG[Diagnostics Manager]
end
CM --> MH
CM --> EN
CM --> MF
CM --> CS
MH --> MQTT
EN --> PEER
SM --> CM
DP --> CM
DIAG --> CM
2.2 Internal Components
2.2.1 Communication Controller
- Central coordination of all communication activities
- Message routing and protocol selection
- Communication policy enforcement
2.2.2 MQTT Handler
- MQTT client implementation
- TLS session management
- Topic subscription and message publishing
- QoS handling and message acknowledgment
2.2.3 ESP-NOW Handler
- ESP-NOW protocol implementation
- Peer discovery and management
- Message encryption and decryption
- Acknowledgment and retry mechanisms
2.2.4 Message Formatter
- CBOR encoding and decoding
- Message versioning and schema validation
- Payload compression and optimization
2.2.5 Connection Supervisor
- Connection health monitoring
- Automatic reconnection logic
- Network status tracking
- Communication diagnostics
3. Interfaces
3.1 Provided Interfaces
3.1.1 ICommunicationManager
class ICommunicationManager {
public:
virtual ~ICommunicationManager() = default;
// Connection Management
virtual Result<void> initialize(const CommunicationConfig& config) = 0;
virtual Result<void> connect() = 0;
virtual Result<void> disconnect() = 0;
virtual ConnectionStatus getConnectionStatus() const = 0;
// Message Operations
virtual Result<void> publishSensorData(const SensorDataMessage& data) = 0;
virtual Result<void> publishDiagnostic(const DiagnosticMessage& diag) = 0;
virtual Result<void> publishHeartbeat(const HeartbeatMessage& heartbeat) = 0;
virtual Result<void> sendPeerMessage(const PeerMessage& message, NodeId peer) = 0;
// Subscription Management
virtual Result<void> subscribeToCommands(ICommandHandler* handler) = 0;
virtual Result<void> subscribeToOTAUpdates(IOTAHandler* handler) = 0;
virtual Result<void> subscribeToPeerMessages(IPeerMessageHandler* handler) = 0;
// Status and Control
virtual CommunicationStats getStatistics() const = 0;
virtual Result<void> resetConnection() = 0;
};
3.1.2 IMessageHandler
class IMessageHandler {
public:
virtual ~IMessageHandler() = default;
virtual Result<void> handleIncomingMessage(const Message& message) = 0;
virtual Result<void> handleConnectionEvent(ConnectionEvent event) = 0;
};
3.1.3 IConnectionStatus
class IConnectionStatus {
public:
virtual ~IConnectionStatus() = default;
virtual bool isConnected() const = 0;
virtual int getSignalStrength() const = 0;
virtual std::chrono::milliseconds getLatency() const = 0;
virtual uint32_t getMessagesSent() const = 0;
virtual uint32_t getMessagesReceived() const = 0;
};
3.2 Required Interfaces
3.2.1 ITLSManager
- TLS session establishment and management
- Certificate validation and management
- Secure communication channel setup
3.2.2 INetworkStack
- Low-level network operations
- Wi-Fi connection management
- Network status monitoring
3.2.3 IDataPool
- Access to sensor data for transmission
- Retrieval of latest sensor values
- Data validity checking
3.2.4 IEventSystem
- Event publication for communication events
- Event subscription for system events
- Asynchronous notification handling
3.2.5 IDiagnosticsManager
- Diagnostic event reporting
- Communication error logging
- Performance metrics reporting
4. Dynamic View
4.1 MQTT Communication Sequence
sequenceDiagram
participant SM as Sensor Manager
participant CM as Communication Manager
participant MH as MQTT Handler
participant TLS as TLS Manager
participant BROKER as MQTT Broker
SM->>CM: publishSensorData(data)
CM->>CM: formatMessage(data)
CM->>MH: publish(topic, payload)
MH->>TLS: sendSecure(message)
TLS->>BROKER: encrypted_message
BROKER-->>TLS: ack
TLS-->>MH: send_result
MH-->>CM: publish_result
CM-->>SM: operation_result
4.2 Connection Management Sequence
sequenceDiagram
participant CS as Connection Supervisor
participant MH as MQTT Handler
participant TLS as TLS Manager
participant DIAG as Diagnostics Manager
CS->>CS: monitorConnection()
CS->>MH: checkConnectionHealth()
MH-->>CS: connection_status
alt Connection Lost
CS->>DIAG: reportConnectionLoss()
CS->>CS: startReconnectionTimer()
CS->>MH: reconnect()
MH->>TLS: establishConnection()
TLS-->>MH: connection_result
MH-->>CS: reconnection_result
end
5. Configuration
5.1 Communication Configuration
struct CommunicationConfig {
// MQTT Configuration
std::string mqtt_broker_url;
uint16_t mqtt_port;
std::string mqtt_client_id;
std::string mqtt_username;
std::string mqtt_password;
uint16_t mqtt_keepalive_seconds;
uint8_t mqtt_qos_level;
// ESP-NOW Configuration
bool espnow_enabled;
uint8_t espnow_channel;
std::vector<uint8_t> espnow_peers;
// TLS Configuration
std::string ca_certificate;
std::string client_certificate;
std::string client_private_key;
// Timing Configuration
uint32_t heartbeat_interval_ms;
uint32_t reconnection_timeout_ms;
uint32_t message_timeout_ms;
};
5.2 Topic Structure
namespace Topics {
constexpr const char* SENSOR_DATA = "/farm/{site_id}/{house_id}/{node_id}/data/{sensor_id}";
constexpr const char* HEARTBEAT = "/farm/{site_id}/{house_id}/{node_id}/status/heartbeat";
constexpr const char* SYSTEM_STATUS = "/farm/{site_id}/{house_id}/{node_id}/status/system";
constexpr const char* COMMANDS = "/farm/{site_id}/{house_id}/{node_id}/cmd/{command_type}";
constexpr const char* DIAGNOSTICS = "/farm/{site_id}/{house_id}/{node_id}/diag/{severity}";
constexpr const char* OTA = "/farm/{site_id}/{house_id}/{node_id}/ota/{action}";
}
6. State Management
6.1 Communication States
enum class CommunicationState {
DISCONNECTED,
CONNECTING,
CONNECTED,
RECONNECTING,
ERROR,
DISABLED
};
6.2 State Transitions
- DISCONNECTED → CONNECTING: Connection initiation
- CONNECTING → CONNECTED: Successful connection establishment
- CONNECTED → RECONNECTING: Connection loss detected
- RECONNECTING → CONNECTED: Successful reconnection
- Any State → ERROR: Critical communication error
- Any State → DISABLED: System shutdown or disable command
7. Error Handling
7.1 Error Categories
- Connection Errors: Network connectivity issues, broker unavailability
- Authentication Errors: Certificate validation failures, credential issues
- Protocol Errors: MQTT protocol violations, message format errors
- Timeout Errors: Message delivery timeouts, keepalive failures
- Resource Errors: Memory allocation failures, buffer overflows
7.2 Error Recovery Strategies
- Automatic Reconnection: Exponential backoff with maximum retry limit
- Message Queuing: Store messages during disconnection periods
- Graceful Degradation: Continue operation with reduced functionality
- Diagnostic Reporting: Log all communication errors for analysis
8. Performance Characteristics
8.1 Timing Requirements
- Message Latency: < 100ms for on-demand data requests
- Heartbeat Interval: 10 seconds (configurable)
- Reconnection Time: < 30 seconds with exponential backoff
- Message Throughput: > 100 messages/minute
8.2 Resource Usage
- Memory: < 32KB for communication buffers
- CPU: < 5% average utilization
- Network: Adaptive based on message frequency and size
9. Security Considerations
9.1 Communication Security
- All MQTT communication encrypted with TLS 1.2
- Device authentication using X.509 certificates
- ESP-NOW messages encrypted with AES-128
- Message integrity verification
9.2 Access Control
- Topic-based access control via broker configuration
- Peer authentication for ESP-NOW communication
- Command validation and authorization
10. Testing Strategy
10.1 Unit Tests
- Message formatting and parsing
- Connection state management
- Error handling and recovery
- Configuration validation
10.2 Integration Tests
- End-to-end message delivery
- TLS session establishment
- ESP-NOW peer communication
- Broker interaction testing
10.3 Performance Tests
- Message throughput and latency
- Connection stability under load
- Memory usage profiling
- Network efficiency analysis
11. Dependencies
11.1 Internal Dependencies
- TLS Manager for secure communication
- Event System for asynchronous notifications
- Data Pool for sensor data access
- Diagnostics Manager for error reporting
11.2 External Dependencies
- ESP-IDF MQTT client library
- ESP-IDF ESP-NOW library
- mbedTLS for cryptographic operations
- CBOR encoding/decoding library
12. Constraints and Assumptions
12.1 Constraints
- Maximum message size: 8KB
- Maximum concurrent connections: 1 MQTT + 20 ESP-NOW peers
- Network latency: < 1000ms for reliable operation
- Memory usage: Bounded and deterministic
12.2 Assumptions
- Reliable network connectivity for MQTT communication
- Proper broker configuration and availability
- Valid certificates and credentials provisioned
- Sufficient system resources for communication operations