software and system v1

1 software design/components/network_stack/NETWORK_STACK_OVERVIEW.md

@@ -0,0 +1,223 @@
+# Network Stack Overview
+## ASF Sensor Hub (Sub-Hub) Embedded System
+
+**Document ID:** COMP-NETWORK-OVERVIEW-001  
+**Version:** 1.0  
+**Date:** 2025-02-01  
+**Platform:** ESP32-S3, ESP-IDF v5.4
+
+---
+
+## 1. Purpose
+
+The Network Stack provides Wi-Fi, MQTT, TLS, and ESP-NOW communication services, abstracting ESP-IDF v5.4 network APIs. This stack enables Communication Manager to handle all network operations without direct ESP-IDF dependencies.
+
+**Primary Goal:** Provide secure, reliable network communication for Main Hub and peer communication.
+
+---
+
+## 2. Network Stack Architecture
+
+```
+Communication Manager
+    ↓
+Network Stack (This Layer)
+    ├─> Wi-Fi Manager
+    ├─> MQTT Client
+    ├─> TLS Manager
+    └─> ESP-NOW Handler
+    ↓
+ESP-IDF Network APIs
+    ↓
+Hardware (Wi-Fi Radio)
+```
+
+---
+
+## 3. Network Stack Components
+
+| Component ID | Component Name | Purpose | ESP-IDF Service |
+|--------------|----------------|---------|-----------------|
+| C-NET-WIFI | Wi-Fi Manager | Wi-Fi connection management | `esp_wifi.h` |
+| C-NET-MQTT | MQTT Client | MQTT protocol implementation | `mqtt_client.h` |
+| C-NET-TLS | TLS Manager | TLS 1.2 encryption | `esp_tls.h` |
+| C-NET-ESPNOW | ESP-NOW Handler | ESP-NOW peer communication | `esp_now.h` |
+
+---
+
+## 4. Design Principles
+
+### 4.1 Security First
+
+- All Main Hub communication encrypted (TLS 1.2)
+- ESP-NOW communication encrypted (application layer)
+- Certificate validation mandatory
+- Secure session establishment
+
+### 4.2 Reliability
+
+- Automatic reconnection with exponential backoff
+- Heartbeat mechanism for connection monitoring
+- Message queuing for store-and-forward
+- Connection state management
+
+### 4.3 Performance
+
+- Non-blocking operations
+- Efficient message encoding (CBOR)
+- Connection pooling
+- Minimal overhead
+
+---
+
+## 5. Wi-Fi Manager
+
+### 5.1 Responsibilities
+
+- Wi-Fi station mode configuration
+- SSID and password management
+- Connection establishment
+- Connection monitoring
+- Automatic reconnection
+- Signal strength monitoring
+
+### 5.2 ESP-IDF Integration
+
+- Uses `esp_wifi.h` APIs
+- Station mode only (no AP mode)
+- WPA2/WPA3 security
+- 802.11n (2.4 GHz)
+
+---
+
+## 6. MQTT Client
+
+### 6.1 Responsibilities
+
+- MQTT protocol implementation
+- Topic subscription management
+- Message publishing
+- QoS level handling
+- Keepalive mechanism
+- Connection state management
+
+### 6.2 MQTT Topic Structure
+
+**Topic Naming Convention:**
+```
+asf/sensorhub/{device_id}/{message_type}/{subtype}
+```
+
+**Message Types:**
+- `data` - Sensor data
+- `diagnostics` - Diagnostic events
+- `status` - System status
+- `command` - Commands from Main Hub
+- `ota` - OTA update messages
+
+**Example Topics:**
+- `asf/sensorhub/001/data/sensors` - Sensor data
+- `asf/sensorhub/001/diagnostics/events` - Diagnostic events
+- `asf/sensorhub/001/command/request` - Command requests
+- `asf/sensorhub/001/ota/update` - OTA updates
+
+### 6.3 ESP-IDF Integration
+
+- Uses `mqtt_client.h` (ESP-IDF MQTT client)
+- Supports QoS 0, 1, 2
+- Automatic reconnection
+- TLS integration
+
+---
+
+## 7. TLS Manager
+
+### 7.1 Responsibilities
+
+- TLS 1.2 connection establishment
+- Certificate validation
+- Mutual authentication (mTLS)
+- Session management
+- Key management
+
+### 7.2 ESP-IDF Integration
+
+- Uses `esp_tls.h` APIs
+- Certificate storage in NVS
+- Private key protection
+- Certificate validation
+
+---
+
+## 8. ESP-NOW Handler
+
+### 8.1 Responsibilities
+
+- ESP-NOW peer communication
+- Peer registration
+- Message encryption (application layer)
+- Acknowledgment handling
+- Retry mechanism
+
+### 8.2 ESP-IDF Integration
+
+- Uses `esp_now.h` APIs
+- Broadcast and unicast modes
+- Application-layer encryption (AES-128)
+
+---
+
+## 9. Error Handling
+
+### 9.1 Error Detection
+
+- Wi-Fi connection failures
+- MQTT connection failures
+- TLS handshake failures
+- ESP-NOW transmission failures
+- Timeout errors
+
+### 9.2 Error Recovery
+
+- Automatic reconnection
+- Exponential backoff
+- Error reporting to Diagnostics Manager
+- Connection state tracking
+
+---
+
+## 10. Dependencies
+
+### 10.1 OSAL Dependencies
+
+- **OSAL-TASK:** Task management for network operations
+
+### 10.2 Application Dependencies
+
+- **Logger:** Network event logging
+- **Diagnostics Manager:** Error reporting
+- **Security Manager:** Certificate management
+- **Time Utils:** Timestamp generation
+
+---
+
+## 11. Traceability
+
+### 11.1 System Requirements
+
+- **SR-COM-001:** Bidirectional Main Hub communication
+- **SR-COM-008:** Peer Sensor Hub communication
+- **SR-SEC-009:** Encrypted communication
+- **SR-SEC-010:** Message integrity and authenticity
+
+### 11.2 Software Requirements
+
+- **SWR-COM-001:** MQTT over TLS communication
+- **SWR-COM-010:** Encrypted communication
+- **SWR-COM-016:** Heartbeat mechanism
+- **SWR-COM-017:** Automatic reconnection
+
+---
+
+**Document Status:** Complete  
+**Next Review:** Before implementation