ASF-Nabd/ASF_01_sys_sw_arch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
80236fa840226b550c2f4dc314cc2dcbfec03de8
ASF_01_sys_sw_arch/1 software design/components/SOFTWARE_COMPONENTS_OVERVIEW.md
mahmamdouh 80236fa840 components
2026-02-01 23:37:00 +01:00

14 KiB
Raw Blame History

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

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