cleanup sw req
This commit is contained in:
866
1 software design/draft/Global_Software_Architecture.md
Normal file
866
1 software design/draft/Global_Software_Architecture.md
Normal file
@@ -0,0 +1,866 @@
|
||||
# Global Software Architecture
|
||||
# ASF Sensor Hub (Sub-Hub) Embedded System
|
||||
|
||||
**Document Type:** Global Software Architecture Specification
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
**Platform:** ESP32-S3, ESP-IDF v5.4, C/C++
|
||||
**Standard:** ISO/IEC/IEEE 42010:2011
|
||||
|
||||
## 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
|
||||
|
||||
### 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
|
||||
|
||||
## 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
|
||||
|
||||
### 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 |
|
||||
|
||||
## 3. Layered Architecture
|
||||
|
||||
### 3.1 Architecture Layers
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Application Layer"
|
||||
subgraph "Business Stack"
|
||||
STM[State Manager]
|
||||
EventSys[Event System]
|
||||
SensorMgr[Sensor Manager]
|
||||
MCMgr[MC Manager]
|
||||
OTAMgr[OTA Manager]
|
||||
MainHubAPI[Main Hub APIs]
|
||||
end
|
||||
|
||||
subgraph "DP Stack"
|
||||
DataPool[Data Pool]
|
||||
Persistence[Persistence]
|
||||
end
|
||||
|
||||
DiagTask[Diagnostics Task]
|
||||
ErrorHandler[Error Handler]
|
||||
HMI[HMI Controller]
|
||||
Engineering[Engineering Session]
|
||||
end
|
||||
|
||||
subgraph "Drivers Layer"
|
||||
SensorDrivers[Sensor Drivers]
|
||||
NetworkStack[Network Stack]
|
||||
StorageDrivers[Storage Drivers]
|
||||
DiagProtocol[Diagnostic Protocol]
|
||||
GPIOManager[GPIO Manager]
|
||||
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
|
||||
```
|
||||
|
||||
### 3.2 Layer Descriptions
|
||||
|
||||
#### 3.2.1 Application Layer
|
||||
|
||||
**Purpose:** Implements business logic and system-specific functionality.
|
||||
|
||||
**Components:**
|
||||
- **Business Stack:** Core business logic components (STM, Event System, Managers)
|
||||
- **DP Stack:** Data management components (Data Pool, Persistence)
|
||||
- **Support Components:** Diagnostics, Error Handling, HMI, Engineering Access
|
||||
|
||||
**Responsibilities:**
|
||||
- System state management and lifecycle control
|
||||
- Sensor data acquisition and processing
|
||||
- Communication protocol implementation
|
||||
- Data persistence and management
|
||||
- User interface and engineering access
|
||||
|
||||
**Constraints:**
|
||||
- SHALL NOT access hardware directly
|
||||
- SHALL use Event System for inter-component communication
|
||||
- SHALL respect system state restrictions
|
||||
- SHALL use Data Pool for runtime data access
|
||||
|
||||
#### 3.2.2 Drivers Layer
|
||||
|
||||
**Purpose:** Provides hardware abstraction and protocol implementation.
|
||||
|
||||
**Components:**
|
||||
- **Sensor Drivers:** Hardware-specific sensor interfaces
|
||||
- **Network Stack:** Communication protocol implementation
|
||||
- **Storage Drivers:** SD Card and NVM access
|
||||
- **Diagnostic Protocol:** Engineering access protocol
|
||||
- **GPIO Manager:** Hardware resource management
|
||||
|
||||
**Responsibilities:**
|
||||
- Hardware device abstraction
|
||||
- Protocol implementation (I2C, SPI, UART, WiFi)
|
||||
- Resource management and conflict resolution
|
||||
- Error detection and reporting
|
||||
|
||||
**Constraints:**
|
||||
- SHALL provide uniform interfaces to application layer
|
||||
- SHALL handle hardware-specific details
|
||||
- SHALL implement proper error handling
|
||||
- SHALL coordinate resource access
|
||||
|
||||
#### 3.2.3 ESP-IDF Wrappers (OSAL)
|
||||
|
||||
**Purpose:** Operating System Abstraction Layer providing platform independence.
|
||||
|
||||
**Components:**
|
||||
- **Hardware Wrappers:** I2C, SPI, UART, ADC, WiFi abstractions
|
||||
- **OS Wrappers:** Task, Timer, Socket abstractions
|
||||
- **System Services:** Logging, Time utilities
|
||||
|
||||
**Responsibilities:**
|
||||
- Platform abstraction for portability
|
||||
- Uniform interface to ESP-IDF services
|
||||
- Resource management and synchronization
|
||||
- System service abstraction
|
||||
|
||||
**Constraints:**
|
||||
- SHALL provide platform-independent interfaces
|
||||
- SHALL encapsulate ESP-IDF specific details
|
||||
- SHALL maintain API stability across ESP-IDF versions
|
||||
- SHALL handle platform-specific error conditions
|
||||
|
||||
#### 3.2.4 ESP-IDF Framework (HAL)
|
||||
|
||||
**Purpose:** Hardware Abstraction Layer and system services.
|
||||
|
||||
**Components:**
|
||||
- **Hardware Drivers:** Low-level hardware access
|
||||
- **FreeRTOS Kernel:** Real-time operating system
|
||||
- **Security Services:** Secure Boot, Flash Encryption
|
||||
- **System Services:** Memory management, interrupt handling
|
||||
|
||||
**Responsibilities:**
|
||||
- Direct hardware access and control
|
||||
- Real-time task scheduling
|
||||
- Security enforcement
|
||||
- System resource management
|
||||
|
||||
## 4. Component Architecture
|
||||
|
||||
### 4.1 Component Dependency Graph
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Application Components"
|
||||
STM[State Manager<br/>COMP-STM]
|
||||
ES[Event System<br/>COMP-EVENT]
|
||||
SM[Sensor Manager<br/>COMP-SENSOR-MGR]
|
||||
MCM[MC Manager<br/>COMP-MC-MGR]
|
||||
OTA[OTA Manager<br/>COMP-OTA-MGR]
|
||||
MHA[Main Hub APIs<br/>COMP-MAIN-HUB]
|
||||
DP[Data Pool<br/>COMP-DATA-POOL]
|
||||
PERS[Persistence<br/>COMP-PERSISTENCE]
|
||||
DIAG[Diagnostics Task<br/>COMP-DIAG-TASK]
|
||||
ERR[Error Handler<br/>COMP-ERROR-HANDLER]
|
||||
HMI[HMI Controller<br/>COMP-HMI]
|
||||
ENG[Engineering Session<br/>COMP-ENGINEERING]
|
||||
end
|
||||
|
||||
subgraph "Driver Components"
|
||||
SD[Sensor Drivers<br/>COMP-SENSOR-DRV]
|
||||
NS[Network Stack<br/>COMP-NETWORK]
|
||||
STOR[Storage Drivers<br/>COMP-STORAGE]
|
||||
DIAG_PROT[Diagnostic Protocol<br/>COMP-DIAG-PROT]
|
||||
GPIO[GPIO Manager<br/>COMP-GPIO]
|
||||
end
|
||||
|
||||
subgraph "Utility Components"
|
||||
LOG[Logger<br/>COMP-LOGGER]
|
||||
TIME[Time Utils<br/>COMP-TIME]
|
||||
SEC[Security Manager<br/>COMP-SECURITY]
|
||||
end
|
||||
|
||||
%% Primary Dependencies
|
||||
STM --> ES
|
||||
SM --> ES
|
||||
SM --> SD
|
||||
SM --> TIME
|
||||
MCM --> PERS
|
||||
OTA --> NS
|
||||
OTA --> PERS
|
||||
MHA --> NS
|
||||
MHA --> DP
|
||||
DP --> TIME
|
||||
PERS --> STOR
|
||||
DIAG --> PERS
|
||||
ERR --> STM
|
||||
ERR --> DIAG
|
||||
HMI --> DP
|
||||
ENG --> SEC
|
||||
|
||||
%% Logging Dependencies
|
||||
STM --> LOG
|
||||
SM --> LOG
|
||||
OTA --> LOG
|
||||
MHA --> LOG
|
||||
DIAG --> LOG
|
||||
ERR --> LOG
|
||||
|
||||
%% Event System Dependencies
|
||||
ES --> DP
|
||||
ES --> DIAG
|
||||
ES --> HMI
|
||||
|
||||
%% Cross-cutting Dependencies
|
||||
SD --> GPIO
|
||||
NS --> GPIO
|
||||
STOR --> GPIO
|
||||
HMI --> GPIO
|
||||
```
|
||||
|
||||
### 4.2 Component Interaction Patterns
|
||||
|
||||
#### 4.2.1 Event-Driven Communication
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant SM as Sensor Manager
|
||||
participant ES as Event System
|
||||
participant DP as Data Pool
|
||||
participant MHA as Main Hub APIs
|
||||
participant PERS as Persistence
|
||||
|
||||
Note over SM,PERS: Sensor Data Update Flow
|
||||
|
||||
SM->>SM: processSensorData()
|
||||
SM->>ES: publish(SENSOR_DATA_UPDATE, data)
|
||||
|
||||
par Parallel Event Delivery
|
||||
ES->>DP: notify(SENSOR_DATA_UPDATE, data)
|
||||
DP->>DP: updateSensorData(data)
|
||||
and
|
||||
ES->>MHA: notify(SENSOR_DATA_UPDATE, data)
|
||||
MHA->>MHA: queueForTransmission(data)
|
||||
and
|
||||
ES->>PERS: notify(SENSOR_DATA_UPDATE, data)
|
||||
PERS->>PERS: persistSensorData(data)
|
||||
end
|
||||
|
||||
Note over SM,PERS: All components updated asynchronously
|
||||
```
|
||||
|
||||
#### 4.2.2 State-Aware Operation
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant COMP as Any Component
|
||||
participant STM as State Manager
|
||||
participant ES as Event System
|
||||
|
||||
Note over COMP,ES: State-Aware Operation Pattern
|
||||
|
||||
COMP->>STM: getCurrentState()
|
||||
STM-->>COMP: current_state
|
||||
|
||||
COMP->>COMP: checkOperationAllowed(current_state)
|
||||
|
||||
alt Operation Allowed
|
||||
COMP->>COMP: executeOperation()
|
||||
COMP->>ES: publish(OPERATION_COMPLETE, result)
|
||||
else Operation Not Allowed
|
||||
COMP->>COMP: skipOperation()
|
||||
COMP->>ES: publish(OPERATION_SKIPPED, reason)
|
||||
end
|
||||
|
||||
Note over COMP,ES: State changes trigger re-evaluation
|
||||
ES->>COMP: notify(STATE_CHANGED, new_state)
|
||||
COMP->>COMP: updateOperationPermissions(new_state)
|
||||
```
|
||||
|
||||
#### 4.2.3 Data Access Pattern
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant COMP as Component
|
||||
participant DP as Data Pool
|
||||
participant PERS as Persistence
|
||||
participant STOR as Storage Driver
|
||||
|
||||
Note over COMP,STOR: Data Access Hierarchy
|
||||
|
||||
COMP->>DP: getLatestSensorData()
|
||||
DP-->>COMP: sensor_data (if available)
|
||||
|
||||
alt Data Not Available in Pool
|
||||
COMP->>PERS: loadSensorData()
|
||||
PERS->>STOR: readFromStorage()
|
||||
STOR-->>PERS: stored_data
|
||||
PERS-->>COMP: sensor_data
|
||||
PERS->>DP: updateDataPool(sensor_data)
|
||||
end
|
||||
|
||||
Note over COMP,STOR: Write operations go through persistence
|
||||
COMP->>PERS: persistSensorData(data)
|
||||
PERS->>DP: updateDataPool(data)
|
||||
PERS->>STOR: writeToStorage(data)
|
||||
```
|
||||
|
||||
## 5. Data Flow Architecture
|
||||
|
||||
### 5.1 Primary Data Flows
|
||||
|
||||
#### 5.1.1 Sensor Data Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
SENSORS[Physical Sensors] --> SD[Sensor Drivers]
|
||||
SD --> SM[Sensor Manager]
|
||||
SM --> FILTER[Local Filtering]
|
||||
FILTER --> TIMESTAMP[Timestamp Generation]
|
||||
TIMESTAMP --> ES[Event System]
|
||||
|
||||
ES --> DP[Data Pool]
|
||||
ES --> PERS[Persistence]
|
||||
ES --> MHA[Main Hub APIs]
|
||||
|
||||
DP --> HMI[HMI Display]
|
||||
DP --> DIAG[Diagnostics]
|
||||
|
||||
PERS --> SD_CARD[SD Card Storage]
|
||||
PERS --> NVM[NVM Storage]
|
||||
|
||||
MHA --> NETWORK[Network Stack]
|
||||
NETWORK --> MAIN_HUB[Main Hub]
|
||||
|
||||
style SENSORS fill:#e1f5fe
|
||||
style SD_CARD fill:#f3e5f5
|
||||
style MAIN_HUB fill:#e8f5e8
|
||||
```
|
||||
|
||||
#### 5.1.2 System State Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
TRIGGER[State Trigger] --> STM[State Manager]
|
||||
STM --> VALIDATE[Validate Transition]
|
||||
VALIDATE --> TEARDOWN{Requires Teardown?}
|
||||
|
||||
TEARDOWN -->|Yes| TD_SEQ[Teardown Sequence]
|
||||
TEARDOWN -->|No| TRANSITION[Execute Transition]
|
||||
|
||||
TD_SEQ --> STOP_OPS[Stop Operations]
|
||||
STOP_OPS --> FLUSH_DATA[Flush Critical Data]
|
||||
FLUSH_DATA --> TRANSITION
|
||||
|
||||
TRANSITION --> ES[Event System]
|
||||
ES --> ALL_COMPONENTS[All Components]
|
||||
ALL_COMPONENTS --> UPDATE_BEHAVIOR[Update Behavior]
|
||||
|
||||
STM --> PERS[Persistence]
|
||||
PERS --> STATE_STORAGE[State Storage]
|
||||
|
||||
style TRIGGER fill:#ffebee
|
||||
style STATE_STORAGE fill:#f3e5f5
|
||||
```
|
||||
|
||||
#### 5.1.3 Diagnostic Data Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
FAULT_SOURCE[Fault Source] --> ERR[Error Handler]
|
||||
ERR --> CLASSIFY[Classify Fault]
|
||||
CLASSIFY --> ESCALATE{Escalation Needed?}
|
||||
|
||||
ESCALATE -->|Yes| STM[State Manager]
|
||||
ESCALATE -->|No| DIAG[Diagnostics Task]
|
||||
|
||||
STM --> STATE_CHANGE[State Transition]
|
||||
STATE_CHANGE --> ES[Event System]
|
||||
|
||||
DIAG --> DP[Data Pool]
|
||||
DIAG --> PERS[Persistence]
|
||||
DIAG --> ES
|
||||
|
||||
DP --> HMI[HMI Display]
|
||||
PERS --> DIAG_STORAGE[Diagnostic Storage]
|
||||
ES --> ENG[Engineering Session]
|
||||
|
||||
style FAULT_SOURCE fill:#ffebee
|
||||
style DIAG_STORAGE fill:#f3e5f5
|
||||
```
|
||||
|
||||
### 5.2 Data Consistency Model
|
||||
|
||||
#### 5.2.1 Data Ownership
|
||||
|
||||
| Data Type | Owner | Access Pattern | Persistence |
|
||||
|-----------|-------|----------------|-------------|
|
||||
| **Sensor Data** | Sensor Manager | Write-once, read-many | Data Pool → Persistence |
|
||||
| **System State** | State Manager | Single writer, multiple readers | Direct persistence |
|
||||
| **Diagnostics** | Diagnostics Task | Append-only, read-many | Circular log |
|
||||
| **Configuration** | MC Manager | Infrequent updates, cached reads | NVM storage |
|
||||
| **Communication Status** | Network components | Frequent updates, latest value | Data Pool only |
|
||||
|
||||
#### 5.2.2 Consistency Guarantees
|
||||
|
||||
- **Sensor Data:** Eventually consistent across all consumers
|
||||
- **System State:** Strongly consistent, atomic updates
|
||||
- **Diagnostics:** Append-only, monotonic ordering
|
||||
- **Configuration:** Consistent after successful update
|
||||
- **Runtime Data:** Best-effort consistency, latest value wins
|
||||
|
||||
## 6. Concurrency Architecture
|
||||
|
||||
### 6.1 Task Model
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "High Priority Tasks"
|
||||
SENSOR_TASK[Sensor Acquisition Task<br/>Priority: HIGH<br/>Stack: 8KB<br/>Period: 1s]
|
||||
SYSTEM_TASK[System Management Task<br/>Priority: HIGH<br/>Stack: 6KB<br/>Event-driven]
|
||||
OTA_TASK[OTA Task<br/>Priority: HIGH<br/>Stack: 16KB<br/>Event-driven]
|
||||
end
|
||||
|
||||
subgraph "Medium Priority Tasks"
|
||||
COMM_TASK[Communication Task<br/>Priority: MEDIUM<br/>Stack: 12KB<br/>Event-driven]
|
||||
PERSIST_TASK[Persistence Task<br/>Priority: MEDIUM<br/>Stack: 6KB<br/>Event-driven]
|
||||
end
|
||||
|
||||
subgraph "Low Priority Tasks"
|
||||
DIAG_TASK[Diagnostics Task<br/>Priority: LOW<br/>Stack: 4KB<br/>Period: 10s]
|
||||
HMI_TASK[HMI Task<br/>Priority: LOW<br/>Stack: 4KB<br/>Event-driven]
|
||||
end
|
||||
|
||||
subgraph "System Tasks"
|
||||
IDLE_TASK[Idle Task<br/>Priority: IDLE<br/>Stack: 2KB]
|
||||
TIMER_TASK[Timer Service Task<br/>Priority: HIGH<br/>Stack: 4KB]
|
||||
end
|
||||
```
|
||||
|
||||
### 6.2 Resource Synchronization
|
||||
|
||||
#### 6.2.1 Synchronization Primitives
|
||||
|
||||
| Resource | Synchronization | Access Pattern | Timeout |
|
||||
|----------|----------------|----------------|---------|
|
||||
| **Data Pool** | Reader-Writer Mutex | Multi-read, single-write | 100ms |
|
||||
| **Event Queue** | Lock-free Queue | Producer-consumer | None |
|
||||
| **Sensor Drivers** | Task-level ownership | Exclusive per task | N/A |
|
||||
| **Storage** | Mutex | Single writer | 1s |
|
||||
| **Network** | Mutex | Single writer | 5s |
|
||||
| **Configuration** | Mutex | Infrequent updates | 500ms |
|
||||
|
||||
#### 6.2.2 Deadlock Prevention
|
||||
|
||||
- **Lock Ordering:** Consistent lock acquisition order across all components
|
||||
- **Timeout-based Locking:** All mutex operations have bounded timeouts
|
||||
- **Lock-free Structures:** Event queues use lock-free algorithms
|
||||
- **Priority Inheritance:** Mutexes support priority inheritance
|
||||
|
||||
### 6.3 Inter-Task Communication
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant ST as Sensor Task
|
||||
participant ES as Event System
|
||||
participant CT as Communication Task
|
||||
participant PT as Persistence Task
|
||||
participant HT as HMI Task
|
||||
|
||||
Note over ST,HT: Event-Driven Communication
|
||||
|
||||
ST->>ES: publish(SENSOR_DATA_UPDATE)
|
||||
|
||||
par Parallel Notification
|
||||
ES->>CT: notify(SENSOR_DATA_UPDATE)
|
||||
CT->>CT: queueForTransmission()
|
||||
and
|
||||
ES->>PT: notify(SENSOR_DATA_UPDATE)
|
||||
PT->>PT: persistData()
|
||||
and
|
||||
ES->>HT: notify(SENSOR_DATA_UPDATE)
|
||||
HT->>HT: updateDisplay()
|
||||
end
|
||||
|
||||
Note over ST,HT: Non-blocking, asynchronous delivery
|
||||
```
|
||||
|
||||
## 7. Security Architecture
|
||||
|
||||
### 7.1 Security Layers
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Application Security"
|
||||
AUTH[Authentication]
|
||||
AUTHZ[Authorization]
|
||||
SESSION[Session Management]
|
||||
INPUT_VAL[Input Validation]
|
||||
end
|
||||
|
||||
subgraph "Communication Security"
|
||||
TLS[TLS 1.2/mTLS]
|
||||
CERT[Certificate Management]
|
||||
ENCRYPT[Message Encryption]
|
||||
end
|
||||
|
||||
subgraph "Data Security"
|
||||
DATA_ENCRYPT[Data Encryption]
|
||||
INTEGRITY[Data Integrity]
|
||||
ACCESS_CTRL[Access Control]
|
||||
end
|
||||
|
||||
subgraph "System Security"
|
||||
SECURE_BOOT[Secure Boot V2]
|
||||
FLASH_ENCRYPT[Flash Encryption]
|
||||
HARDWARE_SEC[Hardware Security]
|
||||
end
|
||||
|
||||
AUTH --> TLS
|
||||
CERT --> TLS
|
||||
DATA_ENCRYPT --> FLASH_ENCRYPT
|
||||
INTEGRITY --> HARDWARE_SEC
|
||||
SECURE_BOOT --> HARDWARE_SEC
|
||||
```
|
||||
|
||||
### 7.2 Security Enforcement Points
|
||||
|
||||
| Layer | Security Mechanism | Implementation |
|
||||
|-------|-------------------|----------------|
|
||||
| **Hardware** | Secure Boot V2, Flash Encryption | ESP32-S3 hardware features |
|
||||
| **System** | Certificate validation, Key management | Security Manager component |
|
||||
| **Communication** | mTLS, Message authentication | Network Stack with TLS |
|
||||
| **Application** | Session authentication, Access control | Engineering Session Manager |
|
||||
| **Data** | Encryption at rest, Integrity checks | Persistence component |
|
||||
|
||||
## 8. Error Handling Architecture
|
||||
|
||||
### 8.1 Error Classification Hierarchy
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
ERROR[System Error] --> SEVERITY{Severity Level}
|
||||
|
||||
SEVERITY --> INFO[INFO<br/>Informational events]
|
||||
SEVERITY --> WARNING[WARNING<br/>Non-fatal issues]
|
||||
SEVERITY --> ERROR_LEVEL[ERROR<br/>Recoverable failures]
|
||||
SEVERITY --> FATAL[FATAL<br/>System-threatening]
|
||||
|
||||
INFO --> LOG_ONLY[Log Only]
|
||||
WARNING --> DIAG_REPORT[Diagnostic Report]
|
||||
ERROR_LEVEL --> RECOVERY[Recovery Action]
|
||||
FATAL --> STATE_TRANSITION[State Transition]
|
||||
|
||||
RECOVERY --> RETRY[Retry Operation]
|
||||
RECOVERY --> FALLBACK[Fallback Mode]
|
||||
RECOVERY --> COMPONENT_RESTART[Component Restart]
|
||||
|
||||
STATE_TRANSITION --> WARNING_STATE[WARNING State]
|
||||
STATE_TRANSITION --> FAULT_STATE[FAULT State]
|
||||
STATE_TRANSITION --> TEARDOWN[TEARDOWN State]
|
||||
```
|
||||
|
||||
### 8.2 Error Propagation Model
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant COMP as Component
|
||||
participant ERR as Error Handler
|
||||
participant DIAG as Diagnostics Task
|
||||
participant STM as State Manager
|
||||
participant ES as Event System
|
||||
|
||||
Note over COMP,ES: Error Detection and Handling
|
||||
|
||||
COMP->>COMP: detectError()
|
||||
COMP->>ERR: reportFault(error_info)
|
||||
|
||||
ERR->>ERR: classifyError(error_info)
|
||||
ERR->>ERR: determineResponse(classification)
|
||||
|
||||
alt INFO/WARNING Level
|
||||
ERR->>DIAG: logDiagnostic(error_info)
|
||||
DIAG->>ES: publish(DIAGNOSTIC_EVENT)
|
||||
else ERROR Level
|
||||
ERR->>COMP: initiateRecovery(recovery_action)
|
||||
ERR->>DIAG: logDiagnostic(error_info)
|
||||
else FATAL Level
|
||||
ERR->>STM: requestStateTransition(FAULT)
|
||||
ERR->>DIAG: logDiagnostic(error_info)
|
||||
STM->>ES: publish(STATE_CHANGED, FAULT)
|
||||
end
|
||||
```
|
||||
|
||||
## 9. Performance Architecture
|
||||
|
||||
### 9.1 Performance Requirements
|
||||
|
||||
| Subsystem | Requirement | Measurement | Constraint |
|
||||
|-----------|-------------|-------------|------------|
|
||||
| **Sensor Acquisition** | 1-second cycle time | End-to-end timing | Hard real-time |
|
||||
| **Communication** | 5-second response | Request-response time | Soft real-time |
|
||||
| **State Transitions** | 50ms transition time | State change duration | Hard real-time |
|
||||
| **Data Access** | 10μs read latency | Data Pool access | Performance critical |
|
||||
| **Memory Usage** | 80% of available | Static + dynamic usage | Resource constraint |
|
||||
|
||||
### 9.2 Performance Optimization Strategies
|
||||
|
||||
#### 9.2.1 Memory Optimization
|
||||
|
||||
- **Static Allocation:** All data structures use static allocation (no malloc/free)
|
||||
- **Memory Pools:** Pre-allocated pools for variable-size data
|
||||
- **Stack Optimization:** Careful stack size allocation per task
|
||||
- **Data Structure Optimization:** Packed structures, aligned access
|
||||
|
||||
#### 9.2.2 CPU Optimization
|
||||
|
||||
- **Lock-free Algorithms:** Event queues use lock-free implementations
|
||||
- **Batch Processing:** Group operations to reduce overhead
|
||||
- **Priority-based Scheduling:** Critical tasks have higher priority
|
||||
- **Interrupt Optimization:** Minimal processing in interrupt context
|
||||
|
||||
#### 9.2.3 I/O Optimization
|
||||
|
||||
- **Asynchronous Operations:** Non-blocking I/O where possible
|
||||
- **Batched Storage:** Group storage operations for efficiency
|
||||
- **DMA Usage:** Hardware DMA for large data transfers
|
||||
- **Buffer Management:** Efficient buffer allocation and reuse
|
||||
|
||||
## 10. Deployment Architecture
|
||||
|
||||
### 10.1 Memory Layout
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "ESP32-S3 Memory Map"
|
||||
subgraph "Flash Memory (8MB)"
|
||||
BOOTLOADER[Bootloader<br/>64KB]
|
||||
PARTITION_TABLE[Partition Table<br/>4KB]
|
||||
OTA_0[OTA Partition 0<br/>3MB]
|
||||
OTA_1[OTA Partition 1<br/>3MB]
|
||||
NVS[NVS Storage<br/>1MB]
|
||||
SPIFFS[SPIFFS<br/>1MB]
|
||||
end
|
||||
|
||||
subgraph "SRAM (512KB)"
|
||||
CODE_CACHE[Code Cache<br/>128KB]
|
||||
DATA_HEAP[Data Heap<br/>256KB]
|
||||
STACK_AREA[Task Stacks<br/>96KB]
|
||||
SYSTEM_RESERVED[System Reserved<br/>32KB]
|
||||
end
|
||||
|
||||
subgraph "External Storage"
|
||||
SD_CARD[SD Card<br/>Variable Size]
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### 10.2 Component Deployment
|
||||
|
||||
| Component | Memory Region | Size Estimate | Criticality |
|
||||
|-----------|---------------|---------------|-------------|
|
||||
| **State Manager** | Code Cache + Heap | 8KB | Critical |
|
||||
| **Event System** | Code Cache + Heap | 12KB | Critical |
|
||||
| **Sensor Manager** | Code Cache + Heap | 24KB | Critical |
|
||||
| **Data Pool** | Heap | 64KB | Critical |
|
||||
| **Persistence** | Code Cache + Heap | 16KB | Important |
|
||||
| **Communication** | Code Cache + Heap | 32KB | Important |
|
||||
| **Diagnostics** | Code Cache + Heap | 8KB | Normal |
|
||||
| **HMI** | Code Cache + Heap | 4KB | Normal |
|
||||
|
||||
## 11. Quality Attributes
|
||||
|
||||
### 11.1 Reliability
|
||||
|
||||
- **MTBF:** 8760 hours (1 year) under normal conditions
|
||||
- **Fault Tolerance:** Graceful degradation under component failures
|
||||
- **Recovery:** Automatic recovery from transient faults within 30 seconds
|
||||
- **Data Integrity:** Error rate < 1 in 10^6 operations
|
||||
|
||||
### 11.2 Performance
|
||||
|
||||
- **Response Time:** Sensor acquisition within 1 second, communication within 5 seconds
|
||||
- **Throughput:** Handle 7 sensors simultaneously with 10 samples each per second
|
||||
- **Resource Usage:** CPU < 80%, Memory < 80% of available
|
||||
- **Scalability:** Support additional sensor types through driver registration
|
||||
|
||||
### 11.3 Security
|
||||
|
||||
- **Authentication:** Certificate-based mutual authentication for all external communication
|
||||
- **Encryption:** AES-256 for data at rest, TLS 1.2 for data in transit
|
||||
- **Access Control:** Role-based access for engineering functions
|
||||
- **Audit:** Complete audit trail for all security-relevant operations
|
||||
|
||||
### 11.4 Maintainability
|
||||
|
||||
- **Modularity:** Clear component boundaries with well-defined interfaces
|
||||
- **Testability:** Comprehensive unit, integration, and system test coverage
|
||||
- **Debuggability:** Extensive logging and diagnostic capabilities
|
||||
- **Updateability:** Secure over-the-air firmware updates with rollback
|
||||
|
||||
## 12. Architectural Decisions
|
||||
|
||||
### 12.1 Key Architectural Decisions
|
||||
|
||||
| Decision | Rationale | Alternatives Considered | Trade-offs |
|
||||
|----------|-----------|------------------------|------------|
|
||||
| **Layered Architecture** | Clear separation of concerns, maintainability | Microkernel, Component-based | Performance vs. Modularity |
|
||||
| **Event-Driven Communication** | Loose coupling, asynchronous operation | Direct calls, Message queues | Complexity vs. Flexibility |
|
||||
| **Static Memory Allocation** | Deterministic behavior, no fragmentation | Dynamic allocation | Memory efficiency vs. Predictability |
|
||||
| **State Machine Control** | Predictable behavior, safety | Ad-hoc state management | Complexity vs. Reliability |
|
||||
| **Hardware Abstraction** | Portability, testability | Direct hardware access | Performance vs. Portability |
|
||||
|
||||
### 12.2 Design Patterns Used
|
||||
|
||||
| Pattern | Application | Benefit |
|
||||
|---------|-------------|---------|
|
||||
| **Layered Architecture** | Overall system structure | Separation of concerns |
|
||||
| **State Machine** | System lifecycle management | Predictable behavior |
|
||||
| **Observer** | Event-driven communication | Loose coupling |
|
||||
| **Singleton** | Data Pool, State Manager | Single source of truth |
|
||||
| **Strategy** | Filter algorithms, communication protocols | Flexibility |
|
||||
| **Template Method** | Component initialization | Code reuse |
|
||||
| **Factory** | Driver instantiation | Extensibility |
|
||||
|
||||
## 13. Compliance and Standards
|
||||
|
||||
### 13.1 Standards Compliance
|
||||
|
||||
- **ISO/IEC/IEEE 42010:2011:** Architecture description standard
|
||||
- **ISO/IEC/IEEE 29148:2018:** Requirements engineering
|
||||
- **IEC 61508:** Functional safety (SIL-1 compliance)
|
||||
- **IEEE 802.11:** WiFi communication standard
|
||||
- **RFC 5246:** TLS 1.2 security protocol
|
||||
|
||||
### 13.2 Coding Standards
|
||||
|
||||
- **MISRA C:2012:** Safety-critical C coding standard
|
||||
- **ESP-IDF Style Guide:** Platform-specific coding conventions
|
||||
- **Doxygen:** Documentation standard for all public APIs
|
||||
- **Unit Testing:** Minimum 80% code coverage requirement
|
||||
|
||||
## 14. Future Evolution
|
||||
|
||||
### 14.1 Planned Enhancements
|
||||
|
||||
- **Additional Sensor Types:** Framework supports easy extension
|
||||
- **Advanced Analytics:** Edge computing capabilities for sensor data
|
||||
- **Cloud Integration:** Direct cloud connectivity option
|
||||
- **Machine Learning:** Predictive maintenance and anomaly detection
|
||||
|
||||
### 14.2 Scalability Considerations
|
||||
|
||||
- **Multi-Hub Coordination:** Support for coordinated operation
|
||||
- **Sensor Fusion:** Advanced sensor data fusion algorithms
|
||||
- **Protocol Extensions:** Support for additional communication protocols
|
||||
- **Performance Scaling:** Optimization for higher sensor densities
|
||||
|
||||
## 15. Validation and Verification
|
||||
|
||||
### 15.1 Architecture Validation
|
||||
|
||||
- **Requirements Traceability:** All requirements mapped to architectural elements
|
||||
- **Interface Consistency:** All component interfaces validated
|
||||
- **Dependency Analysis:** No circular dependencies, proper layering
|
||||
- **Performance Analysis:** Timing and resource usage validated
|
||||
|
||||
### 15.2 Implementation Verification
|
||||
|
||||
- **Component Testing:** Unit tests for all components
|
||||
- **Integration Testing:** Interface and interaction testing
|
||||
- **System Testing:** End-to-end functionality validation
|
||||
- **Performance Testing:** Real-time constraint verification
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Final for Implementation Phase
|
||||
**Architecture Completeness:** 100% (all components and interfaces defined)
|
||||
**Requirements Traceability:** Complete (45 SR, 122 SWR, 10 Features)
|
||||
**Next Review:** After implementation phase completion
|
||||
|
||||
**This document serves as the definitive software architecture specification for the ASF Sensor Hub implementation.**
|
||||
Reference in New Issue
Block a user