# Global Software Architecture
# ASF Sensor Hub (Sub-Hub) Embedded System

**Document ID:** ARCH-ASF-SensorHub-SW-001  
**Version:** 2.0  
**Date:** 2025-02-01  
**Standard:** ISO/IEC/IEEE 42010:2011  
**Platform:** ESP32-S3, ESP-IDF v5.4, C/C++  
**Domain:** Industrial/Agricultural Automation (Smart Poultry Farm)

## 1. Introduction

### 1.1 Purpose

This document defines the complete software architecture for the ASF Sensor Hub (Sub-Hub) embedded system. It provides a comprehensive view of the system's software structure, component relationships, data flows, and architectural decisions that guide implementation.

### 1.2 Scope

This architecture covers:
- Complete software component hierarchy and dependencies
- Layered architecture with strict dependency rules
- Component interfaces and interaction patterns
- Data flow and communication mechanisms
- Concurrency model and resource management
- State-aware operation and system lifecycle
- Security architecture and enforcement points

### 1.3 Architectural Objectives

- **Modularity:** Clear separation of concerns with well-defined interfaces
- **Maintainability:** Structured design enabling easy modification and extension
- **Reliability:** Robust error handling and fault tolerance mechanisms
- **Performance:** Deterministic behavior meeting real-time constraints
- **Portability:** Hardware abstraction enabling platform independence
- **Security:** Layered security with hardware-enforced protection
- **Testability:** Architecture supporting comprehensive testing strategies

## 2. Architectural Overview

### 2.1 Architectural Style

The ASF Sensor Hub follows a **Layered Architecture** with the following characteristics:

- **Strict Layering:** Dependencies flow downward only (Application → Drivers → OSAL → HAL)
- **Component-Based Design:** Modular components with well-defined responsibilities
- **Event-Driven Communication:** Asynchronous inter-component communication
- **State-Aware Operation:** All components respect system state constraints
- **Hardware Abstraction:** Complete isolation of application logic from hardware
- **Data-Centric Design:** Centralized data management through Data Pool and Persistence components

### 2.2 Architectural Principles

| Principle | Description | Enforcement |
|-----------|-------------|-------------|
| **Separation of Concerns** | Each component has single, well-defined responsibility | Component specifications, code reviews |
| **Dependency Inversion** | High-level modules don't depend on low-level modules | Interface abstractions, dependency injection |
| **Single Source of Truth** | Data ownership clearly defined and centralized | Data Pool component, persistence abstraction |
| **Fail-Safe Operation** | System degrades gracefully under fault conditions | Error handling, state machine design |
| **Deterministic Behavior** | Predictable timing and resource usage | Static allocation, bounded operations |
| **Least Privilege** | Components have minimal required permissions | Interface restrictions, access control |
| **Defense in Depth** | Multiple security layers with independent validation | Hardware + software security measures |

## 3. Layered Architecture

### 3.1 Architecture Layers

```mermaid
graph TB
    subgraph "Application Layer"
        subgraph "Business Stack"
            STM[State Manager<br/>STM]
            EventSys[Event System]
            SensorMgr[Sensor Manager]
            MCMgr[MC Manager]
            ActuatorMgr[Actuator Manager]
            OTAMgr[OTA Manager]
            MainHubAPI[Main Hub APIs]
        end
        
        subgraph "DP Stack"
            DataPool[Data Pool]
            Persistence[Persistence]
        end
        
        DiagTask[Diagnostics Task]
        ErrorHandler[Error Handler]
    end
    
    subgraph "Drivers Layer"
        SensorDrivers[Sensor Drivers<br/>I2C/SPI/UART/ADC]
        NetworkStack[Network Stack<br/>Wi-Fi/ESP-NOW]
        StorageDrivers[Storage Drivers<br/>SD/NVM]
        DiagProtocol[Diagnostic Protocol]
    end
    
    subgraph "ESP-IDF Wrappers (OSAL)"
        I2CWrapper[I2C Wrapper]
        SPIWrapper[SPI Wrapper]
        UARTWrapper[UART Wrapper]
        ADCWrapper[ADC Wrapper]
        WiFiWrapper[WiFi Wrapper]
        TaskWrapper[Task Wrapper]
        TimerWrapper[Timer Wrapper]
    end
    
    subgraph "ESP-IDF Framework (HAL)"
        I2CHAL[I2C HAL]
        SPIHAL[SPI HAL]
        UARTHAL[UART HAL]
        ADCHAL[ADC HAL]
        WiFiHAL[WiFi HAL]
        FreeRTOS[FreeRTOS Kernel]
        SecureBoot[Secure Boot]
        FlashEncryption[Flash Encryption]
    end
    
    subgraph "Hardware"
        ESP32S3[ESP32-S3 MCU]
        Sensors[Environmental Sensors]
        SDCard[SD Card]
        OLED[OLED Display]
        Buttons[Navigation Buttons]
    end
    
    %% Layer Dependencies (downward only)
    STM --> EventSys
    SensorMgr --> SensorDrivers
    SensorMgr --> EventSys
    DataPool --> Persistence
    Persistence --> StorageDrivers
    MainHubAPI --> NetworkStack
    
    SensorDrivers --> I2CWrapper
    SensorDrivers --> SPIWrapper
    NetworkStack --> WiFiWrapper
    StorageDrivers --> SPIWrapper
    
    I2CWrapper --> I2CHAL
    SPIWrapper --> SPIHAL
    WiFiWrapper --> WiFiHAL
    TaskWrapper --> FreeRTOS
    
    I2CHAL --> ESP32S3
    SPIHAL --> ESP32S3
    WiFiHAL --> ESP32S3
    FreeRTOS --> ESP32S3
    
    ESP32S3 --> Sensors
    ESP32S3 --> SDCard
    ESP32S3 --> OLED
```