cleanup sw req

2026-02-01 19:47:53 +01:00
parent 0bdbcb1657
commit 304371c6b8
608 changed files with 47798 additions and 0 deletions
--- a/design/software_arch/Global_Software_Architecture.md
+++ b/design/software_arch/Global_Software_Architecture.md
@@ -0,0 +1,151 @@
+# 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
+```