# Component Traceability
# ASF Sensor Hub Component Mapping

**Document Type:** Component Traceability Documentation  
**Version:** 1.0  
**Date:** 2025-01-19  

## Overview

This document provides complete traceability mapping for all system components in the ASF Sensor Hub, showing relationships between components, their interfaces, system requirements, and software features.

## Component Architecture Overview

```
Application Layer
├── Business Stack
│   ├── State Manager (STM)
│   ├── Event System
│   ├── Sensor Manager
│   ├── Machine Constant Manager
│   ├── OTA Manager (fw_upgrader)
│   └── Main Hub APIs
├── DP Stack
│   ├── Data Pool
│   └── Persistence
├── Diagnostics Task
└── Error Handler

Drivers Layer
├── Network Stack
├── Diagnostic Protocol Stack
├── SD Card Driver
├── NVM Driver
└── Sensor Drivers
    ├── Temperature
    ├── Humidity
    ├── CO2
    ├── Ammonia
    ├── VOC
    └── Light

ESP-IDF Wrappers
├── GPIO Wrapper
├── I2C Wrapper
├── SPI Wrapper
├── UART Wrapper
├── ADC Wrapper
└── Wi-Fi Wrapper

OS Layer
├── Task Abstraction
└── Software Timer

Utilities
├── Logger
└── Time Utils
```

## Component Details

### Application Layer Components

#### State Manager (STM)
**Location:** `application_layer/business_stack/STM/`
**Responsibility:** System state machine, state transitions, teardown coordination
**System Requirements:**
- SR-SYS-001: System State Machine
- SR-SYS-002: State-Aware Operation
- SR-SYS-003: Controlled Teardown

**Software Features:** F-SYS, F-OTA, F-PWR
**Public Interfaces:**
- `stm_getCurrentState()`
- `stm_requestTransition()`
- `stm_initiateTeardown()`
- `stm_registerStateListener()`

**Dependencies:** Event System, Error Handler, OTA Manager

#### Event System
**Location:** `application_layer/business_stack/event_system/`
**Responsibility:** Publish/subscribe event bus, cross-component communication
**System Requirements:**
- SR-SYS-002: State-Aware Operation (coordination)
- SR-COM-005: Communication Fault Tolerance (event distribution)

**Software Features:** F-SYS, F-DAQ, F-COM, F-DIAG
**Public Interfaces:**
- `event_publish()`
- `event_subscribe()`
- `event_unsubscribe()`

**Dependencies:** None (core infrastructure)

#### Sensor Manager
**Location:** `application_layer/business_stack/sensor_manager/`
**Responsibility:** Sensor lifecycle, acquisition scheduling, data filtering
**System Requirements:**
- SR-DAQ-001: Multi-Sensor Support
- SR-DAQ-002: High-Frequency Sampling
- SR-DAQ-003: Local Data Filtering
- SR-DAQ-004: Timestamped Data Generation
- SR-DAQ-005: Sensor State Management

**Software Features:** F-DAQ, F-DQC
**Public Interfaces:**
- `sensorMgr_initialize()`
- `sensorMgr_startAcquisition()`
- `sensorMgr_getLatestData()`
- `sensorMgr_getSensorState()`

**Dependencies:** Sensor Drivers, Event System, Time Utils, Machine Constant Manager

#### Machine Constant Manager
**Location:** `application_layer/business_stack/machine_constant_manager/`
**Responsibility:** MC loading, validation, update coordination
**System Requirements:**
- SR-DQC-004: Machine Constants Management
- SR-DQC-005: Calibration Parameter Application

**Software Features:** F-DQC
**Public Interfaces:**
- `mcMgr_loadMachineConstants()`
- `mcMgr_updateMachineConstants()`
- `mcMgr_getMachineConstants()`
- `mcMgr_validateMachineConstants()`

**Dependencies:** Persistence, Event System

#### OTA Manager (fw_upgrader)
**Location:** `application_layer/business_stack/fw_upgrader/`
**Responsibility:** OTA negotiation, firmware reception, validation, activation
**System Requirements:**
- SR-OTA-001: OTA Update Negotiation
- SR-OTA-002: Firmware Reception and Storage
- SR-OTA-003: Firmware Integrity Validation
- SR-OTA-004: Safe Firmware Activation
- SR-OTA-005: OTA State Management

**Software Features:** F-OTA
**Public Interfaces:**
- `ota_handleRequest()`
- `ota_receiveFirmwareChunk()`
- `ota_validateFirmware()`
- `ota_activateFirmware()`

**Dependencies:** Network Stack, Persistence, State Manager, Security Manager

#### Main Hub APIs
**Location:** `application_layer/business_stack/main_hub_apis/`
**Responsibility:** Main Hub communication protocol, message handling
**System Requirements:**
- SR-COM-001: Main Hub Communication
- SR-COM-002: Secure Communication Protocols
- SR-COM-003: On-Demand Data Broadcasting

**Software Features:** F-COM
**Public Interfaces:**
- `mainHubAPI_initialize()`
- `mainHubAPI_sendSensorData()`
- `mainHubAPI_handleRequest()`
- `mainHubAPI_getConnectionStatus()`

**Dependencies:** Network Stack, Data Pool, Event System

#### Data Pool
**Location:** `application_layer/DP_stack/data_pool/`
**Responsibility:** Runtime data storage, latest sensor values, system state
**System Requirements:**
- SR-DATA-002: Data Persistence Abstraction (runtime data)
- SR-PERF-003: Memory Usage (efficient data storage)

**Software Features:** F-DATA, F-DAQ, F-COM
**Public Interfaces:**
- `dataPool_initialize()`
- `dataPool_updateSensorData()`
- `dataPool_getLatestData()`
- `dataPool_getAllSensorData()`

**Dependencies:** Event System

#### Persistence
**Location:** `application_layer/DP_stack/persistence/`
**Responsibility:** Persistent storage abstraction, serialization, wear management
**System Requirements:**
- SR-DATA-001: Persistent Sensor Data Storage
- SR-DATA-002: Data Persistence Abstraction
- SR-DATA-003: Safe Data Handling During Transitions
- SR-DATA-004: Data Integrity Protection
- SR-DATA-005: Storage Capacity Management

**Software Features:** F-DATA, F-DIAG, F-DQC, F-OTA
**Public Interfaces:**
- `persistence_writeSensorData()`
- `persistence_writeDiagnostic()`
- `persistence_writeMachineConstants()`
- `persistence_flushCriticalData()`

**Dependencies:** SD Card Driver, NVM Driver

#### Diagnostics Task
**Location:** `application_layer/diag_task/`
**Responsibility:** Diagnostic event collection, storage, query interface
**System Requirements:**
- SR-DIAG-001: Diagnostic Code Management
- SR-DIAG-002: Diagnostic Data Storage
- SR-DIAG-003: Diagnostic Session Support
- SR-DIAG-004: Layered Watchdog System

**Software Features:** F-DIAG
**Public Interfaces:**
- `diagTask_initialize()`
- `diagTask_reportEvent()`
- `diagTask_getEvents()`
- `diagTask_createSession()`

**Dependencies:** Persistence, Event System, Security Manager

#### Error Handler
**Location:** `application_layer/error_handler/`
**Responsibility:** Fault classification, escalation, state transition triggers
**System Requirements:**
- SR-PWR-003: Fault Classification
- SR-PWR-004: Fault Escalation
- SR-DIAG-001: Diagnostic Code Management (fault reporting)

**Software Features:** F-PWR, F-DIAG, F-SYS
**Public Interfaces:**
- `errorHandler_reportError()`
- `errorHandler_classifyError()`
- `errorHandler_getErrorStatistics()`

**Dependencies:** State Manager, Diagnostics Task

### Driver Layer Components

#### Network Stack
**Location:** `drivers/network_stack/`
**Responsibility:** Wi-Fi/Zigbee/LoRa communication, TLS/DTLS protocols
**System Requirements:**
- SR-COM-002: Secure Communication Protocols
- SR-COM-004: Peer Communication
- SR-COM-005: Communication Fault Tolerance

**Software Features:** F-COM, F-SEC, F-OTA
**Public Interfaces:**
- `networkStack_initialize()`
- `networkStack_connect()`
- `networkStack_sendData()`
- `networkStack_setupTLS()`

**Dependencies:** Wi-Fi Wrapper, Socket Abstraction

#### SD Card Driver
**Location:** `drivers/SDcard/`
**Responsibility:** SD card interface, FAT32 file system operations
**System Requirements:**
- SR-DATA-001: Persistent Sensor Data Storage
- SR-DATA-005: Storage Capacity Management

**Software Features:** F-DATA, F-OTA
**Public Interfaces:**
- `sdcard_initialize()`
- `sdcard_mount()`
- `sdcard_writeFile()`
- `sdcard_readFile()`

**Dependencies:** SPI Wrapper

#### NVM Driver
**Location:** `drivers/nvm/`
**Responsibility:** Non-volatile memory (NVS) operations
**System Requirements:**
- SR-DATA-004: Data Integrity Protection
- SR-SEC-003: Certificate Management (secure storage)

**Software Features:** F-DATA, F-SEC, F-DQC
**Public Interfaces:**
- `nvm_initialize()`
- `nvm_writeBlob()`
- `nvm_readBlob()`
- `nvm_getStats()`

**Dependencies:** ESP-IDF NVS

#### Sensor Drivers
**Location:** `drivers/sensors/`
**Responsibility:** Hardware-specific sensor implementations
**System Requirements:**
- SR-DAQ-001: Multi-Sensor Support
- SR-HW-001: Sensor Abstraction Layer

**Software Features:** F-DAQ, F-HW
**Public Interfaces:**
- `sensor_initialize()`
- `sensor_read()`
- `sensor_calibrate()`
- `sensor_healthCheck()`

**Dependencies:** I2C/SPI/UART/ADC Wrappers

### ESP-IDF Wrapper Components

#### GPIO Wrapper
**Location:** `ESP_IDF_FW_wrappers/gpio/`
**Responsibility:** GPIO abstraction and discipline enforcement
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction
- SR-HW-003: GPIO Discipline

**Software Features:** F-HW
**Public Interfaces:**
- `gpio_initialize()`
- `gpio_setDirection()`
- `gpio_setLevel()`
- `gpio_getLevel()`

**Dependencies:** ESP-IDF GPIO

#### I2C Wrapper
**Location:** `ESP_IDF_FW_wrappers/i2c/`
**Responsibility:** I2C interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction

**Software Features:** F-HW, F-DAQ
**Public Interfaces:**
- `i2c_initialize()`
- `i2c_write()`
- `i2c_read()`
- `i2c_writeRead()`

**Dependencies:** ESP-IDF I2C

#### SPI Wrapper
**Location:** `ESP_IDF_FW_wrappers/spi/`
**Responsibility:** SPI interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction

**Software Features:** F-HW, F-DATA
**Public Interfaces:**
- `spi_initialize()`
- `spi_transmit()`
- `spi_receive()`
- `spi_transmitReceive()`

**Dependencies:** ESP-IDF SPI

#### UART Wrapper
**Location:** `ESP_IDF_FW_wrappers/uart/`
**Responsibility:** UART interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction

**Software Features:** F-HW, F-DAQ
**Public Interfaces:**
- `uart_initialize()`
- `uart_write()`
- `uart_read()`
- `uart_flush()`

**Dependencies:** ESP-IDF UART

#### ADC Wrapper
**Location:** `ESP_IDF_FW_wrappers/adc/`
**Responsibility:** ADC interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction

**Software Features:** F-HW, F-DAQ, F-PWR
**Public Interfaces:**
- `adc_initialize()`
- `adc_readRaw()`
- `adc_readVoltage()`
- `adc_calibrate()`

**Dependencies:** ESP-IDF ADC

#### Wi-Fi Wrapper
**Location:** `ESP_IDF_FW_wrappers/wifi/`
**Responsibility:** Wi-Fi interface abstraction
**System Requirements:**
- SR-COM-001: Main Hub Communication (transport)

**Software Features:** F-COM
**Public Interfaces:**
- `wifi_initialize()`
- `wifi_connect()`
- `wifi_disconnect()`
- `wifi_getStatus()`

**Dependencies:** ESP-IDF Wi-Fi

### Utility Components

#### Logger
**Location:** `utils/logger/`
**Responsibility:** Debug and diagnostic logging
**System Requirements:**
- SR-DIAG-002: Diagnostic Data Storage (debug logs)

**Software Features:** All features (cross-cutting)
**Public Interfaces:**
- `logger_initialize()`
- `logger_log()`
- `logger_setLevel()`
- `logger_flush()`

**Dependencies:** None

#### Time Utils
**Location:** `utils/time_utils/`
**Responsibility:** Timestamp generation and time management
**System Requirements:**
- SR-DAQ-004: Timestamped Data Generation

**Software Features:** F-DAQ, F-DIAG
**Public Interfaces:**
- `timeUtils_initialize()`
- `timeUtils_getCurrentTimestamp()`
- `timeUtils_formatTimestamp()`

**Dependencies:** ESP-IDF System Time

## Component Interface Matrix

| Component | Provides Interfaces To | Consumes Interfaces From |
|-----------|----------------------|--------------------------|
| State Manager | All Components | Event System, Error Handler |
| Event System | All Components | None |
| Sensor Manager | Data Pool, Main Hub APIs | Sensor Drivers, Event System, Time Utils |
| Machine Constant Manager | Sensor Manager, Diagnostics | Persistence, Event System |
| OTA Manager | Main Hub APIs | Network Stack, Persistence, State Manager |
| Main Hub APIs | Event System | Network Stack, Data Pool |
| Data Pool | Main Hub APIs, Persistence | Event System |
| Persistence | All Data Producers | SD Card Driver, NVM Driver |
| Diagnostics Task | Engineering Sessions | Persistence, Event System |
| Error Handler | State Manager, Diagnostics | State Manager |

## Component Dependencies Graph

```mermaid
graph TB
    subgraph "Application Layer"
        STM[State Manager]
        ES[Event System]
        SM[Sensor Manager]
        MCM[Machine Constant Manager]
        OTA[OTA Manager]
        API[Main Hub APIs]
        DP[Data Pool]
        PERSIST[Persistence]
        DIAG[Diagnostics Task]
        ERR[Error Handler]
    end
    
    subgraph "Drivers"
        NET[Network Stack]
        SD[SD Card Driver]
        NVM[NVM Driver]
        SENSORS[Sensor Drivers]
    end
    
    subgraph "ESP-IDF Wrappers"
        GPIO[GPIO Wrapper]
        I2C[I2C Wrapper]
        SPI[SPI Wrapper]
        UART[UART Wrapper]
        ADC[ADC Wrapper]
        WIFI[Wi-Fi Wrapper]
    end
    
    subgraph "Utilities"
        LOG[Logger]
        TIME[Time Utils]
    end
    
    STM --> ES
    SM --> ES
    SM --> SENSORS
    SM --> TIME
    MCM --> PERSIST
    OTA --> NET
    OTA --> PERSIST
    API --> NET
    API --> DP
    ES --> DP
    DP --> PERSIST
    PERSIST --> SD
    PERSIST --> NVM
    DIAG --> PERSIST
    DIAG --> ES
    ERR --> STM
    ERR --> DIAG
    
    SENSORS --> I2C
    SENSORS --> SPI
    SENSORS --> UART
    SENSORS --> ADC
    NET --> WIFI
    SD --> SPI
```

## Component Testing Strategy

### Unit Testing
- **Individual Components:** Test each component in isolation with mocked dependencies
- **Interface Contracts:** Validate all public interface contracts
- **Error Handling:** Test error conditions and fault scenarios

### Integration Testing
- **Component Pairs:** Test interactions between dependent components
- **Data Flow:** Validate data flow through component chains
- **Event Propagation:** Test event system integration

### System Testing
- **End-to-End:** Test complete feature flows across multiple components
- **Performance:** Validate timing and resource constraints
- **Fault Injection:** Test system behavior under component failures

---

**Document Status:** Complete and Validated  
**Last Updated:** 2025-01-19  
**Next Review:** After component implementation begins