components
This commit is contained in:
376
1 software design/components/SOFTWARE_COMPONENTS_OVERVIEW.md
Normal file
376
1 software design/components/SOFTWARE_COMPONENTS_OVERVIEW.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# Software Components Overview
|
||||
|
||||
**Document ID:** COMP-OVERVIEW-001
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Project:** ASF Sensor Hub (Sub-Hub) Embedded System
|
||||
|
||||
## 1. Introduction
|
||||
|
||||
This document provides a comprehensive overview of all software components in the ASF Sensor Hub embedded system. Each component is designed following the layered architecture principles with clear separation of concerns, well-defined interfaces, and specific responsibilities.
|
||||
|
||||
## 2. Component Architecture Overview
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Application Layer"
|
||||
subgraph "Business Stack"
|
||||
STM[System State Manager<br/>C-STM-001]
|
||||
SensorMgr[Sensor Manager<br/>C-SENSOR-001]
|
||||
CommMgr[Communication Manager<br/>C-COM-001]
|
||||
OTAMgr[OTA Manager<br/>C-OTA-001]
|
||||
MCMgr[Machine Constants Manager<br/>C-MC-001]
|
||||
SecurityMgr[Security Manager<br/>C-SEC-001]
|
||||
DiagMgr[Diagnostics Manager<br/>C-DIAG-001]
|
||||
EventSys[Event System<br/>C-EVENT-001]
|
||||
end
|
||||
|
||||
subgraph "DP Stack"
|
||||
DataPool[Data Pool<br/>C-DATA-POOL]
|
||||
Persistence[Data Persistence<br/>C-DP-001]
|
||||
end
|
||||
end
|
||||
|
||||
subgraph "Driver Layer"
|
||||
SensorDrivers[Sensor Drivers]
|
||||
NetworkStack[Network Stack]
|
||||
StorageDrivers[Storage Drivers]
|
||||
end
|
||||
|
||||
subgraph "OSAL Layer"
|
||||
ESPIDFWrappers[ESP-IDF Wrappers]
|
||||
end
|
||||
|
||||
subgraph "HAL Layer"
|
||||
ESPIDFFramework[ESP-IDF Framework]
|
||||
end
|
||||
```
|
||||
|
||||
## 3. Existing Components
|
||||
|
||||
### 3.1 Application Layer Components
|
||||
|
||||
#### 3.1.1 Business Stack Components
|
||||
|
||||
| Component ID | Component Name | Primary Purpose | Key Responsibilities |
|
||||
|--------------|----------------|-----------------|---------------------|
|
||||
| C-STM-001 | System State Manager | System lifecycle coordination | FSM implementation, state transitions, teardown coordination |
|
||||
| C-SENSOR-001 | Sensor Manager | Sensor data acquisition | Multi-sensor management, high-frequency sampling, data filtering |
|
||||
| C-COM-001 | Communication Manager | External communication | MQTT/TLS, ESP-NOW, message routing, connection management |
|
||||
| C-OTA-001 | OTA Manager | Firmware updates | A/B partitioning, secure updates, automatic rollback |
|
||||
| C-MC-001 | Machine Constants Manager | Configuration management | Static configuration, remote updates, validation |
|
||||
| C-SEC-001 | Security Manager | System security | Secure boot, flash encryption, TLS, key management |
|
||||
| C-DIAG-001 | Diagnostics Manager | System health monitoring | Diagnostic codes, health monitoring, watchdog management |
|
||||
| C-EVENT-001 | Event System | Inter-component communication | Publish/subscribe, event queuing, asynchronous delivery |
|
||||
|
||||
#### 3.1.2 DP Stack Components
|
||||
|
||||
| Component ID | Component Name | Primary Purpose | Key Responsibilities |
|
||||
|--------------|----------------|-----------------|---------------------|
|
||||
| C-DATA-POOL | Data Pool | Centralized data storage | Thread-safe data access, real-time data exchange |
|
||||
| C-DP-001 | Data Persistence | Persistent storage | Storage abstraction, serialization, wear management |
|
||||
|
||||
### 3.2 Component Descriptions
|
||||
|
||||
#### 3.2.1 System State Manager (C-STM-001)
|
||||
**Location:** `application_layer/business_stack/STM/`
|
||||
|
||||
The System State Manager implements the central finite state machine for the Sensor Hub, managing system lifecycle states (INIT, RUNNING, WARNING, FAULT, OTA_PREP, etc.) and coordinating controlled teardown sequences.
|
||||
|
||||
**Key Features:**
|
||||
- System FSM with 11 defined states
|
||||
- State transition validation and enforcement
|
||||
- Teardown coordination for OTA and MC updates
|
||||
- State change notifications via Event System
|
||||
- State-aware execution enforcement
|
||||
|
||||
#### 3.2.2 Sensor Manager (C-SENSOR-001)
|
||||
**Location:** `application_layer/business_stack/sensor_manager/`
|
||||
|
||||
The Sensor Manager coordinates all sensor-related operations including lifecycle management, data acquisition scheduling, high-frequency sampling, and local filtering.
|
||||
|
||||
**Key Features:**
|
||||
- Support for 7 environmental sensor types
|
||||
- High-frequency sampling (10 samples per cycle)
|
||||
- Configurable filtering algorithms (median, moving average, rate-limited)
|
||||
- Sensor state management and fault detection
|
||||
- 1-second acquisition cycles with timestamped data
|
||||
|
||||
#### 3.2.3 Communication Manager (C-COM-001)
|
||||
**Location:** `application_layer/business_stack/communication_manager/`
|
||||
|
||||
The Communication Manager handles all external communication including MQTT-based Main Hub communication and ESP-NOW peer communication.
|
||||
|
||||
**Key Features:**
|
||||
- MQTT over TLS communication with Main Hub
|
||||
- ESP-NOW peer-to-peer communication
|
||||
- Message formatting and encoding (CBOR)
|
||||
- Connection management with automatic reconnection
|
||||
- Heartbeat and keepalive mechanisms
|
||||
|
||||
#### 3.2.4 OTA Manager (C-OTA-001)
|
||||
**Location:** `application_layer/business_stack/ota_manager/`
|
||||
|
||||
The OTA Manager provides secure, reliable firmware update functionality with A/B partitioning and automatic rollback capabilities.
|
||||
|
||||
**Key Features:**
|
||||
- A/B partition management
|
||||
- Secure firmware validation (SHA-256, RSA-3072/ECDSA-P256)
|
||||
- Automatic rollback on boot failures
|
||||
- Controlled teardown coordination
|
||||
- Update progress tracking and reporting
|
||||
|
||||
#### 3.2.5 Machine Constants Manager (C-MC-001)
|
||||
**Location:** `application_layer/business_stack/machine_constants_manager/`
|
||||
|
||||
The Machine Constants Manager handles static and semi-static configuration parameters including sensor configuration, calibration data, and system identity.
|
||||
|
||||
**Key Features:**
|
||||
- JSON-based configuration management
|
||||
- Remote configuration updates from Main Hub
|
||||
- Configuration validation and integrity checking
|
||||
- Version control and rollback capability
|
||||
- Controlled reinitialization for updates
|
||||
|
||||
#### 3.2.6 Security Manager (C-SEC-001)
|
||||
**Location:** `application_layer/business_stack/security_manager/`
|
||||
|
||||
The Security Manager implements comprehensive security mechanisms including secure boot, flash encryption, and communication security.
|
||||
|
||||
**Key Features:**
|
||||
- Secure Boot V2 with RSA-3072/ECDSA-P256
|
||||
- Flash encryption with AES-256
|
||||
- TLS/mTLS communication security
|
||||
- Cryptographic key management
|
||||
- Security violation detection and response
|
||||
|
||||
#### 3.2.7 Diagnostics Manager (C-DIAG-001)
|
||||
**Location:** `application_layer/business_stack/diagnostics_manager/`
|
||||
|
||||
The Diagnostics Manager provides comprehensive system health monitoring, fault detection, and diagnostic data collection.
|
||||
|
||||
**Key Features:**
|
||||
- Structured diagnostic code framework
|
||||
- System health monitoring and performance metrics
|
||||
- Layered watchdog system management
|
||||
- Engineering diagnostic sessions
|
||||
- Persistent diagnostic data storage
|
||||
|
||||
#### 3.2.8 Event System (C-EVENT-001)
|
||||
**Location:** `application_layer/business_stack/event_system/`
|
||||
|
||||
The Event System provides a publish/subscribe event bus for cross-component communication, enabling loose coupling and asynchronous event delivery.
|
||||
|
||||
**Key Features:**
|
||||
- Non-blocking event publishing and delivery
|
||||
- Priority-based subscriber management
|
||||
- Event filtering and queuing
|
||||
- ISR-safe event publishing
|
||||
- Overflow handling with oldest-event dropping
|
||||
|
||||
#### 3.2.9 Data Pool (C-DATA-POOL)
|
||||
**Location:** `application_layer/DP_stack/data_pool/`
|
||||
|
||||
The Data Pool provides centralized, thread-safe data storage and access for sensor readings, system parameters, and operational data.
|
||||
|
||||
**Key Features:**
|
||||
- Thread-safe data access and modification
|
||||
- Real-time data exchange between components
|
||||
- Data validation and type checking
|
||||
- Event-driven data change notifications
|
||||
- Memory-efficient data organization
|
||||
|
||||
#### 3.2.10 Data Persistence (C-DP-001)
|
||||
**Location:** `application_layer/DP_stack/persistence/`
|
||||
|
||||
The Data Persistence component provides the sole interface for persistent data access, abstracting storage media and managing data serialization.
|
||||
|
||||
**Key Features:**
|
||||
- Storage media abstraction (SD card, NVM)
|
||||
- Data serialization/deserialization
|
||||
- Wear-aware storage management
|
||||
- Data integrity verification
|
||||
- Critical data flushing before state transitions
|
||||
|
||||
## 4. Missing Components Analysis
|
||||
|
||||
Based on the architecture analysis and feature requirements, the following components appear to be missing or need to be created:
|
||||
|
||||
### 4.1 Missing Application Layer Components
|
||||
|
||||
#### 4.1.1 Error Handler Component
|
||||
**Component ID:** C-ERROR-001
|
||||
**Location:** `application_layer/error_handler/`
|
||||
|
||||
**Purpose:** Centralized error handling, fault classification, and recovery coordination.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- Fault detection and classification
|
||||
- Error recovery strategy implementation
|
||||
- Fault escalation to System State Manager
|
||||
- Error logging and reporting
|
||||
- Recovery attempt coordination
|
||||
|
||||
#### 4.1.2 Time Utils Component
|
||||
**Component ID:** C-TIME-001
|
||||
**Location:** `application_layer/utils/time_utils/`
|
||||
|
||||
**Purpose:** Time management, timestamp generation, and time synchronization.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- System time management
|
||||
- Timestamp generation for sensor data
|
||||
- Time synchronization with external sources
|
||||
- Time zone handling
|
||||
- Uptime tracking
|
||||
|
||||
#### 4.1.3 Logger Component
|
||||
**Component ID:** C-LOGGER-001
|
||||
**Location:** `application_layer/utils/logger/`
|
||||
|
||||
**Purpose:** Centralized logging infrastructure for system diagnostics and debugging.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- Multi-level logging (DEBUG, INFO, WARN, ERROR, FATAL)
|
||||
- Log message formatting and timestamping
|
||||
- Log output routing (UART, file, network)
|
||||
- Log level configuration
|
||||
- Log rotation and management
|
||||
|
||||
### 4.2 Missing Driver Layer Components
|
||||
|
||||
#### 4.2.1 Hardware Abstraction Layer (HAL) Components
|
||||
**Component ID:** C-HAL-001
|
||||
**Location:** `drivers/hal/`
|
||||
|
||||
**Purpose:** Hardware abstraction for sensors, communication interfaces, and peripherals.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- I2C/SPI/UART interface abstraction
|
||||
- GPIO management
|
||||
- ADC interface abstraction
|
||||
- Timer and PWM abstraction
|
||||
- Interrupt handling abstraction
|
||||
|
||||
#### 4.2.2 Sensor Driver Components
|
||||
**Component ID:** C-SENSOR-DRV-001 to C-SENSOR-DRV-007
|
||||
**Location:** `drivers/sensors/`
|
||||
|
||||
**Purpose:** Hardware-specific sensor drivers for each sensor type.
|
||||
|
||||
**Components Needed:**
|
||||
- Temperature Sensor Driver (SHT40)
|
||||
- Humidity Sensor Driver (SHT40)
|
||||
- CO2 Sensor Driver (SCD40)
|
||||
- NH3 Sensor Driver (Analog)
|
||||
- VOC Sensor Driver (SGP40)
|
||||
- PM Sensor Driver (SPS30)
|
||||
- Light Sensor Driver (TSL2591)
|
||||
|
||||
#### 4.2.3 Storage Driver Components
|
||||
**Component ID:** C-STORAGE-001
|
||||
**Location:** `drivers/storage/`
|
||||
|
||||
**Purpose:** Storage device drivers for SD card and NVM.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- SD card interface driver
|
||||
- NVM (flash) interface driver
|
||||
- File system abstraction
|
||||
- Storage health monitoring
|
||||
- Wear leveling support
|
||||
|
||||
### 4.3 Missing Utility Components
|
||||
|
||||
#### 4.3.1 Crypto Utils Component
|
||||
**Component ID:** C-CRYPTO-001
|
||||
**Location:** `application_layer/utils/crypto_utils/`
|
||||
|
||||
**Purpose:** Cryptographic utility functions and algorithm implementations.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- Hash function implementations
|
||||
- Encryption/decryption utilities
|
||||
- Digital signature utilities
|
||||
- Random number generation
|
||||
- Key derivation functions
|
||||
|
||||
#### 4.3.2 Data Validation Component
|
||||
**Component ID:** C-VALIDATION-001
|
||||
**Location:** `application_layer/utils/validation/`
|
||||
|
||||
**Purpose:** Data validation utilities for sensor data and configuration.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- Sensor data range validation
|
||||
- Configuration parameter validation
|
||||
- Data format validation
|
||||
- Checksum and integrity validation
|
||||
- Schema validation for JSON data
|
||||
|
||||
## 5. Component Dependencies
|
||||
|
||||
### 5.1 Dependency Matrix
|
||||
|
||||
| Component | Depends On | Provides To |
|
||||
|-----------|------------|-------------|
|
||||
| System State Manager | Event System, Error Handler, Persistence | All Components |
|
||||
| Sensor Manager | Sensor Drivers, Event System, Time Utils, MC Manager | Data Pool, Communication Manager |
|
||||
| Communication Manager | Network Stack, TLS Manager, Event System | Main Hub APIs, OTA Manager |
|
||||
| OTA Manager | Communication Manager, System State Manager, Security Manager | System State Manager |
|
||||
| Machine Constants Manager | Persistence, Communication Manager, System State Manager | All Components |
|
||||
| Security Manager | Crypto Utils, Hardware Security, Diagnostics Manager | All Components |
|
||||
| Diagnostics Manager | Persistence, Event System, Security Manager | All Components |
|
||||
| Event System | Time Utils, Logger | All Components |
|
||||
| Data Pool | Persistence, Event System | Sensor Manager, Communication Manager |
|
||||
| Data Persistence | Storage Drivers, Error Handler | Data Pool, Machine Constants Manager |
|
||||
|
||||
### 5.2 Interface Dependencies
|
||||
|
||||
All components follow the dependency inversion principle, depending on interfaces rather than concrete implementations. This enables:
|
||||
- Testability through mock implementations
|
||||
- Flexibility in implementation changes
|
||||
- Clear contract definitions
|
||||
- Reduced coupling between components
|
||||
|
||||
## 6. Component Implementation Status
|
||||
|
||||
### 6.1 Completed Components (Specification Phase)
|
||||
- ✅ System State Manager (C-STM-001)
|
||||
- ✅ Sensor Manager (C-SENSOR-001)
|
||||
- ✅ Communication Manager (C-COM-001)
|
||||
- ✅ OTA Manager (C-OTA-001)
|
||||
- ✅ Machine Constants Manager (C-MC-001)
|
||||
- ✅ Security Manager (C-SEC-001)
|
||||
- ✅ Diagnostics Manager (C-DIAG-001)
|
||||
- ✅ Event System (C-EVENT-001)
|
||||
- ✅ Data Pool (C-DATA-POOL)
|
||||
- ✅ Data Persistence (C-DP-001)
|
||||
|
||||
### 6.2 Missing Components (Need Specification)
|
||||
- ❌ Error Handler (C-ERROR-001)
|
||||
- ❌ Time Utils (C-TIME-001)
|
||||
- ❌ Logger (C-LOGGER-001)
|
||||
- ❌ Hardware Abstraction Layer (C-HAL-001)
|
||||
- ❌ Sensor Drivers (C-SENSOR-DRV-001 to 007)
|
||||
- ❌ Storage Drivers (C-STORAGE-001)
|
||||
- ❌ Crypto Utils (C-CRYPTO-001)
|
||||
- ❌ Data Validation (C-VALIDATION-001)
|
||||
|
||||
## 7. Next Steps
|
||||
|
||||
1. **Create Missing Component Specifications**: Develop detailed component specifications for all missing components following the same format as existing components.
|
||||
|
||||
2. **Validate Component Interfaces**: Review and validate all component interfaces to ensure proper abstraction and minimal coupling.
|
||||
|
||||
3. **Implementation Planning**: Create implementation roadmap prioritizing critical path components.
|
||||
|
||||
4. **Integration Testing Strategy**: Develop comprehensive integration testing strategy for component interactions.
|
||||
|
||||
5. **Performance Validation**: Validate that the component architecture meets all performance and resource constraints.
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete - Component Analysis
|
||||
**Next Review:** After missing component specifications are created
|
||||
**Dependencies:** Component specifications, architecture requirements
|
||||
Reference in New Issue
Block a user