# 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