# 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. Newly Added Components (Gap Resolution)

The following components have been added to close identified gaps:

### 4.1 OSAL Layer Components

| Component ID | Component Name | Purpose | Status |
|--------------|----------------|---------|--------|
| C-OSAL-I2C | I2C Wrapper | I2C bus abstraction | ✅ Specified |
| C-OSAL-SPI | SPI Wrapper | SPI bus abstraction | ✅ Specified |
| C-OSAL-UART | UART Wrapper | UART communication abstraction | ✅ Specified |
| C-OSAL-ADC | ADC Wrapper | Analog-to-digital conversion abstraction | ✅ Specified |
| C-OSAL-GPIO | GPIO Wrapper | GPIO operations with discipline enforcement | ✅ Specified |
| C-OSAL-TASK | Task Wrapper | FreeRTOS task abstraction | ✅ Specified |
| C-OSAL-TIMER | Timer Wrapper | Hardware timer abstraction | ✅ Specified |
| C-OSAL-MUTEX | Mutex Wrapper | Mutual exclusion abstraction | ✅ Specified |
| C-OSAL-QUEUE | Queue Wrapper | Inter-task communication abstraction | ✅ Specified |
| C-OSAL-SEM | Semaphore Wrapper | Synchronization abstraction | ✅ Specified |

### 4.2 Sensor Driver Components

| Component ID | Component Name | Sensor Type | Interface | Status |
|--------------|----------------|-------------|-----------|--------|
| C-SENSOR-DRV-TEMP | Temperature Driver | SHT40 | I2C | ✅ Specified |
| C-SENSOR-DRV-HUM | Humidity Driver | SHT40 | I2C | ✅ Specified |
| C-SENSOR-DRV-CO2 | CO2 Driver | SCD40 | I2C | ✅ Specified |
| C-SENSOR-DRV-NH3 | NH3 Driver | Analog | ADC | ✅ Specified |
| C-SENSOR-DRV-VOC | VOC Driver | SGP40 | I2C | ✅ Specified |
| C-SENSOR-DRV-PM | PM Driver | SPS30 | UART | ✅ Specified |
| C-SENSOR-DRV-LIGHT | Light Driver | TSL2591 | I2C | ✅ Specified |

### 4.3 Network Stack Components

| Component ID | Component Name | Purpose | Status |
|--------------|----------------|---------|--------|
| C-NET-WIFI | Wi-Fi Manager | Wi-Fi connection management | ✅ Specified |
| C-NET-MQTT | MQTT Client | MQTT protocol implementation | ✅ Specified |
| C-NET-TLS | TLS Manager | TLS 1.2 encryption | ✅ Specified |
| C-NET-ESPNOW | ESP-NOW Handler | ESP-NOW peer communication | ✅ Specified |

### 4.4 Storage Driver Components

| Component ID | Component Name | Purpose | Status |
|--------------|----------------|---------|--------|
| C-STORAGE-SD | SD Card Driver | SD card file system access | ✅ Specified |
| C-STORAGE-NVM | NVM Driver | Non-volatile storage access | ✅ Specified |

### 4.5 Service Components

| Component ID | Component Name | Purpose | Status |
|--------------|----------------|---------|--------|
| C-TIME-SYNC-001 | Time Synchronization Service | Time sync with Main Hub/NTP | ✅ Specified |
| C-WATCHDOG-001 | Watchdog Manager | Layered watchdog system | ✅ Specified |

### 4.6 Utility Components

| Component ID | Component Name | Purpose | Status |
|--------------|----------------|---------|--------|
| C-CRYPTO-001 | Crypto Utils | Cryptographic functions | ✅ Specified |
| C-MSG-FMT-001 | Message Formatter | CBOR encoding/decoding | ✅ Specified |
| C-FILTER-001 | Filter Engine | Sensor data filtering | ✅ Specified |
| C-HMI-001 | HMI Controller | OLED display and buttons | ✅ Specified |

## 5. Missing Components Analysis (Resolved)

All previously identified missing components have been specified:

### 5.1 Previously Missing Components (Now Specified)

All components listed in section 4 have been fully specified with complete component documentation.

## 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 Component Status Summary

**Total Components:** 40+  
**Fully Specified:** 40+ (100%)  
**Implementation Status:** Not Started (all components)

**Component Categories:**
- Application Layer: 14 components ✅
- OSAL Layer: 10 components ✅
- Sensor Drivers: 7 components ✅
- Network Stack: 4 components ✅
- Storage Drivers: 2 components ✅
- Services: 2 components ✅
- Utilities: 5 components ✅

## 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