# ASF Sensor Hub – System Architecture Documentation

**Version:** 2.0  
**Date:** 2025-01-19  
**Platform:** ESP32-S3, ESP-IDF v5.4  
**Status:** Final for Implementation Phase

## 1. Document Purpose

This document provides comprehensive system architecture documentation for the ASF Sensor Hub (Sub-Hub). It consolidates all architectural decisions, technology choices, feature definitions, and system specifications required for the implementation phase.

## 2. Document Structure

This documentation package includes:

1. **Features.md** – Complete feature catalog with technology specifications
2. **Feature Files** – Detailed feature specifications:
   - `[DAQ] Sensor Data Acquisition Features.md`
   - `[DQC] Data Quality & Calibration Features.md`
   - `[COM] Communication Features.md`
   - `[DIAG] Diagnostics & Health Monitoring Features.md`
   - `[DATA] Persistence & Data Management Features.md`
   - `[OTA] Firmware Update (OTA) Features.md`
   - `[SEC] Security & Safety Features.md`
   - `[SYS] System Management Features.md`
   - `[PWR] Power & Fault Handling Features.md` [NEW]
   - `[HW] Hardware Abstraction Features.md` [NEW]
3. **Cross-Feature Constraints.md** – Architectural constraints
4. **System Assumptions & Limitations.md** – System context and boundaries
5. **System State Machine Specification** – Complete FSM definition
6. **Failure Handling Model** – Fault taxonomy and recovery rules

## 3. System Overview

### 3.1 Platform

- **Hardware:** ESP32-S3 microcontroller
- **Framework:** ESP-IDF v5.4
- **RTOS:** FreeRTOS (included in ESP-IDF)
- **Language:** C/C++

### 3.2 Technology Stack

| Layer | Technology | Justification |
|-------|------------|---------------|
| **Hardware** | ESP32-S3 | Dual-core, 512KB SRAM, 8MB flash, security features |
| **Framework** | ESP-IDF v5.4 | Native support, mature drivers |
| **Physical/Link** | Wi-Fi 802.11n (2.4 GHz) | Native support, good range, sufficient throughput |
| **Peer-to-Peer** | ESP-NOW | Deterministic, low-latency, no AP dependency |
| **Application Protocol** | MQTT over TLS 1.2 | Store-and-forward, keepalive, industrial standard |
| **Payload Encoding** | CBOR | Binary, efficient, versioned |
| **Security** | Secure Boot V2, Flash Encryption, mTLS | Hardware root of trust, IP protection |
| **Storage** | FAT32 (SD Card), NVS (Encrypted) | Wear-aware, reliable |
| **OTA** | A/B Partitioning, SHA-256 | Safe updates, automatic rollback |

### 3.3 System States

The system operates as a finite state machine with 11 states:

1. **INIT** – Hardware and software initialization
2. **BOOT_FAILURE** – Secure boot verification failed
3. **RUNNING** – Normal sensor acquisition and communication
4. **WARNING** – Non-fatal fault detected, degraded operation
5. **FAULT** – Fatal error, core functionality disabled
6. **OTA_PREP** – OTA preparation phase
7. **OTA_UPDATE** – Firmware update in progress
8. **MC_UPDATE** – Machine constants update in progress
9. **TEARDOWN** – Controlled shutdown sequence
10. **SERVICE** – Engineering or diagnostic interaction
11. **SD_DEGRADED** – SD card failure detected, fallback mode

**Reference:** `System_State_Machine_Specification.md`

## 4. Feature Groups

### 4.1 Sensor Data Acquisition (DAQ)

- **F-DAQ-01:** Multi-Sensor Data Acquisition
- **F-DAQ-02:** High-Frequency Sampling and Local Filtering
- **F-DAQ-03:** Timestamped Sensor Data Generation
- **F-DAQ-04:** Sensor State Management [UPDATED]

**Technology:** Sensor Abstraction Layer (SAL), Median filter N=5, Rate-of-change limiter

### 4.2 Data Quality & Calibration (DQC)

- **F-DQC-01:** Automatic Sensor Detection
- **F-DQC-02:** Sensor Type Enforcement
- **F-DQC-03:** Sensor Failure Detection
- **F-DQC-04:** Machine Constants & Calibration Management
- **F-DQC-05:** Redundant Sensor Support [NEW]

### 4.3 Communication (COM)

- **F-COM-01:** Main Hub Communication (MQTT over TLS 1.2)
- **F-COM-02:** On-Demand Data Broadcasting
- **F-COM-03:** Peer Sensor Hub Communication (ESP-NOW)
- **F-COM-04:** Long-Range Fallback Communication [NEW]

**Technology:** Wi-Fi 802.11n, MQTT, TLS 1.2/mTLS, CBOR encoding, ESP-NOW

### 4.4 Diagnostics & Health Monitoring (DIAG)

- **F-DIAG-01:** Diagnostic Code Management
- **F-DIAG-02:** Diagnostic Data Storage
- **F-DIAG-03:** Diagnostic Session
- **F-DIAG-04:** Layered Watchdog System [NEW]

**Technology:** Diagnostic code format `0xSCCC`, Bounded circular log, Task/Interrupt/RTC watchdogs

### 4.5 Persistence & Data Management (DATA)

- **F-DATA-01:** Persistent Sensor Data Storage
- **F-DATA-02:** Data Persistence Abstraction (DP Component)
- **F-DATA-03:** Safe Data Handling During State Transitions
- **F-DATA-04:** Power-Loss Data Protection [NEW]

**Technology:** FAT32 (SD Card), NVS (Encrypted), Wear-aware batch writing

### 4.6 Firmware Update (OTA)

- **F-OTA-01:** OTA Update Negotiation
- **F-OTA-02:** Firmware Reception and Storage
- **F-OTA-03:** Firmware Integrity Validation (SHA-256)
- **F-OTA-04:** Safe Firmware Activation
- **F-OTA-05:** A/B Partitioning with Rollback [NEW]

**Technology:** A/B partitioning (ota_0/ota_1), SHA-256 hash verification, Automatic rollback

### 4.7 Security & Safety (SEC)

- **F-SEC-01:** Secure Boot (Secure Boot V2)
- **F-SEC-02:** Secure Flash Storage (Flash Encryption, AES-256)
- **F-SEC-03:** Encrypted Communication (mTLS, X.509 certificates)
- **F-SEC-04:** Security Violation Handling [NEW]

**Technology:** Secure Boot V2, Flash Encryption (AES-256), mTLS, X.509 certificates

### 4.8 System Management (SYS)

- **F-SYS-01:** System State Management
- **F-SYS-02:** Controlled Teardown Mechanism
- **F-SYS-03:** Status Indication (OLED-Based HMI)
- **F-SYS-04:** Debug & Engineering Sessions
- **F-SYS-05:** GPIO & Hardware Discipline [NEW]

**Technology:** OLED I2C display, Three-button navigation, State machine enforcement

### 4.9 Power & Fault Handling (PWR) [NEW]

- **F-PWR-01:** Brownout Detection and Handling
- **F-PWR-02:** Power-Loss Recovery

**Technology:** Hardware brownout detector (BOD), Supercapacitor (optional), RTC battery (optional)

### 4.10 Hardware Abstraction (HW) [NEW]

- **F-HW-01:** Sensor Abstraction Layer (SAL)
- **F-HW-02:** Hardware Interface Abstraction

**Technology:** SAL interface, ESP-IDF driver wrappers, GPIO discipline

## 5. Architectural Principles

### 5.1 Layered Architecture

```
Application Layer
    ↓
Business Stack (STM, Event System, Managers)
    ↓
DP Stack (Data Pool, Persistence)
    ↓
Drivers (Network, Sensors, Storage)
    ↓
ESP-IDF Wrappers (GPIO, I2C, SPI, UART, ADC)
    ↓
ESP-IDF Framework
    ↓
Hardware (ESP32-S3)
```

**Constraint:** Application layer SHALL NOT access hardware directly (CFC-ARCH-01)

### 5.2 State-Aware Execution

All features must be aware of the current system state and respect state-based operation restrictions.

**Reference:** `System_State_Machine_Specification.md`

### 5.3 Event-Driven Communication

Internal communication uses an event-driven publish/subscribe model.

**Reference:** `software design/components/application_layer/business_stack/event_system/COMPONENT_SPEC.md`

### 5.4 Data Persistence Abstraction

All persistent data access goes through the DP (Data Persistence) component.

**Reference:** `software design/components/application_layer/DP_stack/persistence/COMPONENT_SPEC.md`

## 6. Key Specifications

### 6.1 System State Machine

**Document:** `System_State_Machine_Specification.md`

- 11 states with defined transitions
- Per-state feature execution rules
- State transition timing requirements

### 6.2 Failure Handling Model

**Document:** `Failure_Handling_Model.md`

- Fault taxonomy (INFO, WARNING, ERROR, FATAL)
- 7 fault categories with detection rules
- Escalation and recovery behaviors
- Integration with state machine

### 6.3 Cross-Feature Constraints

**Document:** `Cross-Feature Constraints.md`

- Architectural constraints (CFC-ARCH-*)
- Timing constraints (CFC-TIME-*)
- Data constraints (CFC-DATA-*)
- Security constraints (CFC-SEC-*)
- HMI/Debug constraints (CFC-HMI-*, CFC-DBG-*)

## 7. Implementation Readiness

### 7.1 Completed Artifacts

- ✅ Feature definitions with technology specifications
- ✅ System State Machine Specification
- ✅ Failure Handling Model
- ✅ Software Requirements Specification (SRS)
- ✅ Static Architecture Views
- ✅ Component Specifications (STM, Event System, Persistence)
- ✅ Verification & Validation Matrix

### 7.2 Next Steps

1. **Component Design Phase:**
   - Detailed component APIs
   - Threading models
   - Error handling strategies
   - State machine implementation

2. **Implementation Phase:**
   - Code implementation following SRS
   - Unit tests
   - Integration tests
   - HIL/System tests

## 8. Traceability

All features trace to:
- System Requirements (SR-*)
- Software Requirements (SWR-*)
- System State Machine Specification
- Failure Handling Model
- Cross-Feature Constraints
- Component Specifications

**Reference:** `System Design/SRS/Annex_A_Traceability.md`

## 9. References

### 9.1 Internal Documents

- `Features.md` – Feature catalog
- `[XXX] Feature Files.md` – Detailed feature specifications
- `Cross-Feature Constraints.md` – Architectural constraints
- `System Assumptions & Limitations.md` – System context
- `System_State_Machine_Specification.md` – FSM definition
- `Failure_Handling_Model.md` – Fault taxonomy

### 9.2 External Documents

- `System Design/SRS/SRS.md` – Software Requirements Specification
- `System Design/SRS/Annex_A_Traceability.md` – Traceability matrix
- `System Design/SRS/Annex_B_Interfaces.md` – External interfaces
- `System Design/SRS/Annex_C_Budgets.md` – Timing and resource budgets
- `System Design/SRS/VV_Matrix.md` – Verification & Validation matrix
- `software design/components/ARCHITECTURE.md` – Static architecture views
- `software design/components/application_layer/business_stack/STM/COMPONENT_SPEC.md` – State Manager spec
- `software design/components/application_layer/business_stack/event_system/COMPONENT_SPEC.md` – Event System spec
- `software design/components/application_layer/DP_stack/persistence/COMPONENT_SPEC.md` – Persistence spec

## 10. Document Status

**Status:** Final for Implementation Phase  
**Version:** 2.0  
**Date:** 2025-01-19  
**Next Review:** After Component Design Phase

---

**This document serves as the authoritative system architecture reference for the ASF Sensor Hub implementation phase.**
