ASF-Nabd/ASF_01_sys_sw_arch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
a23dbf0828c214c0f1689bbcfc84f6293316e276
ASF_01_sys_sw_arch/1 software design/components/SOFTWARE_COMPONENTS_OVERVIEW.md
mahmamdouh a23dbf0828 software and system v1
2026-02-02 00:49:50 +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. 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