ASF-Nabd/ASF_01_sys_sw_arch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

update

Browse Source
This commit is contained in:
mahmamdouh
2026-01-26 12:43:14 +01:00
parent c631110349
commit bedcd373f5
133 changed files with 37347 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

373
system_arch_final/Feature_to_System_Requirements_Traceability.md Normal file
View File

@@ -0,0 +1,373 @@
# Feature to System Requirements Traceability Matrix
**Version:** 2.0
**Date:** 2025-01-19
**Document Type:** Traceability Matrix
**Scope:** ASF Sensor Hub (Sub-Hub)
## 1. Purpose
This document provides complete bidirectional traceability between Features and System Requirements (SR-*). It serves as a reference for:
- Requirements verification
- Impact analysis
- Change management
- Test coverage analysis
## 2. Traceability Overview
| Feature Group | Feature Count | System Requirements Count |
|---------------|---------------|---------------------------|
| DAQ (Data Acquisition) | 4 | 13 |
| DQC (Data Quality & Calibration) | 5 | 18 |
| COM (Communication) | 4 | 17 |
| DIAG (Diagnostics) | 4 | 14 |
| DATA (Persistence) | 4 | 13 |
| OTA (Firmware Update) | 5 | 16 |
| SEC (Security) | 4 | 15 |
| SYS (System Management) | 5 | 17 |
| PWR (Power & Fault Handling) | 2 | 8 |
| HW (Hardware Abstraction) | 2 | 8 |
| **TOTAL** | **39** | **139** |
## 3. Complete Feature to System Requirements Mapping
### 3.1 Data Acquisition Features (DAQ)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-DAQ-01 | Multi-Sensor Data Acquisition | SR-DAQ-001, SR-DAQ-002, SR-DAQ-003 |
| F-DAQ-02 | High-Frequency Sampling and Local Filtering | SR-DAQ-004, SR-DAQ-005, SR-DAQ-006, SR-DAQ-010 |
| F-DAQ-03 | Timestamped Sensor Data Generation | SR-DAQ-007, SR-DAQ-008, SR-DAQ-009 |
| F-DAQ-04 | Sensor State Management | SR-DAQ-011, SR-DAQ-012, SR-DAQ-013 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-DAQ-001 | The system shall support acquisition of data from multiple environmental sensor types simultaneously. |
| SR-DAQ-002 | The system shall provide a dedicated software driver abstraction for each supported sensor type. |
| SR-DAQ-003 | The system shall acquire sensor data only from sensors detected as present and enabled. |
| SR-DAQ-004 | The system shall sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples). |
| SR-DAQ-005 | The system shall apply a local filtering mechanism to raw sensor samples to produce a single representative value. |
| SR-DAQ-006 | The system shall allow configuration of sampling count and filtering parameters via system configuration data (Machine Constants). |
| SR-DAQ-007 | The system shall associate each processed sensor value with a timestamp. |
| SR-DAQ-008 | The system shall generate timestamps after completion of filtering. |
| SR-DAQ-009 | The system shall include sensor identifier, sensor type, value, unit, timestamp, and validity status in each sensor data record. |
| SR-DAQ-010 | The system shall complete sensor acquisition cycle within a maximum of 100ms per sensor. |
| SR-DAQ-011 | The system shall track sensor operational states (INIT, WARMUP, STABLE, DEGRADED, FAILED). |
| SR-DAQ-012 | The system shall never publish raw sensor values without an accompanying validity flag indicating the current state. |
| SR-DAQ-013 | The system shall enforce sensor warmup durations (CO2: 30 seconds, Temperature: 5 seconds, others: sensor-specific). |
### 3.2 Data Quality & Calibration Features (DQC)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-DQC-01 | Automatic Sensor Detection | SR-DQC-001, SR-DQC-002, SR-DQC-003 |
| F-DQC-02 | Sensor Type Enforcement | SR-DQC-004, SR-DQC-005, SR-DQC-006 |
| F-DQC-03 | Sensor Failure Detection | SR-DQC-007, SR-DQC-008, SR-DQC-009, SR-DQC-010 |
| F-DQC-04 | Machine Constants & Calibration Management | SR-DQC-011, SR-DQC-012, SR-DQC-013, SR-DQC-014, SR-DQC-015 |
| F-DQC-05 | Redundant Sensor Support | SR-DQC-016, SR-DQC-017, SR-DQC-018 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-DQC-001 | The system shall detect the presence of each sensor using a dedicated hardware detection mechanism. |
| SR-DQC-002 | The system shall perform sensor presence detection during system startup and after any reinitialization event. |
| SR-DQC-003 | The system shall initialize only those sensors that are detected as present. |
| SR-DQC-004 | The system shall assign each sensor slot to a predefined sensor type. |
| SR-DQC-005 | The system shall verify that the detected sensor matches the expected sensor type for the slot. |
| SR-DQC-006 | The system shall reject and report any sensor-slot mismatch as a diagnostic event. |
| SR-DQC-007 | The system shall continuously monitor sensor responsiveness and signal validity during operation. |
| SR-DQC-008 | The system shall detect sensor failures including disconnection, non-responsiveness, and invalid measurement ranges. |
| SR-DQC-009 | The system shall mark a failed sensor as defective and exclude it from data reporting. |
| SR-DQC-010 | The system shall report detected sensor failures to the Main Hub with timestamps and failure classification. |
| SR-DQC-011 | The system shall maintain a Machine Constants dataset defining sensor configuration, calibration parameters, and communication identifiers. |
| SR-DQC-012 | The system shall persist the Machine Constants dataset in non-volatile storage. |
| SR-DQC-013 | The system shall load and apply Machine Constants during system initialization. |
| SR-DQC-014 | The system shall support remote updates of the Machine Constants dataset initiated by the Main Hub. |
| SR-DQC-015 | The system shall apply updated Machine Constants only after executing a controlled teardown and reinitialization sequence. |
| SR-DQC-016 | The system shall support redundant sensors for critical parameters (CO2, NH3) using different technologies or interfaces. |
| SR-DQC-017 | The system shall implement sensor fusion algorithm to combine redundant sensor data (average, weighted, or voting mechanism). |
| SR-DQC-018 | The system shall ensure that every critical parameter has two qualified sensor options to avoid common-mode failures. |
### 3.3 Communication Features (COM)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-COM-01 | Main Hub Communication | SR-COM-001, SR-COM-002, SR-COM-003, SR-COM-004, SR-COM-011, SR-COM-012, SR-COM-013 |
| F-COM-02 | On-Demand Data Broadcasting | SR-COM-005, SR-COM-006, SR-COM-007 |
| F-COM-03 | Peer Sensor Hub Communication | SR-COM-008, SR-COM-009, SR-COM-010, SR-COM-014, SR-COM-015 |
| F-COM-04 | Long-Range Fallback Communication | SR-COM-016, SR-COM-017 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-COM-001 | The system shall support bidirectional communication between the Sensor Hub and the Main Hub using MQTT over TLS 1.2. |
| SR-COM-002 | The system shall transmit sensor data, diagnostics, and system status information to the Main Hub via MQTT. |
| SR-COM-003 | The system shall receive commands, configuration updates, and firmware update requests from the Main Hub via MQTT. |
| SR-COM-004 | The system shall monitor and report the communication link status with the Main Hub. |
| SR-COM-005 | The system shall support on-demand requests from the Main Hub for sensor data. |
| SR-COM-006 | The system shall respond to on-demand data requests with the most recent timestamped sensor data within 100ms. |
| SR-COM-007 | The system shall include data validity and sensor status information in on-demand responses. |
| SR-COM-008 | The system shall support limited peer-to-peer communication between Sensor Hubs using ESP-NOW. |
| SR-COM-009 | The system shall allow peer communication for basic coordination functions such as connectivity checks or time synchronization. |
| SR-COM-010 | The system shall ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations. |
| SR-COM-011 | The system shall implement a heartbeat mechanism with 10-second interval and 30-second timeout. |
| SR-COM-012 | The system shall use CBOR encoding for all MQTT payloads. |
| SR-COM-013 | The system shall support automatic reconnection with exponential backoff on connection loss. |
| SR-COM-014 | The system shall encrypt all ESP-NOW peer communication using application-layer encryption (AES-128 minimum). |
| SR-COM-015 | The system shall implement acknowledgment and retry mechanism for ESP-NOW peer communication. |
| SR-COM-016 | The system may support long-range fallback communication using LoRa or cellular (LTE-M/NB-IoT) for farm-scale distances. |
| SR-COM-017 | If implemented, long-range fallback communication shall be used only for emergency alerts and data backup, not for OTA updates. |
### 3.4 Diagnostics & Health Monitoring Features (DIAG)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-DIAG-01 | Diagnostic Code Management | SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004 |
| F-DIAG-02 | Diagnostic Data Storage | SR-DIAG-005, SR-DIAG-006, SR-DIAG-007 |
| F-DIAG-03 | Diagnostic Session | SR-DIAG-008, SR-DIAG-009, SR-DIAG-010, SR-DIAG-011 |
| F-DIAG-04 | Layered Watchdog System | SR-DIAG-012, SR-DIAG-013, SR-DIAG-014 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-DIAG-001 | The system shall implement a diagnostic code framework for reporting system health, warnings, errors, and fatal faults. |
| SR-DIAG-002 | The system shall assign a unique diagnostic code to each detected fault or abnormal condition. |
| SR-DIAG-003 | The system shall classify diagnostic codes by severity level. |
| SR-DIAG-004 | The system shall associate each diagnostic event with a timestamp and source component. |
| SR-DIAG-005 | The system shall persist diagnostic events in non-volatile storage. |
| SR-DIAG-006 | The system shall retain diagnostic data across system resets and power cycles. |
| SR-DIAG-007 | The system shall implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy. |
| SR-DIAG-008 | The system shall provide a diagnostic session interface for accessing diagnostic data. |
| SR-DIAG-009 | The system shall allow authorized diagnostic sessions to retrieve stored diagnostic events. |
| SR-DIAG-010 | The system shall allow authorized diagnostic sessions to clear diagnostic records. |
| SR-DIAG-011 | The system shall ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations. |
| SR-DIAG-012 | The system shall implement Task Watchdog (Task WDT) to detect deadlocks in FreeRTOS tasks with a baseline timeout of 10 seconds. |
| SR-DIAG-013 | The system shall implement Interrupt Watchdog (Interrupt WDT) to detect hangs within ISRs with a baseline timeout of 3 seconds. |
| SR-DIAG-014 | The system shall implement RTC Watchdog (RTC WDT) as a final safety net for total system freezes with a baseline timeout of 30 seconds. |
### 3.5 Persistence & Data Management Features (DATA)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-DATA-01 | Persistent Sensor Data Storage | SR-DATA-001, SR-DATA-002, SR-DATA-003 |
| F-DATA-02 | Data Persistence Abstraction (DP Component) | SR-DATA-004, SR-DATA-005, SR-DATA-006 |
| F-DATA-03 | Safe Data Handling During State Transitions | SR-DATA-007, SR-DATA-008, SR-DATA-009 |
| F-DATA-04 | Power-Loss Data Protection | SR-DATA-010, SR-DATA-011, SR-DATA-012, SR-DATA-013 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-DATA-001 | The system shall persist timestamped sensor data in non-volatile storage. |
| SR-DATA-002 | The system shall store sensor data together with sensor identifiers, timestamps, and validity status. |
| SR-DATA-003 | The system shall support configurable data retention and overwrite policies. |
| SR-DATA-004 | The system shall provide a Data Persistence (DP) component as the sole interface for persistent data access. |
| SR-DATA-005 | The system shall prevent application and feature modules from directly accessing storage hardware. |
| SR-DATA-006 | The DP component shall support serialization and deserialization of structured system data. |
| SR-DATA-007 | The system shall ensure that all critical runtime data is flushed to non-volatile storage before entering a controlled teardown or reset. |
| SR-DATA-008 | The system shall protect data integrity during firmware updates and configuration changes. |
| SR-DATA-009 | The system shall verify successful data persistence before completing a state transition. |
| SR-DATA-010 | The system shall detect brownout conditions using hardware brownout detector (BOD) at 3.0V threshold. |
| SR-DATA-011 | The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection. |
| SR-DATA-012 | The system shall complete data flush operations within supercapacitor runtime (1-2 seconds) during brownout. |
| SR-DATA-013 | The system shall implement wear-aware batch writing to prevent SD card wear. |
### 3.6 Firmware Update (OTA) Features
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-OTA-01 | OTA Update Negotiation | SR-OTA-001, SR-OTA-002, SR-OTA-003 |
| F-OTA-02 | Firmware Reception and Storage | SR-OTA-004, SR-OTA-005, SR-OTA-006 |
| F-OTA-03 | Firmware Integrity Validation | SR-OTA-007, SR-OTA-008, SR-OTA-009 |
| F-OTA-04 | Safe Firmware Activation | SR-OTA-010, SR-OTA-011, SR-OTA-012, SR-OTA-013 |
| F-OTA-05 | A/B Partitioning with Rollback | SR-OTA-014, SR-OTA-015, SR-OTA-016 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-OTA-001 | The system shall support OTA update negotiation initiated by the Main Hub. |
| SR-OTA-002 | The system shall verify internal readiness before accepting an OTA update request. |
| SR-OTA-003 | The system shall explicitly acknowledge or reject OTA requests. |
| SR-OTA-004 | The system shall receive firmware images over the established communication channel (HTTPS or MQTT). |
| SR-OTA-005 | The system shall store received firmware images in non-volatile storage (SD card) prior to validation. |
| SR-OTA-006 | The system shall prevent overwriting the active firmware during firmware reception. |
| SR-OTA-007 | The system shall validate the integrity of the received firmware image before activation using SHA-256 hash. |
| SR-OTA-008 | The system shall reject firmware images that fail integrity validation. |
| SR-OTA-009 | The system shall report firmware validation results to the Main Hub. |
| SR-OTA-010 | The system shall execute a controlled teardown before firmware activation. |
| SR-OTA-011 | The system shall persist critical runtime data and calibration data prior to firmware flashing. |
| SR-OTA-012 | The system shall activate new firmware only after successful integrity validation. |
| SR-OTA-013 | The system shall reboot into the new firmware after successful activation. |
| SR-OTA-014 | The system shall implement A/B partitioning for safe firmware updates. |
| SR-OTA-015 | The system shall automatically rollback to previous firmware if new firmware fails validation or health check. |
| SR-OTA-016 | The system shall report rollback events to the Main Hub. |
### 3.7 Security & Safety Features (SEC)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-SEC-01 | Secure Boot | SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 |
| F-SEC-02 | Secure Flash Storage | SR-SEC-005, SR-SEC-006, SR-SEC-007, SR-SEC-008 |
| F-SEC-03 | Encrypted Communication | SR-SEC-009, SR-SEC-010, SR-SEC-011, SR-SEC-012 |
| F-SEC-04 | Security Violation Handling | SR-SEC-013, SR-SEC-014, SR-SEC-015 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-SEC-001 | The system shall verify the authenticity of the firmware image before execution during every boot cycle using Secure Boot V2. |
| SR-SEC-002 | The system shall prevent execution of firmware images that fail cryptographic verification. |
| SR-SEC-003 | The system shall enter BOOT_FAILURE state upon secure boot verification failure. |
| SR-SEC-004 | The system shall protect the root-of-trust against modification (eFuse protection). |
| SR-SEC-005 | The system shall protect sensitive data stored in internal flash memory from unauthorized access using Flash Encryption (AES-256). |
| SR-SEC-006 | The system shall support encryption of sensitive data stored in external storage devices (SD card). |
| SR-SEC-007 | The system shall restrict access to cryptographic keys to authorized system components only. |
| SR-SEC-008 | The system shall ensure data integrity for stored configuration and machine constant files. |
| SR-SEC-009 | The system shall encrypt all communication with the Main Hub using TLS 1.2 with mutual authentication (mTLS). |
| SR-SEC-010 | The system shall ensure integrity and authenticity of all received and transmitted messages. |
| SR-SEC-011 | The system shall use secure communication channels for OTA firmware updates. |
| SR-SEC-012 | The system shall detect and report communication security violations. |
| SR-SEC-013 | The system shall report security violations as FATAL diagnostic events. |
| SR-SEC-014 | The system shall implement eFuse-based anti-rollback to prevent downgrade attacks. |
| SR-SEC-015 | The system shall protect cryptographic keys during power loss and system resets. |
### 3.8 System Management Features (SYS)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-SYS-01 | System State Management | SR-SYS-001, SR-SYS-002, SR-SYS-003 |
| F-SYS-02 | Controlled Teardown Mechanism | SR-SYS-004, SR-SYS-005, SR-SYS-006 |
| F-SYS-03 | Status Indication (OLED-Based HMI) | SR-SYS-007, SR-SYS-008, SR-SYS-009, SR-SYS-010 |
| F-SYS-04 | Debug & Engineering Sessions | SR-SYS-011, SR-SYS-012, SR-SYS-013 |
| F-SYS-05 | GPIO & Hardware Discipline | SR-SYS-014, SR-SYS-015, SR-SYS-016, SR-SYS-017 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-SYS-001 | The system shall implement a defined finite state machine for operational control. |
| SR-SYS-002 | The system shall restrict operations based on the current system state. |
| SR-SYS-003 | The system shall notify system components of state transitions. |
| SR-SYS-004 | The system shall execute a controlled teardown sequence before firmware or machine constant updates. |
| SR-SYS-005 | The system shall persist all critical runtime data before completing teardown. |
| SR-SYS-006 | The system shall prevent data corruption during teardown and reset operations. |
| SR-SYS-007 | The system shall provide a local OLED display using I2C communication. |
| SR-SYS-008 | The system shall display connectivity status, system state, sensor summary, and time/date. |
| SR-SYS-009 | The system shall provide menu navigation using Up, Down, and Select buttons. |
| SR-SYS-010 | The system shall provide diagnostic, sensor, and health information via the local menu. |
| SR-SYS-011 | The system shall support diagnostic sessions for retrieving logs and system status. |
| SR-SYS-012 | The system shall support debug sessions for controlled engineering operations. |
| SR-SYS-013 | The system shall restrict debug actions to authorized sessions only. |
| SR-SYS-014 | The system shall enforce GPIO discipline by avoiding strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O. |
| SR-SYS-015 | The system shall ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V). |
| SR-SYS-016 | The system shall use ADC1 for all analog sensors when Wi-Fi is active (ADC2 is not available with Wi-Fi). |
| SR-SYS-017 | The system shall maintain a canonical GPIO map document as a single source of truth. |
### 3.9 Power & Fault Handling Features (PWR)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-PWR-01 | Brownout Detection and Handling | SR-PWR-001, SR-PWR-002, SR-PWR-003, SR-PWR-004 |
| F-PWR-02 | Power-Loss Recovery | SR-PWR-005, SR-PWR-006, SR-PWR-007, SR-PWR-008 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-PWR-001 | The system shall monitor input voltage and detect brownout conditions below 3.0V. |
| SR-PWR-002 | The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection. |
| SR-PWR-003 | The system shall enter graceful shutdown mode during brownout conditions. |
| SR-PWR-004 | The system shall perform clean reboot after power stabilization. |
| SR-PWR-005 | The system shall recover gracefully from power interruptions. |
| SR-PWR-006 | The system shall verify data integrity after power restoration. |
| SR-PWR-007 | The system shall restore system state from persistent storage after power restoration. |
| SR-PWR-008 | The system shall report power-loss and recovery events via diagnostics. |
### 3.10 Hardware Abstraction Features (HW)
| Feature ID | Feature Name | System Requirements |
|------------|--------------|---------------------|
| F-HW-01 | Sensor Abstraction Layer (SAL) | SR-HW-001, SR-HW-002, SR-HW-003, SR-HW-004 |
| F-HW-02 | Hardware Interface Abstraction | SR-HW-005, SR-HW-006, SR-HW-007, SR-HW-008 |
**System Requirements Details:**
| SR ID | Requirement Description |
|-------|------------------------|
| SR-HW-001 | The system shall provide a Sensor Abstraction Layer (SAL) for all sensor access. |
| SR-HW-002 | The system shall prevent application layer from directly accessing sensor hardware. |
| SR-HW-003 | The system shall track sensor state (INIT, WARMUP, STABLE, DEGRADED, FAILED). |
| SR-HW-004 | The system shall provide sensor validation and health check functions. |
| SR-HW-005 | The system shall abstract all hardware interfaces (I2C, SPI, UART, ADC, GPIO) through driver layers. |
| SR-HW-006 | The system shall enforce GPIO discipline (no strapping pins, proper pull-ups, ADC1/ADC2 separation). |
| SR-HW-007 | The system shall maintain a canonical GPIO map document. |
| SR-HW-008 | The system shall detect and report hardware resource conflicts. |
## 4. Summary Statistics
### 4.1 Requirements by Feature Group
| Feature Group | Requirements Count | Percentage |
|---------------|-------------------|------------|
| DAQ | 13 | 9.4% |
| DQC | 18 | 12.9% |
| COM | 17 | 12.2% |
| DIAG | 14 | 10.1% |
| DATA | 13 | 9.4% |
| OTA | 16 | 11.5% |
| SEC | 15 | 10.8% |
| SYS | 17 | 12.2% |
| PWR | 8 | 5.8% |
| HW | 8 | 5.8% |
| **TOTAL** | **139** | **100%** |
### 4.2 New Requirements Added (Version 2.0)
| Feature Group | New Requirements | Requirement IDs |
|---------------|----------------|-----------------|
| DAQ | 4 | SR-DAQ-010, SR-DAQ-011, SR-DAQ-012, SR-DAQ-013 |
| DQC | 3 | SR-DQC-016, SR-DQC-017, SR-DQC-018 |
| COM | 7 | SR-COM-011 through SR-COM-017 |
| DIAG | 3 | SR-DIAG-012, SR-DIAG-013, SR-DIAG-014 |
| DATA | 4 | SR-DATA-010 through SR-DATA-013 |
| OTA | 3 | SR-OTA-014, SR-OTA-015, SR-OTA-016 |
| SEC | 3 | SR-SEC-013, SR-SEC-014, SR-SEC-015 |
| SYS | 4 | SR-SYS-014 through SR-SYS-017 |
| PWR | 8 | SR-PWR-001 through SR-PWR-008 (all new) |
| HW | 8 | SR-HW-001 through SR-HW-008 (all new) |
**Total New Requirements:** 47
## 5. Reverse Traceability (System Requirement → Feature)
This section provides reverse traceability for impact analysis.
| System Requirement | Feature(s) | Feature Group |
|-------------------|------------|---------------|
| SR-DAQ-001 through SR-DAQ-013 | F-DAQ-01, F-DAQ-02, F-DAQ-03, F-DAQ-04 | DAQ |
| SR-DQC-001 through SR-DQC-018 | F-DQC-01, F-DQC-02, F-DQC-03, F-DQC-04, F-DQC-05 | DQC |
| SR-COM-001 through SR-COM-017 | F-COM-01, F-COM-02, F-COM-03, F-COM-04 | COM |
| SR-DIAG-001 through SR-DIAG-014 | F-DIAG-01, F-DIAG-02, F-DIAG-03, F-DIAG-04 | DIAG |
| SR-DATA-001 through SR-DATA-013 | F-DATA-01, F-DATA-02, F-DATA-03, F-DATA-04 | DATA |
| SR-OTA-001 through SR-OTA-016 | F-OTA-01, F-OTA-02, F-OTA-03, F-OTA-04, F-OTA-05 | OTA |
| SR-SEC-001 through SR-SEC-015 | F-SEC-01, F-SEC-02, F-SEC-03, F-SEC-04 | SEC |
| SR-SYS-001 through SR-SYS-017 | F-SYS-01, F-SYS-02, F-SYS-03, F-SYS-04, F-SYS-05 | SYS |
| SR-PWR-001 through SR-PWR-008 | F-PWR-01, F-PWR-02 | PWR |
| SR-HW-001 through SR-HW-008 | F-HW-01, F-HW-02 | HW |
## 6. Document Status
**Status:** Complete
**Version:** 2.0
**Date:** 2025-01-19
**Next Review:** After Component Design Phase
---
**This document provides complete bidirectional traceability between Features and System Requirements for the ASF Sensor Hub.**

43
system_arch_final/[DAQ] Sensor Data Acquisition Features.md
View File

@@ -281,40 +281,59 @@ sequenceDiagram
#### **Multi-Sensor Acquisition**
* **REQ-DAQ-001**
* **SR-DAQ-001**
The system shall support acquisition of data from multiple environmental sensor types simultaneously.
* **REQ-DAQ-002**
* **SR-DAQ-002**
The system shall provide a dedicated software driver abstraction for each supported sensor type.
* **REQ-DAQ-003**
* **SR-DAQ-003**
The system shall acquire sensor data only from sensors detected as present and enabled.
#### **High-Frequency Sampling & Filtering**
* **REQ-DAQ-004**
The system shall sample each enabled sensor multiple times within a single acquisition cycle.
* **SR-DAQ-004**
The system shall sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples).
* **REQ-DAQ-005**
* **SR-DAQ-005**
The system shall apply a local filtering mechanism to raw sensor samples to produce a single representative value.
* **REQ-DAQ-006**
The system shall allow configuration of sampling count and filtering parameters via system configuration data.
* **SR-DAQ-006**
The system shall allow configuration of sampling count and filtering parameters via system configuration data (Machine Constants).
* **SR-DAQ-010**
The system shall complete sensor acquisition cycle within a maximum of 100ms per sensor.
#### **Timestamped Data Generation**
* **REQ-DAQ-007**
* **SR-DAQ-007**
The system shall associate each processed sensor value with a timestamp.
* **REQ-DAQ-008**
* **SR-DAQ-008**
The system shall generate timestamps after completion of filtering.
* **REQ-DAQ-009**
* **SR-DAQ-009**
The system shall include sensor identifier, sensor type, value, unit, timestamp, and validity status in each sensor data record.
#### **Sensor State Management**
* **SR-DAQ-011**
The system shall track sensor operational states (INIT, WARMUP, STABLE, DEGRADED, FAILED).
* **SR-DAQ-012**
The system shall never publish raw sensor values without an accompanying validity flag indicating the current state.
* **SR-DAQ-013**
The system shall enforce sensor warmup durations (CO2: 30 seconds, Temperature: 5 seconds, others: sensor-specific).
## **9\. Feature-to-Requirement Traceability**
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Requirement IDs</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">REQ-DAQ-001, REQ-DAQ-002, REQ-DAQ-003</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">REQ-DAQ-004, REQ-DAQ-005, REQ-DAQ-006</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">REQ-DAQ-007, REQ-DAQ-008, REQ-DAQ-009</p></td></tr></tbody></table></figure>
| Feature ID | System Requirements |
|------------|---------------------|
| F-DAQ-01 | SR-DAQ-001, SR-DAQ-002, SR-DAQ-003 |
| F-DAQ-02 | SR-DAQ-004, SR-DAQ-005, SR-DAQ-006, SR-DAQ-010 |
| F-DAQ-03 | SR-DAQ-007, SR-DAQ-008, SR-DAQ-009 |
| F-DAQ-04 | SR-DAQ-011, SR-DAQ-012, SR-DAQ-013 |

21
system_arch_final/[DATA] Persistence & Data Management Features.md
View File

@@ -155,9 +155,28 @@ The system shall protect data integrity during firmware updates and configuratio
**SR-DATA-009**
The system shall verify successful data persistence before completing a state transition.
### 4.4 Power-Loss Data Protection [NEW]
**SR-DATA-010**
The system shall detect brownout conditions using hardware brownout detector (BOD) at 3.0V threshold.
**SR-DATA-011**
The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection.
**SR-DATA-012**
The system shall complete data flush operations within supercapacitor runtime (1-2 seconds) during brownout.
**SR-DATA-013**
The system shall implement wear-aware batch writing to prevent SD card wear.
## 5\. Feature ↔ System Requirement Mapping
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">System Requirements</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DATA-001, SR-DATA-002, SR-DATA-003</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DATA-004, SR-DATA-005, SR-DATA-006</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DATA-007, SR-DATA-008, SR-DATA-009</p></td></tr></tbody></table></figure>
| Feature ID | System Requirements |
|------------|---------------------|
| F-DATA-01 | SR-DATA-001, SR-DATA-002, SR-DATA-003 |
| F-DATA-02 | SR-DATA-004, SR-DATA-005, SR-DATA-006 |
| F-DATA-03 | SR-DATA-007, SR-DATA-008, SR-DATA-009 |
| F-DATA-04 | SR-DATA-010, SR-DATA-011, SR-DATA-012, SR-DATA-013 |
## 6\. Engineering Notes

18
system_arch_final/[DIAG] Diagnostics & Health Monitoring Features.md
View File

@@ -149,9 +149,25 @@ The system shall allow authorized diagnostic sessions to clear diagnostic record
**SR-DIAG-011**
The system shall ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations.
### 4.4 Layered Watchdog System [NEW]
**SR-DIAG-012**
The system shall implement Task Watchdog (Task WDT) to detect deadlocks in FreeRTOS tasks with a baseline timeout of 10 seconds.
**SR-DIAG-013**
The system shall implement Interrupt Watchdog (Interrupt WDT) to detect hangs within ISRs with a baseline timeout of 3 seconds.
**SR-DIAG-014**
The system shall implement RTC Watchdog (RTC WDT) as a final safety net for total system freezes with a baseline timeout of 30 seconds.
## 5\. Feature ↔ System Requirement Mapping
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">System Requirements</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DIAG-005, SR-DIAG-006, SR-DIAG-007</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DIAG-008, SR-DIAG-009, SR-DIAG-010, SR-DIAG-011</p></td></tr></tbody></table></figure>
| Feature ID | System Requirements |
|------------|---------------------|
| F-DIAG-01 | SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004 |
| F-DIAG-02 | SR-DIAG-005, SR-DIAG-006, SR-DIAG-007 |
| F-DIAG-03 | SR-DIAG-008, SR-DIAG-009, SR-DIAG-010, SR-DIAG-011 |
| F-DIAG-04 | SR-DIAG-012, SR-DIAG-013, SR-DIAG-014 |
## 6\. Engineering Notes

19
system_arch_final/[DQC] Data Quality & Calibration Features.md
View File

@@ -173,8 +173,25 @@ The system shall support remote updates of the Machine Constants dataset initiat
**SR-DQC-015**
The system shall apply updated Machine Constants only after executing a controlled teardown and reinitialization sequence.
### 4.5 Redundant Sensor Support [NEW]
**SR-DQC-016**
The system shall support redundant sensors for critical parameters (CO2, NH3) using different technologies or interfaces.
**SR-DQC-017**
The system shall implement sensor fusion algorithm to combine redundant sensor data (average, weighted, or voting mechanism).
**SR-DQC-018**
The system shall ensure that every critical parameter has two qualified sensor options to avoid common-mode failures.
## 5\. Traceability Summary
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">System Requirements</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DQC-001 → SR-DQC-003</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DQC-004 → SR-DQC-006</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DQC-007 → SR-DQC-010</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-04</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-DQC-011 → SR-DQC-015</p></td></tr></tbody></table></figure>
| Feature ID | System Requirements |
|------------|---------------------|
| F-DQC-01 | SR-DQC-001, SR-DQC-002, SR-DQC-003 |
| F-DQC-02 | SR-DQC-004, SR-DQC-005, SR-DQC-006 |
| F-DQC-03 | SR-DQC-007, SR-DQC-008, SR-DQC-009, SR-DQC-010 |
| F-DQC-04 | SR-DQC-011, SR-DQC-012, SR-DQC-013, SR-DQC-014, SR-DQC-015 |
| F-DQC-05 | SR-DQC-016, SR-DQC-017, SR-DQC-018 |
##

16
system_arch_final/[SYS] System Management Features.md
View File

@@ -292,11 +292,23 @@ Buttons → UI Controller → State/Menu Logic
* **SR-SYS-012**: The system shall support debug sessions for controlled engineering operations.
* **SR-SYS-013**: The system shall restrict debug actions to authorized sessions only.
### GPIO & Hardware Discipline [NEW]
* **SR-SYS-014**: The system shall enforce GPIO discipline by avoiding strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O.
* **SR-SYS-015**: The system shall ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V).
* **SR-SYS-016**: The system shall use ADC1 for all analog sensors when Wi-Fi is active (ADC2 is not available with Wi-Fi).
* **SR-SYS-017**: The system shall maintain a canonical GPIO map document as a single source of truth.
## 6 Traceability Matrix
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">System Requirements</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-SYS-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-SYS-001, SR-SYS-002, SR-SYS-003</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-SYS-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-SYS-004, SR-SYS-005, SR-SYS-006</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-SYS-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-SYS-007, SR-SYS-008, SR-SYS-009, SR-SYS-010</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-SYS-04</p></td><td class="op-uc-table--cell"><p class="op-uc-p">SR-SYS-011, SR-SYS-012, SR-SYS-013</p></td></tr></tbody></table></figure>
| Feature ID | System Requirements |
|------------|---------------------|
| F-SYS-01 | SR-SYS-001, SR-SYS-002, SR-SYS-003 |
| F-SYS-02 | SR-SYS-004, SR-SYS-005, SR-SYS-006 |
| F-SYS-03 | SR-SYS-007, SR-SYS-008, SR-SYS-009, SR-SYS-010 |
| F-SYS-04 | SR-SYS-011, SR-SYS-012, SR-SYS-013 |
| F-SYS-05 | SR-SYS-014, SR-SYS-015, SR-SYS-016, SR-SYS-017 |
## 7 Dependencies

561
system_arch_final/software/features/F-COM_Communication.md Normal file
View File

@@ -0,0 +1,561 @@
# Feature Specification: Communication
# Feature ID: F-COM (F-COM-001 to F-COM-005)
**Document Type:** Feature Specification
**Version:** 1.0
**Date:** 2025-01-19
**Feature Category:** Communication
## 1. Feature Overview
### 1.1 Feature Purpose
The Communication feature provides comprehensive data exchange capabilities between the ASF Sensor Hub and external entities including the Main Hub and peer Sensor Hubs. This feature ensures reliable, secure, and deterministic transfer of sensor data, diagnostics, configuration updates, and control commands.
### 1.2 Feature Scope
**In Scope:**
- Bidirectional communication with Main Hub via MQTT over TLS 1.2
- On-demand data broadcasting and request/response handling
- Peer-to-peer communication between Sensor Hubs via ESP-NOW
- Long-range fallback communication options (LoRa/Cellular)
- Communication protocol management and error handling
**Out of Scope:**
- Main Hub broker implementation and configuration
- Cloud communication protocols and interfaces
- Internet connectivity and routing management
- Physical network infrastructure design
## 2. Sub-Features
### 2.1 F-COM-001: Main Hub Communication
**Description:** Primary bidirectional communication channel with the Main Hub using MQTT over TLS 1.2 for secure and reliable data exchange.
**Protocol Stack:**
```mermaid
graph TB
subgraph "Communication Protocol Stack"
APP[Application Layer - CBOR Messages]
MQTT[MQTT Layer - QoS 1, Topics, Keepalive]
TLS[TLS 1.2 Layer - mTLS, X.509 Certificates]
TCP[TCP Layer - Reliable Transport]
IP[IP Layer - Network Routing]
WIFI[Wi-Fi 802.11n - 2.4 GHz Physical Layer]
end
APP --> MQTT
MQTT --> TLS
TLS --> TCP
TCP --> IP
IP --> WIFI
```
**MQTT Configuration:**
- **Broker:** Main Hub / Edge Gateway
- **QoS Level:** QoS 1 (At least once delivery)
- **Keepalive:** 60 seconds with 30-second timeout
- **Max Message Size:** 8KB per message
- **Payload Format:** CBOR (Compact Binary Object Representation)
**Topic Structure:**
```
/farm/{site_id}/{house_id}/{node_id}/data/{sensor_type}
/farm/{site_id}/{house_id}/{node_id}/status/heartbeat
/farm/{site_id}/{house_id}/{node_id}/status/system
/farm/{site_id}/{house_id}/{node_id}/cmd/{command_type}
/farm/{site_id}/{house_id}/{node_id}/diag/{severity_level}
/farm/{site_id}/{house_id}/{node_id}/ota/{action}
```
### 2.2 F-COM-002: On-Demand Data Broadcasting
**Description:** Real-time data request/response mechanism allowing the Main Hub to query current sensor data without waiting for periodic updates.
**Request/Response Flow:**
```mermaid
sequenceDiagram
participant MH as Main Hub
participant API as Main Hub APIs
participant DP as Data Pool
participant SM as Sensor Manager
Note over MH,SM: On-Demand Data Request
MH->>API: REQUEST_SENSOR_DATA(sensor_ids)
API->>DP: getLatestSensorData(sensor_ids)
DP-->>API: sensor_data_records
alt Data available and fresh
API->>API: formatCBORResponse(data)
API->>MH: SENSOR_DATA_RESPONSE(data)
else Data stale or unavailable
API->>SM: requestImmediateSample(sensor_ids)
SM->>SM: performSampling()
SM->>DP: updateSensorData(fresh_data)
DP-->>API: fresh_sensor_data
API->>MH: SENSOR_DATA_RESPONSE(fresh_data)
end
Note over MH,SM: Response time < 100ms
```
**Response Characteristics:**
- **Maximum Response Time:** 100ms from request to response
- **Data Freshness:** Timestamp included with all data
- **Validity Status:** Data quality indicators included
- **Batch Support:** Multiple sensors in single response
### 2.3 F-COM-003: Peer Sensor Hub Communication
**Description:** Limited peer-to-peer communication between Sensor Hubs using ESP-NOW for coordination and status exchange.
**ESP-NOW Configuration:**
- **Protocol:** ESP-NOW (IEEE 802.11 vendor-specific)
- **Range:** ~200m line-of-sight, ~50m through walls
- **Security:** Application-layer AES-128 encryption
- **Max Peers:** 20 concurrent peer connections
- **Acknowledgment:** Application-layer retry mechanism
**Peer Message Types:**
```c
typedef enum {
PEER_MSG_PING = 0x01, // Connectivity check
PEER_MSG_PONG = 0x02, // Connectivity response
PEER_MSG_TIME_SYNC_REQ = 0x03, // Time synchronization request
PEER_MSG_TIME_SYNC_RESP = 0x04, // Time synchronization response
PEER_MSG_STATUS_UPDATE = 0x05, // Status information exchange
PEER_MSG_EMERGENCY = 0x06 // Emergency notification
} peer_message_type_t;
typedef struct {
uint8_t message_type;
uint8_t source_id[6]; // MAC address
uint8_t sequence_number;
uint16_t payload_length;
uint8_t payload[ESP_NOW_MAX_DATA_LEN - 10];
uint8_t checksum;
} peer_message_t;
```
### 2.4 F-COM-004: Heartbeat and Status Reporting
**Description:** Continuous system health and status reporting to maintain connection awareness and system monitoring.
**Heartbeat Message Structure:**
```c
typedef struct {
uint32_t uptime_seconds;
char firmware_version[16];
uint32_t free_heap_bytes;
int8_t wifi_rssi_dbm;
uint32_t error_bitmap;
system_state_t current_state;
uint8_t sensor_count_active;
uint8_t sensor_count_total;
uint32_t last_data_timestamp;
uint16_t communication_errors;
} heartbeat_payload_t;
```
**Status Reporting Schedule:**
- **Heartbeat Interval:** 10 seconds (configurable)
- **Status Update:** On state changes (immediate)
- **Error Reporting:** On fault detection (immediate)
- **Performance Metrics:** Every 5 minutes
### 2.5 F-COM-005: Long-Range Fallback Communication
**Description:** Optional long-range communication capability for farm-scale distances where Wi-Fi coverage is insufficient.
**Fallback Options:**
1. **LoRa Module (Optional):**
- External LoRa transceiver (SX1276/SX1262)
- LoRaWAN or proprietary protocol
- Use cases: Emergency alerts, basic status
- Data rate: Low (not suitable for OTA updates)
2. **Cellular Module (Alternative):**
- LTE-M or NB-IoT modem
- Higher data rate than LoRa
- Suitable for OTA updates
- Higher power consumption and cost
**Fallback Activation Logic:**
```mermaid
graph TD
START[Communication Start] --> WIFI{Wi-Fi Available?}
WIFI -->|Yes| CONNECT[Connect to Wi-Fi]
WIFI -->|No| FALLBACK{Fallback Enabled?}
CONNECT --> MQTT{MQTT Connected?}
MQTT -->|Yes| NORMAL[Normal Operation]
MQTT -->|No| RETRY[Retry Connection]
RETRY --> TIMEOUT{Timeout Exceeded?}
TIMEOUT -->|No| MQTT
TIMEOUT -->|Yes| FALLBACK
FALLBACK -->|Yes| LORA[Activate LoRa/Cellular]
FALLBACK -->|No| OFFLINE[Offline Mode]
LORA --> LIMITED[Limited Communication]
OFFLINE --> STORE[Store Data Locally]
NORMAL --> MONITOR[Monitor Connection]
LIMITED --> MONITOR
MONITOR --> WIFI
```
## 3. Requirements Coverage
### 3.1 System Requirements (SR-XXX)
| Feature | System Requirements | Description |
|---------|-------------------|-------------|
| **F-COM-001** | SR-COM-001, SR-COM-002, SR-COM-003 | MQTT over TLS communication with Main Hub |
| **F-COM-002** | SR-COM-004, SR-COM-005 | On-demand data requests and responses |
| **F-COM-003** | SR-COM-006, SR-COM-007 | ESP-NOW peer communication |
| **F-COM-004** | SR-COM-008, SR-COM-009 | Heartbeat and status reporting |
| **F-COM-005** | SR-COM-010, SR-COM-011 | Long-range fallback communication |
### 3.2 Software Requirements (SWR-XXX)
| Feature | Software Requirements | Implementation Details |
|---------|---------------------|----------------------|
| **F-COM-001** | SWR-COM-001, SWR-COM-002, SWR-COM-003 | MQTT client, TLS implementation, topic management |
| **F-COM-002** | SWR-COM-004, SWR-COM-005, SWR-COM-006 | Request handling, data formatting, response timing |
| **F-COM-003** | SWR-COM-007, SWR-COM-008, SWR-COM-009 | ESP-NOW driver, peer management, encryption |
| **F-COM-004** | SWR-COM-010, SWR-COM-011, SWR-COM-012 | Status collection, heartbeat scheduling, error reporting |
| **F-COM-005** | SWR-COM-013, SWR-COM-014, SWR-COM-015 | Fallback protocols, activation logic, data prioritization |
## 4. Component Implementation Mapping
### 4.1 Primary Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| **Main Hub APIs** | MQTT communication, message handling, protocol management | `application_layer/business_stack/main_hub_apis/` |
| **Network Stack** | Wi-Fi management, TCP/IP, TLS implementation | `drivers/network_stack/` |
| **Peer Communication Manager** | ESP-NOW management, peer coordination | `application_layer/peer_comm/` |
| **Communication Controller** | Protocol coordination, fallback management | `application_layer/comm_controller/` |
### 4.2 Supporting Components
| Component | Support Role | Interface |
|-----------|-------------|-----------|
| **Event System** | Message routing, status notifications | `application_layer/business_stack/event_system/` |
| **Data Pool** | Latest sensor data access | `application_layer/DP_stack/data_pool/` |
| **Security Manager** | Certificate management, encryption | `application_layer/security/` |
| **Diagnostics Task** | Communication error logging | `application_layer/diag_task/` |
### 4.3 Component Interaction Diagram
```mermaid
graph TB
subgraph "Communication Feature"
API[Main Hub APIs]
NS[Network Stack]
PCM[Peer Comm Manager]
CC[Communication Controller]
end
subgraph "Core System"
ES[Event System]
DP[Data Pool]
SEC[Security Manager]
DIAG[Diagnostics Task]
end
subgraph "Hardware Interfaces"
WIFI[Wi-Fi Radio]
ESPNOW[ESP-NOW Interface]
LORA[LoRa Module]
CELL[Cellular Module]
end
subgraph "External"
MAINHUB[Main Hub]
PEERS[Peer Hubs]
end
API <--> NS
API <--> ES
API <--> DP
API <--> SEC
PCM <--> ESPNOW
PCM <--> ES
PCM <--> SEC
CC --> API
CC --> PCM
CC --> NS
NS --> WIFI
NS --> SEC
NS --> DIAG
WIFI <--> MAINHUB
ESPNOW <--> PEERS
LORA -.-> MAINHUB
CELL -.-> MAINHUB
ES -.->|Status Events| API
DP -.->|Sensor Data| API
DIAG -.->|Error Events| API
```
### 4.4 Communication Flow Sequence
```mermaid
sequenceDiagram
participant SM as Sensor Manager
participant ES as Event System
participant API as Main Hub APIs
participant NS as Network Stack
participant MH as Main Hub
Note over SM,MH: Sensor Data Communication Flow
SM->>ES: publish(SENSOR_DATA_UPDATE, data)
ES->>API: sensorDataEvent(data)
API->>API: formatMQTTMessage(data)
API->>NS: publishMQTT(topic, payload)
NS->>NS: encryptTLS(payload)
NS->>MH: MQTT_PUBLISH(encrypted_data)
MH-->>NS: MQTT_PUBACK
NS-->>API: publishComplete()
alt Communication Error
NS->>DIAG: logCommError(error_details)
NS->>ES: publish(COMM_ERROR, error)
ES->>API: commErrorEvent(error)
API->>API: handleCommError()
end
Note over SM,MH: Heartbeat Flow
loop Every 10 seconds
API->>API: collectSystemStatus()
API->>NS: publishHeartbeat(status)
NS->>MH: MQTT_PUBLISH(heartbeat)
end
```
## 5. Feature Behavior
### 5.1 Normal Operation Flow
1. **Connection Establishment:**
- Initialize Wi-Fi connection with configured credentials
- Establish TLS session with Main Hub broker
- Authenticate using device certificate (mTLS)
- Subscribe to command and configuration topics
2. **Data Communication:**
- Publish sensor data on acquisition completion
- Send heartbeat messages at regular intervals
- Handle on-demand data requests from Main Hub
- Process configuration and command messages
3. **Peer Communication:**
- Maintain ESP-NOW peer list and connections
- Exchange status information with nearby hubs
- Coordinate time synchronization when needed
- Handle emergency notifications from peers
4. **Error Recovery:**
- Detect communication failures and timeouts
- Implement exponential backoff for reconnection
- Switch to fallback communication if available
- Store data locally during communication outages
### 5.2 Error Handling
| Error Condition | Detection Method | Response Action |
|----------------|------------------|-----------------|
| **Wi-Fi Disconnection** | Link status monitoring | Attempt reconnection, activate fallback |
| **MQTT Broker Unreachable** | Connection timeout | Retry with backoff, store data locally |
| **TLS Certificate Error** | Certificate validation failure | Log security event, request new certificate |
| **Message Timeout** | Acknowledgment timeout | Retry message, escalate if persistent |
| **Peer Communication Failure** | ESP-NOW transmission failure | Remove peer, attempt rediscovery |
### 5.3 State-Dependent Behavior
| System State | Feature Behavior |
|-------------|------------------|
| **INIT** | Establish connections, authenticate, subscribe to topics |
| **RUNNING** | Full communication functionality, all protocols active |
| **WARNING** | Continue communication, increase error reporting |
| **FAULT** | Emergency communication only, diagnostic data priority |
| **OTA_UPDATE** | OTA-specific communication, suspend normal data flow |
| **TEARDOWN** | Send final status, gracefully close connections |
| **SERVICE** | Engineering communication enabled, diagnostic access |
| **SD_DEGRADED** | Continue communication, no local data buffering |
## 6. Feature Constraints
### 6.1 Timing Constraints
- **Connection Establishment:** Maximum 30 seconds for initial connection
- **Message Transmission:** Maximum 5 seconds for MQTT publish
- **On-Demand Response:** Maximum 100ms from request to response
- **Heartbeat Interval:** 10 seconds ±1 second tolerance
### 6.2 Resource Constraints
- **Memory Usage:** Maximum 64KB for communication buffers
- **Bandwidth Usage:** Maximum 1 Mbps average, 5 Mbps peak
- **Connection Limit:** 1 Main Hub + 20 peer connections maximum
- **Message Queue:** Maximum 100 pending messages
### 6.3 Security Constraints
- **Encryption:** All communication must use TLS 1.2 or higher
- **Authentication:** Mutual TLS required for Main Hub communication
- **Certificate Validation:** Full certificate chain validation required
- **Key Management:** Automatic key rotation support required
## 7. Interface Specifications
### 7.1 Main Hub APIs Public Interface
```c
// Connection management
bool mainHubAPI_initialize(const comm_config_t* config);
bool mainHubAPI_connect(void);
bool mainHubAPI_disconnect(void);
bool mainHubAPI_isConnected(void);
// Message publishing
bool mainHubAPI_publishSensorData(const sensor_data_record_t* data);
bool mainHubAPI_publishHeartbeat(const heartbeat_payload_t* heartbeat);
bool mainHubAPI_publishDiagnostic(const diagnostic_event_t* event);
bool mainHubAPI_publishStatus(const system_status_t* status);
// Message handling
bool mainHubAPI_subscribeToCommands(command_handler_t handler);
bool mainHubAPI_subscribeToConfig(config_handler_t handler);
bool mainHubAPI_handleOnDemandRequest(const data_request_t* request);
// Status and statistics
comm_status_t mainHubAPI_getConnectionStatus(void);
comm_stats_t mainHubAPI_getStatistics(void);
bool mainHubAPI_resetStatistics(void);
```
### 7.2 Peer Communication Manager API
```c
// Peer management
bool peerComm_initialize(void);
bool peerComm_addPeer(const uint8_t* mac_address);
bool peerComm_removePeer(const uint8_t* mac_address);
bool peerComm_getPeerList(peer_info_t* peers, size_t* count);
// Message transmission
bool peerComm_sendPing(const uint8_t* peer_mac);
bool peerComm_sendTimeSync(const uint8_t* peer_mac, uint64_t timestamp);
bool peerComm_sendStatus(const uint8_t* peer_mac, const peer_status_t* status);
bool peerComm_broadcastEmergency(const emergency_msg_t* emergency);
// Message reception
bool peerComm_registerMessageHandler(peer_message_handler_t handler);
bool peerComm_setEncryptionKey(const uint8_t* key, size_t key_length);
```
### 7.3 Network Stack Interface
```c
// Network management
bool networkStack_initialize(void);
bool networkStack_connectWiFi(const wifi_config_t* config);
bool networkStack_disconnectWiFi(void);
wifi_status_t networkStack_getWiFiStatus(void);
// MQTT operations
bool networkStack_connectMQTT(const mqtt_config_t* config);
bool networkStack_publishMQTT(const char* topic, const uint8_t* payload, size_t length);
bool networkStack_subscribeMQTT(const char* topic, mqtt_message_handler_t handler);
bool networkStack_disconnectMQTT(void);
// TLS management
bool networkStack_loadCertificate(const uint8_t* cert, size_t cert_length);
bool networkStack_loadPrivateKey(const uint8_t* key, size_t key_length);
bool networkStack_validateCertificate(const uint8_t* cert);
```
## 8. Testing and Validation
### 8.1 Unit Testing
- **Protocol Implementation:** MQTT, TLS, ESP-NOW protocol compliance
- **Message Formatting:** CBOR encoding/decoding validation
- **Error Handling:** Network failure and recovery scenarios
- **Security:** Certificate validation and encryption testing
### 8.2 Integration Testing
- **Main Hub Communication:** End-to-end MQTT communication testing
- **Peer Communication:** ESP-NOW multi-device testing
- **Fallback Systems:** LoRa/Cellular fallback activation
- **Event Integration:** Communication event publication and handling
### 8.3 System Testing
- **Load Testing:** High-frequency data transmission under load
- **Reliability Testing:** 48-hour continuous communication
- **Security Testing:** Penetration testing and certificate validation
- **Interoperability:** Communication with actual Main Hub systems
### 8.4 Acceptance Criteria
- Successful connection establishment within timing constraints
- 99.9% message delivery success rate under normal conditions
- On-demand responses within 100ms requirement
- Secure communication with proper certificate validation
- Graceful handling of all communication error conditions
- Peer communication functional with multiple concurrent peers
## 9. Dependencies
### 9.1 Internal Dependencies
- **Event System:** Message routing and status notifications
- **Data Pool:** Access to latest sensor data for transmission
- **Security Manager:** Certificate management and encryption
- **State Manager:** System state awareness for communication control
### 9.2 External Dependencies
- **ESP-IDF Framework:** Wi-Fi, TCP/IP, TLS, ESP-NOW drivers
- **Main Hub Broker:** MQTT broker availability and configuration
- **Network Infrastructure:** Wi-Fi access points and internet connectivity
- **Certificate Authority:** X.509 certificates for device authentication
## 10. Future Enhancements
### 10.1 Planned Improvements
- **Adaptive QoS:** Dynamic quality of service based on network conditions
- **Mesh Networking:** Sensor Hub mesh for extended coverage
- **Edge Computing:** Local data processing and filtering
- **5G Integration:** 5G connectivity for high-bandwidth applications
### 10.2 Scalability Considerations
- **Protocol Optimization:** Compressed protocols for bandwidth efficiency
- **Load Balancing:** Multiple Main Hub connections for redundancy
- **Cloud Integration:** Direct cloud connectivity bypass Main Hub
- **IoT Platform Integration:** Standard IoT platform protocol support
---
**Document Status:** Final for Implementation Phase
**Component Dependencies:** Verified against architecture
**Requirements Traceability:** Complete (SR-COM, SWR-COM)
**Next Review:** After component implementation

0
system_arch_final/software/features/F-DATA_Persistence_Management.md Normal file
View File

581
system_arch_final/software/features/F-DIAG_Diagnostics_Health.md Normal file
View File

@@ -0,0 +1,581 @@
# Feature Specification: Diagnostics & Health Monitoring
# Feature ID: F-DIAG (F-DIAG-001 to F-DIAG-004)
**Document Type:** Feature Specification
**Version:** 1.0
**Date:** 2025-01-19
**Feature Category:** Diagnostics & Health Monitoring
## 1. Feature Overview
### 1.1 Feature Purpose
The Diagnostics & Health Monitoring feature provides comprehensive system health assessment, fault detection, diagnostic event management, and engineering access capabilities for the ASF Sensor Hub. This feature ensures system reliability through proactive monitoring, structured fault reporting, and maintenance support.
### 1.2 Feature Scope
**In Scope:**
- Structured diagnostic code framework with severity classification
- Persistent diagnostic event storage and management
- Engineering diagnostic sessions with secure access
- System health monitoring and performance metrics
- Cross-component fault correlation and root cause analysis
**Out of Scope:**
- Main Hub diagnostic aggregation and analysis
- Predictive maintenance algorithms (future enhancement)
- Hardware fault injection testing equipment
- Remote diagnostic access without Main Hub coordination
## 2. Sub-Features
### 2.1 F-DIAG-001: Diagnostic Code Management
**Description:** Comprehensive diagnostic code framework for standardized fault identification, classification, and reporting across all system components.
**Diagnostic Code Structure:**
```c
typedef struct {
uint16_t code; // Unique diagnostic code (0x0001-0xFFFF)
diagnostic_severity_t severity; // INFO, WARNING, ERROR, FATAL
diagnostic_category_t category; // SENSOR, COMM, STORAGE, SYSTEM, SECURITY
uint64_t timestamp_ms; // Event occurrence time
uint8_t source_component_id; // Component that generated the event
char description[64]; // Human-readable description
uint8_t data[32]; // Context-specific diagnostic data
uint16_t occurrence_count; // Number of times this event occurred
} diagnostic_event_t;
typedef enum {
DIAG_SEVERITY_INFO = 0, // Informational, no action required
DIAG_SEVERITY_WARNING = 1, // Warning, monitoring required
DIAG_SEVERITY_ERROR = 2, // Error, corrective action needed
DIAG_SEVERITY_FATAL = 3 // Fatal, system functionality compromised
} diagnostic_severity_t;
typedef enum {
DIAG_CATEGORY_SENSOR = 0, // Sensor-related diagnostics
DIAG_CATEGORY_COMM = 1, // Communication diagnostics
DIAG_CATEGORY_STORAGE = 2, // Storage and persistence diagnostics
DIAG_CATEGORY_SYSTEM = 3, // System management diagnostics
DIAG_CATEGORY_SECURITY = 4, // Security-related diagnostics
DIAG_CATEGORY_POWER = 5, // Power and fault handling diagnostics
DIAG_CATEGORY_OTA = 6 // OTA update diagnostics
} diagnostic_category_t;
```
**Diagnostic Code Registry (Examples):**
| Code | Severity | Category | Description |
|------|----------|----------|-------------|
| 0x1001 | WARNING | SENSOR | Sensor communication timeout |
| 0x1002 | ERROR | SENSOR | Sensor out-of-range value detected |
| 0x1003 | FATAL | SENSOR | Critical sensor hardware failure |
| 0x2001 | WARNING | COMM | Wi-Fi signal strength low |
| 0x2002 | ERROR | COMM | MQTT broker connection failed |
| 0x2003 | FATAL | COMM | TLS certificate validation failed |
| 0x3001 | WARNING | STORAGE | SD card space low (< 10%) |
| 0x3002 | ERROR | STORAGE | SD card write failure |
| 0x3003 | FATAL | STORAGE | SD card not detected |
| 0x4001 | INFO | SYSTEM | System state transition |
| 0x4002 | WARNING | SYSTEM | Memory usage high (> 80%) |
| 0x4003 | FATAL | SYSTEM | Watchdog timer reset |
### 2.2 F-DIAG-002: Diagnostic Data Storage
**Description:** Persistent storage of diagnostic events in non-volatile memory with efficient storage management and retrieval capabilities.
**Storage Architecture:**
```mermaid
graph TB
subgraph "Diagnostic Storage System"
GEN[Diagnostic Generator] --> BUF[Ring Buffer]
BUF --> FILTER[Severity Filter]
FILTER --> PERSIST[Persistence Layer]
PERSIST --> SD[SD Card Storage]
PERSIST --> NVS[NVS Flash Storage]
end
subgraph "Storage Policy"
CRITICAL[FATAL/ERROR Events] --> NVS
NORMAL[WARNING/INFO Events] --> SD
OVERFLOW[Buffer Overflow] --> DISCARD[Discard Oldest]
end
subgraph "Retrieval Interface"
QUERY[Query Interface] --> PERSIST
EXPORT[Export Interface] --> PERSIST
CLEAR[Clear Interface] --> PERSIST
end
```
**Storage Management:**
- **Ring Buffer:** 100 events in RAM for immediate access
- **NVS Storage:** Critical events (ERROR/FATAL) persisted to flash
- **SD Card Storage:** All events stored to SD card when available
- **Retention Policy:** 30 days or 10,000 events maximum
- **Compression:** Event data compressed for efficient storage
### 2.3 F-DIAG-003: Diagnostic Session
**Description:** Secure engineering access interface for diagnostic data retrieval, system inspection, and maintenance operations.
**Session Types:**
| Session Type | Access Level | Authentication | Capabilities |
|-------------|-------------|----------------|--------------|
| **Read-Only** | Basic | PIN code | View diagnostics, system status |
| **Engineering** | Advanced | Certificate | Diagnostic management, configuration |
| **Service** | Full | Multi-factor | System control, debug access |
**Session Interface:**
```c
typedef struct {
session_id_t session_id;
session_type_t type;
uint64_t start_time;
uint64_t last_activity;
uint32_t timeout_seconds;
bool authenticated;
char user_id[32];
} diagnostic_session_t;
// Session management API
session_id_t diag_createSession(session_type_t type);
bool diag_authenticateSession(session_id_t session, const auth_credentials_t* creds);
bool diag_closeSession(session_id_t session);
bool diag_isSessionValid(session_id_t session);
// Diagnostic access API
bool diag_getEvents(session_id_t session, diagnostic_filter_t* filter,
diagnostic_event_t* events, size_t* count);
bool diag_clearEvents(session_id_t session, diagnostic_filter_t* filter);
bool diag_exportEvents(session_id_t session, export_format_t format,
uint8_t* buffer, size_t* size);
bool diag_getSystemHealth(session_id_t session, system_health_t* health);
```
### 2.4 F-DIAG-004: System Health Monitoring
**Description:** Continuous monitoring of system performance metrics, resource utilization, and component health status.
**Health Metrics:**
```c
typedef struct {
// CPU and Memory
uint8_t cpu_usage_percent;
uint32_t free_heap_bytes;
uint32_t min_free_heap_bytes;
uint16_t task_count;
// Storage
uint64_t sd_free_bytes;
uint64_t sd_total_bytes;
uint32_t nvs_free_entries;
uint32_t nvs_used_entries;
// Communication
int8_t wifi_rssi_dbm;
uint32_t mqtt_messages_sent;
uint32_t mqtt_messages_failed;
uint32_t comm_error_count;
// Sensors
uint8_t sensors_active;
uint8_t sensors_total;
uint8_t sensors_failed;
uint32_t sensor_error_count;
// System
uint32_t uptime_seconds;
uint32_t reset_count;
system_state_t current_state;
uint32_t state_change_count;
// Power
float supply_voltage;
bool brownout_detected;
uint32_t power_cycle_count;
} system_health_t;
```
**Health Monitoring Flow:**
```mermaid
sequenceDiagram
participant HM as Health Monitor
participant COMP as System Components
participant DIAG as Diagnostic Storage
participant ES as Event System
participant HMI as Local HMI
Note over HM,HMI: Health Monitoring Cycle (10 seconds)
loop Every 10 seconds
HM->>COMP: collectHealthMetrics()
COMP-->>HM: health_data
HM->>HM: analyzeHealthTrends()
HM->>HM: detectAnomalies()
alt Anomaly detected
HM->>DIAG: logDiagnosticEvent(anomaly)
HM->>ES: publish(HEALTH_ANOMALY, details)
end
HM->>ES: publish(HEALTH_UPDATE, metrics)
ES->>HMI: updateHealthDisplay(metrics)
end
```
## 3. Requirements Coverage
### 3.1 System Requirements (SR-XXX)
| Feature | System Requirements | Description |
|---------|-------------------|-------------|
| **F-DIAG-001** | SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004 | Diagnostic code framework and event management |
| **F-DIAG-002** | SR-DIAG-005, SR-DIAG-006, SR-DIAG-007 | Persistent diagnostic storage and retention |
| **F-DIAG-003** | SR-DIAG-008, SR-DIAG-009, SR-DIAG-010, SR-DIAG-011 | Engineering diagnostic sessions and access control |
| **F-DIAG-004** | SR-DIAG-012, SR-DIAG-013, SR-DIAG-014 | System health monitoring and performance metrics |
### 3.2 Software Requirements (SWR-XXX)
| Feature | Software Requirements | Implementation Details |
|---------|---------------------|----------------------|
| **F-DIAG-001** | SWR-DIAG-001, SWR-DIAG-002, SWR-DIAG-003 | Event structure, code registry, severity classification |
| **F-DIAG-002** | SWR-DIAG-004, SWR-DIAG-005, SWR-DIAG-006 | Storage management, persistence, retrieval interface |
| **F-DIAG-003** | SWR-DIAG-007, SWR-DIAG-008, SWR-DIAG-009 | Session management, authentication, access control |
| **F-DIAG-004** | SWR-DIAG-010, SWR-DIAG-011, SWR-DIAG-012 | Health metrics collection, anomaly detection, reporting |
## 4. Component Implementation Mapping
### 4.1 Primary Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| **Diagnostics Task** | Health monitoring, event coordination, session management | `application_layer/diag_task/` |
| **Error Handler** | Diagnostic event generation, fault classification | `application_layer/error_handler/` |
| **Diagnostic Storage Manager** | Event persistence, retrieval, storage management | `application_layer/diag_storage/` |
| **Health Monitor** | System metrics collection, anomaly detection | `application_layer/health_monitor/` |
### 4.2 Supporting Components
| Component | Support Role | Interface |
|-----------|-------------|-----------|
| **Event System** | Diagnostic event distribution, component coordination | `application_layer/business_stack/event_system/` |
| **Data Persistence** | Storage abstraction, NVS and SD card access | `application_layer/DP_stack/persistence/` |
| **Security Manager** | Session authentication, access control | `application_layer/security/` |
| **State Manager** | System state awareness, state-dependent diagnostics | `application_layer/business_stack/STM/` |
### 4.3 Component Interaction Diagram
```mermaid
graph TB
subgraph "Diagnostics & Health Monitoring Feature"
DT[Diagnostics Task]
EH[Error Handler]
DSM[Diagnostic Storage Manager]
HM[Health Monitor]
end
subgraph "Core System Components"
ES[Event System]
DP[Data Persistence]
SEC[Security Manager]
STM[State Manager]
end
subgraph "System Components"
SM[Sensor Manager]
COM[Communication]
OTA[OTA Manager]
PWR[Power Manager]
end
subgraph "Storage"
NVS[NVS Flash]
SD[SD Card]
end
subgraph "Interfaces"
HMI[Local HMI]
UART[UART Debug]
NET[Network Session]
end
DT <--> ES
DT <--> DSM
DT <--> HM
DT <--> SEC
EH --> ES
EH --> DSM
DSM <--> DP
DSM --> NVS
DSM --> SD
HM --> SM
HM --> COM
HM --> OTA
HM --> PWR
HM --> STM
ES -.->|Health Events| HMI
ES -.->|Diagnostic Events| COM
DT -.->|Session Access| UART
DT -.->|Session Access| NET
```
### 4.4 Diagnostic Event Flow
```mermaid
sequenceDiagram
participant COMP as System Component
participant EH as Error Handler
participant ES as Event System
participant DSM as Diagnostic Storage
participant DT as Diagnostics Task
participant COM as Communication
Note over COMP,COM: Diagnostic Event Generation and Processing
COMP->>EH: reportError(error_info)
EH->>EH: classifyError(error_info)
EH->>EH: generateDiagnosticEvent()
EH->>ES: publish(DIAGNOSTIC_EVENT, event)
ES->>DSM: storeDiagnosticEvent(event)
ES->>DT: processDiagnosticEvent(event)
ES->>COM: reportDiagnosticEvent(event)
DSM->>DSM: checkStoragePolicy(event.severity)
alt Critical Event (ERROR/FATAL)
DSM->>NVS: persistToFlash(event)
end
DSM->>SD: persistToSDCard(event)
DT->>DT: updateHealthMetrics(event)
DT->>DT: checkSystemHealth()
alt Health degradation detected
DT->>ES: publish(HEALTH_DEGRADATION, metrics)
end
```
## 5. Feature Behavior
### 5.1 Normal Operation Flow
1. **System Initialization:**
- Initialize diagnostic storage and load existing events
- Start health monitoring tasks and metric collection
- Register diagnostic event handlers with all components
- Establish baseline health metrics and thresholds
2. **Continuous Monitoring:**
- Collect system health metrics every 10 seconds
- Process diagnostic events from all system components
- Store events according to severity and storage policy
- Analyze health trends and detect anomalies
3. **Event Processing:**
- Classify and timestamp all diagnostic events
- Apply filtering and correlation rules
- Persist events to appropriate storage (NVS/SD)
- Distribute events to interested components
4. **Session Management:**
- Handle engineering session requests and authentication
- Provide secure access to diagnostic data and system health
- Log all diagnostic session activities for audit
- Enforce session timeouts and access controls
### 5.2 Error Handling
| Error Condition | Detection Method | Response Action |
|----------------|------------------|-----------------|
| **Storage Full** | Storage capacity monitoring | Implement retention policy, discard oldest events |
| **SD Card Failure** | Write operation failure | Switch to NVS-only storage, log degradation |
| **Memory Exhaustion** | Heap monitoring | Reduce buffer sizes, increase event filtering |
| **Session Timeout** | Activity monitoring | Close session, clear authentication |
| **Authentication Failure** | Credential validation | Reject session, log security event |
### 5.3 State-Dependent Behavior
| System State | Feature Behavior |
|-------------|------------------|
| **INIT** | Initialize storage, load existing events, start monitoring |
| **RUNNING** | Full diagnostic functionality, continuous health monitoring |
| **WARNING** | Enhanced monitoring, increased event generation |
| **FAULT** | Critical diagnostics only, preserve fault information |
| **OTA_UPDATE** | Suspend monitoring, log OTA-related events |
| **TEARDOWN** | Flush pending events, preserve diagnostic state |
| **SERVICE** | Full diagnostic access, engineering session support |
| **SD_DEGRADED** | NVS-only storage, reduced event retention |
## 6. Feature Constraints
### 6.1 Timing Constraints
- **Event Processing:** Maximum 10ms from generation to storage
- **Health Monitoring:** 10-second monitoring cycle with ±1 second tolerance
- **Session Response:** Maximum 500ms for diagnostic queries
- **Storage Operations:** Maximum 100ms for event persistence
### 6.2 Resource Constraints
- **Memory Usage:** Maximum 32KB for diagnostic buffers and storage
- **Event Storage:** Maximum 10,000 events or 30 days retention
- **Session Limit:** Maximum 2 concurrent diagnostic sessions
- **CPU Usage:** Maximum 5% of available CPU time for diagnostics
### 6.3 Security Constraints
- **Session Authentication:** All diagnostic access must be authenticated
- **Data Protection:** Diagnostic data encrypted when stored
- **Access Logging:** All diagnostic activities logged for audit
- **Privilege Separation:** Role-based access to diagnostic functions
## 7. Interface Specifications
### 7.1 Diagnostics Task Public API
```c
// Initialization and control
bool diagTask_initialize(void);
bool diagTask_start(void);
bool diagTask_stop(void);
bool diagTask_isRunning(void);
// Event management
bool diagTask_reportEvent(const diagnostic_event_t* event);
bool diagTask_getEvents(const diagnostic_filter_t* filter,
diagnostic_event_t* events, size_t* count);
bool diagTask_clearEvents(const diagnostic_filter_t* filter);
bool diagTask_exportEvents(export_format_t format, uint8_t* buffer, size_t* size);
// Health monitoring
bool diagTask_getSystemHealth(system_health_t* health);
bool diagTask_getHealthHistory(health_history_t* history, size_t* count);
bool diagTask_resetHealthMetrics(void);
// Session management
session_id_t diagTask_createSession(session_type_t type);
bool diagTask_authenticateSession(session_id_t session, const auth_credentials_t* creds);
bool diagTask_closeSession(session_id_t session);
bool diagTask_isSessionValid(session_id_t session);
```
### 7.2 Error Handler API
```c
// Error reporting
bool errorHandler_reportError(component_id_t source, error_code_t code,
const char* description, const uint8_t* context_data);
bool errorHandler_reportWarning(component_id_t source, warning_code_t code,
const char* description);
bool errorHandler_reportInfo(component_id_t source, info_code_t code,
const char* description);
// Error classification
diagnostic_severity_t errorHandler_classifyError(error_code_t code);
diagnostic_category_t errorHandler_categorizeError(component_id_t source, error_code_t code);
bool errorHandler_isErrorCritical(error_code_t code);
// Error statistics
bool errorHandler_getErrorStatistics(error_statistics_t* stats);
bool errorHandler_resetErrorStatistics(void);
```
### 7.3 Health Monitor API
```c
// Health monitoring
bool healthMonitor_initialize(void);
bool healthMonitor_startMonitoring(void);
bool healthMonitor_stopMonitoring(void);
bool healthMonitor_getCurrentHealth(system_health_t* health);
// Metric collection
bool healthMonitor_collectMetrics(void);
bool healthMonitor_updateMetric(health_metric_id_t metric_id, float value);
bool healthMonitor_getMetricHistory(health_metric_id_t metric_id,
metric_history_t* history, size_t* count);
// Anomaly detection
bool healthMonitor_setThreshold(health_metric_id_t metric_id, float threshold);
bool healthMonitor_enableAnomalyDetection(health_metric_id_t metric_id, bool enable);
bool healthMonitor_getAnomalies(anomaly_t* anomalies, size_t* count);
```
## 8. Testing and Validation
### 8.1 Unit Testing
- **Event Generation:** Diagnostic event creation and classification
- **Storage Management:** Event persistence and retrieval operations
- **Health Monitoring:** Metric collection and anomaly detection
- **Session Management:** Authentication and access control
### 8.2 Integration Testing
- **Cross-Component Events:** Diagnostic events from all system components
- **Storage Integration:** NVS and SD card storage operations
- **Event Distribution:** Event system integration and notification
- **Session Integration:** Engineering access via multiple interfaces
### 8.3 System Testing
- **Long-Duration Monitoring:** 48-hour continuous diagnostic operation
- **Storage Stress Testing:** High-frequency event generation and storage
- **Session Security Testing:** Authentication bypass attempts
- **Fault Injection Testing:** Component failure simulation and detection
### 8.4 Acceptance Criteria
- All diagnostic events properly classified and stored
- Health monitoring detects system anomalies within timing constraints
- Engineering sessions provide secure access to diagnostic data
- Storage management maintains data integrity under all conditions
- No diagnostic overhead impact on core system functionality
- Complete audit trail of all diagnostic activities
## 9. Dependencies
### 9.1 Internal Dependencies
- **Event System:** Diagnostic event distribution and coordination
- **Data Persistence:** Storage abstraction for diagnostic data
- **Security Manager:** Session authentication and access control
- **State Manager:** System state awareness for state-dependent diagnostics
### 9.2 External Dependencies
- **ESP-IDF Framework:** NVS, SD card, and system monitoring APIs
- **FreeRTOS:** Task scheduling and system resource monitoring
- **Hardware Components:** SD card, NVS flash, UART interface
- **System Components:** All components for health metric collection
## 10. Future Enhancements
### 10.1 Planned Improvements
- **Predictive Analytics:** Machine learning for failure prediction
- **Advanced Correlation:** Multi-component fault correlation analysis
- **Remote Diagnostics:** Cloud-based diagnostic data analysis
- **Automated Recovery:** Self-healing mechanisms based on diagnostics
### 10.2 Scalability Considerations
- **Distributed Diagnostics:** Cross-hub diagnostic correlation
- **Cloud Integration:** Real-time diagnostic streaming to cloud
- **Advanced Analytics:** Big data analytics for fleet-wide diagnostics
- **Mobile Interface:** Smartphone app for field diagnostic access
---
**Document Status:** Final for Implementation Phase
**Component Dependencies:** Verified against architecture
**Requirements Traceability:** Complete (SR-DIAG, SWR-DIAG)
**Next Review:** After component implementation

528
system_arch_final/software/features/F-DQC_Data_Quality_Calibration.md Normal file
View File

@@ -0,0 +1,528 @@
# Feature Specification: Data Quality & Calibration
# Feature ID: F-DQC (F-DQC-001 to F-DQC-005)
**Document Type:** Feature Specification
**Version:** 1.0
**Date:** 2025-01-19
**Feature Category:** Data Quality & Calibration
## 1. Feature Overview
### 1.1 Feature Purpose
The Data Quality & Calibration feature ensures that all sensor data generated by the ASF Sensor Hub is valid, trustworthy, correctly classified, and calibrated throughout the system lifecycle. This feature provides mechanisms for automatic sensor identification, compatibility enforcement, failure detection, and centralized calibration management.
### 1.2 Feature Scope
**In Scope:**
- Automatic sensor detection and identification
- Sensor-slot compatibility enforcement
- Real-time sensor failure detection and isolation
- Machine constants and calibration parameter management
- Redundant sensor support and sensor fusion
**Out of Scope:**
- Sensor hardware manufacturing and design
- External calibration equipment and procedures
- Main Hub calibration algorithms
- Sensor replacement and maintenance procedures
## 2. Sub-Features
### 2.1 F-DQC-001: Automatic Sensor Detection
**Description:** Dynamic detection and identification of connected sensors using hardware-based presence detection mechanisms.
**Detection Methods:**
- **GPIO Presence Pins:** Dedicated detection signals per sensor slot
- **I2C Device Scanning:** Automatic I2C address enumeration
- **Device ID Reading:** Sensor-specific identification protocols
- **Electrical Signature:** Voltage/resistance-based detection
**Detection Process:**
```mermaid
sequenceDiagram
participant SM as Sensor Manager
participant DD as Device Detector
participant SD as Sensor Driver
participant MC as Machine Constants
Note over SM,MC: Sensor Detection Cycle
SM->>DD: scanForSensors()
loop For each sensor slot
DD->>DD: checkPresencePin(slot_id)
alt Presence detected
DD->>SD: probeSensorType(slot_id)
SD->>SD: readDeviceID()
SD-->>DD: sensor_type_info
DD->>MC: validateSensorSlot(slot_id, sensor_type)
MC-->>DD: validation_result
end
end
DD-->>SM: detected_sensors_list
SM->>SM: updateSensorRegistry()
```
### 2.2 F-DQC-002: Sensor Type Enforcement
**Description:** Enforcement of sensor-slot compatibility to prevent incorrect sensor installation and configuration errors.
**Enforcement Mechanisms:**
- **Physical Slot Design:** Mechanical keying for sensor types
- **Electrical Validation:** Pin configuration verification
- **Software Validation:** Machine constants cross-reference
- **Protocol Validation:** Communication interface verification
**Slot Mapping Table:**
| Slot ID | Sensor Type | Interface | Detection Pin | Validation Method |
|---------|-------------|-----------|---------------|-------------------|
| SLOT_01 | Temperature | I2C/Analog | GPIO_12 | Device ID + Range |
| SLOT_02 | Humidity | I2C | GPIO_13 | Device ID + Protocol |
| SLOT_03 | CO2 | UART/I2C | GPIO_14 | Device ID + Calibration |
| SLOT_04 | NH3 | Analog/I2C | GPIO_15 | Range + Sensitivity |
| SLOT_05 | VOC | I2C | GPIO_16 | Device ID + Algorithm |
| SLOT_06 | PM | UART/I2C | GPIO_17 | Protocol + Range |
| SLOT_07 | Light | Analog/I2C | GPIO_18 | Range + Spectral |
### 2.3 F-DQC-003: Sensor Failure Detection
**Description:** Continuous monitoring of sensor behavior to detect and isolate failures in real-time.
**Failure Detection Methods:**
- **Communication Timeouts:** I2C/UART/SPI response monitoring
- **Range Validation:** Out-of-specification value detection
- **Trend Analysis:** Abnormal rate-of-change detection
- **Cross-Validation:** Multi-sensor consistency checking
- **Health Monitoring:** Sensor self-diagnostic features
**Failure Classification:**
```c
typedef enum {
SENSOR_FAILURE_NONE = 0,
SENSOR_FAILURE_COMMUNICATION, // Timeout, NACK, protocol error
SENSOR_FAILURE_OUT_OF_RANGE, // Values outside physical limits
SENSOR_FAILURE_STUCK_VALUE, // No change over time
SENSOR_FAILURE_ERRATIC, // Excessive noise or variation
SENSOR_FAILURE_CALIBRATION, // Drift beyond acceptable limits
SENSOR_FAILURE_HARDWARE, // Self-diagnostic failure
SENSOR_FAILURE_UNKNOWN // Unclassified failure
} sensor_failure_type_t;
```
### 2.4 F-DQC-004: Machine Constants & Calibration Management
**Description:** Centralized management of sensor configuration, calibration parameters, and system identity information.
**Machine Constants Structure:**
```c
typedef struct {
// System Identity
char device_id[32];
char site_id[16];
char house_id[16];
uint32_t firmware_version;
// Sensor Configuration
sensor_config_t sensors[MAX_SENSORS];
// Calibration Parameters
calibration_params_t calibration[MAX_SENSORS];
// Communication Settings
comm_config_t communication;
// System Limits
system_limits_t limits;
// Validation
uint32_t checksum;
uint64_t timestamp;
} machine_constants_t;
typedef struct {
uint8_t sensor_id;
sensor_type_t type;
bool enabled;
uint32_t sampling_rate;
filter_config_t filter;
float min_value, max_value;
char unit[8];
} sensor_config_t;
typedef struct {
float offset;
float scale;
float[] polynomial_coeffs;
uint8_t coeff_count;
uint64_t calibration_date;
uint32_t calibration_interval;
} calibration_params_t;
```
### 2.5 F-DQC-005: Redundant Sensor Support
**Description:** Support for redundant sensors and sensor fusion for critical measurements.
**Redundancy Strategies:**
- **Dual Sensors:** Two sensors of same type for critical parameters
- **Cross-Validation:** Different sensor types measuring related parameters
- **Voting Logic:** Majority voting for multiple sensors
- **Graceful Degradation:** Fallback to single sensor operation
**Sensor Fusion Algorithm:**
```mermaid
graph TB
subgraph "Sensor Fusion Process"
S1[Sensor 1] --> V[Validator]
S2[Sensor 2] --> V
S3[Sensor 3] --> V
V --> F[Fusion Algorithm]
F --> O[Output Value]
F --> C[Confidence Level]
end
subgraph "Fusion Methods"
AVG[Weighted Average]
MED[Median Filter]
KAL[Kalman Filter]
VOT[Voting Logic]
end
F --> AVG
F --> MED
F --> KAL
F --> VOT
```
## 3. Requirements Coverage
### 3.1 System Requirements (SR-XXX)
| Feature | System Requirements | Description |
|---------|-------------------|-------------|
| **F-DQC-001** | SR-DQC-001, SR-DQC-002 | Automatic sensor detection and enumeration |
| **F-DQC-002** | SR-DQC-003, SR-DQC-004 | Sensor type enforcement and slot validation |
| **F-DQC-003** | SR-DQC-005, SR-DQC-006 | Failure detection and isolation |
| **F-DQC-004** | SR-DQC-007, SR-DQC-008 | Machine constants management and persistence |
| **F-DQC-005** | SR-DQC-009, SR-DQC-010 | Redundant sensor support and fusion |
### 3.2 Software Requirements (SWR-XXX)
| Feature | Software Requirements | Implementation Details |
|---------|---------------------|----------------------|
| **F-DQC-001** | SWR-DQC-001, SWR-DQC-002, SWR-DQC-003 | Detection algorithms, device probing, registry management |
| **F-DQC-002** | SWR-DQC-004, SWR-DQC-005, SWR-DQC-006 | Slot mapping, validation logic, error reporting |
| **F-DQC-003** | SWR-DQC-007, SWR-DQC-008, SWR-DQC-009 | Health monitoring, failure classification, isolation |
| **F-DQC-004** | SWR-DQC-010, SWR-DQC-011, SWR-DQC-012 | MC structure, persistence, update mechanisms |
| **F-DQC-005** | SWR-DQC-013, SWR-DQC-014, SWR-DQC-015 | Fusion algorithms, redundancy management, voting logic |
## 4. Component Implementation Mapping
### 4.1 Primary Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| **Machine Constant Manager** | MC loading, validation, update coordination | `application_layer/business_stack/machine_constant_manager/` |
| **Sensor Manager** | Detection coordination, failure monitoring | `application_layer/business_stack/sensor_manager/` |
| **Device Detector** | Hardware detection, sensor probing | `drivers/device_detector/` |
| **Calibration Manager** | Calibration algorithms, parameter management | `application_layer/calibration/` |
### 4.2 Supporting Components
| Component | Support Role | Interface |
|-----------|-------------|-----------|
| **Sensor Drivers** | Hardware interface, device identification | `drivers/sensors/` |
| **Event System** | Detection events, failure notifications | `application_layer/business_stack/event_system/` |
| **Data Persistence** | MC storage, calibration data persistence | `application_layer/DP_stack/persistence/` |
| **Diagnostics Task** | Failure logging, health reporting | `application_layer/diag_task/` |
### 4.3 Component Interaction Diagram
```mermaid
graph TB
subgraph "Data Quality & Calibration Feature"
MCM[Machine Constant Manager]
SM[Sensor Manager]
DD[Device Detector]
CAL[Calibration Manager]
end
subgraph "Supporting Components"
SD[Sensor Drivers]
ES[Event System]
DP[Data Persistence]
DIAG[Diagnostics Task]
end
subgraph "Hardware"
SENSORS[Physical Sensors]
GPIO[Detection Pins]
I2C[I2C Bus]
UART[UART Interface]
end
MCM <--> DP
MCM --> SM
MCM --> CAL
SM <--> ES
SM --> DD
SM --> DIAG
DD --> SD
DD --> GPIO
CAL --> MCM
CAL <--> DP
SD --> I2C
SD --> UART
SD --> SENSORS
ES -.->|Detection Events| SM
ES -.->|Failure Events| DIAG
DIAG -.->|Health Data| SM
```
### 4.4 Detection and Validation Flow
```mermaid
sequenceDiagram
participant HW as Hardware
participant DD as Device Detector
participant SD as Sensor Driver
participant SM as Sensor Manager
participant MCM as MC Manager
participant ES as Event System
participant DIAG as Diagnostics
Note over HW,DIAG: Sensor Detection and Validation
SM->>DD: initiateSensorScan()
loop For each sensor slot
DD->>HW: checkPresencePin(slot_id)
HW-->>DD: presence_status
alt Sensor present
DD->>SD: probeSensorType(slot_id)
SD->>HW: readDeviceID()
HW-->>SD: device_info
SD-->>DD: sensor_type_info
DD->>MCM: validateSensorSlot(slot_id, sensor_type)
MCM-->>DD: validation_result
alt Validation successful
DD->>SM: registerSensor(slot_id, sensor_info)
SM->>ES: publish(SENSOR_DETECTED, sensor_info)
else Validation failed
DD->>DIAG: reportValidationError(slot_id, error)
DIAG->>ES: publish(SENSOR_VALIDATION_FAILED, error)
end
end
end
DD-->>SM: scanComplete(detected_sensors)
SM->>ES: publish(SENSOR_SCAN_COMPLETE, summary)
```
## 5. Feature Behavior
### 5.1 Normal Operation Flow
1. **System Initialization:**
- Load machine constants from persistent storage
- Validate MC integrity and version compatibility
- Initialize sensor detection and calibration systems
- Perform initial sensor scan and validation
2. **Sensor Detection Cycle:**
- Scan all sensor slots for presence
- Identify sensor types and validate compatibility
- Register detected sensors in system registry
- Configure sensors according to machine constants
3. **Continuous Monitoring:**
- Monitor sensor health and communication status
- Detect failures and classify failure types
- Apply calibration corrections to sensor data
- Manage redundant sensors and sensor fusion
4. **Configuration Management:**
- Handle machine constants updates from Main Hub
- Validate new configurations before application
- Coordinate system teardown for MC updates
- Persist updated configurations to storage
### 5.2 Error Handling
| Error Condition | Detection Method | Response Action |
|----------------|------------------|-----------------|
| **Sensor Mismatch** | Type validation against MC | Reject sensor, log diagnostic event |
| **Communication Failure** | Timeout or protocol error | Mark sensor as faulty, continue with others |
| **Calibration Drift** | Value trend analysis | Flag for recalibration, continue operation |
| **MC Corruption** | Checksum validation | Use backup MC, request update from Main Hub |
| **Detection Hardware Failure** | GPIO or I2C failure | Disable detection, use last known configuration |
### 5.3 State-Dependent Behavior
| System State | Feature Behavior |
|-------------|------------------|
| **INIT** | Load MC, detect sensors, validate configuration |
| **RUNNING** | Continuous monitoring, failure detection, calibration |
| **WARNING** | Enhanced monitoring, diagnostic reporting |
| **FAULT** | Minimal operation, preserve sensor states |
| **MC_UPDATE** | Stop monitoring, update MC, re-detect sensors |
| **SERVICE** | Full diagnostic access, manual sensor control |
| **SD_DEGRADED** | Continue operation, no MC persistence |
## 6. Feature Constraints
### 6.1 Timing Constraints
- **Detection Cycle:** Maximum 5 seconds for complete sensor scan
- **Failure Detection:** Maximum 3 seconds to detect communication failure
- **MC Update:** Maximum 30 seconds for complete MC reload
- **Calibration Application:** Maximum 100ms per sensor
### 6.2 Resource Constraints
- **Memory Usage:** Maximum 8KB for MC data and sensor registry
- **Detection Frequency:** Maximum once per minute for presence scan
- **Calibration Storage:** Maximum 1KB per sensor for calibration data
- **Failure History:** Maximum 100 failure events in memory
### 6.3 Quality Constraints
- **Detection Accuracy:** 99.9% accurate sensor presence detection
- **Type Validation:** 100% prevention of incorrect sensor installation
- **Failure Detection:** 95% of failures detected within 10 seconds
- **Calibration Accuracy:** Within ±2% of reference standards
## 7. Interface Specifications
### 7.1 Machine Constant Manager API
```c
// Machine constants management
bool mcMgr_initialize(void);
bool mcMgr_loadMachineConstants(machine_constants_t* mc);
bool mcMgr_validateMachineConstants(const machine_constants_t* mc);
bool mcMgr_updateMachineConstants(const machine_constants_t* new_mc);
bool mcMgr_backupMachineConstants(void);
// Sensor configuration access
bool mcMgr_getSensorConfig(uint8_t sensor_id, sensor_config_t* config);
bool mcMgr_getCalibrationParams(uint8_t sensor_id, calibration_params_t* params);
bool mcMgr_validateSensorSlot(uint8_t slot_id, sensor_type_t sensor_type);
// System configuration
bool mcMgr_getSystemIdentity(system_identity_t* identity);
bool mcMgr_getCommunicationConfig(comm_config_t* config);
bool mcMgr_getSystemLimits(system_limits_t* limits);
```
### 7.2 Device Detector API
```c
// Detection operations
bool detector_initialize(void);
bool detector_scanSensors(detected_sensor_t* sensors, size_t* count);
bool detector_probeSensorType(uint8_t slot_id, sensor_type_info_t* info);
bool detector_validateSensorPresence(uint8_t slot_id);
// Hardware interface
bool detector_checkPresencePin(uint8_t slot_id);
bool detector_readDeviceID(uint8_t slot_id, device_id_t* id);
bool detector_testCommunication(uint8_t slot_id, comm_interface_t interface);
```
### 7.3 Calibration Manager API
```c
// Calibration operations
bool cal_initialize(void);
bool cal_applyCalibratio(uint8_t sensor_id, float raw_value, float* calibrated_value);
bool cal_updateCalibrationParams(uint8_t sensor_id, const calibration_params_t* params);
bool cal_validateCalibration(uint8_t sensor_id, validation_result_t* result);
// Calibration management
bool cal_scheduleRecalibration(uint8_t sensor_id, uint32_t interval_days);
bool cal_isCalibrationExpired(uint8_t sensor_id);
bool cal_getCalibrationStatus(uint8_t sensor_id, calibration_status_t* status);
```
## 8. Testing and Validation
### 8.1 Unit Testing
- **Detection Logic:** Mock hardware for detection algorithm testing
- **Validation Rules:** Sensor-slot compatibility matrix testing
- **Calibration Math:** Known input/output calibration validation
- **MC Management:** Configuration loading and validation testing
### 8.2 Integration Testing
- **Hardware Detection:** Real sensor hardware detection testing
- **Communication Interfaces:** I2C, UART, SPI sensor communication
- **Event Integration:** Detection and failure event publication
- **Persistence Integration:** MC storage and retrieval testing
### 8.3 System Testing
- **Multi-Sensor Detection:** All 7 sensor types simultaneously
- **Failure Scenarios:** Sensor disconnection and failure injection
- **MC Update Testing:** Complete configuration update scenarios
- **Long-Duration Testing:** 48-hour continuous monitoring
### 8.4 Acceptance Criteria
- All supported sensor types correctly detected and identified
- 100% prevention of incorrect sensor-slot configurations
- Failure detection within specified timing constraints
- Machine constants updates complete without data loss
- Calibration accuracy within specified tolerances
- No false positive or negative detection events
## 9. Dependencies
### 9.1 Internal Dependencies
- **Sensor Manager:** Sensor lifecycle and state management
- **Event System:** Detection and failure event communication
- **Data Persistence:** Machine constants and calibration storage
- **Diagnostics Task:** Failure logging and health reporting
### 9.2 External Dependencies
- **ESP-IDF Framework:** GPIO, I2C, UART, SPI drivers
- **Hardware Sensors:** Physical sensor devices and interfaces
- **Detection Hardware:** Presence pins and identification circuits
- **Main Hub:** Machine constants updates and calibration data
## 10. Future Enhancements
### 10.1 Planned Improvements
- **AI-Based Detection:** Machine learning for sensor identification
- **Predictive Calibration:** Drift prediction and automatic correction
- **Advanced Fusion:** Multi-sensor data fusion algorithms
- **Remote Calibration:** Over-the-air calibration updates
### 10.2 Scalability Considerations
- **Additional Sensor Types:** Framework supports easy extension
- **Enhanced Validation:** Multi-level validation mechanisms
- **Cloud Calibration:** Cloud-based calibration management
- **Sensor Networks:** Cross-hub sensor validation and fusion
---
**Document Status:** Final for Implementation Phase
**Component Dependencies:** Verified against architecture
**Requirements Traceability:** Complete (SR-DQC, SWR-DQC)
**Next Review:** After component implementation

650
system_arch_final/software/features/F-HW_Hardware_Abstraction.md Normal file
View File

@@ -0,0 +1,650 @@
# Feature Specification: Hardware Abstraction
# Feature ID: F-HW (F-HW-001 to F-HW-002)
**Document Type:** Feature Specification
**Version:** 1.0
**Date:** 2025-01-19
**Feature Category:** Hardware Abstraction
## 1. Feature Overview
### 1.1 Feature Purpose
The Hardware Abstraction feature provides a clean separation between application logic and hardware interfaces for the ASF Sensor Hub. This feature ensures hardware independence, maintainability, and testability by abstracting all hardware access through well-defined interfaces and preventing direct hardware access from the application layer.
### 1.2 Feature Scope
**In Scope:**
- Sensor Abstraction Layer (SAL) for uniform sensor access
- Hardware interface abstraction for I2C, SPI, UART, ADC, GPIO
- Storage interface abstraction for SD Card and NVM
- Display and user interface abstraction
- GPIO discipline enforcement and resource conflict detection
**Out of Scope:**
- Hardware driver implementation details (delegated to ESP-IDF)
- Hardware-specific performance optimizations
- Physical hardware design and pin assignments
- Low-level hardware debugging interfaces
## 2. Sub-Features
### 2.1 F-HW-001: Sensor Abstraction Layer (SAL)
**Description:** Comprehensive sensor abstraction layer providing uniform access to all sensor types while maintaining hardware independence and enabling runtime sensor management.
**Sensor Abstraction Interface:**
```c
typedef struct {
uint8_t sensor_id; // Unique sensor identifier
sensor_type_t type; // Sensor type enumeration
char name[32]; // Human-readable sensor name
char unit[8]; // Measurement unit (°C, %, ppm, etc.)
float min_value; // Minimum valid measurement
float max_value; // Maximum valid measurement
float accuracy; // Sensor accuracy specification
uint32_t warmup_time_ms; // Required warmup time
uint32_t sampling_interval_ms; // Minimum sampling interval
sensor_interface_t interface; // Hardware interface type
} sensor_metadata_t;
typedef enum {
SENSOR_TYPE_TEMPERATURE = 0, // Temperature sensors
SENSOR_TYPE_HUMIDITY = 1, // Humidity sensors
SENSOR_TYPE_CO2 = 2, // Carbon dioxide sensors
SENSOR_TYPE_AMMONIA = 3, // Ammonia sensors
SENSOR_TYPE_VOC = 4, // Volatile organic compounds
SENSOR_TYPE_LIGHT = 5, // Light intensity sensors
SENSOR_TYPE_PARTICULATE = 6 // Particulate matter sensors
} sensor_type_t;
typedef enum {
SENSOR_INTERFACE_I2C = 0, // I2C interface
SENSOR_INTERFACE_SPI = 1, // SPI interface
SENSOR_INTERFACE_UART = 2, // UART interface
SENSOR_INTERFACE_ADC = 3, // Analog ADC interface
SENSOR_INTERFACE_GPIO = 4 // Digital GPIO interface
} sensor_interface_t;
```
**Sensor State Management:**
```c
typedef enum {
SENSOR_STATE_UNKNOWN = 0, // Initial state, not detected
SENSOR_STATE_DETECTED = 1, // Presence confirmed
SENSOR_STATE_INITIALIZED = 2, // Driver loaded and configured
SENSOR_STATE_WARMUP = 3, // Warming up, not stable
SENSOR_STATE_STABLE = 4, // Operational and stable
SENSOR_STATE_ENABLED = 5, // Active data acquisition
SENSOR_STATE_DISABLED = 6, // Present but not acquiring
SENSOR_STATE_DEGRADED = 7, // Operational but degraded
SENSOR_STATE_FAULTY = 8, // Detected failure condition
SENSOR_STATE_REMOVED = 9 // Previously present, now absent
} sensor_state_t;
typedef struct {
sensor_state_t current_state; // Current sensor state
sensor_state_t previous_state; // Previous sensor state
uint64_t state_change_time; // Last state change timestamp
uint32_t state_change_count; // Total state changes
uint32_t fault_count; // Number of faults detected
uint32_t recovery_count; // Number of successful recoveries
float last_valid_reading; // Last known good reading
uint64_t last_reading_time; // Timestamp of last reading
} sensor_state_info_t;
```
**Sensor State Machine:**
```mermaid
stateDiagram-v2
[*] --> UNKNOWN
UNKNOWN --> DETECTED : Presence detected
DETECTED --> INITIALIZED : Driver loaded
INITIALIZED --> WARMUP : Acquisition started
WARMUP --> STABLE : Warmup complete
STABLE --> ENABLED : Enable command
ENABLED --> DISABLED : Disable command
DISABLED --> ENABLED : Enable command
ENABLED --> DEGRADED : Performance degradation
DEGRADED --> ENABLED : Performance restored
ENABLED --> FAULTY : Failure detected
DEGRADED --> FAULTY : Failure detected
FAULTY --> ENABLED : Recovery successful
FAULTY --> REMOVED : Hardware removed
ENABLED --> REMOVED : Hardware removed
DISABLED --> REMOVED : Hardware removed
DEGRADED --> REMOVED : Hardware removed
REMOVED --> DETECTED : Hardware restored
```
**Uniform Sensor API:**
```c
// Sensor lifecycle management
bool sal_initializeSensor(uint8_t sensor_id);
bool sal_enableSensor(uint8_t sensor_id);
bool sal_disableSensor(uint8_t sensor_id);
bool sal_resetSensor(uint8_t sensor_id);
// Sensor data operations
bool sal_readSensor(uint8_t sensor_id, float* value);
bool sal_calibrateSensor(uint8_t sensor_id, const calibration_data_t* cal_data);
bool sal_validateReading(uint8_t sensor_id, float value);
bool sal_performHealthCheck(uint8_t sensor_id);
// Sensor information and status
bool sal_getSensorMetadata(uint8_t sensor_id, sensor_metadata_t* metadata);
sensor_state_t sal_getSensorState(uint8_t sensor_id);
bool sal_getSensorStateInfo(uint8_t sensor_id, sensor_state_info_t* info);
bool sal_isSensorPresent(uint8_t sensor_id);
bool sal_isSensorHealthy(uint8_t sensor_id);
```
**Sensor Driver Interface:**
```c
typedef struct {
// Driver identification
char driver_name[32]; // Driver name
char driver_version[16]; // Driver version
sensor_type_t supported_type; // Supported sensor type
// Driver operations
bool (*initialize)(uint8_t sensor_id);
bool (*read_raw)(uint8_t sensor_id, uint32_t* raw_value);
bool (*convert_value)(uint32_t raw_value, float* converted_value);
bool (*calibrate)(uint8_t sensor_id, const calibration_data_t* cal_data);
bool (*health_check)(uint8_t sensor_id);
bool (*reset)(uint8_t sensor_id);
// Driver configuration
sensor_metadata_t metadata; // Sensor metadata
void* driver_config; // Driver-specific configuration
} sensor_driver_interface_t;
```
### 2.2 F-HW-002: Hardware Interface Abstraction
**Description:** Comprehensive abstraction of all hardware interfaces to prevent direct hardware access from the application layer and ensure consistent interface usage across the system.
**GPIO Discipline and Management:**
```c
typedef struct {
uint8_t gpio_number; // Physical GPIO pin number
gpio_function_t function; // Assigned function
gpio_direction_t direction; // Input/Output direction
gpio_pull_t pull_config; // Pull-up/Pull-down configuration
bool is_strapping_pin; // Strapping pin flag
bool is_reserved; // Reserved for system use
char assigned_component[32]; // Component using this GPIO
} gpio_pin_config_t;
typedef enum {
GPIO_FUNC_UNUSED = 0, // Pin not used
GPIO_FUNC_I2C_SDA = 1, // I2C data line
GPIO_FUNC_I2C_SCL = 2, // I2C clock line
GPIO_FUNC_SPI_MOSI = 3, // SPI master out, slave in
GPIO_FUNC_SPI_MISO = 4, // SPI master in, slave out
GPIO_FUNC_SPI_CLK = 5, // SPI clock
GPIO_FUNC_SPI_CS = 6, // SPI chip select
GPIO_FUNC_UART_TX = 7, // UART transmit
GPIO_FUNC_UART_RX = 8, // UART receive
GPIO_FUNC_ADC_INPUT = 9, // ADC analog input
GPIO_FUNC_DIGITAL_INPUT = 10, // Digital input
GPIO_FUNC_DIGITAL_OUTPUT = 11, // Digital output
GPIO_FUNC_PWM_OUTPUT = 12 // PWM output
} gpio_function_t;
// Strapping pins that must be avoided for general-purpose I/O
#define GPIO_STRAPPING_PINS {0, 3, 45, 46}
```
**I2C Interface Abstraction:**
```c
typedef struct {
uint8_t i2c_port; // I2C port number (0 or 1)
uint8_t sda_pin; // SDA pin assignment
uint8_t scl_pin; // SCL pin assignment
uint32_t frequency_hz; // I2C frequency (100kHz, 400kHz)
bool pullup_enabled; // Internal pull-up enable
uint32_t timeout_ms; // Transaction timeout
} i2c_config_t;
// I2C abstraction API
bool hw_i2c_initialize(uint8_t port, const i2c_config_t* config);
bool hw_i2c_write(uint8_t port, uint8_t device_addr, const uint8_t* data, size_t len);
bool hw_i2c_read(uint8_t port, uint8_t device_addr, uint8_t* data, size_t len);
bool hw_i2c_write_read(uint8_t port, uint8_t device_addr,
const uint8_t* write_data, size_t write_len,
uint8_t* read_data, size_t read_len);
bool hw_i2c_scan_devices(uint8_t port, uint8_t* found_devices, size_t* count);
```
**SPI Interface Abstraction:**
```c
typedef struct {
uint8_t spi_host; // SPI host (SPI2_HOST, SPI3_HOST)
uint8_t mosi_pin; // MOSI pin assignment
uint8_t miso_pin; // MISO pin assignment
uint8_t sclk_pin; // Clock pin assignment
uint8_t cs_pin; // Chip select pin
uint32_t frequency_hz; // SPI frequency
uint8_t mode; // SPI mode (0-3)
uint8_t bit_order; // MSB/LSB first
} spi_config_t;
// SPI abstraction API
bool hw_spi_initialize(uint8_t host, const spi_config_t* config);
bool hw_spi_transmit(uint8_t host, const uint8_t* tx_data, size_t len);
bool hw_spi_receive(uint8_t host, uint8_t* rx_data, size_t len);
bool hw_spi_transmit_receive(uint8_t host, const uint8_t* tx_data,
uint8_t* rx_data, size_t len);
```
**ADC Interface Abstraction:**
```c
typedef struct {
adc_unit_t adc_unit; // ADC1 or ADC2 (ADC1 only when Wi-Fi active)
adc_channel_t channel; // ADC channel
adc_atten_t attenuation; // Input attenuation
adc_bitwidth_t resolution; // ADC resolution
uint32_t sample_count; // Samples for averaging
} adc_config_t;
// ADC abstraction API
bool hw_adc_initialize(const adc_config_t* config);
bool hw_adc_read_raw(adc_unit_t unit, adc_channel_t channel, uint32_t* raw_value);
bool hw_adc_read_voltage(adc_unit_t unit, adc_channel_t channel, float* voltage);
bool hw_adc_calibrate(adc_unit_t unit, adc_channel_t channel);
```
**Storage Interface Abstraction:**
```c
// SD Card abstraction
typedef struct {
uint8_t mosi_pin; // SD card MOSI pin
uint8_t miso_pin; // SD card MISO pin
uint8_t clk_pin; // SD card clock pin
uint8_t cs_pin; // SD card chip select pin
uint32_t frequency_hz; // SD card SPI frequency
bool format_if_mount_failed; // Auto-format on mount failure
} sd_card_config_t;
bool hw_sd_initialize(const sd_card_config_t* config);
bool hw_sd_mount(const char* mount_point);
bool hw_sd_unmount(void);
bool hw_sd_get_info(sd_card_info_t* info);
// NVM (NVS) abstraction
bool hw_nvs_initialize(void);
bool hw_nvs_write_blob(const char* namespace, const char* key,
const void* data, size_t size);
bool hw_nvs_read_blob(const char* namespace, const char* key,
void* data, size_t* size);
bool hw_nvs_erase_key(const char* namespace, const char* key);
bool hw_nvs_get_stats(nvs_stats_t* stats);
```
**GPIO Map Management:**
```c
typedef struct {
gpio_pin_config_t pins[GPIO_NUM_MAX]; // All GPIO pin configurations
uint32_t used_pin_count; // Number of used pins
uint32_t conflict_count; // Number of detected conflicts
bool map_validated; // GPIO map validation status
} gpio_map_t;
// GPIO map management API
bool hw_gpio_initialize_map(void);
bool hw_gpio_reserve_pin(uint8_t gpio_num, gpio_function_t function,
const char* component_name);
bool hw_gpio_release_pin(uint8_t gpio_num);
bool hw_gpio_validate_map(void);
bool hw_gpio_detect_conflicts(gpio_conflict_t* conflicts, size_t* count);
bool hw_gpio_get_map(gpio_map_t* map);
```
**Hardware Resource Conflict Detection:**
```c
typedef enum {
HW_CONFLICT_GPIO_DUPLICATE = 0, // Same GPIO used by multiple components
HW_CONFLICT_I2C_ADDRESS = 1, // I2C address conflict
HW_CONFLICT_SPI_CS = 2, // SPI chip select conflict
HW_CONFLICT_ADC_WIFI = 3, // ADC2 used with Wi-Fi active
HW_CONFLICT_STRAPPING_PIN = 4, // Strapping pin used for I/O
HW_CONFLICT_POWER_DOMAIN = 5 // Power domain conflict
} hw_conflict_type_t;
typedef struct {
hw_conflict_type_t type; // Conflict type
uint8_t resource_id; // Conflicting resource ID
char component1[32]; // First component involved
char component2[32]; // Second component involved
char description[128]; // Human-readable description
} hw_conflict_t;
```
## 3. Requirements Coverage
### 3.1 System Requirements (SR-XXX)
| Feature | System Requirements | Description |
|---------|-------------------|-------------|
| **F-HW-001** | SR-HW-001, SR-HW-002, SR-HW-003, SR-HW-004 | Sensor abstraction layer and state management |
| **F-HW-002** | SR-HW-005, SR-HW-006, SR-HW-007, SR-HW-008 | Hardware interface abstraction and GPIO discipline |
### 3.2 Software Requirements (SWR-XXX)
| Feature | Software Requirements | Implementation Details |
|---------|---------------------|----------------------|
| **F-HW-001** | SWR-HW-001, SWR-HW-002, SWR-HW-003 | SAL interface, sensor drivers, state machine |
| **F-HW-002** | SWR-HW-004, SWR-HW-005, SWR-HW-006 | Interface abstraction, GPIO management, conflict detection |
## 4. Component Implementation Mapping
### 4.1 Primary Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| **Sensor Abstraction Layer** | Uniform sensor interface, state management | `drivers/sensor_abstraction/` |
| **Hardware Interface Manager** | Interface abstraction, resource management | `drivers/hw_interface_mgr/` |
| **GPIO Manager** | GPIO discipline, conflict detection | `drivers/gpio_manager/` |
| **Sensor Drivers** | Hardware-specific sensor implementations | `drivers/sensors/` |
### 4.2 Supporting Components
| Component | Support Role | Interface |
|-----------|-------------|-----------|
| **ESP-IDF Wrappers** | Low-level hardware access | `ESP_IDF_FW_wrappers/` |
| **Diagnostics** | Hardware fault reporting | `application_layer/diag_task/` |
| **Machine Constant Manager** | Hardware configuration management | `application_layer/business_stack/machine_constant_manager/` |
### 4.3 Component Interaction Diagram
```mermaid
graph TB
subgraph "Hardware Abstraction Feature"
SAL[Sensor Abstraction Layer]
HW_MGR[Hardware Interface Manager]
GPIO_MGR[GPIO Manager]
SENSOR_DRV[Sensor Drivers]
end
subgraph "Application Layer"
SENSOR_MGR[Sensor Manager]
PERSIST[Persistence]
DIAG[Diagnostics]
end
subgraph "ESP-IDF Wrappers"
I2C_WRAP[I2C Wrapper]
SPI_WRAP[SPI Wrapper]
UART_WRAP[UART Wrapper]
ADC_WRAP[ADC Wrapper]
GPIO_WRAP[GPIO Wrapper]
end
subgraph "Physical Hardware"
SENSORS[Physical Sensors]
SD_CARD[SD Card]
OLED[OLED Display]
BUTTONS[Buttons]
end
SENSOR_MGR --> SAL
SAL --> SENSOR_DRV
SENSOR_DRV --> HW_MGR
HW_MGR --> I2C_WRAP
HW_MGR --> SPI_WRAP
HW_MGR --> UART_WRAP
HW_MGR --> ADC_WRAP
GPIO_MGR --> GPIO_WRAP
I2C_WRAP --> SENSORS
SPI_WRAP --> SD_CARD
UART_WRAP --> SENSORS
ADC_WRAP --> SENSORS
GPIO_WRAP --> BUTTONS
GPIO_WRAP --> OLED
SAL -.->|Hardware Events| DIAG
HW_MGR -.->|Resource Conflicts| DIAG
```
### 4.4 Sensor Abstraction Flow
```mermaid
sequenceDiagram
participant APP as Application
participant SAL as Sensor Abstraction Layer
participant DRV as Sensor Driver
participant HW as Hardware Interface
participant SENSOR as Physical Sensor
Note over APP,SENSOR: Sensor Access Through Abstraction
APP->>SAL: sal_readSensor(sensor_id)
SAL->>SAL: validateSensorState(sensor_id)
alt Sensor State Valid
SAL->>DRV: driver_read_raw(sensor_id)
DRV->>HW: hw_i2c_read(port, addr, data)
HW->>SENSOR: I2C transaction
SENSOR-->>HW: sensor_data
HW-->>DRV: raw_value
DRV->>DRV: convert_value(raw_value)
DRV-->>SAL: converted_value
SAL->>SAL: validateReading(converted_value)
SAL-->>APP: sensor_reading
else Sensor State Invalid
SAL->>SAL: attemptSensorRecovery(sensor_id)
SAL-->>APP: error_sensor_not_ready
end
```
## 5. Feature Behavior
### 5.1 Normal Operation Flow
1. **System Initialization:**
- Initialize GPIO map and validate pin assignments
- Detect hardware resource conflicts and report violations
- Initialize hardware interface abstractions (I2C, SPI, UART, ADC)
- Scan for connected sensors and initialize sensor drivers
- Establish sensor abstraction layer and state management
2. **Sensor Management:**
- Maintain sensor state machine for all detected sensors
- Provide uniform access interface regardless of hardware interface
- Handle sensor failures and recovery attempts
- Monitor sensor health and performance metrics
3. **Hardware Interface Management:**
- Enforce GPIO discipline and prevent strapping pin usage
- Manage shared resources and prevent conflicts
- Provide consistent interface abstraction across all hardware types
- Monitor interface health and detect hardware failures
4. **Resource Conflict Prevention:**
- Validate GPIO assignments during initialization
- Detect and report hardware resource conflicts
- Enforce ADC1/ADC2 separation when Wi-Fi is active
- Maintain canonical GPIO map as single source of truth
### 5.2 Error Handling
| Error Condition | Detection Method | Response Action |
|----------------|------------------|-----------------|
| **GPIO Conflict** | Pin assignment validation | Report conflict, prevent initialization |
| **Sensor Communication Failure** | Interface timeout/error | Mark sensor as faulty, attempt recovery |
| **Hardware Interface Failure** | Transaction failure | Report hardware fault, disable interface |
| **Strapping Pin Usage** | GPIO map validation | Prevent usage, report configuration error |
| **ADC2/Wi-Fi Conflict** | Resource validation | Force ADC1 usage, report conflict |
| **I2C Address Conflict** | Device scanning | Report conflict, disable conflicting devices |
### 5.3 State-Dependent Behavior
| System State | Feature Behavior |
|-------------|------------------|
| **INIT** | Initialize hardware abstractions, detect sensors |
| **RUNNING** | Full hardware abstraction, continuous sensor monitoring |
| **WARNING** | Enhanced hardware monitoring, sensor health checks |
| **FAULT** | Critical hardware functions only, preserve sensor states |
| **OTA_UPDATE** | Maintain hardware state, suspend sensor operations |
| **TEARDOWN** | Graceful hardware shutdown, preserve configurations |
| **SERVICE** | Limited hardware access for diagnostics |
| **SD_DEGRADED** | Continue sensor operations, report storage degradation |
## 6. Feature Constraints
### 6.1 Timing Constraints
- **Sensor State Transitions:** Maximum 100ms for state changes
- **Hardware Interface Operations:** Bounded timeouts for all transactions
- **GPIO Conflict Detection:** Complete during system initialization
- **Sensor Recovery Attempts:** Maximum 3 attempts with exponential backoff
### 6.2 Resource Constraints
- **GPIO Usage:** Enforce strapping pin restrictions and conflict prevention
- **I2C Pull-ups:** Physical pull-ups required (2.2kΩ - 4.7kΩ for 3.3V)
- **ADC Constraints:** ADC1 only when Wi-Fi active, ADC2 when Wi-Fi inactive
- **Memory Usage:** Maximum 32KB for abstraction layer buffers and state
### 6.3 Hardware Constraints
- **ESP32-S3 Limitations:** Respect hardware capabilities and restrictions
- **Interface Speeds:** I2C up to 400kHz, SPI up to 80MHz
- **Voltage Levels:** 3.3V logic levels for all interfaces
- **Current Limitations:** Respect GPIO current drive capabilities
## 7. Interface Specifications
### 7.1 Sensor Abstraction Layer API
```c
// SAL initialization and management
bool sal_initialize(void);
bool sal_detectSensors(void);
bool sal_getSensorCount(uint8_t* count);
bool sal_getSensorList(uint8_t* sensor_ids, size_t* count);
// Sensor operations
bool sal_readSensor(uint8_t sensor_id, float* value);
bool sal_readMultipleSensors(uint8_t* sensor_ids, size_t count,
sensor_reading_t* readings);
bool sal_calibrateSensor(uint8_t sensor_id, const calibration_data_t* cal_data);
bool sal_resetSensor(uint8_t sensor_id);
// Sensor state and health
sensor_state_t sal_getSensorState(uint8_t sensor_id);
bool sal_getSensorHealth(uint8_t sensor_id, sensor_health_t* health);
bool sal_performSensorDiagnostics(uint8_t sensor_id, sensor_diagnostics_t* diag);
```
### 7.2 Hardware Interface Manager API
```c
// Interface initialization
bool hwMgr_initialize(void);
bool hwMgr_initializeI2C(uint8_t port, const i2c_config_t* config);
bool hwMgr_initializeSPI(uint8_t host, const spi_config_t* config);
bool hwMgr_initializeUART(uint8_t port, const uart_config_t* config);
bool hwMgr_initializeADC(const adc_config_t* config);
// Resource management
bool hwMgr_reserveResource(hw_resource_type_t type, uint8_t resource_id,
const char* component_name);
bool hwMgr_releaseResource(hw_resource_type_t type, uint8_t resource_id);
bool hwMgr_validateResources(void);
bool hwMgr_getResourceConflicts(hw_conflict_t* conflicts, size_t* count);
```
### 7.3 GPIO Manager API
```c
// GPIO management
bool gpioMgr_initialize(void);
bool gpioMgr_reservePin(uint8_t gpio_num, gpio_function_t function,
const char* component_name);
bool gpioMgr_releasePin(uint8_t gpio_num);
bool gpioMgr_configurePin(uint8_t gpio_num, const gpio_config_t* config);
// GPIO validation and conflict detection
bool gpioMgr_validateGPIOMap(void);
bool gpioMgr_isStrappingPin(uint8_t gpio_num);
bool gpioMgr_detectConflicts(gpio_conflict_t* conflicts, size_t* count);
bool gpioMgr_getGPIOMap(gpio_map_t* map);
```
## 8. Testing and Validation
### 8.1 Unit Testing
- **Sensor Abstraction:** All sensor types and state transitions
- **Interface Abstraction:** I2C, SPI, UART, ADC operations
- **GPIO Management:** Pin assignment and conflict detection
- **Resource Management:** Resource allocation and validation
### 8.2 Integration Testing
- **Cross-Interface Testing:** Multiple interfaces operating simultaneously
- **Sensor Integration:** All sensor types through abstraction layer
- **Resource Conflict Testing:** Deliberate conflict scenarios
- **State Coordination:** Hardware abstraction with system states
### 8.3 System Testing
- **Hardware Compatibility:** All supported sensor hardware configurations
- **Performance Testing:** Interface throughput and timing constraints
- **Fault Injection:** Hardware failure simulation and recovery
- **Long-Duration Testing:** Extended operation with hardware monitoring
### 8.4 Acceptance Criteria
- All sensor types accessible through uniform SAL interface
- Hardware interfaces properly abstracted from application layer
- GPIO conflicts detected and prevented during initialization
- No direct hardware access from application components
- Sensor state management operates correctly under all conditions
- Hardware resource conflicts properly detected and reported
- Complete hardware abstraction maintains system performance
## 9. Dependencies
### 9.1 Internal Dependencies
- **Sensor Manager:** Primary consumer of sensor abstraction layer
- **Diagnostics:** Hardware fault reporting and event logging
- **Machine Constant Manager:** Hardware configuration management
- **State Manager:** Hardware behavior coordination across system states
### 9.2 External Dependencies
- **ESP-IDF Framework:** Low-level hardware drivers and HAL
- **Hardware Components:** Physical sensors, interfaces, and peripherals
- **FreeRTOS:** Task coordination and resource management
- **Hardware Design:** GPIO assignments and interface configurations
## 10. Future Enhancements
### 10.1 Planned Improvements
- **Dynamic Sensor Discovery:** Runtime sensor detection and configuration
- **Advanced Sensor Fusion:** Multi-sensor data correlation and validation
- **Hardware Health Monitoring:** Predictive hardware failure detection
- **Plug-and-Play Support:** Hot-swappable sensor support
### 10.2 Scalability Considerations
- **Additional Sensor Types:** Framework supports easy sensor type extension
- **Multiple Interface Support:** Support for additional hardware interfaces
- **Advanced GPIO Management:** Dynamic GPIO allocation and optimization
- **Hardware Virtualization:** Virtual hardware interfaces for testing
---
**Document Status:** Final for Implementation Phase
**Component Dependencies:** Verified against architecture
**Requirements Traceability:** Complete (SR-HW, SWR-HW)
**Next Review:** After component implementation

749
system_arch_final/software/features/F-OTA_Firmware_Update.md Normal file
View File

@@ -0,0 +1,749 @@
# Feature Specification: Firmware Update (OTA)
# Feature ID: F-OTA (F-OTA-001 to F-OTA-005)
**Document Type:** Feature Specification
**Version:** 1.0
**Date:** 2025-01-19
**Feature Category:** Firmware Update (OTA)
## 1. Feature Overview
### 1.1 Feature Purpose
The Firmware Update (OTA) feature provides secure, reliable over-the-air firmware update capabilities for the ASF Sensor Hub. This feature enables controlled firmware lifecycle management, ensuring system availability, data integrity, and fault containment during firmware update operations.
### 1.2 Feature Scope
**In Scope:**
- OTA negotiation and readiness validation with Main Hub
- Secure firmware reception over encrypted communication channels
- Firmware integrity validation using cryptographic verification
- Safe firmware activation with A/B partitioning and automatic rollback
- Controlled system teardown and data preservation during updates
**Out of Scope:**
- Firmware generation and cryptographic signing infrastructure
- Cloud-side firmware distribution and management
- Main Hub OTA coordination logic
- Hardware-level secure boot implementation (dependency)
## 2. Sub-Features
### 2.1 F-OTA-001: OTA Update Negotiation
**Description:** Comprehensive negotiation phase between Sensor Hub and Main Hub to establish OTA readiness and coordinate update initiation.
**Readiness Validation Criteria:**
```c
typedef struct {
system_state_t current_state; // Must be RUNNING
bool power_stable; // Power supply stable
bool storage_available; // SD card accessible with sufficient space
bool communication_stable; // Network connection stable
uint32_t free_sd_space_mb; // Available SD card space
uint32_t free_nvs_entries; // Available NVS entries
float supply_voltage; // Current supply voltage
uint32_t uptime_seconds; // System uptime for stability
} ota_readiness_t;
typedef enum {
OTA_READY_ACCEPT = 0, // System ready for OTA
OTA_READY_REJECT_STATE = 1, // Invalid system state
OTA_READY_REJECT_POWER = 2, // Power instability
OTA_READY_REJECT_STORAGE = 3, // Storage unavailable
OTA_READY_REJECT_COMM = 4, // Communication unstable
OTA_READY_REJECT_RESOURCES = 5 // Insufficient resources
} ota_readiness_result_t;
```
**Negotiation Sequence:**
```mermaid
sequenceDiagram
participant MH as Main Hub
participant API as Main Hub APIs
participant OTA as OTA Manager
participant STM as State Manager
participant DIAG as Diagnostics
MH->>API: OTA_AVAILABILITY_NOTIFICATION
API->>OTA: otaAvailabilityReceived(metadata)
OTA->>OTA: validateSystemReadiness()
alt System Ready
OTA->>STM: requestStateTransition(OTA_PREP)
STM->>STM: validateTransition()
STM-->>OTA: transitionAccepted()
OTA->>API: otaResponse(ACCEPT, readiness_info)
API->>MH: OTA_NEGOTIATION_RESPONSE(ACCEPT)
else System Not Ready
OTA->>DIAG: logDiagnosticEvent(OTA_REJECTED, reason)
OTA->>API: otaResponse(REJECT, rejection_reason)
API->>MH: OTA_NEGOTIATION_RESPONSE(REJECT)
end
```
**Readiness Validation Logic:**
- **System State Check:** Must be in RUNNING state (not WARNING/FAULT/SERVICE/SD_DEGRADED)
- **Power Stability:** Supply voltage within 3.0V-3.6V range for >30 seconds
- **Storage Availability:** SD card accessible with >100MB free space
- **Communication Stability:** Network connection stable for >60 seconds
- **Resource Availability:** Sufficient NVS entries and heap memory
### 2.2 F-OTA-002: Firmware Reception and Storage
**Description:** Secure reception of firmware image from Main Hub with chunked download, progress monitoring, and temporary storage management.
**Download Configuration:**
```c
typedef struct {
uint32_t chunk_size; // 4096 bytes (optimized for flash page)
uint32_t total_size; // Total firmware size
uint32_t total_chunks; // Number of chunks
char firmware_version[32]; // Target firmware version
uint8_t sha256_hash[32]; // Expected SHA-256 hash
uint32_t timeout_seconds; // Download timeout (600 seconds)
} ota_download_config_t;
typedef struct {
uint32_t chunks_received; // Number of chunks received
uint32_t bytes_received; // Total bytes received
uint32_t chunks_failed; // Failed chunk count
uint32_t retries_performed; // Retry attempts
uint64_t start_time_ms; // Download start timestamp
uint64_t last_chunk_time_ms; // Last chunk received timestamp
ota_download_state_t state; // Current download state
} ota_download_progress_t;
typedef enum {
OTA_DOWNLOAD_IDLE = 0,
OTA_DOWNLOAD_ACTIVE = 1,
OTA_DOWNLOAD_PAUSED = 2,
OTA_DOWNLOAD_COMPLETE = 3,
OTA_DOWNLOAD_FAILED = 4,
OTA_DOWNLOAD_TIMEOUT = 5
} ota_download_state_t;
```
**Storage Management:**
- **Temporary Storage:** SD card path `/ota/firmware_temp.bin`
- **Chunk Verification:** Per-chunk CRC32 validation
- **Progress Persistence:** Download state persisted to NVS for recovery
- **Timeout Handling:** 10-minute maximum download duration
- **Retry Logic:** Up to 3 retries per failed chunk
**Download Flow:**
```mermaid
sequenceDiagram
participant MH as Main Hub
participant NET as Network Stack
participant OTA as OTA Manager
participant SD as SD Card Storage
participant NVS as NVS Storage
Note over MH,NVS: Firmware Download Phase
MH->>NET: firmwareChunk(chunk_id, data, crc32)
NET->>OTA: chunkReceived(chunk_id, data, crc32)
OTA->>OTA: validateChunkCRC(data, crc32)
alt CRC Valid
OTA->>SD: writeChunk(chunk_id, data)
SD-->>OTA: writeComplete()
OTA->>NVS: updateProgress(chunks_received++)
OTA->>NET: chunkAck(chunk_id, SUCCESS)
NET->>MH: CHUNK_ACK(chunk_id, SUCCESS)
else CRC Invalid
OTA->>NET: chunkAck(chunk_id, RETRY)
NET->>MH: CHUNK_ACK(chunk_id, RETRY)
end
OTA->>OTA: checkDownloadComplete()
alt All Chunks Received
OTA->>OTA: transitionToValidation()
end
```
### 2.3 F-OTA-003: Firmware Integrity Validation
**Description:** Comprehensive firmware integrity and authenticity validation using cryptographic verification before activation.
**Validation Methods:**
```c
typedef struct {
bool size_valid; // Firmware size matches metadata
bool sha256_valid; // SHA-256 hash verification
bool signature_valid; // Digital signature verification (if available)
bool partition_valid; // Partition table validation
bool version_valid; // Version number validation
bool compatibility_valid; // Hardware compatibility check
} ota_validation_result_t;
typedef enum {
OTA_VALIDATION_PENDING = 0,
OTA_VALIDATION_IN_PROGRESS = 1,
OTA_VALIDATION_SUCCESS = 2,
OTA_VALIDATION_FAILED_SIZE = 3,
OTA_VALIDATION_FAILED_HASH = 4,
OTA_VALIDATION_FAILED_SIGNATURE = 5,
OTA_VALIDATION_FAILED_PARTITION = 6,
OTA_VALIDATION_FAILED_VERSION = 7,
OTA_VALIDATION_FAILED_COMPATIBILITY = 8
} ota_validation_status_t;
```
**Validation Sequence:**
1. **Size Validation:** Verify received firmware size matches metadata
2. **SHA-256 Verification:** Calculate and compare full image hash
3. **Partition Table Validation:** Verify partition structure compatibility
4. **Version Validation:** Ensure version progression (anti-rollback)
5. **Hardware Compatibility:** Verify target platform compatibility
**Validation Flow:**
```mermaid
sequenceDiagram
participant OTA as OTA Manager
participant SD as SD Card Storage
participant SEC as Security Manager
participant DIAG as Diagnostics
participant API as Main Hub APIs
Note over OTA,API: Firmware Validation Phase
OTA->>SD: readFirmwareImage()
SD-->>OTA: firmware_data
OTA->>OTA: validateSize(firmware_data)
alt Size Valid
OTA->>SEC: calculateSHA256(firmware_data)
SEC-->>OTA: calculated_hash
OTA->>OTA: compareSHA256(calculated_hash, expected_hash)
alt Hash Valid
OTA->>SEC: validateSignature(firmware_data)
SEC-->>OTA: signature_result
alt Signature Valid
OTA->>OTA: validatePartitionTable(firmware_data)
OTA->>OTA: validateVersion(firmware_data)
OTA->>OTA: validateCompatibility(firmware_data)
OTA->>API: validationComplete(SUCCESS)
else Signature Invalid
OTA->>DIAG: logDiagnosticEvent(OTA_VALIDATION_FAILED)
OTA->>API: validationComplete(FAILED_SIGNATURE)
end
else Hash Invalid
OTA->>DIAG: logDiagnosticEvent(OTA_HASH_MISMATCH)
OTA->>API: validationComplete(FAILED_HASH)
end
else Size Invalid
OTA->>DIAG: logDiagnosticEvent(OTA_SIZE_MISMATCH)
OTA->>API: validationComplete(FAILED_SIZE)
end
```
### 2.4 F-OTA-004: Safe Firmware Activation
**Description:** Controlled firmware activation with system teardown, data preservation, and safe transition to new firmware.
**Activation Sequence:**
```c
typedef enum {
OTA_ACTIVATION_IDLE = 0,
OTA_ACTIVATION_TEARDOWN = 1,
OTA_ACTIVATION_DATA_FLUSH = 2,
OTA_ACTIVATION_FLASHING = 3,
OTA_ACTIVATION_PARTITION_UPDATE = 4,
OTA_ACTIVATION_REBOOT = 5,
OTA_ACTIVATION_COMPLETE = 6,
OTA_ACTIVATION_FAILED = 7
} ota_activation_state_t;
typedef struct {
bool sensor_data_flushed; // Latest sensor data preserved
bool diagnostics_flushed; // Diagnostic events preserved
bool machine_constants_flushed; // Machine constants preserved
bool calibration_data_flushed; // Calibration data preserved
bool system_state_flushed; // System state preserved
} ota_data_flush_status_t;
```
**Activation Flow:**
```mermaid
sequenceDiagram
participant OTA as OTA Manager
participant STM as State Manager
participant PERSIST as Persistence
participant FLASH as Flash Manager
participant BOOT as Boot Manager
Note over OTA,BOOT: Firmware Activation Phase
OTA->>STM: requestStateTransition(TEARDOWN)
STM->>STM: initiateTeardown()
STM->>PERSIST: flushCriticalData()
PERSIST->>PERSIST: flushSensorData()
PERSIST->>PERSIST: flushDiagnostics()
PERSIST->>PERSIST: flushMachineConstants()
PERSIST->>PERSIST: flushCalibrationData()
PERSIST-->>STM: flushComplete()
STM->>OTA: teardownComplete()
OTA->>STM: requestStateTransition(OTA_UPDATE)
OTA->>FLASH: flashFirmwareToInactivePartition()
FLASH-->>OTA: flashingComplete()
OTA->>BOOT: updatePartitionTable()
BOOT-->>OTA: partitionTableUpdated()
OTA->>STM: systemReboot()
```
**Data Preservation Priority:**
1. **Critical System Data:** Machine constants, calibration data
2. **Diagnostic Data:** Recent diagnostic events and system health
3. **Sensor Data:** Latest sensor readings and statistics
4. **System State:** Current system state and configuration
### 2.5 F-OTA-005: A/B Partitioning with Rollback
**Description:** A/B partitioning implementation with automatic rollback capability for safe firmware updates.
**Partition Management:**
```c
typedef enum {
OTA_PARTITION_A = 0, // Primary partition (ota_0)
OTA_PARTITION_B = 1, // Secondary partition (ota_1)
OTA_PARTITION_FACTORY = 2 // Factory partition (rescue)
} ota_partition_t;
typedef struct {
ota_partition_t active_partition; // Currently running partition
ota_partition_t inactive_partition; // Target for next update
char active_version[32]; // Version of active firmware
char inactive_version[32]; // Version of inactive firmware
uint32_t boot_count; // Boot attempts since activation
uint64_t activation_time; // Activation timestamp
bool rollback_pending; // Rollback flag
} ota_partition_status_t;
```
**Rollback Triggers:**
- **Boot Failure:** System fails to boot within 60 seconds
- **Health Check Failure:** No health report within 120 seconds after boot
- **Application Crash:** Critical application failure during confirmation period
- **Manual Rollback:** Explicit rollback command from Main Hub
**Rollback Flow:**
```mermaid
sequenceDiagram
participant BOOT as Boot Manager
participant APP as Application
participant HEALTH as Health Monitor
participant OTA as OTA Manager
participant DIAG as Diagnostics
Note over BOOT,DIAG: Firmware Rollback Scenario
BOOT->>APP: startApplication()
alt Boot Successful
APP->>HEALTH: startHealthMonitoring()
HEALTH->>HEALTH: waitForConfirmationWindow(120s)
alt Health Report Received
HEALTH->>OTA: confirmFirmwareStability()
OTA->>OTA: markFirmwareAsValid()
else No Health Report
HEALTH->>OTA: firmwareValidationTimeout()
OTA->>OTA: triggerRollback(HEALTH_TIMEOUT)
end
else Boot Failed
BOOT->>OTA: bootFailureDetected()
OTA->>OTA: triggerRollback(BOOT_FAILURE)
end
alt Rollback Triggered
OTA->>BOOT: switchToInactivePartition()
OTA->>DIAG: logDiagnosticEvent(FIRMWARE_ROLLBACK)
OTA->>BOOT: systemReboot()
end
```
**Rollback Process:**
1. **Failure Detection:** Detect rollback trigger condition
2. **Partition Switch:** Update partition table to boot from previous partition
3. **Diagnostic Logging:** Record rollback event and reason
4. **System Reboot:** Restart system with previous firmware
5. **Rollback Notification:** Report rollback to Main Hub after recovery
## 3. Requirements Coverage
### 3.1 System Requirements (SR-XXX)
| Feature | System Requirements | Description |
|---------|-------------------|-------------|
| **F-OTA-001** | SR-OTA-001, SR-OTA-002, SR-OTA-003 | OTA negotiation and readiness validation |
| **F-OTA-002** | SR-OTA-004, SR-OTA-005, SR-OTA-006 | Firmware reception and temporary storage |
| **F-OTA-003** | SR-OTA-007, SR-OTA-008, SR-OTA-009 | Firmware integrity and authenticity validation |
| **F-OTA-004** | SR-OTA-010, SR-OTA-011, SR-OTA-012, SR-OTA-013 | Safe firmware activation and data preservation |
| **F-OTA-005** | SR-OTA-014, SR-OTA-015, SR-OTA-016 | A/B partitioning and automatic rollback |
### 3.2 Software Requirements (SWR-XXX)
| Feature | Software Requirements | Implementation Details |
|---------|---------------------|----------------------|
| **F-OTA-001** | SWR-OTA-001, SWR-OTA-002, SWR-OTA-003 | Readiness validation, negotiation protocol, state coordination |
| **F-OTA-002** | SWR-OTA-004, SWR-OTA-005, SWR-OTA-006 | Chunked download, progress tracking, storage management |
| **F-OTA-003** | SWR-OTA-007, SWR-OTA-008, SWR-OTA-009 | SHA-256 validation, signature verification, compatibility checks |
| **F-OTA-004** | SWR-OTA-010, SWR-OTA-011, SWR-OTA-012 | Teardown coordination, data flush, firmware flashing |
| **F-OTA-005** | SWR-OTA-013, SWR-OTA-014, SWR-OTA-015 | Partition management, rollback detection, recovery procedures |
## 4. Component Implementation Mapping
### 4.1 Primary Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| **OTA Manager** | OTA coordination, validation, activation | `application_layer/business_stack/fw_upgrader/` |
| **State Manager** | System state coordination, teardown management | `application_layer/business_stack/STM/` |
| **Persistence** | Data flush, firmware storage | `application_layer/DP_stack/persistence/` |
| **Security Manager** | Cryptographic validation, signature verification | `application_layer/security/` |
### 4.2 Supporting Components
| Component | Support Role | Interface |
|-----------|-------------|-----------|
| **Main Hub APIs** | OTA communication protocol, message handling | `application_layer/business_stack/main_hub_apis/` |
| **Network Stack** | Secure firmware download transport | `drivers/network_stack/` |
| **SD Card Driver** | Temporary firmware storage | `drivers/SDcard/` |
| **NVM Driver** | Progress persistence, partition management | `drivers/nvm/` |
| **Diagnostics** | OTA event logging, failure reporting | `application_layer/diag_task/` |
### 4.3 Component Interaction Diagram
```mermaid
graph TB
subgraph "OTA Firmware Update Feature"
OTA[OTA Manager]
STM[State Manager]
PERSIST[Persistence]
SEC[Security Manager]
end
subgraph "Communication Components"
API[Main Hub APIs]
NET[Network Stack]
end
subgraph "Storage Components"
SD[SD Card Driver]
NVM[NVM Driver]
end
subgraph "System Components"
DIAG[Diagnostics]
BOOT[Boot Manager]
HEALTH[Health Monitor]
end
subgraph "External Interfaces"
MH[Main Hub]
FLASH[Flash Memory]
PART[Partition Table]
end
MH <-->|OTA Protocol| API
API <--> OTA
OTA <--> STM
OTA <--> PERSIST
OTA <--> SEC
OTA --> NET
NET -->|Firmware Download| MH
PERSIST --> SD
PERSIST --> NVM
OTA --> DIAG
OTA --> BOOT
OTA --> HEALTH
BOOT --> FLASH
BOOT --> PART
STM -.->|State Events| DIAG
SEC -.->|Validation Events| DIAG
```
### 4.4 OTA Update Sequence
```mermaid
sequenceDiagram
participant MH as Main Hub
participant API as Main Hub APIs
participant OTA as OTA Manager
participant STM as State Manager
participant PERSIST as Persistence
participant SEC as Security Manager
participant BOOT as Boot Manager
Note over MH,BOOT: Complete OTA Update Flow
MH->>API: OTA_AVAILABILITY_NOTIFICATION
API->>OTA: otaAvailabilityReceived()
OTA->>OTA: validateReadiness()
OTA->>STM: requestStateTransition(OTA_PREP)
OTA->>API: otaResponse(ACCEPT)
loop Firmware Download
MH->>API: firmwareChunk(data)
API->>OTA: chunkReceived(data)
OTA->>PERSIST: storeChunk(data)
end
OTA->>SEC: validateFirmware()
SEC-->>OTA: validationResult(SUCCESS)
OTA->>STM: requestStateTransition(TEARDOWN)
STM->>PERSIST: flushCriticalData()
PERSIST-->>STM: flushComplete()
OTA->>BOOT: flashFirmwareToInactivePartition()
OTA->>BOOT: updatePartitionTable()
OTA->>STM: systemReboot()
Note over MH,BOOT: System Reboots with New Firmware
BOOT->>BOOT: bootFromNewPartition()
BOOT->>OTA: firmwareActivated()
OTA->>API: otaStatus(ACTIVATION_SUCCESS)
API->>MH: OTA_STATUS_REPORT(SUCCESS)
```
## 5. Feature Behavior
### 5.1 Normal Operation Flow
1. **OTA Availability Phase:**
- Receive OTA availability notification from Main Hub
- Validate system readiness (state, power, storage, communication)
- Negotiate OTA acceptance or rejection with detailed reasons
- Transition to OTA_PREP state if accepted
2. **Firmware Download Phase:**
- Receive firmware in 4KB chunks over secure channel
- Validate each chunk with CRC32 verification
- Store chunks to SD card temporary location
- Track download progress and handle retries
- Enforce 10-minute download timeout
3. **Validation Phase:**
- Perform comprehensive firmware integrity validation
- Verify SHA-256 hash, digital signature, and compatibility
- Report validation results to Main Hub
- Proceed to activation only if all validations pass
4. **Activation Phase:**
- Coordinate system teardown with State Manager
- Flush all critical data to persistent storage
- Flash validated firmware to inactive partition
- Update partition table for next boot
- Perform controlled system reboot
5. **Confirmation Phase:**
- Boot with new firmware and start health monitoring
- Confirm firmware stability within 120-second window
- Mark firmware as valid or trigger automatic rollback
- Report final OTA status to Main Hub
### 5.2 Error Handling
| Error Condition | Detection Method | Response Action |
|----------------|------------------|-----------------|
| **System Not Ready** | Readiness validation failure | Reject OTA request, report specific reason |
| **Download Timeout** | 10-minute timeout exceeded | Abort download, clean up temporary files |
| **Chunk Corruption** | CRC32 validation failure | Request chunk retransmission (up to 3 retries) |
| **Validation Failure** | Integrity check failure | Abort OTA, report validation error |
| **Flash Failure** | Firmware flashing error | Abort OTA, maintain current firmware |
| **Boot Failure** | New firmware boot failure | Automatic rollback to previous firmware |
| **Health Check Failure** | No health report within window | Automatic rollback to previous firmware |
### 5.3 State-Dependent Behavior
| System State | Feature Behavior |
|-------------|------------------|
| **INIT** | OTA Manager initialization, partition status check |
| **RUNNING** | Accept OTA requests, perform readiness validation |
| **WARNING** | Reject OTA requests (system not stable) |
| **FAULT** | Reject OTA requests (system in fault state) |
| **OTA_PREP** | Prepare for OTA, coordinate with other components |
| **OTA_UPDATE** | Execute OTA download, validation, and activation |
| **TEARDOWN** | Coordinate data flush before firmware activation |
| **SERVICE** | Reject OTA requests (maintenance mode) |
| **SD_DEGRADED** | Reject OTA requests (storage unavailable) |
## 6. Feature Constraints
### 6.1 Timing Constraints
- **Negotiation Response:** Maximum 5 seconds for readiness validation
- **Download Timeout:** Maximum 10 minutes for complete firmware download
- **Validation Time:** Maximum 2 minutes for integrity validation
- **Activation Time:** Maximum 5 minutes for firmware activation
- **Confirmation Window:** 120 seconds for firmware stability confirmation
### 6.2 Resource Constraints
- **Storage Requirements:** Minimum 100MB free space on SD card
- **Memory Usage:** Maximum 64KB for OTA buffers and state
- **Network Bandwidth:** Optimized for 4KB chunk size
- **Flash Wear:** Minimize flash write cycles during activation
### 6.3 Security Constraints
- **Encrypted Transport:** All firmware data must be transmitted over TLS
- **Integrity Validation:** SHA-256 verification mandatory
- **Anti-Rollback:** Version progression enforcement via eFuse
- **Secure Storage:** Temporary firmware files encrypted on SD card
## 7. Interface Specifications
### 7.1 OTA Manager Public API
```c
// OTA lifecycle management
bool otaMgr_initialize(void);
bool otaMgr_isReady(void);
ota_status_t otaMgr_getStatus(void);
// OTA operations
bool otaMgr_handleAvailabilityNotification(const ota_metadata_t* metadata);
bool otaMgr_receiveFirmwareChunk(uint32_t chunk_id, const uint8_t* data,
size_t size, uint32_t crc32);
bool otaMgr_validateFirmware(void);
bool otaMgr_activateFirmware(void);
// Rollback operations
bool otaMgr_triggerRollback(rollback_reason_t reason);
bool otaMgr_confirmFirmwareStability(void);
bool otaMgr_isRollbackPending(void);
// Status and diagnostics
bool otaMgr_getDownloadProgress(ota_download_progress_t* progress);
bool otaMgr_getValidationResult(ota_validation_result_t* result);
bool otaMgr_getPartitionStatus(ota_partition_status_t* status);
```
### 7.2 State Manager Integration
**State Transitions:**
- `RUNNING → OTA_PREP`: OTA request accepted
- `OTA_PREP → TEARDOWN`: Firmware validated, ready for activation
- `TEARDOWN → OTA_UPDATE`: Data flushed, ready for flashing
- `OTA_UPDATE → REBOOT`: Firmware activated, system restart
**State Coordination:**
```c
// State transition requests
bool otaMgr_requestStateTransition(system_state_t target_state,
transition_reason_t reason);
bool otaMgr_onStateChanged(system_state_t new_state, system_state_t old_state);
// Teardown coordination
bool otaMgr_initiateTeardown(teardown_reason_t reason);
bool otaMgr_onTeardownComplete(void);
```
### 7.3 Security Manager Integration
**Validation Interface:**
```c
// Firmware integrity validation
bool secMgr_calculateSHA256(const uint8_t* data, size_t size, uint8_t* hash);
bool secMgr_validateSignature(const uint8_t* firmware, size_t size,
const uint8_t* signature);
bool secMgr_validateAntiRollback(const char* version);
// Secure storage
bool secMgr_encryptFirmwareChunk(const uint8_t* plaintext, size_t size,
uint8_t* ciphertext);
bool secMgr_decryptFirmwareChunk(const uint8_t* ciphertext, size_t size,
uint8_t* plaintext);
```
## 8. Testing and Validation
### 8.1 Unit Testing
- **Readiness Validation:** All readiness criteria and rejection scenarios
- **Chunk Processing:** Chunk reception, validation, and storage
- **Integrity Validation:** SHA-256, signature, and compatibility checks
- **Rollback Logic:** All rollback triggers and recovery procedures
### 8.2 Integration Testing
- **End-to-End OTA:** Complete OTA flow from negotiation to confirmation
- **State Coordination:** Integration with State Manager and other components
- **Security Integration:** Cryptographic validation and secure storage
- **Network Integration:** Firmware download over encrypted channels
### 8.3 System Testing
- **Fault Injection:** Network failures, power loss, corruption scenarios
- **Performance Testing:** Large firmware downloads and timing constraints
- **Security Testing:** Malicious firmware rejection and rollback scenarios
- **Long-Duration Testing:** Multiple OTA cycles and partition wear
### 8.4 Acceptance Criteria
- OTA negotiation completes within timing constraints
- Firmware download handles all error conditions gracefully
- Integrity validation rejects all invalid firmware images
- Activation preserves all critical data during transition
- Rollback mechanism recovers from all failure scenarios
- No security vulnerabilities in OTA process
- Complete audit trail of all OTA activities
## 9. Dependencies
### 9.1 Internal Dependencies
- **State Manager:** System state coordination and teardown management
- **Persistence:** Data flush and firmware storage operations
- **Security Manager:** Cryptographic validation and secure storage
- **Main Hub APIs:** OTA communication protocol implementation
- **Diagnostics:** OTA event logging and failure reporting
### 9.2 External Dependencies
- **ESP-IDF Framework:** Partition management and flash operations
- **Secure Boot:** Hardware-enforced firmware authentication
- **Network Stack:** Secure communication transport (TLS/DTLS)
- **Hardware Components:** SD card, NVS flash, network interface
## 10. Future Enhancements
### 10.1 Planned Improvements
- **Delta Updates:** Incremental firmware updates to reduce download size
- **Compression:** Firmware compression to optimize storage and bandwidth
- **Multi-Stage Rollback:** Graduated rollback with multiple recovery points
- **Predictive Validation:** Pre-validation of firmware compatibility
### 10.2 Scalability Considerations
- **Fleet Management:** Coordinated OTA updates across multiple sensor hubs
- **Cloud Integration:** Direct cloud-based firmware distribution
- **Advanced Analytics:** OTA success rate monitoring and optimization
- **Automated Testing:** Continuous integration with automated OTA testing
---
**Document Status:** Final for Implementation Phase
**Component Dependencies:** Verified against architecture
**Requirements Traceability:** Complete (SR-OTA, SWR-OTA)
**Next Review:** After component implementation

586
system_arch_final/software/features/F-PWR_Power_Fault_Handling.md Normal file
View File

@@ -0,0 +1,586 @@
# Feature Specification: Power & Fault Handling
# Feature ID: F-PWR (F-PWR-001 to F-PWR-002)
**Document Type:** Feature Specification
**Version:** 1.0
**Date:** 2025-01-19
**Feature Category:** Power & Fault Handling
## 1. Feature Overview
### 1.1 Feature Purpose
The Power & Fault Handling feature provides comprehensive power management and fault recovery capabilities for the ASF Sensor Hub. This feature ensures reliable operation under power fluctuations, graceful recovery from power interruptions, and protection of critical data during power loss events.
### 1.2 Feature Scope
**In Scope:**
- Hardware-based brownout detection and response
- Power-loss data protection with supercapacitor backup
- Graceful shutdown and recovery procedures
- Power quality monitoring and reporting
- Critical data preservation during power events
**Out of Scope:**
- Battery-powered operation modes (system assumes continuous power)
- Advanced power management for low-power modes
- External power supply design and regulation
- Hardware power supply fault diagnosis
## 2. Sub-Features
### 2.1 F-PWR-001: Brownout Detection and Handling
**Description:** Hardware-based brownout detection with immediate response to protect system integrity and preserve critical data during power supply fluctuations.
**Brownout Detection Configuration:**
```c
typedef struct {
float brownout_threshold_v; // 3.0V threshold (configurable)
uint32_t detection_delay_ms; // 10ms detection delay
bool hardware_detection_enabled; // ESP32-S3 BOD enabled
brownout_response_t response; // Immediate response action
uint32_t supercap_runtime_ms; // Available supercapacitor runtime
} brownout_config_t;
typedef enum {
BROWNOUT_RESPONSE_IMMEDIATE_FLUSH = 0, // Flush critical data immediately
BROWNOUT_RESPONSE_GRACEFUL_SHUTDOWN = 1, // Attempt graceful shutdown
BROWNOUT_RESPONSE_EMERGENCY_SAVE = 2 // Emergency data save only
} brownout_response_t;
typedef struct {
bool brownout_detected; // Current brownout status
uint64_t brownout_start_time; // Brownout detection timestamp
uint32_t brownout_duration_ms; // Duration of current brownout
uint32_t brownout_count; // Total brownout events
float min_voltage_recorded; // Minimum voltage during event
power_loss_severity_t severity; // Brownout severity classification
} brownout_status_t;
typedef enum {
POWER_LOSS_MINOR = 0, // Brief voltage dip, no action needed
POWER_LOSS_MODERATE = 1, // Voltage drop, flush critical data
POWER_LOSS_SEVERE = 2, // Extended brownout, emergency shutdown
POWER_LOSS_CRITICAL = 3 // Imminent power loss, immediate save
} power_loss_severity_t;
```
**Hardware Configuration:**
- **Brownout Detector:** ESP32-S3 hardware BOD with 3.0V threshold
- **Supercapacitor:** 0.5-1.0F capacitor providing 1-2 seconds runtime at 3.3V
- **Detection ISR:** High-priority interrupt service routine for immediate response
- **Voltage Monitoring:** Continuous ADC monitoring of supply voltage
**Brownout Response Flow:**
```mermaid
sequenceDiagram
participant PWR as Power Supply
participant BOD as Brownout Detector
participant ISR as Brownout ISR
participant PWR_MGR as Power Manager
participant PERSIST as Persistence
participant DIAG as Diagnostics
Note over PWR,DIAG: Brownout Detection and Response
PWR->>PWR: voltageDropBelow3.0V()
PWR->>BOD: triggerBrownoutDetection()
BOD->>ISR: brownoutInterrupt()
ISR->>ISR: setPowerLossFlag()
ISR->>PWR_MGR: notifyBrownoutDetected()
PWR_MGR->>PWR_MGR: assessSeverity(voltage, duration)
alt Severity >= MODERATE
PWR_MGR->>PERSIST: flushCriticalDataImmediate()
PERSIST->>PERSIST: flushMachineConstants()
PERSIST->>PERSIST: flushCalibrationData()
PERSIST->>PERSIST: flushDiagnosticEvents()
PERSIST-->>PWR_MGR: criticalDataFlushed()
end
alt Severity >= SEVERE
PWR_MGR->>PWR_MGR: initiateGracefulShutdown()
PWR_MGR->>DIAG: logPowerEvent(BROWNOUT_SHUTDOWN)
end
PWR->>PWR: voltageRestored()
BOD->>ISR: brownoutCleared()
ISR->>PWR_MGR: notifyBrownoutCleared()
PWR_MGR->>PWR_MGR: initiatePowerRecovery()
```
**Critical Data Flush Priority:**
1. **Machine Constants:** System configuration and calibration parameters
2. **Diagnostic Events:** Recent fault and warning events
3. **Sensor Calibration:** Current sensor calibration data
4. **System State:** Current system state and operational parameters
5. **Recent Sensor Data:** Latest sensor readings (if time permits)
**Supercapacitor Runtime Management:**
```c
typedef struct {
float capacitance_f; // Supercapacitor capacitance (0.5-1.0F)
float initial_voltage_v; // Initial charge voltage (3.3V)
float cutoff_voltage_v; // Minimum operating voltage (2.7V)
uint32_t estimated_runtime_ms; // Calculated runtime at current load
uint32_t flush_time_budget_ms; // Time allocated for data flush
bool supercap_present; // Supercapacitor detection status
} supercapacitor_config_t;
// Runtime calculation: t = C * (V_initial - V_cutoff) / I_load
uint32_t calculateSupercapRuntime(float capacitance, float v_init,
float v_cutoff, float current_ma);
```
### 2.2 F-PWR-002: Power-Loss Recovery
**Description:** Comprehensive power-loss recovery system that detects power restoration, performs system integrity checks, and restores normal operation with full data consistency validation.
**Recovery Configuration:**
```c
typedef struct {
uint32_t power_stabilization_delay_ms; // 100ms stabilization wait
uint32_t recovery_timeout_ms; // 30s maximum recovery time
bool integrity_check_required; // Data integrity validation
bool state_restoration_enabled; // System state restoration
recovery_mode_t recovery_mode; // Recovery behavior mode
} power_recovery_config_t;
typedef enum {
RECOVERY_MODE_FAST = 0, // Quick recovery, minimal checks
RECOVERY_MODE_SAFE = 1, // Full integrity checks
RECOVERY_MODE_DIAGNOSTIC = 2 // Extended diagnostics during recovery
} recovery_mode_t;
typedef struct {
bool power_restored; // Power restoration status
uint64_t power_loss_start; // Power loss start timestamp
uint64_t power_loss_duration; // Total power loss duration
uint32_t recovery_attempts; // Number of recovery attempts
recovery_status_t status; // Current recovery status
data_integrity_result_t integrity; // Data integrity check results
} power_recovery_status_t;
typedef enum {
RECOVERY_STATUS_PENDING = 0, // Recovery not started
RECOVERY_STATUS_IN_PROGRESS = 1, // Recovery in progress
RECOVERY_STATUS_SUCCESS = 2, // Recovery completed successfully
RECOVERY_STATUS_FAILED = 3, // Recovery failed
RECOVERY_STATUS_PARTIAL = 4 // Partial recovery (degraded mode)
} recovery_status_t;
```
**Data Integrity Validation:**
```c
typedef struct {
bool machine_constants_valid; // MC data integrity
bool calibration_data_valid; // Calibration integrity
bool diagnostic_logs_valid; // Diagnostic data integrity
bool system_state_valid; // State data integrity
bool sensor_data_valid; // Sensor data integrity
uint32_t corrupted_files; // Number of corrupted files
uint32_t recovered_files; // Number of recovered files
} data_integrity_result_t;
typedef enum {
INTEGRITY_CHECK_PASS = 0, // All data intact
INTEGRITY_CHECK_MINOR_LOSS = 1, // Minor data loss, recoverable
INTEGRITY_CHECK_MAJOR_LOSS = 2, // Major data loss, degraded operation
INTEGRITY_CHECK_CRITICAL_LOSS = 3 // Critical data loss, requires intervention
} integrity_check_result_t;
```
**Power Recovery Flow:**
```mermaid
sequenceDiagram
participant PWR as Power Supply
participant PWR_MGR as Power Manager
participant PERSIST as Persistence
participant DIAG as Diagnostics
participant STM as State Manager
participant SENSOR as Sensor Manager
Note over PWR,SENSOR: Power Recovery Sequence
PWR->>PWR: powerRestored()
PWR->>PWR_MGR: notifyPowerRestoration()
PWR_MGR->>PWR_MGR: waitForStabilization(100ms)
PWR_MGR->>PWR_MGR: detectPowerLossDuration()
PWR_MGR->>PERSIST: performIntegrityCheck()
PERSIST->>PERSIST: validateMachineConstants()
PERSIST->>PERSIST: validateCalibrationData()
PERSIST->>PERSIST: validateDiagnosticLogs()
PERSIST-->>PWR_MGR: integrityResults()
alt Integrity Check PASS
PWR_MGR->>STM: restoreSystemState()
STM->>STM: transitionToRunningState()
PWR_MGR->>SENSOR: restoreSensorConfiguration()
PWR_MGR->>DIAG: logPowerEvent(RECOVERY_SUCCESS)
else Integrity Check MINOR_LOSS
PWR_MGR->>PERSIST: attemptDataRecovery()
PWR_MGR->>STM: transitionToWarningState()
PWR_MGR->>DIAG: logPowerEvent(RECOVERY_PARTIAL)
else Integrity Check MAJOR_LOSS
PWR_MGR->>STM: transitionToFaultState()
PWR_MGR->>DIAG: logPowerEvent(RECOVERY_FAILED)
end
PWR_MGR->>PWR_MGR: reportRecoveryStatus()
```
**Recovery Validation Steps:**
1. **Power Stabilization:** Wait 100ms for power supply stabilization
2. **System Clock Recovery:** Restore system time from RTC (if available)
3. **Data Integrity Check:** Validate all persistent data structures
4. **Configuration Restoration:** Reload machine constants and calibration
5. **State Restoration:** Restore system state and component configuration
6. **Sensor Reinitialization:** Reinitialize sensors and resume acquisition
7. **Communication Recovery:** Re-establish network connections
8. **Recovery Reporting:** Log recovery status and any data loss
**RTC Battery Support (Optional):**
```c
typedef struct {
bool rtc_battery_present; // External RTC battery detected
float rtc_battery_voltage; // Current RTC battery voltage
uint64_t time_before_loss; // Time before power loss
uint64_t time_after_recovery; // Time after power recovery
bool time_accuracy_maintained; // Time accuracy status
} rtc_battery_status_t;
// RTC battery specifications: CR2032, 3V, 220mAh
// Maintains time accuracy during power loss up to several months
```
## 3. Requirements Coverage
### 3.1 System Requirements (SR-XXX)
| Feature | System Requirements | Description |
|---------|-------------------|-------------|
| **F-PWR-001** | SR-PWR-001, SR-PWR-002, SR-PWR-003, SR-PWR-004 | Brownout detection, data flush, graceful shutdown, clean reboot |
| **F-PWR-002** | SR-PWR-005, SR-PWR-006, SR-PWR-007, SR-PWR-008 | Power recovery, integrity validation, state restoration, event reporting |
### 3.2 Software Requirements (SWR-XXX)
| Feature | Software Requirements | Implementation Details |
|---------|---------------------|----------------------|
| **F-PWR-001** | SWR-PWR-001, SWR-PWR-002, SWR-PWR-003 | BOD configuration, ISR handling, supercapacitor management |
| **F-PWR-002** | SWR-PWR-004, SWR-PWR-005, SWR-PWR-006 | Recovery procedures, integrity checks, state restoration |
## 4. Component Implementation Mapping
### 4.1 Primary Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| **Power Manager** | Power event coordination, recovery management | `application_layer/power_manager/` |
| **Error Handler** | Power fault classification, escalation | `application_layer/error_handler/` |
| **Persistence** | Critical data flush, integrity validation | `application_layer/DP_stack/persistence/` |
| **State Manager** | System state coordination during power events | `application_layer/business_stack/STM/` |
### 4.2 Supporting Components
| Component | Support Role | Interface |
|-----------|-------------|-----------|
| **Diagnostics** | Power event logging, recovery reporting | `application_layer/diag_task/` |
| **Sensor Manager** | Sensor state preservation and restoration | `application_layer/business_stack/sensor_manager/` |
| **Machine Constant Manager** | Configuration preservation and restoration | `application_layer/business_stack/machine_constant_manager/` |
| **ADC Driver** | Voltage monitoring, supercapacitor status | `ESP_IDF_FW_wrappers/adc/` |
### 4.3 Component Interaction Diagram
```mermaid
graph TB
subgraph "Power & Fault Handling Feature"
PWR_MGR[Power Manager]
ERR[Error Handler]
PERSIST[Persistence]
STM[State Manager]
end
subgraph "System Components"
DIAG[Diagnostics]
SENSOR[Sensor Manager]
MC_MGR[MC Manager]
end
subgraph "Hardware Interfaces"
BOD[Brownout Detector]
ADC[ADC Driver]
SUPERCAP[Supercapacitor]
RTC[RTC Battery]
end
subgraph "Storage"
NVS[NVS Flash]
SD[SD Card]
end
BOD -->|Brownout ISR| PWR_MGR
ADC -->|Voltage Monitoring| PWR_MGR
SUPERCAP -->|Runtime Power| PWR_MGR
RTC -->|Time Backup| PWR_MGR
PWR_MGR <--> STM
PWR_MGR <--> ERR
PWR_MGR <--> PERSIST
PWR_MGR --> DIAG
PWR_MGR --> SENSOR
PWR_MGR --> MC_MGR
PERSIST --> NVS
PERSIST --> SD
ERR -.->|Power Faults| DIAG
STM -.->|State Events| DIAG
```
### 4.4 Power Event Sequence
```mermaid
sequenceDiagram
participant HW as Hardware
participant BOD as Brownout Detector
participant PWR as Power Manager
participant PERSIST as Persistence
participant STM as State Manager
participant DIAG as Diagnostics
Note over HW,DIAG: Complete Power Event Cycle
HW->>BOD: voltageDropDetected(2.9V)
BOD->>PWR: brownoutISR()
PWR->>PWR: assessPowerLossSeverity()
alt Critical Power Loss
PWR->>PERSIST: emergencyDataFlush()
PERSIST->>NVS: flushCriticalData()
PWR->>STM: notifyPowerLoss(CRITICAL)
PWR->>DIAG: logPowerEvent(BROWNOUT_CRITICAL)
end
Note over HW,DIAG: Power Loss Period
HW->>HW: powerLost()
Note over HW,DIAG: Power Restoration
HW->>PWR: powerRestored()
PWR->>PWR: waitForStabilization()
PWR->>PERSIST: performIntegrityCheck()
alt Data Integrity OK
PWR->>STM: restoreSystemState()
STM->>STM: transitionToRunning()
PWR->>DIAG: logPowerEvent(RECOVERY_SUCCESS)
else Data Corruption Detected
PWR->>STM: transitionToFault()
PWR->>DIAG: logPowerEvent(RECOVERY_FAILED)
end
```
## 5. Feature Behavior
### 5.1 Normal Operation Flow
1. **Continuous Monitoring:**
- Monitor supply voltage using ADC and hardware brownout detector
- Track supercapacitor charge level and estimated runtime
- Maintain power quality statistics and trend analysis
- Report power events to diagnostics system
2. **Brownout Response:**
- Detect voltage drop below 3.0V threshold within 10ms
- Assess brownout severity based on voltage level and duration
- Execute immediate data flush for critical system data
- Coordinate graceful shutdown if extended brownout detected
3. **Power Recovery:**
- Detect power restoration and wait for stabilization
- Perform comprehensive data integrity validation
- Restore system state and component configuration
- Resume normal operation or enter degraded mode if data loss detected
4. **Event Reporting:**
- Log all power events with timestamps and severity
- Report power quality metrics to Main Hub
- Maintain power event history for trend analysis
- Generate diagnostic alerts for recurring power issues
### 5.2 Error Handling
| Error Condition | Detection Method | Response Action |
|----------------|------------------|-----------------|
| **Supercapacitor Failure** | Voltage monitoring, runtime calculation | Log warning, reduce flush scope |
| **Data Flush Timeout** | Flush operation timeout | Abort flush, log partial completion |
| **Recovery Failure** | Integrity check failure | Enter fault state, request intervention |
| **RTC Battery Low** | Battery voltage monitoring | Log warning, continue without RTC |
| **Repeated Brownouts** | Event frequency analysis | Escalate to system fault, notify Main Hub |
| **Critical Data Loss** | Integrity validation failure | Enter fault state, preserve remaining data |
### 5.3 State-Dependent Behavior
| System State | Feature Behavior |
|-------------|------------------|
| **INIT** | Initialize power monitoring, configure brownout detection |
| **RUNNING** | Full power monitoring, immediate brownout response |
| **WARNING** | Enhanced power monitoring, preemptive data flush |
| **FAULT** | Critical power functions only, preserve fault data |
| **OTA_UPDATE** | Reject OTA if power unstable, maintain power monitoring |
| **TEARDOWN** | Coordinate with teardown, ensure data preservation |
| **SERVICE** | Limited power monitoring for diagnostics |
| **SD_DEGRADED** | NVS-only data flush, reduced recovery capabilities |
## 6. Feature Constraints
### 6.1 Timing Constraints
- **Brownout Detection:** Maximum 10ms detection delay
- **Data Flush:** Must complete within supercapacitor runtime (1-2 seconds)
- **Power Stabilization:** 100ms wait after power restoration
- **Recovery Timeout:** Maximum 30 seconds for complete recovery
### 6.2 Resource Constraints
- **Supercapacitor Runtime:** 1-2 seconds at 3.3V with 0.5-1.0F capacitance
- **Critical Data Size:** Maximum data that can be flushed within runtime
- **Memory Usage:** Maximum 16KB for power management buffers
- **Flash Wear:** Minimize NVS writes during frequent brownouts
### 6.3 Hardware Constraints
- **Brownout Threshold:** 3.0V ±0.1V (ESP32-S3 BOD limitation)
- **Voltage Monitoring:** ADC accuracy ±50mV
- **Supercapacitor Leakage:** Account for self-discharge over time
- **RTC Battery Life:** CR2032 provides several months of timekeeping
## 7. Interface Specifications
### 7.1 Power Manager Public API
```c
// Power management initialization
bool powerMgr_initialize(void);
bool powerMgr_configureBrownoutDetection(const brownout_config_t* config);
bool powerMgr_configureRecovery(const power_recovery_config_t* config);
// Power monitoring
bool powerMgr_getCurrentVoltage(float* voltage);
bool powerMgr_getSupercapStatus(supercapacitor_status_t* status);
bool powerMgr_getPowerQuality(power_quality_metrics_t* metrics);
// Power event handling
bool powerMgr_isBrownoutActive(void);
bool powerMgr_isRecoveryInProgress(void);
bool powerMgr_getPowerEventHistory(power_event_t* events, size_t* count);
// Emergency operations
bool powerMgr_triggerEmergencyFlush(void);
bool powerMgr_estimateFlushTime(uint32_t* estimated_ms);
```
### 7.2 Brownout ISR Interface
```c
// Brownout interrupt service routine
void IRAM_ATTR brownout_isr_handler(void* arg);
// ISR-safe operations
void IRAM_ATTR powerMgr_setBrownoutFlag(void);
void IRAM_ATTR powerMgr_recordBrownoutTime(void);
void IRAM_ATTR powerMgr_triggerEmergencyResponse(void);
```
### 7.3 Recovery Validation Interface
```c
// Data integrity validation
bool powerMgr_validateDataIntegrity(data_integrity_result_t* result);
bool powerMgr_attemptDataRecovery(const char* data_type);
bool powerMgr_restoreSystemConfiguration(void);
// Recovery status
recovery_status_t powerMgr_getRecoveryStatus(void);
bool powerMgr_isRecoveryComplete(void);
bool powerMgr_getRecoveryReport(recovery_report_t* report);
```
## 8. Testing and Validation
### 8.1 Unit Testing
- **Brownout Detection:** Simulated voltage drops and ISR response
- **Data Flush:** Critical data preservation under time constraints
- **Recovery Logic:** Data integrity validation and state restoration
- **Supercapacitor Management:** Runtime calculation and monitoring
### 8.2 Integration Testing
- **End-to-End Power Cycle:** Complete brownout and recovery sequence
- **State Coordination:** Integration with State Manager during power events
- **Data Persistence:** Integration with Persistence component for data flush
- **Diagnostic Integration:** Power event logging and reporting
### 8.3 System Testing
- **Hardware Power Testing:** Real power supply interruptions and brownouts
- **Stress Testing:** Repeated power cycles and brownout events
- **Data Integrity Testing:** Validation of data preservation under various scenarios
- **Performance Testing:** Timing constraints under different system loads
### 8.4 Acceptance Criteria
- Brownout detection responds within 10ms of voltage drop
- Critical data successfully preserved during power loss events
- System recovers gracefully from power interruptions
- Data integrity maintained across power cycles
- No data corruption during normal power events
- Power quality monitoring provides accurate metrics
- Complete audit trail of all power events
## 9. Dependencies
### 9.1 Internal Dependencies
- **State Manager:** System state coordination during power events
- **Persistence:** Critical data flush and integrity validation
- **Error Handler:** Power fault classification and escalation
- **Diagnostics:** Power event logging and reporting
### 9.2 External Dependencies
- **ESP-IDF Framework:** Brownout detector, ADC, NVS, RTC
- **Hardware Components:** Supercapacitor, RTC battery, voltage regulators
- **FreeRTOS:** ISR handling, task coordination
- **Power Supply:** Stable 3.3V supply with brownout protection
## 10. Future Enhancements
### 10.1 Planned Improvements
- **Predictive Power Management:** Machine learning for power failure prediction
- **Advanced Supercapacitor Management:** Dynamic runtime optimization
- **Power Quality Analytics:** Advanced power supply analysis and reporting
- **Battery Backup Support:** Optional battery backup for extended operation
### 10.2 Scalability Considerations
- **Fleet Power Monitoring:** Centralized power quality monitoring across hubs
- **Predictive Maintenance:** Power supply health monitoring and replacement alerts
- **Advanced Recovery:** Multi-level recovery strategies based on data loss severity
- **Energy Harvesting:** Integration with renewable energy sources
---
**Document Status:** Final for Implementation Phase
**Component Dependencies:** Verified against architecture
**Requirements Traceability:** Complete (SR-PWR, SWR-PWR)
**Next Review:** After component implementation

693
system_arch_final/software/features/F-SEC_Security_Safety.md Normal file
View File

@@ -0,0 +1,693 @@
# Feature Specification: Security & Safety
# Feature ID: F-SEC (F-SEC-001 to F-SEC-004)
**Document Type:** Feature Specification
**Version:** 1.0
**Date:** 2025-01-19
**Feature Category:** Security & Safety
## 1. Feature Overview
### 1.1 Feature Purpose
The Security & Safety feature provides comprehensive security enforcement and safety mechanisms for the ASF Sensor Hub. This feature ensures that only trusted firmware executes, sensitive data is protected at rest and in transit, and all communications maintain confidentiality and integrity through cryptographic mechanisms.
### 1.2 Feature Scope
**In Scope:**
- Hardware-enforced secure boot with cryptographic verification
- Flash encryption for sensitive data protection at rest
- Mutual TLS (mTLS) for secure communication channels
- Security violation detection and response mechanisms
- Device identity management and authentication
**Out of Scope:**
- Cloud server security policies and infrastructure
- User identity management and access control systems
- Physical tamper detection hardware (future enhancement)
- Cryptographic key generation and signing infrastructure
## 2. Sub-Features
### 2.1 F-SEC-001: Secure Boot
**Description:** Hardware-enforced secure boot implementation using Secure Boot V2 to ensure only authenticated and authorized firmware images execute on the Sensor Hub.
**Secure Boot Configuration:**
```c
typedef struct {
secure_boot_version_t version; // Secure Boot V2
signature_algorithm_t algorithm; // RSA-3072 or ECDSA-P256
uint8_t root_key_hash[32]; // Root-of-trust key hash (eFuse)
bool anti_rollback_enabled; // eFuse-based anti-rollback
uint32_t security_version; // Current security version
boot_verification_mode_t mode; // Hardware-enforced verification
} secure_boot_config_t;
typedef enum {
SECURE_BOOT_V2 = 2 // Only supported version
} secure_boot_version_t;
typedef enum {
SIG_ALG_RSA_3072 = 0, // RSA-3072 signature
SIG_ALG_ECDSA_P256 = 1 // ECDSA-P256 signature
} signature_algorithm_t;
typedef enum {
BOOT_MODE_DEVELOPMENT = 0, // Development mode (key revocable)
BOOT_MODE_PRODUCTION = 1 // Production mode (key permanent)
} boot_verification_mode_t;
```
**Boot Verification Flow:**
```mermaid
sequenceDiagram
participant PWR as Power On
participant ROM as ROM Bootloader
participant SB as Secure Boot V2
participant EFUSE as eFuse Storage
participant APP as Application
participant DIAG as Diagnostics
PWR->>ROM: System Reset/Power On
ROM->>SB: Load Firmware Image
SB->>EFUSE: readRootKeyHash()
EFUSE-->>SB: root_key_hash
SB->>SB: verifyFirmwareSignature(root_key_hash)
alt Signature Valid
SB->>SB: checkAntiRollback()
alt Version Valid
SB->>APP: jumpToApplication()
APP->>DIAG: logBootEvent(SECURE_BOOT_SUCCESS)
else Version Invalid
SB->>SB: enterBootFailureState()
SB->>DIAG: logBootEvent(ANTI_ROLLBACK_VIOLATION)
end
else Signature Invalid
SB->>SB: enterBootFailureState()
SB->>DIAG: logBootEvent(SECURE_BOOT_FAILURE)
end
```
**Root-of-Trust Management:**
- **Key Storage:** Root public key hash stored in eFuse (one-time programmable)
- **Key Revocation:** Not supported in production mode (permanent key)
- **Anti-Rollback:** eFuse-based security version enforcement
- **Verification:** Every boot cycle (cold and warm boots)
**Boot Failure Handling:**
- **BOOT_FAILURE State:** System enters safe state, no application execution
- **Diagnostic Logging:** Boot failure events logged to NVS (if accessible)
- **Recovery:** Manual intervention required (re-flashing with valid firmware)
### 2.2 F-SEC-002: Secure Flash Storage
**Description:** Comprehensive flash encryption implementation using AES-256 to protect sensitive data stored in internal flash and external storage devices.
**Flash Encryption Configuration:**
```c
typedef struct {
encryption_algorithm_t algorithm; // AES-256
encryption_mode_t mode; // Release mode (recommended)
uint8_t encryption_key[32]; // Hardware-derived key (eFuse)
bool transparent_decryption; // Automatic decryption on read
flash_encryption_scope_t scope; // Encrypted regions
} flash_encryption_config_t;
typedef enum {
ENCRYPT_AES_256 = 0 // AES-256 encryption
} encryption_algorithm_t;
typedef enum {
ENCRYPT_MODE_DEVELOPMENT = 0, // Development mode (key readable)
ENCRYPT_MODE_RELEASE = 1 // Release mode (key protected)
} encryption_mode_t;
typedef struct {
bool firmware_encrypted; // Application partitions
bool nvs_encrypted; // NVS partition
bool machine_constants_encrypted; // MC data
bool calibration_encrypted; // Calibration data
bool diagnostics_encrypted; // Diagnostic logs
} flash_encryption_scope_t;
```
**Encrypted Data Categories:**
| Data Type | Storage Location | Encryption Method | Access Control |
|-----------|------------------|-------------------|----------------|
| **Firmware Images** | Flash partitions | Hardware AES-256 | Transparent |
| **Machine Constants** | NVS partition | Hardware AES-256 | Component-mediated |
| **Calibration Data** | NVS partition | Hardware AES-256 | Component-mediated |
| **Cryptographic Keys** | eFuse/Secure NVS | Hardware AES-256 | Restricted access |
| **Diagnostic Logs** | NVS partition | Hardware AES-256 | Component-mediated |
| **SD Card Data** | External storage | Software AES-256 | Optional encryption |
**External Storage Encryption:**
```c
typedef struct {
bool sd_encryption_enabled; // SD card encryption flag
uint8_t sd_encryption_key[32]; // SD-specific encryption key
encryption_algorithm_t algorithm; // AES-256 for SD card
file_encryption_policy_t policy; // Per-file encryption policy
} external_storage_encryption_t;
typedef enum {
FILE_ENCRYPT_NONE = 0, // No encryption
FILE_ENCRYPT_SENSITIVE = 1, // Encrypt sensitive files only
FILE_ENCRYPT_ALL = 2 // Encrypt all files
} file_encryption_policy_t;
```
**Encryption Flow:**
```mermaid
sequenceDiagram
participant APP as Application
participant PERSIST as Persistence
participant ENCRYPT as Encryption Engine
participant NVS as NVS Storage
participant SD as SD Card
Note over APP,SD: Secure Data Storage Flow
APP->>PERSIST: storeSensitiveData(data, type)
PERSIST->>PERSIST: classifyDataSensitivity(type)
alt Critical Data (NVS)
PERSIST->>ENCRYPT: encryptData(data, NVS_KEY)
ENCRYPT-->>PERSIST: encrypted_data
PERSIST->>NVS: writeEncrypted(encrypted_data)
NVS-->>PERSIST: writeComplete()
else Regular Data (SD Card)
alt SD Encryption Enabled
PERSIST->>ENCRYPT: encryptData(data, SD_KEY)
ENCRYPT-->>PERSIST: encrypted_data
PERSIST->>SD: writeEncrypted(encrypted_data)
else SD Encryption Disabled
PERSIST->>SD: writePlaintext(data)
end
end
PERSIST-->>APP: storageComplete()
```
### 2.3 F-SEC-003: Encrypted Communication
**Description:** Mutual TLS (mTLS) implementation for secure communication with Main Hub and peer devices, ensuring confidentiality, integrity, and authenticity of all transmitted data.
**Device Identity and Authentication:**
```c
typedef struct {
uint8_t device_certificate[2048]; // X.509 device certificate (max 2KB)
uint8_t private_key[256]; // Device private key (RSA-2048/ECDSA-P256)
uint8_t ca_certificate[2048]; // Certificate Authority certificate
char device_id[64]; // Unique device identifier
uint64_t certificate_expiry; // Certificate expiration timestamp
bool certificate_valid; // Certificate validation status
} device_identity_t;
typedef struct {
tls_version_t version; // TLS 1.2 minimum
cipher_suite_t cipher_suite; // Supported cipher suites
bool mutual_auth_required; // mTLS enforcement
uint32_t session_timeout; // TLS session timeout
bool session_resumption; // Session resumption support
} tls_config_t;
typedef enum {
TLS_VERSION_1_2 = 0x0303, // TLS 1.2 (minimum required)
TLS_VERSION_1_3 = 0x0304 // TLS 1.3 (preferred)
} tls_version_t;
```
**Supported Cipher Suites:**
| Cipher Suite | Key Exchange | Encryption | MAC | Recommended |
|-------------|-------------|------------|-----|-------------|
| **TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384** | ECDHE-RSA | AES-256-GCM | SHA384 | Yes |
| **TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384** | ECDHE-ECDSA | AES-256-GCM | SHA384 | Yes |
| **TLS_RSA_WITH_AES_256_GCM_SHA384** | RSA | AES-256-GCM | SHA384 | Fallback |
**mTLS Handshake Flow:**
```mermaid
sequenceDiagram
participant SH as Sensor Hub
participant MH as Main Hub
participant CA as Certificate Authority
Note over SH,CA: Mutual TLS Handshake
SH->>MH: ClientHello + SupportedCipherSuites
MH->>SH: ServerHello + SelectedCipherSuite
MH->>SH: ServerCertificate
MH->>SH: CertificateRequest
MH->>SH: ServerHelloDone
SH->>SH: validateServerCertificate()
SH->>CA: verifyCertificateChain(server_cert)
CA-->>SH: validationResult(VALID)
SH->>MH: ClientCertificate
SH->>MH: ClientKeyExchange
SH->>MH: CertificateVerify
SH->>MH: ChangeCipherSpec
SH->>MH: Finished
MH->>MH: validateClientCertificate()
MH->>CA: verifyCertificateChain(client_cert)
CA-->>MH: validationResult(VALID)
MH->>SH: ChangeCipherSpec
MH->>SH: Finished
Note over SH,MH: Secure Channel Established
SH<->>MH: EncryptedApplicationData
```
**Certificate Management:**
- **Device Certificate:** Unique X.509 certificate per device (max 2KB)
- **Private Key:** RSA-2048 or ECDSA-P256 stored securely in eFuse/NVS
- **Certificate Chain:** Root CA and intermediate certificates
- **Certificate Rotation:** Managed on broker/server side
- **Revocation:** Certificate Revocation Lists (CRL) or broker-side denylists
**Key Lifecycle Management:**
| Phase | Mechanism | Responsibility |
|-------|-----------|----------------|
| **Manufacturing** | Device certificate and private key injection | Manufacturing process |
| **Provisioning** | Certificate validation and registration | Onboarding system |
| **Operation** | TLS session key generation and management | Runtime TLS stack |
| **Rotation** | Certificate renewal and update | Server-side management |
| **Revocation** | Certificate invalidation and replacement | Certificate Authority |
### 2.4 F-SEC-004: Security Violation Handling
**Description:** Comprehensive security violation detection, classification, and response system to handle security threats and maintain system integrity.
**Security Violation Types:**
```c
typedef enum {
SEC_VIOLATION_BOOT_FAILURE = 0x1001, // Secure boot verification failure
SEC_VIOLATION_AUTH_FAILURE = 0x1002, // Authentication failure
SEC_VIOLATION_CERT_INVALID = 0x1003, // Certificate validation failure
SEC_VIOLATION_MESSAGE_TAMPER = 0x1004, // Message integrity violation
SEC_VIOLATION_UNAUTHORIZED_ACCESS = 0x1005, // Unauthorized access attempt
SEC_VIOLATION_ROLLBACK_ATTEMPT = 0x1006, // Anti-rollback violation
SEC_VIOLATION_KEY_COMPROMISE = 0x1007, // Cryptographic key compromise
SEC_VIOLATION_REPLAY_ATTACK = 0x1008 // Message replay attack
} security_violation_type_t;
typedef struct {
security_violation_type_t type; // Violation type
diagnostic_severity_t severity; // FATAL, ERROR, WARNING
uint64_t timestamp; // Violation timestamp
char source_component[32]; // Component that detected violation
char description[128]; // Human-readable description
uint8_t context_data[64]; // Violation-specific context
uint32_t occurrence_count; // Number of occurrences
bool escalation_triggered; // Escalation flag
} security_violation_event_t;
```
**Violation Response Matrix:**
| Violation Type | Severity | Immediate Response | Escalation Action |
|---------------|----------|-------------------|-------------------|
| **Boot Failure** | FATAL | Enter BOOT_FAILURE state | System halt, manual recovery |
| **Auth Failure** | ERROR | Reject connection, log event | Escalate to FATAL after 3 failures |
| **Cert Invalid** | ERROR | Reject connection, log event | Escalate to FATAL if persistent |
| **Message Tamper** | WARNING | Discard message, log event | Escalate to ERROR if repeated |
| **Unauthorized Access** | FATAL | Deny access, log event | System lockdown |
| **Rollback Attempt** | FATAL | Prevent rollback, log event | System halt |
| **Key Compromise** | FATAL | Revoke keys, log event | System lockdown |
| **Replay Attack** | WARNING | Discard message, log event | Escalate to ERROR if persistent |
**Security Event Flow:**
```mermaid
sequenceDiagram
participant COMP as Security Component
participant SEC as Security Manager
participant DIAG as Diagnostics
participant STM as State Manager
participant LOG as Security Logger
Note over COMP,LOG: Security Violation Detection and Response
COMP->>SEC: reportSecurityViolation(type, context)
SEC->>SEC: classifyViolation(type)
SEC->>SEC: determineResponse(type, severity)
alt Severity == FATAL
SEC->>STM: triggerStateTransition(FAULT)
SEC->>LOG: logSecurityEvent(FATAL, details)
SEC->>DIAG: reportDiagnosticEvent(FATAL, violation)
else Severity == ERROR
SEC->>SEC: checkEscalationCriteria()
alt Escalation Required
SEC->>STM: triggerStateTransition(WARNING)
end
SEC->>LOG: logSecurityEvent(ERROR, details)
SEC->>DIAG: reportDiagnosticEvent(ERROR, violation)
else Severity == WARNING
SEC->>LOG: logSecurityEvent(WARNING, details)
SEC->>DIAG: reportDiagnosticEvent(WARNING, violation)
end
SEC->>SEC: updateViolationStatistics()
SEC->>SEC: checkPatterns()
```
**Escalation Criteria:**
- **Authentication Failures:** 3 consecutive failures within 5 minutes
- **Message Tampering:** 5 tampered messages within 1 minute
- **Certificate Violations:** Persistent certificate validation failures
- **Pattern Detection:** Coordinated attack patterns across multiple violation types
## 3. Requirements Coverage
### 3.1 System Requirements (SR-XXX)
| Feature | System Requirements | Description |
|---------|-------------------|-------------|
| **F-SEC-001** | SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 | Secure boot verification and root-of-trust protection |
| **F-SEC-002** | SR-SEC-005, SR-SEC-006, SR-SEC-007, SR-SEC-008 | Flash encryption and secure storage |
| **F-SEC-003** | SR-SEC-009, SR-SEC-010, SR-SEC-011, SR-SEC-012 | Encrypted communication and mTLS |
| **F-SEC-004** | SR-SEC-013, SR-SEC-014, SR-SEC-015 | Security violation handling and response |
### 3.2 Software Requirements (SWR-XXX)
| Feature | Software Requirements | Implementation Details |
|---------|---------------------|----------------------|
| **F-SEC-001** | SWR-SEC-001, SWR-SEC-002, SWR-SEC-003 | Boot verification, signature validation, anti-rollback |
| **F-SEC-002** | SWR-SEC-004, SWR-SEC-005, SWR-SEC-006 | AES-256 encryption, key management, storage protection |
| **F-SEC-003** | SWR-SEC-007, SWR-SEC-008, SWR-SEC-009 | mTLS implementation, certificate management, session security |
| **F-SEC-004** | SWR-SEC-010, SWR-SEC-011, SWR-SEC-012 | Violation detection, response coordination, escalation logic |
## 4. Component Implementation Mapping
### 4.1 Primary Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| **Security Manager** | Security policy enforcement, violation handling | `application_layer/security/` |
| **Secure Boot** | Boot-time firmware verification | `bootloader/secure_boot/` |
| **Encryption Engine** | Cryptographic operations, key management | `application_layer/security/crypto/` |
| **Certificate Manager** | Certificate validation, lifecycle management | `application_layer/security/cert_mgr/` |
### 4.2 Supporting Components
| Component | Support Role | Interface |
|-----------|-------------|-----------|
| **Network Stack** | TLS/DTLS transport layer | `drivers/network_stack/` |
| **NVM Driver** | Secure storage access | `drivers/nvm/` |
| **Diagnostics** | Security event logging | `application_layer/diag_task/` |
| **State Manager** | Security-triggered state transitions | `application_layer/business_stack/STM/` |
### 4.3 Component Interaction Diagram
```mermaid
graph TB
subgraph "Security & Safety Feature"
SEC[Security Manager]
BOOT[Secure Boot]
CRYPTO[Encryption Engine]
CERT[Certificate Manager]
end
subgraph "System Components"
STM[State Manager]
DIAG[Diagnostics]
NET[Network Stack]
NVM[NVM Driver]
end
subgraph "Hardware Security"
EFUSE[eFuse Storage]
HWCRYPTO[Hardware Crypto]
FLASH[Flash Memory]
end
subgraph "External Interfaces"
MH[Main Hub]
CA[Certificate Authority]
end
BOOT --> EFUSE
BOOT --> HWCRYPTO
BOOT --> SEC
SEC <--> STM
SEC <--> DIAG
SEC --> CRYPTO
SEC --> CERT
CRYPTO --> HWCRYPTO
CRYPTO --> NVM
CERT --> NET
CERT --> CA
NET <-->|mTLS| MH
SEC -.->|Security Events| DIAG
STM -.->|State Changes| SEC
```
### 4.4 Security Enforcement Flow
```mermaid
sequenceDiagram
participant BOOT as Secure Boot
participant SEC as Security Manager
participant CRYPTO as Encryption Engine
participant CERT as Certificate Manager
participant NET as Network Stack
participant MH as Main Hub
Note over BOOT,MH: Security Enforcement Flow
BOOT->>BOOT: verifyFirmwareSignature()
BOOT->>SEC: secureBootComplete(SUCCESS)
SEC->>SEC: initializeSecurityPolicies()
SEC->>CRYPTO: initializeEncryption()
CRYPTO->>CRYPTO: loadEncryptionKeys()
SEC->>CERT: initializeCertificates()
CERT->>CERT: validateDeviceCertificate()
NET->>CERT: establishTLSConnection(main_hub)
CERT->>CERT: performMutualAuthentication()
CERT-->>NET: tlsConnectionEstablished()
NET<->>MH: secureDataExchange()
alt Security Violation Detected
SEC->>SEC: handleSecurityViolation(type)
SEC->>DIAG: logSecurityEvent(violation)
SEC->>STM: triggerSecurityResponse(action)
end
```
## 5. Feature Behavior
### 5.1 Normal Operation Flow
1. **Boot-Time Security:**
- Secure Boot V2 verifies firmware signature using root-of-trust
- Anti-rollback mechanism prevents firmware downgrade attacks
- Flash encryption automatically decrypts application code
- Security Manager initializes and loads security policies
2. **Runtime Security:**
- All communication channels use mTLS with mutual authentication
- Sensitive data encrypted before storage using AES-256
- Certificate validation performed for all external connections
- Security violations monitored and logged continuously
3. **Communication Security:**
- Device certificate presented during TLS handshake
- Server certificate validated against trusted CA chain
- Encrypted data exchange using negotiated cipher suite
- Session keys rotated according to security policy
4. **Violation Response:**
- Security violations detected and classified by severity
- Immediate response actions taken based on violation type
- Escalation logic applied for repeated or coordinated attacks
- Security events logged for audit and analysis
### 5.2 Error Handling
| Error Condition | Detection Method | Response Action |
|----------------|------------------|-----------------|
| **Boot Verification Failure** | Signature validation failure | Enter BOOT_FAILURE state, halt system |
| **Certificate Validation Failure** | X.509 validation error | Reject connection, log security event |
| **Encryption Key Failure** | Key derivation/access error | Enter FAULT state, disable encryption |
| **TLS Handshake Failure** | Protocol negotiation failure | Retry with fallback, log failure |
| **Message Integrity Failure** | MAC/signature verification failure | Discard message, log tampering event |
| **Anti-Rollback Violation** | Version check failure | Prevent boot, log violation |
### 5.3 State-Dependent Behavior
| System State | Feature Behavior |
|-------------|------------------|
| **INIT** | Initialize security components, load certificates and keys |
| **RUNNING** | Full security enforcement, continuous violation monitoring |
| **WARNING** | Enhanced security monitoring, stricter validation |
| **FAULT** | Critical security functions only, preserve security logs |
| **OTA_UPDATE** | Secure OTA validation, maintain security during update |
| **TEARDOWN** | Secure data flush, maintain encryption during shutdown |
| **SERVICE** | Limited security access for diagnostics |
| **BOOT_FAILURE** | Security violation state, no application execution |
## 6. Feature Constraints
### 6.1 Timing Constraints
- **Boot Verification:** Maximum 5 seconds for secure boot completion
- **TLS Handshake:** Maximum 10 seconds for mTLS establishment
- **Certificate Validation:** Maximum 2 seconds per certificate
- **Violation Response:** Maximum 100ms for immediate response actions
### 6.2 Resource Constraints
- **Certificate Storage:** Maximum 2KB per certificate (device, CA)
- **Key Storage:** Secure storage in eFuse or encrypted NVS
- **Memory Usage:** Maximum 64KB for security buffers and state
- **CPU Usage:** Maximum 10% for cryptographic operations
### 6.3 Security Constraints
- **Root-of-Trust:** eFuse-based, one-time programmable
- **Key Protection:** Hardware-protected keys, no plaintext exposure
- **Certificate Validation:** Full chain validation required
- **Encryption Strength:** AES-256 minimum for all encryption
## 7. Interface Specifications
### 7.1 Security Manager Public API
```c
// Security initialization and control
bool secMgr_initialize(void);
bool secMgr_isSecurityEnabled(void);
security_status_t secMgr_getSecurityStatus(void);
// Violation handling
bool secMgr_reportViolation(security_violation_type_t type,
const char* source, const uint8_t* context);
bool secMgr_getViolationHistory(security_violation_event_t* events, size_t* count);
bool secMgr_clearViolationHistory(void);
// Security policy management
bool secMgr_setSecurityPolicy(const security_policy_t* policy);
bool secMgr_getSecurityPolicy(security_policy_t* policy);
bool secMgr_enforceSecurityPolicy(void);
```
### 7.2 Encryption Engine API
```c
// Encryption operations
bool crypto_encrypt(const uint8_t* plaintext, size_t plaintext_len,
const uint8_t* key, uint8_t* ciphertext, size_t* ciphertext_len);
bool crypto_decrypt(const uint8_t* ciphertext, size_t ciphertext_len,
const uint8_t* key, uint8_t* plaintext, size_t* plaintext_len);
// Hash operations
bool crypto_sha256(const uint8_t* data, size_t data_len, uint8_t* hash);
bool crypto_hmac_sha256(const uint8_t* data, size_t data_len,
const uint8_t* key, size_t key_len, uint8_t* hmac);
// Key management
bool crypto_generateKey(key_type_t type, uint8_t* key, size_t key_len);
bool crypto_deriveKey(const uint8_t* master_key, const char* context,
uint8_t* derived_key, size_t key_len);
```
### 7.3 Certificate Manager API
```c
// Certificate operations
bool certMgr_loadDeviceCertificate(const uint8_t* cert_data, size_t cert_len);
bool certMgr_validateCertificate(const uint8_t* cert_data, size_t cert_len);
bool certMgr_getCertificateInfo(certificate_info_t* info);
// TLS integration
bool certMgr_setupTLSContext(tls_context_t* ctx);
bool certMgr_validatePeerCertificate(const uint8_t* peer_cert, size_t cert_len);
bool certMgr_getTLSCredentials(tls_credentials_t* credentials);
```
## 8. Testing and Validation
### 8.1 Unit Testing
- **Secure Boot:** Firmware signature validation with valid/invalid signatures
- **Encryption:** AES-256 encryption/decryption with known test vectors
- **Certificate Validation:** X.509 certificate parsing and validation
- **Violation Handling:** All violation types and response actions
### 8.2 Integration Testing
- **End-to-End Security:** Complete security flow from boot to communication
- **mTLS Integration:** Full TLS handshake with certificate validation
- **State Integration:** Security behavior across all system states
- **Cross-Component Security:** Security enforcement across all components
### 8.3 System Testing
- **Security Penetration Testing:** Simulated attacks and vulnerability assessment
- **Performance Testing:** Cryptographic operations under load
- **Fault Injection:** Security behavior under hardware/software faults
- **Long-Duration Testing:** Security stability over extended operation
### 8.4 Acceptance Criteria
- Secure boot prevents execution of unsigned firmware
- All sensitive data encrypted at rest and in transit
- mTLS successfully established with valid certificates
- Security violations properly detected and responded to
- No security vulnerabilities identified in penetration testing
- Performance impact of security features within acceptable limits
- Complete audit trail of all security events
## 9. Dependencies
### 9.1 Internal Dependencies
- **State Manager:** Security-triggered state transitions
- **Diagnostics:** Security event logging and audit trail
- **Network Stack:** TLS/DTLS transport implementation
- **NVM Driver:** Secure storage for keys and certificates
### 9.2 External Dependencies
- **ESP-IDF Security Features:** Secure Boot V2, Flash Encryption, eFuse
- **Hardware Security Module:** Hardware-accelerated cryptography
- **Certificate Authority:** Certificate validation and management
- **Cryptographic Libraries:** mbedTLS or equivalent for TLS implementation
## 10. Future Enhancements
### 10.1 Planned Improvements
- **Hardware Security Module:** Dedicated HSM for key management
- **Physical Tamper Detection:** Hardware-based tamper detection
- **Advanced Threat Detection:** Machine learning-based anomaly detection
- **Quantum-Resistant Cryptography:** Post-quantum cryptographic algorithms
### 10.2 Scalability Considerations
- **Fleet Security Management:** Centralized security policy management
- **Certificate Automation:** Automated certificate lifecycle management
- **Security Analytics:** Advanced security event correlation and analysis
- **Zero-Trust Architecture:** Comprehensive zero-trust security model
---
**Document Status:** Final for Implementation Phase
**Component Dependencies:** Verified against architecture
**Requirements Traceability:** Complete (SR-SEC, SWR-SEC)
**Next Review:** After component implementation

24
system_arch_final/software/features/README.md
View File

@@ -35,18 +35,18 @@ This directory contains the complete feature specifications for the ASF Sensor H
### Feature Files
| Feature File | Features Covered | Component Dependencies |
|--------------|------------------|----------------------|
| `F-DAQ_Sensor_Data_Acquisition.md` | F-DAQ-001 to F-DAQ-005 | Sensor Manager, Sensor Drivers, Event System |
| `F-DQC_Data_Quality_Calibration.md` | F-DQC-001 to F-DQC-005 | Machine Constant Manager, Sensor Manager |
| `F-COM_Communication.md` | F-COM-001 to F-COM-005 | Main Hub APIs, Network Stack, Event System |
| `F-DIAG_Diagnostics_Health.md` | F-DIAG-001 to F-DIAG-004 | Diagnostics Task, Error Handler, Persistence |
| `F-DATA_Persistence_Management.md` | F-DATA-001 to F-DATA-005 | Data Pool, Persistence, Storage Drivers |
| `F-OTA_Firmware_Update.md` | F-OTA-001 to F-OTA-005 | OTA Manager, State Manager, Security |
| `F-SEC_Security_Safety.md` | F-SEC-001 to F-SEC-004 | Security components, Boot system |
| `F-SYS_System_Management.md` | F-SYS-001 to F-SYS-005 | State Manager, HMI, Event System |
| `F-PWR_Power_Fault_Handling.md` | F-PWR-001 to F-PWR-004 | Error Handler, Power Management |
| `F-HW_Hardware_Abstraction.md` | F-HW-001 to F-HW-003 | Sensor Abstraction Layer, Drivers |
| Feature File | Features Covered | Component Dependencies | Status |
|--------------|------------------|----------------------|--------|
| `F-DAQ_Sensor_Data_Acquisition.md` | F-DAQ-001 to F-DAQ-005 | Sensor Manager, Sensor Drivers, Event System | ✅ Complete |
| `F-DQC_Data_Quality_Calibration.md` | F-DQC-001 to F-DQC-005 | Machine Constant Manager, Sensor Manager | ✅ Complete |
| `F-COM_Communication.md` | F-COM-001 to F-COM-005 | Main Hub APIs, Network Stack, Event System | ✅ Complete |
| `F-DIAG_Diagnostics_Health.md` | F-DIAG-001 to F-DIAG-004 | Diagnostics Task, Error Handler, Persistence | ✅ Complete |
| `F-DATA_Persistence_Management.md` | F-DATA-001 to F-DATA-005 | Data Pool, Persistence, Storage Drivers | ✅ Complete |
| `F-OTA_Firmware_Update.md` | F-OTA-001 to F-OTA-005 | OTA Manager, State Manager, Security | ✅ Complete |
| `F-SEC_Security_Safety.md` | F-SEC-001 to F-SEC-004 | Security Manager, Boot System, Encryption | ✅ Complete |
| `F-SYS_System_Management.md` | F-SYS-001 to F-SYS-005 | State Manager, HMI, Event System | ✅ Complete |
| `F-PWR_Power_Fault_Handling.md` | F-PWR-001 to F-PWR-002 | Power Manager, Error Handler, Persistence | ✅ Complete |
| `F-HW_Hardware_Abstraction.md` | F-HW-001 to F-HW-002 | Sensor Abstraction Layer, GPIO Manager, Drivers | ✅ Complete |
## Traceability

69
system_arch_final/traceability/README.md Normal file
View File

@@ -0,0 +1,69 @@
# Traceability Documentation
# ASF Sensor Hub System Traceability
**Document Type:** Traceability Index
**Version:** 1.0
**Date:** 2025-01-19
## Overview
This directory contains comprehensive traceability documentation for the ASF Sensor Hub system, providing complete mapping between system requirements, software features, components, and interfaces.
## Directory Structure
```
traceability/
├── README.md # This file
├── feature_info/ # Software features traceability
│ ├── feature_traceability.md # Feature mapping documentation
│ └── feature_traceability.csv # Feature mapping data (CSV)
├── component_info/ # Component traceability
│ ├── component_traceability.md # Component mapping documentation
│ └── component_traceability.csv # Component mapping data (CSV)
└── interface_info/ # Software interfaces traceability
├── interface_traceability.md # Interface mapping documentation
└── interface_traceability.csv # Interface mapping data (CSV)
```
## Traceability Scope
### Feature Traceability
- **Software Features:** All 10 software features (F-DAQ, F-DQC, F-COM, etc.)
- **System Features:** Mapping to original system feature groups
- **System Requirements:** Complete SR-XXX requirement coverage
- **Component Mapping:** Which components implement each feature
### Component Traceability
- **Components:** All system components and their responsibilities
- **Interfaces:** Public APIs and integration points
- **System Requirements:** Requirements implemented by each component
- **Software Features:** Features supported by each component
### Interface Traceability
- **Software Interfaces:** All public APIs and communication interfaces
- **Component Providers:** Which components provide each interface
- **Software Features:** Features that use each interface
- **System Requirements:** Requirements addressed by each interface
## Usage
1. **Requirements Analysis:** Use feature traceability to understand requirement coverage
2. **Architecture Review:** Use component traceability to validate system structure
3. **Interface Design:** Use interface traceability for integration planning
4. **Testing:** Use all traceability data for test case development
## Traceability Standards
All traceability documentation follows:
- ISO/IEC/IEEE 29148:2018 requirements engineering standards
- Complete bidirectional traceability
- Consistent ID formats and naming conventions
- Machine-readable CSV format for tool integration
---
**Next Steps:**
1. Review individual traceability documents for completeness
2. Validate mappings against source documentation
3. Update traceability data as system evolves
4. Use for impact analysis during changes

36
system_arch_final/traceability/component_info/component_traceability.csv Normal file
View File

@@ -0,0 +1,36 @@
Component_Name,Location,Layer,Responsibility,System_Requirements,Software_Features,Public_Interfaces,Dependencies,Interface_Type
State Manager,application_layer/business_stack/STM/,Application,"System state machine, state transitions, teardown coordination","SR-SYS-001, SR-SYS-002, SR-SYS-003","F-SYS, F-OTA, F-PWR","stm_getCurrentState(), stm_requestTransition(), stm_initiateTeardown(), stm_registerStateListener()","Event System, Error Handler, OTA Manager",API
Event System,application_layer/business_stack/event_system/,Application,"Publish/subscribe event bus, cross-component communication","SR-SYS-002, SR-COM-005","F-SYS, F-DAQ, F-COM, F-DIAG","event_publish(), event_subscribe(), event_unsubscribe()",None,Event Bus
Sensor Manager,application_layer/business_stack/sensor_manager/,Application,"Sensor lifecycle, acquisition scheduling, data filtering","SR-DAQ-001, SR-DAQ-002, SR-DAQ-003, SR-DAQ-004, SR-DAQ-005","F-DAQ, F-DQC","sensorMgr_initialize(), sensorMgr_startAcquisition(), sensorMgr_getLatestData(), sensorMgr_getSensorState()","Sensor Drivers, Event System, Time Utils, Machine Constant Manager",API
Machine Constant Manager,application_layer/business_stack/machine_constant_manager/,Application,"MC loading, validation, update coordination","SR-DQC-004, SR-DQC-005",F-DQC,"mcMgr_loadMachineConstants(), mcMgr_updateMachineConstants(), mcMgr_getMachineConstants(), mcMgr_validateMachineConstants()","Persistence, Event System",API
OTA Manager,application_layer/business_stack/fw_upgrader/,Application,"OTA negotiation, firmware reception, validation, activation","SR-OTA-001, SR-OTA-002, SR-OTA-003, SR-OTA-004, SR-OTA-005",F-OTA,"ota_handleRequest(), ota_receiveFirmwareChunk(), ota_validateFirmware(), ota_activateFirmware()","Network Stack, Persistence, State Manager, Security Manager",API
Main Hub APIs,application_layer/business_stack/main_hub_apis/,Application,"Main Hub communication protocol, message handling","SR-COM-001, SR-COM-002, SR-COM-003",F-COM,"mainHubAPI_initialize(), mainHubAPI_sendSensorData(), mainHubAPI_handleRequest(), mainHubAPI_getConnectionStatus()","Network Stack, Data Pool, Event System",API
Data Pool,application_layer/DP_stack/data_pool/,Application,"Runtime data storage, latest sensor values, system state","SR-DATA-002, SR-PERF-003","F-DATA, F-DAQ, F-COM","dataPool_initialize(), dataPool_updateSensorData(), dataPool_getLatestData(), dataPool_getAllSensorData()",Event System,API
Persistence,application_layer/DP_stack/persistence/,Application,"Persistent storage abstraction, serialization, wear management","SR-DATA-001, SR-DATA-002, SR-DATA-003, SR-DATA-004, SR-DATA-005","F-DATA, F-DIAG, F-DQC, F-OTA","persistence_writeSensorData(), persistence_writeDiagnostic(), persistence_writeMachineConstants(), persistence_flushCriticalData()","SD Card Driver, NVM Driver",API
Diagnostics Task,application_layer/diag_task/,Application,"Diagnostic event collection, storage, query interface","SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004",F-DIAG,"diagTask_initialize(), diagTask_reportEvent(), diagTask_getEvents(), diagTask_createSession()","Persistence, Event System, Security Manager",API
Error Handler,application_layer/error_handler/,Application,"Fault classification, escalation, state transition triggers","SR-PWR-003, SR-PWR-004, SR-DIAG-001","F-PWR, F-DIAG, F-SYS","errorHandler_reportError(), errorHandler_classifyError(), errorHandler_getErrorStatistics()","State Manager, Diagnostics Task",API
Network Stack,drivers/network_stack/,Driver,"Wi-Fi/Zigbee/LoRa communication, TLS/DTLS protocols","SR-COM-002, SR-COM-004, SR-COM-005","F-COM, F-SEC, F-OTA","networkStack_initialize(), networkStack_connect(), networkStack_sendData(), networkStack_setupTLS()","Wi-Fi Wrapper, Socket Abstraction",API
SD Card Driver,drivers/SDcard/,Driver,"SD card interface, FAT32 file system operations","SR-DATA-001, SR-DATA-005","F-DATA, F-OTA","sdcard_initialize(), sdcard_mount(), sdcard_writeFile(), sdcard_readFile()",SPI Wrapper,API
NVM Driver,drivers/nvm/,Driver,"Non-volatile memory (NVS) operations","SR-DATA-004, SR-SEC-003","F-DATA, F-SEC, F-DQC","nvm_initialize(), nvm_writeBlob(), nvm_readBlob(), nvm_getStats()",ESP-IDF NVS,API
Sensor Drivers,drivers/sensors/,Driver,"Hardware-specific sensor implementations","SR-DAQ-001, SR-HW-001","F-DAQ, F-HW","sensor_initialize(), sensor_read(), sensor_calibrate(), sensor_healthCheck()","I2C/SPI/UART/ADC Wrappers",API
Temperature Sensor,drivers/sensors/temprature/,Driver,"Temperature sensor hardware interface",SR-DAQ-001,F-DAQ,"temp_initialize(), temp_read(), temp_calibrate()","I2C Wrapper, ADC Wrapper",Hardware
Humidity Sensor,drivers/sensors/humidity/,Driver,"Humidity sensor hardware interface",SR-DAQ-001,F-DAQ,"humidity_initialize(), humidity_read(), humidity_calibrate()",I2C Wrapper,Hardware
CO2 Sensor,drivers/sensors/co2/,Driver,"CO2 sensor hardware interface",SR-DAQ-001,F-DAQ,"co2_initialize(), co2_read(), co2_calibrate()","UART Wrapper, I2C Wrapper",Hardware
Ammonia Sensor,drivers/sensors/ammonia/,Driver,"Ammonia sensor hardware interface",SR-DAQ-001,F-DAQ,"ammonia_initialize(), ammonia_read(), ammonia_calibrate()","ADC Wrapper, I2C Wrapper",Hardware
VOC Sensor,drivers/sensors/voc/,Driver,"VOC sensor hardware interface",SR-DAQ-001,F-DAQ,"voc_initialize(), voc_read(), voc_calibrate()",I2C Wrapper,Hardware
Light Sensor,drivers/sensors/light/,Driver,"Light sensor hardware interface",SR-DAQ-001,F-DAQ,"light_initialize(), light_read(), light_calibrate()","ADC Wrapper, I2C Wrapper",Hardware
GPIO Wrapper,ESP_IDF_FW_wrappers/gpio/,ESP-IDF Wrapper,"GPIO abstraction and discipline enforcement","SR-HW-002, SR-HW-003",F-HW,"gpio_initialize(), gpio_setDirection(), gpio_setLevel(), gpio_getLevel()",ESP-IDF GPIO,Hardware
I2C Wrapper,ESP_IDF_FW_wrappers/i2c/,ESP-IDF Wrapper,"I2C interface abstraction",SR-HW-002,"F-HW, F-DAQ","i2c_initialize(), i2c_write(), i2c_read(), i2c_writeRead()",ESP-IDF I2C,Hardware
SPI Wrapper,ESP_IDF_FW_wrappers/spi/,ESP-IDF Wrapper,"SPI interface abstraction",SR-HW-002,"F-HW, F-DATA","spi_initialize(), spi_transmit(), spi_receive(), spi_transmitReceive()",ESP-IDF SPI,Hardware
UART Wrapper,ESP_IDF_FW_wrappers/uart/,ESP-IDF Wrapper,"UART interface abstraction",SR-HW-002,"F-HW, F-DAQ","uart_initialize(), uart_write(), uart_read(), uart_flush()",ESP-IDF UART,Hardware
ADC Wrapper,ESP_IDF_FW_wrappers/adc/,ESP-IDF Wrapper,"ADC interface abstraction",SR-HW-002,"F-HW, F-DAQ, F-PWR","adc_initialize(), adc_readRaw(), adc_readVoltage(), adc_calibrate()",ESP-IDF ADC,Hardware
Wi-Fi Wrapper,ESP_IDF_FW_wrappers/wifi/,ESP-IDF Wrapper,"Wi-Fi interface abstraction",SR-COM-001,F-COM,"wifi_initialize(), wifi_connect(), wifi_disconnect(), wifi_getStatus()",ESP-IDF Wi-Fi,Hardware
Task Abstraction,os/task/,OS,"Task management and scheduling abstraction",SR-PERF-001,All Features,"task_create(), task_delete(), task_suspend(), task_resume()",FreeRTOS,OS
Software Timer,os/swtimer/,OS,"Software timer abstraction",SR-PERF-001,All Features,"swtimer_create(), swtimer_start(), swtimer_stop(), swtimer_delete()",FreeRTOS,OS
Logger,utils/logger/,Utility,"Debug and diagnostic logging",SR-DIAG-002,All Features,"logger_initialize(), logger_log(), logger_setLevel(), logger_flush()",None,Utility
Time Utils,utils/time_utils/,Utility,"Timestamp generation and time management",SR-DAQ-004,"F-DAQ, F-DIAG","timeUtils_initialize(), timeUtils_getCurrentTimestamp(), timeUtils_formatTimestamp()",ESP-IDF System Time,Utility
Security Manager,application_layer/security/,Application,"Security policy enforcement, violation handling","SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004",F-SEC,"secMgr_initialize(), secMgr_reportViolation(), secMgr_setSecurityPolicy()","Encryption Engine, Certificate Manager, Diagnostics",API
Encryption Engine,application_layer/security/crypto/,Application,"Cryptographic operations, key management","SR-SEC-002, SR-SEC-003",F-SEC,"crypto_encrypt(), crypto_decrypt(), crypto_sha256(), crypto_generateKey()","Hardware Crypto, NVM Driver",API
Certificate Manager,application_layer/security/cert_mgr/,Application,"Certificate validation, lifecycle management",SR-SEC-003,F-SEC,"certMgr_loadDeviceCertificate(), certMgr_validateCertificate(), certMgr_setupTLSContext()","Network Stack, Encryption Engine",API
Power Manager,application_layer/power_manager/,Application,"Power event coordination, recovery management","SR-PWR-001, SR-PWR-002",F-PWR,"powerMgr_initialize(), powerMgr_getCurrentVoltage(), powerMgr_triggerEmergencyFlush()","ADC Driver, Persistence, State Manager",API
HMI Manager,application_layer/hmi/,Application,"Local display and button interface management",SR-SYS-004,F-SYS,"hmi_initialize(), hmi_updateDisplay(), hmi_handleButtonPress()","OLED Driver, Button Driver, Event System",API
1 Component_Name Location Layer Responsibility System_Requirements Software_Features Public_Interfaces Dependencies Interface_Type
2 State Manager application_layer/business_stack/STM/ Application System state machine, state transitions, teardown coordination SR-SYS-001, SR-SYS-002, SR-SYS-003 F-SYS, F-OTA, F-PWR stm_getCurrentState(), stm_requestTransition(), stm_initiateTeardown(), stm_registerStateListener() Event System, Error Handler, OTA Manager API
3 Event System application_layer/business_stack/event_system/ Application Publish/subscribe event bus, cross-component communication SR-SYS-002, SR-COM-005 F-SYS, F-DAQ, F-COM, F-DIAG event_publish(), event_subscribe(), event_unsubscribe() None Event Bus
4 Sensor Manager application_layer/business_stack/sensor_manager/ Application Sensor lifecycle, acquisition scheduling, data filtering SR-DAQ-001, SR-DAQ-002, SR-DAQ-003, SR-DAQ-004, SR-DAQ-005 F-DAQ, F-DQC sensorMgr_initialize(), sensorMgr_startAcquisition(), sensorMgr_getLatestData(), sensorMgr_getSensorState() Sensor Drivers, Event System, Time Utils, Machine Constant Manager API
5 Machine Constant Manager application_layer/business_stack/machine_constant_manager/ Application MC loading, validation, update coordination SR-DQC-004, SR-DQC-005 F-DQC mcMgr_loadMachineConstants(), mcMgr_updateMachineConstants(), mcMgr_getMachineConstants(), mcMgr_validateMachineConstants() Persistence, Event System API
6 OTA Manager application_layer/business_stack/fw_upgrader/ Application OTA negotiation, firmware reception, validation, activation SR-OTA-001, SR-OTA-002, SR-OTA-003, SR-OTA-004, SR-OTA-005 F-OTA ota_handleRequest(), ota_receiveFirmwareChunk(), ota_validateFirmware(), ota_activateFirmware() Network Stack, Persistence, State Manager, Security Manager API
7 Main Hub APIs application_layer/business_stack/main_hub_apis/ Application Main Hub communication protocol, message handling SR-COM-001, SR-COM-002, SR-COM-003 F-COM mainHubAPI_initialize(), mainHubAPI_sendSensorData(), mainHubAPI_handleRequest(), mainHubAPI_getConnectionStatus() Network Stack, Data Pool, Event System API
8 Data Pool application_layer/DP_stack/data_pool/ Application Runtime data storage, latest sensor values, system state SR-DATA-002, SR-PERF-003 F-DATA, F-DAQ, F-COM dataPool_initialize(), dataPool_updateSensorData(), dataPool_getLatestData(), dataPool_getAllSensorData() Event System API
9 Persistence application_layer/DP_stack/persistence/ Application Persistent storage abstraction, serialization, wear management SR-DATA-001, SR-DATA-002, SR-DATA-003, SR-DATA-004, SR-DATA-005 F-DATA, F-DIAG, F-DQC, F-OTA persistence_writeSensorData(), persistence_writeDiagnostic(), persistence_writeMachineConstants(), persistence_flushCriticalData() SD Card Driver, NVM Driver API
10 Diagnostics Task application_layer/diag_task/ Application Diagnostic event collection, storage, query interface SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004 F-DIAG diagTask_initialize(), diagTask_reportEvent(), diagTask_getEvents(), diagTask_createSession() Persistence, Event System, Security Manager API
11 Error Handler application_layer/error_handler/ Application Fault classification, escalation, state transition triggers SR-PWR-003, SR-PWR-004, SR-DIAG-001 F-PWR, F-DIAG, F-SYS errorHandler_reportError(), errorHandler_classifyError(), errorHandler_getErrorStatistics() State Manager, Diagnostics Task API
12 Network Stack drivers/network_stack/ Driver Wi-Fi/Zigbee/LoRa communication, TLS/DTLS protocols SR-COM-002, SR-COM-004, SR-COM-005 F-COM, F-SEC, F-OTA networkStack_initialize(), networkStack_connect(), networkStack_sendData(), networkStack_setupTLS() Wi-Fi Wrapper, Socket Abstraction API
13 SD Card Driver drivers/SDcard/ Driver SD card interface, FAT32 file system operations SR-DATA-001, SR-DATA-005 F-DATA, F-OTA sdcard_initialize(), sdcard_mount(), sdcard_writeFile(), sdcard_readFile() SPI Wrapper API
14 NVM Driver drivers/nvm/ Driver Non-volatile memory (NVS) operations SR-DATA-004, SR-SEC-003 F-DATA, F-SEC, F-DQC nvm_initialize(), nvm_writeBlob(), nvm_readBlob(), nvm_getStats() ESP-IDF NVS API
15 Sensor Drivers drivers/sensors/ Driver Hardware-specific sensor implementations SR-DAQ-001, SR-HW-001 F-DAQ, F-HW sensor_initialize(), sensor_read(), sensor_calibrate(), sensor_healthCheck() I2C/SPI/UART/ADC Wrappers API
16 Temperature Sensor drivers/sensors/temprature/ Driver Temperature sensor hardware interface SR-DAQ-001 F-DAQ temp_initialize(), temp_read(), temp_calibrate() I2C Wrapper, ADC Wrapper Hardware
17 Humidity Sensor drivers/sensors/humidity/ Driver Humidity sensor hardware interface SR-DAQ-001 F-DAQ humidity_initialize(), humidity_read(), humidity_calibrate() I2C Wrapper Hardware
18 CO2 Sensor drivers/sensors/co2/ Driver CO2 sensor hardware interface SR-DAQ-001 F-DAQ co2_initialize(), co2_read(), co2_calibrate() UART Wrapper, I2C Wrapper Hardware
19 Ammonia Sensor drivers/sensors/ammonia/ Driver Ammonia sensor hardware interface SR-DAQ-001 F-DAQ ammonia_initialize(), ammonia_read(), ammonia_calibrate() ADC Wrapper, I2C Wrapper Hardware
20 VOC Sensor drivers/sensors/voc/ Driver VOC sensor hardware interface SR-DAQ-001 F-DAQ voc_initialize(), voc_read(), voc_calibrate() I2C Wrapper Hardware
21 Light Sensor drivers/sensors/light/ Driver Light sensor hardware interface SR-DAQ-001 F-DAQ light_initialize(), light_read(), light_calibrate() ADC Wrapper, I2C Wrapper Hardware
22 GPIO Wrapper ESP_IDF_FW_wrappers/gpio/ ESP-IDF Wrapper GPIO abstraction and discipline enforcement SR-HW-002, SR-HW-003 F-HW gpio_initialize(), gpio_setDirection(), gpio_setLevel(), gpio_getLevel() ESP-IDF GPIO Hardware
23 I2C Wrapper ESP_IDF_FW_wrappers/i2c/ ESP-IDF Wrapper I2C interface abstraction SR-HW-002 F-HW, F-DAQ i2c_initialize(), i2c_write(), i2c_read(), i2c_writeRead() ESP-IDF I2C Hardware
24 SPI Wrapper ESP_IDF_FW_wrappers/spi/ ESP-IDF Wrapper SPI interface abstraction SR-HW-002 F-HW, F-DATA spi_initialize(), spi_transmit(), spi_receive(), spi_transmitReceive() ESP-IDF SPI Hardware
25 UART Wrapper ESP_IDF_FW_wrappers/uart/ ESP-IDF Wrapper UART interface abstraction SR-HW-002 F-HW, F-DAQ uart_initialize(), uart_write(), uart_read(), uart_flush() ESP-IDF UART Hardware
26 ADC Wrapper ESP_IDF_FW_wrappers/adc/ ESP-IDF Wrapper ADC interface abstraction SR-HW-002 F-HW, F-DAQ, F-PWR adc_initialize(), adc_readRaw(), adc_readVoltage(), adc_calibrate() ESP-IDF ADC Hardware
27 Wi-Fi Wrapper ESP_IDF_FW_wrappers/wifi/ ESP-IDF Wrapper Wi-Fi interface abstraction SR-COM-001 F-COM wifi_initialize(), wifi_connect(), wifi_disconnect(), wifi_getStatus() ESP-IDF Wi-Fi Hardware
28 Task Abstraction os/task/ OS Task management and scheduling abstraction SR-PERF-001 All Features task_create(), task_delete(), task_suspend(), task_resume() FreeRTOS OS
29 Software Timer os/swtimer/ OS Software timer abstraction SR-PERF-001 All Features swtimer_create(), swtimer_start(), swtimer_stop(), swtimer_delete() FreeRTOS OS
30 Logger utils/logger/ Utility Debug and diagnostic logging SR-DIAG-002 All Features logger_initialize(), logger_log(), logger_setLevel(), logger_flush() None Utility
31 Time Utils utils/time_utils/ Utility Timestamp generation and time management SR-DAQ-004 F-DAQ, F-DIAG timeUtils_initialize(), timeUtils_getCurrentTimestamp(), timeUtils_formatTimestamp() ESP-IDF System Time Utility
32 Security Manager application_layer/security/ Application Security policy enforcement, violation handling SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 F-SEC secMgr_initialize(), secMgr_reportViolation(), secMgr_setSecurityPolicy() Encryption Engine, Certificate Manager, Diagnostics API
33 Encryption Engine application_layer/security/crypto/ Application Cryptographic operations, key management SR-SEC-002, SR-SEC-003 F-SEC crypto_encrypt(), crypto_decrypt(), crypto_sha256(), crypto_generateKey() Hardware Crypto, NVM Driver API
34 Certificate Manager application_layer/security/cert_mgr/ Application Certificate validation, lifecycle management SR-SEC-003 F-SEC certMgr_loadDeviceCertificate(), certMgr_validateCertificate(), certMgr_setupTLSContext() Network Stack, Encryption Engine API
35 Power Manager application_layer/power_manager/ Application Power event coordination, recovery management SR-PWR-001, SR-PWR-002 F-PWR powerMgr_initialize(), powerMgr_getCurrentVoltage(), powerMgr_triggerEmergencyFlush() ADC Driver, Persistence, State Manager API
36 HMI Manager application_layer/hmi/ Application Local display and button interface management SR-SYS-004 F-SYS hmi_initialize(), hmi_updateDisplay(), hmi_handleButtonPress() OLED Driver, Button Driver, Event System API

526
system_arch_final/traceability/component_info/component_traceability.md Normal file
View File

@@ -0,0 +1,526 @@
# Component Traceability
# ASF Sensor Hub Component Mapping
**Document Type:** Component Traceability Documentation
**Version:** 1.0
**Date:** 2025-01-19
## Overview
This document provides complete traceability mapping for all system components in the ASF Sensor Hub, showing relationships between components, their interfaces, system requirements, and software features.
## Component Architecture Overview
```
Application Layer
├── Business Stack
│ ├── State Manager (STM)
│ ├── Event System
│ ├── Sensor Manager
│ ├── Machine Constant Manager
│ ├── OTA Manager (fw_upgrader)
│ └── Main Hub APIs
├── DP Stack
│ ├── Data Pool
│ └── Persistence
├── Diagnostics Task
└── Error Handler
Drivers Layer
├── Network Stack
├── Diagnostic Protocol Stack
├── SD Card Driver
├── NVM Driver
└── Sensor Drivers
├── Temperature
├── Humidity
├── CO2
├── Ammonia
├── VOC
└── Light
ESP-IDF Wrappers
├── GPIO Wrapper
├── I2C Wrapper
├── SPI Wrapper
├── UART Wrapper
├── ADC Wrapper
└── Wi-Fi Wrapper
OS Layer
├── Task Abstraction
└── Software Timer
Utilities
├── Logger
└── Time Utils
```
## Component Details
### Application Layer Components
#### State Manager (STM)
**Location:** `application_layer/business_stack/STM/`
**Responsibility:** System state machine, state transitions, teardown coordination
**System Requirements:**
- SR-SYS-001: System State Machine
- SR-SYS-002: State-Aware Operation
- SR-SYS-003: Controlled Teardown
**Software Features:** F-SYS, F-OTA, F-PWR
**Public Interfaces:**
- `stm_getCurrentState()`
- `stm_requestTransition()`
- `stm_initiateTeardown()`
- `stm_registerStateListener()`
**Dependencies:** Event System, Error Handler, OTA Manager
#### Event System
**Location:** `application_layer/business_stack/event_system/`
**Responsibility:** Publish/subscribe event bus, cross-component communication
**System Requirements:**
- SR-SYS-002: State-Aware Operation (coordination)
- SR-COM-005: Communication Fault Tolerance (event distribution)
**Software Features:** F-SYS, F-DAQ, F-COM, F-DIAG
**Public Interfaces:**
- `event_publish()`
- `event_subscribe()`
- `event_unsubscribe()`
**Dependencies:** None (core infrastructure)
#### Sensor Manager
**Location:** `application_layer/business_stack/sensor_manager/`
**Responsibility:** Sensor lifecycle, acquisition scheduling, data filtering
**System Requirements:**
- SR-DAQ-001: Multi-Sensor Support
- SR-DAQ-002: High-Frequency Sampling
- SR-DAQ-003: Local Data Filtering
- SR-DAQ-004: Timestamped Data Generation
- SR-DAQ-005: Sensor State Management
**Software Features:** F-DAQ, F-DQC
**Public Interfaces:**
- `sensorMgr_initialize()`
- `sensorMgr_startAcquisition()`
- `sensorMgr_getLatestData()`
- `sensorMgr_getSensorState()`
**Dependencies:** Sensor Drivers, Event System, Time Utils, Machine Constant Manager
#### Machine Constant Manager
**Location:** `application_layer/business_stack/machine_constant_manager/`
**Responsibility:** MC loading, validation, update coordination
**System Requirements:**
- SR-DQC-004: Machine Constants Management
- SR-DQC-005: Calibration Parameter Application
**Software Features:** F-DQC
**Public Interfaces:**
- `mcMgr_loadMachineConstants()`
- `mcMgr_updateMachineConstants()`
- `mcMgr_getMachineConstants()`
- `mcMgr_validateMachineConstants()`
**Dependencies:** Persistence, Event System
#### OTA Manager (fw_upgrader)
**Location:** `application_layer/business_stack/fw_upgrader/`
**Responsibility:** OTA negotiation, firmware reception, validation, activation
**System Requirements:**
- SR-OTA-001: OTA Update Negotiation
- SR-OTA-002: Firmware Reception and Storage
- SR-OTA-003: Firmware Integrity Validation
- SR-OTA-004: Safe Firmware Activation
- SR-OTA-005: OTA State Management
**Software Features:** F-OTA
**Public Interfaces:**
- `ota_handleRequest()`
- `ota_receiveFirmwareChunk()`
- `ota_validateFirmware()`
- `ota_activateFirmware()`
**Dependencies:** Network Stack, Persistence, State Manager, Security Manager
#### Main Hub APIs
**Location:** `application_layer/business_stack/main_hub_apis/`
**Responsibility:** Main Hub communication protocol, message handling
**System Requirements:**
- SR-COM-001: Main Hub Communication
- SR-COM-002: Secure Communication Protocols
- SR-COM-003: On-Demand Data Broadcasting
**Software Features:** F-COM
**Public Interfaces:**
- `mainHubAPI_initialize()`
- `mainHubAPI_sendSensorData()`
- `mainHubAPI_handleRequest()`
- `mainHubAPI_getConnectionStatus()`
**Dependencies:** Network Stack, Data Pool, Event System
#### Data Pool
**Location:** `application_layer/DP_stack/data_pool/`
**Responsibility:** Runtime data storage, latest sensor values, system state
**System Requirements:**
- SR-DATA-002: Data Persistence Abstraction (runtime data)
- SR-PERF-003: Memory Usage (efficient data storage)
**Software Features:** F-DATA, F-DAQ, F-COM
**Public Interfaces:**
- `dataPool_initialize()`
- `dataPool_updateSensorData()`
- `dataPool_getLatestData()`
- `dataPool_getAllSensorData()`
**Dependencies:** Event System
#### Persistence
**Location:** `application_layer/DP_stack/persistence/`
**Responsibility:** Persistent storage abstraction, serialization, wear management
**System Requirements:**
- SR-DATA-001: Persistent Sensor Data Storage
- SR-DATA-002: Data Persistence Abstraction
- SR-DATA-003: Safe Data Handling During Transitions
- SR-DATA-004: Data Integrity Protection
- SR-DATA-005: Storage Capacity Management
**Software Features:** F-DATA, F-DIAG, F-DQC, F-OTA
**Public Interfaces:**
- `persistence_writeSensorData()`
- `persistence_writeDiagnostic()`
- `persistence_writeMachineConstants()`
- `persistence_flushCriticalData()`
**Dependencies:** SD Card Driver, NVM Driver
#### Diagnostics Task
**Location:** `application_layer/diag_task/`
**Responsibility:** Diagnostic event collection, storage, query interface
**System Requirements:**
- SR-DIAG-001: Diagnostic Code Management
- SR-DIAG-002: Diagnostic Data Storage
- SR-DIAG-003: Diagnostic Session Support
- SR-DIAG-004: Layered Watchdog System
**Software Features:** F-DIAG
**Public Interfaces:**
- `diagTask_initialize()`
- `diagTask_reportEvent()`
- `diagTask_getEvents()`
- `diagTask_createSession()`
**Dependencies:** Persistence, Event System, Security Manager
#### Error Handler
**Location:** `application_layer/error_handler/`
**Responsibility:** Fault classification, escalation, state transition triggers
**System Requirements:**
- SR-PWR-003: Fault Classification
- SR-PWR-004: Fault Escalation
- SR-DIAG-001: Diagnostic Code Management (fault reporting)
**Software Features:** F-PWR, F-DIAG, F-SYS
**Public Interfaces:**
- `errorHandler_reportError()`
- `errorHandler_classifyError()`
- `errorHandler_getErrorStatistics()`
**Dependencies:** State Manager, Diagnostics Task
### Driver Layer Components
#### Network Stack
**Location:** `drivers/network_stack/`
**Responsibility:** Wi-Fi/Zigbee/LoRa communication, TLS/DTLS protocols
**System Requirements:**
- SR-COM-002: Secure Communication Protocols
- SR-COM-004: Peer Communication
- SR-COM-005: Communication Fault Tolerance
**Software Features:** F-COM, F-SEC, F-OTA
**Public Interfaces:**
- `networkStack_initialize()`
- `networkStack_connect()`
- `networkStack_sendData()`
- `networkStack_setupTLS()`
**Dependencies:** Wi-Fi Wrapper, Socket Abstraction
#### SD Card Driver
**Location:** `drivers/SDcard/`
**Responsibility:** SD card interface, FAT32 file system operations
**System Requirements:**
- SR-DATA-001: Persistent Sensor Data Storage
- SR-DATA-005: Storage Capacity Management
**Software Features:** F-DATA, F-OTA
**Public Interfaces:**
- `sdcard_initialize()`
- `sdcard_mount()`
- `sdcard_writeFile()`
- `sdcard_readFile()`
**Dependencies:** SPI Wrapper
#### NVM Driver
**Location:** `drivers/nvm/`
**Responsibility:** Non-volatile memory (NVS) operations
**System Requirements:**
- SR-DATA-004: Data Integrity Protection
- SR-SEC-003: Certificate Management (secure storage)
**Software Features:** F-DATA, F-SEC, F-DQC
**Public Interfaces:**
- `nvm_initialize()`
- `nvm_writeBlob()`
- `nvm_readBlob()`
- `nvm_getStats()`
**Dependencies:** ESP-IDF NVS
#### Sensor Drivers
**Location:** `drivers/sensors/`
**Responsibility:** Hardware-specific sensor implementations
**System Requirements:**
- SR-DAQ-001: Multi-Sensor Support
- SR-HW-001: Sensor Abstraction Layer
**Software Features:** F-DAQ, F-HW
**Public Interfaces:**
- `sensor_initialize()`
- `sensor_read()`
- `sensor_calibrate()`
- `sensor_healthCheck()`
**Dependencies:** I2C/SPI/UART/ADC Wrappers
### ESP-IDF Wrapper Components
#### GPIO Wrapper
**Location:** `ESP_IDF_FW_wrappers/gpio/`
**Responsibility:** GPIO abstraction and discipline enforcement
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction
- SR-HW-003: GPIO Discipline
**Software Features:** F-HW
**Public Interfaces:**
- `gpio_initialize()`
- `gpio_setDirection()`
- `gpio_setLevel()`
- `gpio_getLevel()`
**Dependencies:** ESP-IDF GPIO
#### I2C Wrapper
**Location:** `ESP_IDF_FW_wrappers/i2c/`
**Responsibility:** I2C interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction
**Software Features:** F-HW, F-DAQ
**Public Interfaces:**
- `i2c_initialize()`
- `i2c_write()`
- `i2c_read()`
- `i2c_writeRead()`
**Dependencies:** ESP-IDF I2C
#### SPI Wrapper
**Location:** `ESP_IDF_FW_wrappers/spi/`
**Responsibility:** SPI interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction
**Software Features:** F-HW, F-DATA
**Public Interfaces:**
- `spi_initialize()`
- `spi_transmit()`
- `spi_receive()`
- `spi_transmitReceive()`
**Dependencies:** ESP-IDF SPI
#### UART Wrapper
**Location:** `ESP_IDF_FW_wrappers/uart/`
**Responsibility:** UART interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction
**Software Features:** F-HW, F-DAQ
**Public Interfaces:**
- `uart_initialize()`
- `uart_write()`
- `uart_read()`
- `uart_flush()`
**Dependencies:** ESP-IDF UART
#### ADC Wrapper
**Location:** `ESP_IDF_FW_wrappers/adc/`
**Responsibility:** ADC interface abstraction
**System Requirements:**
- SR-HW-002: Hardware Interface Abstraction
**Software Features:** F-HW, F-DAQ, F-PWR
**Public Interfaces:**
- `adc_initialize()`
- `adc_readRaw()`
- `adc_readVoltage()`
- `adc_calibrate()`
**Dependencies:** ESP-IDF ADC
#### Wi-Fi Wrapper
**Location:** `ESP_IDF_FW_wrappers/wifi/`
**Responsibility:** Wi-Fi interface abstraction
**System Requirements:**
- SR-COM-001: Main Hub Communication (transport)
**Software Features:** F-COM
**Public Interfaces:**
- `wifi_initialize()`
- `wifi_connect()`
- `wifi_disconnect()`
- `wifi_getStatus()`
**Dependencies:** ESP-IDF Wi-Fi
### Utility Components
#### Logger
**Location:** `utils/logger/`
**Responsibility:** Debug and diagnostic logging
**System Requirements:**
- SR-DIAG-002: Diagnostic Data Storage (debug logs)
**Software Features:** All features (cross-cutting)
**Public Interfaces:**
- `logger_initialize()`
- `logger_log()`
- `logger_setLevel()`
- `logger_flush()`
**Dependencies:** None
#### Time Utils
**Location:** `utils/time_utils/`
**Responsibility:** Timestamp generation and time management
**System Requirements:**
- SR-DAQ-004: Timestamped Data Generation
**Software Features:** F-DAQ, F-DIAG
**Public Interfaces:**
- `timeUtils_initialize()`
- `timeUtils_getCurrentTimestamp()`
- `timeUtils_formatTimestamp()`
**Dependencies:** ESP-IDF System Time
## Component Interface Matrix
| Component | Provides Interfaces To | Consumes Interfaces From |
|-----------|----------------------|--------------------------|
| State Manager | All Components | Event System, Error Handler |
| Event System | All Components | None |
| Sensor Manager | Data Pool, Main Hub APIs | Sensor Drivers, Event System, Time Utils |
| Machine Constant Manager | Sensor Manager, Diagnostics | Persistence, Event System |
| OTA Manager | Main Hub APIs | Network Stack, Persistence, State Manager |
| Main Hub APIs | Event System | Network Stack, Data Pool |
| Data Pool | Main Hub APIs, Persistence | Event System |
| Persistence | All Data Producers | SD Card Driver, NVM Driver |
| Diagnostics Task | Engineering Sessions | Persistence, Event System |
| Error Handler | State Manager, Diagnostics | State Manager |
## Component Dependencies Graph
```mermaid
graph TB
subgraph "Application Layer"
STM[State Manager]
ES[Event System]
SM[Sensor Manager]
MCM[Machine Constant Manager]
OTA[OTA Manager]
API[Main Hub APIs]
DP[Data Pool]
PERSIST[Persistence]
DIAG[Diagnostics Task]
ERR[Error Handler]
end
subgraph "Drivers"
NET[Network Stack]
SD[SD Card Driver]
NVM[NVM Driver]
SENSORS[Sensor Drivers]
end
subgraph "ESP-IDF Wrappers"
GPIO[GPIO Wrapper]
I2C[I2C Wrapper]
SPI[SPI Wrapper]
UART[UART Wrapper]
ADC[ADC Wrapper]
WIFI[Wi-Fi Wrapper]
end
subgraph "Utilities"
LOG[Logger]
TIME[Time Utils]
end
STM --> ES
SM --> ES
SM --> SENSORS
SM --> TIME
MCM --> PERSIST
OTA --> NET
OTA --> PERSIST
API --> NET
API --> DP
ES --> DP
DP --> PERSIST
PERSIST --> SD
PERSIST --> NVM
DIAG --> PERSIST
DIAG --> ES
ERR --> STM
ERR --> DIAG
SENSORS --> I2C
SENSORS --> SPI
SENSORS --> UART
SENSORS --> ADC
NET --> WIFI
SD --> SPI
```
## Component Testing Strategy
### Unit Testing
- **Individual Components:** Test each component in isolation with mocked dependencies
- **Interface Contracts:** Validate all public interface contracts
- **Error Handling:** Test error conditions and fault scenarios
### Integration Testing
- **Component Pairs:** Test interactions between dependent components
- **Data Flow:** Validate data flow through component chains
- **Event Propagation:** Test event system integration
### System Testing
- **End-to-End:** Test complete feature flows across multiple components
- **Performance:** Validate timing and resource constraints
- **Fault Injection:** Test system behavior under component failures
---
**Document Status:** Complete and Validated
**Last Updated:** 2025-01-19
**Next Review:** After component implementation begins

11
system_arch_final/traceability/feature_info/feature_traceability.csv Normal file
View File

@@ -0,0 +1,11 @@
Feature_ID,Feature_Name,Sub_Features,System_Feature_Group,System_Requirements,Primary_Components,Supporting_Components,Status,Dependencies
F-DAQ,Sensor Data Acquisition,"F-DAQ-001, F-DAQ-002, F-DAQ-003, F-DAQ-004, F-DAQ-005",FG-DAQ,"SR-DAQ-001, SR-DAQ-002, SR-DAQ-003, SR-DAQ-004, SR-DAQ-005","Sensor Manager, Sensor Drivers, Event System, Data Pool","Time Utils, Logger, Machine Constant Manager",Complete,"F-HW, F-DATA"
F-DQC,Data Quality & Calibration,"F-DQC-001, F-DQC-002, F-DQC-003, F-DQC-004, F-DQC-005",FG-DQC,"SR-DQC-001, SR-DQC-002, SR-DQC-003, SR-DQC-004, SR-DQC-005","Machine Constant Manager, Sensor Manager, Persistence","Event System, Diagnostics, State Manager",Complete,"F-DAQ, F-DATA"
F-COM,Communication,"F-COM-001, F-COM-002, F-COM-003, F-COM-004, F-COM-005",FG-COM,"SR-COM-001, SR-COM-002, SR-COM-003, SR-COM-004, SR-COM-005","Main Hub APIs, Network Stack, Event System","Data Pool, Diagnostics, State Manager",Complete,"F-SEC, F-DATA"
F-DIAG,Diagnostics & Health Monitoring,"F-DIAG-001, F-DIAG-002, F-DIAG-003, F-DIAG-004",FG-DIAG,"SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004","Diagnostics Task, Error Handler, Persistence","Event System, Security Manager, State Manager",Complete,"F-DATA, F-SYS"
F-DATA,Persistence & Data Management,"F-DATA-001, F-DATA-002, F-DATA-003, F-DATA-004, F-DATA-005",FG-DATA,"SR-DATA-001, SR-DATA-002, SR-DATA-003, SR-DATA-004, SR-DATA-005","Data Pool, Persistence, SD Card Driver, NVM Driver","Event System, State Manager, Logger",Complete,None
F-OTA,Firmware Update (OTA),"F-OTA-001, F-OTA-002, F-OTA-003, F-OTA-004, F-OTA-005",FG-OTA,"SR-OTA-001, SR-OTA-002, SR-OTA-003, SR-OTA-004, SR-OTA-005","OTA Manager, State Manager, Persistence, Security Manager","Main Hub APIs, Network Stack, Diagnostics",Complete,"F-SEC, F-SYS"
F-SEC,Security & Safety,"F-SEC-001, F-SEC-002, F-SEC-003, F-SEC-004",FG-SEC,"SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004","Security Manager, Secure Boot, Encryption Engine, Certificate Manager","Network Stack, NVM Driver, Diagnostics, State Manager",Complete,None
F-SYS,System Management,"F-SYS-001, F-SYS-002, F-SYS-003, F-SYS-004, F-SYS-005",FG-SYS,"SR-SYS-001, SR-SYS-002, SR-SYS-003, SR-SYS-004, SR-SYS-005","State Manager, HMI Manager, Event System","Diagnostics, Error Handler, All Components",Complete,F-DIAG
F-PWR,Power & Fault Handling,"F-PWR-001, F-PWR-002",FG-PWR,"SR-PWR-001, SR-PWR-002, SR-PWR-003, SR-PWR-004","Power Manager, Error Handler, Persistence","Diagnostics, Sensor Manager, Machine Constant Manager, State Manager",Complete,F-DATA
F-HW,Hardware Abstraction,"F-HW-001, F-HW-002",FG-HW,"SR-HW-001, SR-HW-002, SR-HW-003","Sensor Abstraction Layer, Hardware Interface Manager, GPIO Manager, Sensor Drivers","ESP-IDF Wrappers, Diagnostics, Machine Constant Manager",Complete,None
1 Feature_ID Feature_Name Sub_Features System_Feature_Group System_Requirements Primary_Components Supporting_Components Status Dependencies
2 F-DAQ Sensor Data Acquisition F-DAQ-001, F-DAQ-002, F-DAQ-003, F-DAQ-004, F-DAQ-005 FG-DAQ SR-DAQ-001, SR-DAQ-002, SR-DAQ-003, SR-DAQ-004, SR-DAQ-005 Sensor Manager, Sensor Drivers, Event System, Data Pool Time Utils, Logger, Machine Constant Manager Complete F-HW, F-DATA
3 F-DQC Data Quality & Calibration F-DQC-001, F-DQC-002, F-DQC-003, F-DQC-004, F-DQC-005 FG-DQC SR-DQC-001, SR-DQC-002, SR-DQC-003, SR-DQC-004, SR-DQC-005 Machine Constant Manager, Sensor Manager, Persistence Event System, Diagnostics, State Manager Complete F-DAQ, F-DATA
4 F-COM Communication F-COM-001, F-COM-002, F-COM-003, F-COM-004, F-COM-005 FG-COM SR-COM-001, SR-COM-002, SR-COM-003, SR-COM-004, SR-COM-005 Main Hub APIs, Network Stack, Event System Data Pool, Diagnostics, State Manager Complete F-SEC, F-DATA
5 F-DIAG Diagnostics & Health Monitoring F-DIAG-001, F-DIAG-002, F-DIAG-003, F-DIAG-004 FG-DIAG SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004 Diagnostics Task, Error Handler, Persistence Event System, Security Manager, State Manager Complete F-DATA, F-SYS
6 F-DATA Persistence & Data Management F-DATA-001, F-DATA-002, F-DATA-003, F-DATA-004, F-DATA-005 FG-DATA SR-DATA-001, SR-DATA-002, SR-DATA-003, SR-DATA-004, SR-DATA-005 Data Pool, Persistence, SD Card Driver, NVM Driver Event System, State Manager, Logger Complete None
7 F-OTA Firmware Update (OTA) F-OTA-001, F-OTA-002, F-OTA-003, F-OTA-004, F-OTA-005 FG-OTA SR-OTA-001, SR-OTA-002, SR-OTA-003, SR-OTA-004, SR-OTA-005 OTA Manager, State Manager, Persistence, Security Manager Main Hub APIs, Network Stack, Diagnostics Complete F-SEC, F-SYS
8 F-SEC Security & Safety F-SEC-001, F-SEC-002, F-SEC-003, F-SEC-004 FG-SEC SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 Security Manager, Secure Boot, Encryption Engine, Certificate Manager Network Stack, NVM Driver, Diagnostics, State Manager Complete None
9 F-SYS System Management F-SYS-001, F-SYS-002, F-SYS-003, F-SYS-004, F-SYS-005 FG-SYS SR-SYS-001, SR-SYS-002, SR-SYS-003, SR-SYS-004, SR-SYS-005 State Manager, HMI Manager, Event System Diagnostics, Error Handler, All Components Complete F-DIAG
10 F-PWR Power & Fault Handling F-PWR-001, F-PWR-002 FG-PWR SR-PWR-001, SR-PWR-002, SR-PWR-003, SR-PWR-004 Power Manager, Error Handler, Persistence Diagnostics, Sensor Manager, Machine Constant Manager, State Manager Complete F-DATA
11 F-HW Hardware Abstraction F-HW-001, F-HW-002 FG-HW SR-HW-001, SR-HW-002, SR-HW-003 Sensor Abstraction Layer, Hardware Interface Manager, GPIO Manager, Sensor Drivers ESP-IDF Wrappers, Diagnostics, Machine Constant Manager Complete None

208
system_arch_final/traceability/feature_info/feature_traceability.md Normal file
View File

@@ -0,0 +1,208 @@
# Software Feature Traceability
# ASF Sensor Hub Feature Mapping
**Document Type:** Feature Traceability Documentation
**Version:** 1.0
**Date:** 2025-01-19
## Overview
This document provides complete traceability mapping for all software features in the ASF Sensor Hub system, showing relationships between software features, system features, system requirements, and implementing components.
## Software Features Summary
| Feature ID | Feature Name | Sub-Features | System Feature Group | Status |
|------------|--------------|--------------|---------------------|--------|
| F-DAQ | Sensor Data Acquisition | F-DAQ-001 to F-DAQ-005 | FG-DAQ | ✅ Complete |
| F-DQC | Data Quality & Calibration | F-DQC-001 to F-DQC-005 | FG-DQC | ✅ Complete |
| F-COM | Communication | F-COM-001 to F-COM-005 | FG-COM | ✅ Complete |
| F-DIAG | Diagnostics & Health Monitoring | F-DIAG-001 to F-DIAG-004 | FG-DIAG | ✅ Complete |
| F-DATA | Persistence & Data Management | F-DATA-001 to F-DATA-005 | FG-DATA | ✅ Complete |
| F-OTA | Firmware Update (OTA) | F-OTA-001 to F-OTA-005 | FG-OTA | ✅ Complete |
| F-SEC | Security & Safety | F-SEC-001 to F-SEC-004 | FG-SEC | ✅ Complete |
| F-SYS | System Management | F-SYS-001 to F-SYS-005 | FG-SYS | ✅ Complete |
| F-PWR | Power & Fault Handling | F-PWR-001 to F-PWR-002 | FG-PWR | ✅ Complete |
| F-HW | Hardware Abstraction | F-HW-001 to F-HW-002 | FG-HW | ✅ Complete |
## Feature to System Requirements Mapping
### F-DAQ: Sensor Data Acquisition
**System Requirements Covered:**
- SR-DAQ-001: Multi-Sensor Support
- SR-DAQ-002: High-Frequency Sampling
- SR-DAQ-003: Local Data Filtering
- SR-DAQ-004: Timestamped Data Generation
- SR-DAQ-005: Sensor State Management
**Primary Components:**
- Sensor Manager (`application_layer/business_stack/sensor_manager/`)
- Sensor Drivers (`drivers/sensors/`)
- Event System (`application_layer/business_stack/event_system/`)
- Data Pool (`application_layer/DP_stack/data_pool/`)
### F-DQC: Data Quality & Calibration
**System Requirements Covered:**
- SR-DQC-001: Automatic Sensor Detection
- SR-DQC-002: Sensor Type Enforcement
- SR-DQC-003: Sensor Failure Detection
- SR-DQC-004: Machine Constants Management
- SR-DQC-005: Calibration Parameter Application
**Primary Components:**
- Machine Constant Manager (`application_layer/business_stack/machine_constant_manager/`)
- Sensor Manager (`application_layer/business_stack/sensor_manager/`)
- Persistence (`application_layer/DP_stack/persistence/`)
### F-COM: Communication
**System Requirements Covered:**
- SR-COM-001: Main Hub Communication
- SR-COM-002: Secure Communication Protocols
- SR-COM-003: On-Demand Data Broadcasting
- SR-COM-004: Peer Communication
- SR-COM-005: Communication Fault Tolerance
**Primary Components:**
- Main Hub APIs (`application_layer/business_stack/main_hub_apis/`)
- Network Stack (`drivers/network_stack/`)
- Event System (`application_layer/business_stack/event_system/`)
### F-DIAG: Diagnostics & Health Monitoring
**System Requirements Covered:**
- SR-DIAG-001: Diagnostic Code Management
- SR-DIAG-002: Diagnostic Data Storage
- SR-DIAG-003: Diagnostic Session Support
- SR-DIAG-004: Layered Watchdog System
**Primary Components:**
- Diagnostics Task (`application_layer/diag_task/`)
- Error Handler (`application_layer/error_handler/`)
- Persistence (`application_layer/DP_stack/persistence/`)
### F-DATA: Persistence & Data Management
**System Requirements Covered:**
- SR-DATA-001: Persistent Sensor Data Storage
- SR-DATA-002: Data Persistence Abstraction
- SR-DATA-003: Safe Data Handling During Transitions
- SR-DATA-004: Data Integrity Protection
- SR-DATA-005: Storage Capacity Management
**Primary Components:**
- Data Pool (`application_layer/DP_stack/data_pool/`)
- Persistence (`application_layer/DP_stack/persistence/`)
- SD Card Driver (`drivers/SDcard/`)
- NVM Driver (`drivers/nvm/`)
### F-OTA: Firmware Update (OTA)
**System Requirements Covered:**
- SR-OTA-001: OTA Update Negotiation
- SR-OTA-002: Firmware Reception and Storage
- SR-OTA-003: Firmware Integrity Validation
- SR-OTA-004: Safe Firmware Activation
- SR-OTA-005: OTA State Management
**Primary Components:**
- OTA Manager (`application_layer/business_stack/fw_upgrader/`)
- State Manager (`application_layer/business_stack/STM/`)
- Persistence (`application_layer/DP_stack/persistence/`)
- Security Manager (`application_layer/security/`)
### F-SEC: Security & Safety
**System Requirements Covered:**
- SR-SEC-001: Secure Boot
- SR-SEC-002: Flash Encryption
- SR-SEC-003: Certificate Management
- SR-SEC-004: Security Violation Handling
**Primary Components:**
- Security Manager (`application_layer/security/`)
- Secure Boot (`bootloader/secure_boot/`)
- Encryption Engine (`application_layer/security/crypto/`)
- Certificate Manager (`application_layer/security/cert_mgr/`)
### F-SYS: System Management
**System Requirements Covered:**
- SR-SYS-001: System State Machine
- SR-SYS-002: State-Aware Operation
- SR-SYS-003: Controlled Teardown
- SR-SYS-004: Local Human-Machine Interface
- SR-SYS-005: Engineering Access
**Primary Components:**
- State Manager (`application_layer/business_stack/STM/`)
- HMI Manager (`application_layer/hmi/`)
- Event System (`application_layer/business_stack/event_system/`)
### F-PWR: Power & Fault Handling
**System Requirements Covered:**
- SR-PWR-001: Brownout Detection
- SR-PWR-002: Power-Loss Recovery
- SR-PWR-003: Fault Classification
- SR-PWR-004: Fault Escalation
**Primary Components:**
- Power Manager (`application_layer/power_manager/`)
- Error Handler (`application_layer/error_handler/`)
- Persistence (`application_layer/DP_stack/persistence/`)
### F-HW: Hardware Abstraction
**System Requirements Covered:**
- SR-HW-001: Sensor Abstraction Layer
- SR-HW-002: Hardware Interface Abstraction
- SR-HW-003: GPIO Discipline
**Primary Components:**
- Sensor Abstraction Layer (`drivers/sensor_abstraction/`)
- Hardware Interface Manager (`drivers/hw_interface_mgr/`)
- GPIO Manager (`drivers/gpio_manager/`)
- ESP-IDF Wrappers (`ESP_IDF_FW_wrappers/`)
## Cross-Feature Dependencies
| Feature | Depends On | Dependency Type |
|---------|------------|-----------------|
| F-DAQ | F-HW | Hardware abstraction for sensor access |
| F-DAQ | F-DATA | Data persistence for sensor readings |
| F-DQC | F-DAQ | Sensor data for quality validation |
| F-DQC | F-DATA | Machine constants persistence |
| F-COM | F-SEC | Secure communication protocols |
| F-COM | F-DATA | Data access for transmission |
| F-DIAG | F-DATA | Diagnostic data persistence |
| F-DIAG | F-SYS | System state awareness |
| F-OTA | F-SEC | Secure firmware validation |
| F-OTA | F-SYS | State coordination during updates |
| F-SYS | F-DIAG | System health monitoring |
| F-PWR | F-DATA | Critical data preservation |
## Feature Implementation Status
All 10 software features are **complete** with:
- ✅ Complete sub-feature specifications
- ✅ System requirements coverage
- ✅ Component implementation mapping
- ✅ Interface specifications
- ✅ Mermaid interaction diagrams
- ✅ State-dependent behavior definitions
- ✅ Testing and validation criteria
## Traceability Validation
### Requirements Coverage
- **Total System Requirements:** 45+ SR-XXX requirements
- **Covered by Features:** 100% coverage achieved
- **Orphan Requirements:** None identified
### Component Coverage
- **Total Components:** 25+ components identified
- **Mapped to Features:** 100% coverage achieved
- **Orphan Components:** None identified
### Interface Coverage
- **Public APIs:** All major interfaces documented
- **Integration Points:** Complete cross-component mapping
- **Communication Protocols:** All protocols specified
---
**Document Status:** Complete and Validated
**Last Updated:** 2025-01-19
**Next Review:** After implementation phase begins

29
system_arch_final/traceability/interface_info/interface_traceability.csv Normal file
View File

@@ -0,0 +1,29 @@
Interface_Name,Interface_Type,Provider_Component,Provider_Location,Used_By_Components,Software_Features,System_Requirements,Communication_Pattern,Data_Types,Description
State Manager Interface,API,State Manager,application_layer/business_stack/STM/,All components requiring state awareness,F-SYS;F-OTA;F-PWR,SR-SYS-001;SR-SYS-002;SR-SYS-003,Synchronous API calls,system_state_t;transition_reason_t;state_listener_t,System state machine management and coordination
Event System Interface,Event Bus,Event System,application_layer/business_stack/event_system/,All components for inter-component communication,F-SYS;F-DAQ;F-COM;F-DIAG,SR-SYS-002;SR-COM-005,Asynchronous publish/subscribe,event_type_t;event_handler_t,Cross-component event-based communication
Sensor Manager Interface,API,Sensor Manager,application_layer/business_stack/sensor_manager/,"Data Pool, Main Hub APIs, Diagnostics",F-DAQ;F-DQC,SR-DAQ-001;SR-DAQ-002;SR-DAQ-003;SR-DAQ-004;SR-DAQ-005,Synchronous API calls,sensor_data_record_t;sensor_state_t;machine_constants_t,Sensor lifecycle and data acquisition management
Sensor Abstraction Layer Interface,Hardware Abstraction,Sensor Abstraction Layer,drivers/sensor_abstraction/,Sensor Manager,F-HW;F-DAQ,SR-HW-001;SR-HW-002,Synchronous API calls,sensor_metadata_t;calibration_data_t,Hardware abstraction for sensor access
Data Pool Interface,API,Data Pool,application_layer/DP_stack/data_pool/,"Main Hub APIs, Persistence, Diagnostics",F-DATA;F-DAQ;F-COM,SR-DATA-002;SR-PERF-003,Synchronous API calls,sensor_data_record_t;system_state_t,Runtime data storage and access
Persistence Interface,API,Persistence,application_layer/DP_stack/persistence/,All components requiring persistent storage,F-DATA;F-DIAG;F-DQC;F-OTA,SR-DATA-001;SR-DATA-002;SR-DATA-003;SR-DATA-004;SR-DATA-005,Synchronous API calls,sensor_data_record_t;diagnostic_event_t;machine_constants_t,Persistent storage abstraction and management
Main Hub APIs Interface,Communication Protocol,Main Hub APIs,application_layer/business_stack/main_hub_apis/,Event System (for data transmission triggers),F-COM,SR-COM-001;SR-COM-002;SR-COM-003,Asynchronous network communication,main_hub_request_t;connection_status_t,Main Hub communication protocol implementation
Network Stack Interface,Network Protocol,Network Stack,drivers/network_stack/,"Main Hub APIs, OTA Manager",F-COM;F-SEC;F-OTA,SR-COM-002;SR-COM-004;SR-COM-005,Asynchronous network I/O,tls_config_t;network_status_t,Network protocol and connectivity management
Diagnostics Task Interface,API,Diagnostics Task,application_layer/diag_task/,"Error Handler, Engineering Tools",F-DIAG,SR-DIAG-001;SR-DIAG-002;SR-DIAG-003;SR-DIAG-004,Synchronous API calls,diagnostic_event_t;diagnostic_filter_t;system_health_t,Diagnostic event collection and management
Error Handler Interface,API,Error Handler,application_layer/error_handler/,All components for error reporting,F-PWR;F-DIAG;F-SYS,SR-PWR-003;SR-PWR-004;SR-DIAG-001,Synchronous API calls,error_code_t;diagnostic_severity_t;error_statistics_t,Error classification and escalation management
GPIO Manager Interface,Hardware Abstraction,GPIO Manager,drivers/gpio_manager/,All components requiring GPIO access,F-HW,SR-HW-002;SR-HW-003,Synchronous API calls,gpio_function_t;gpio_config_t;gpio_conflict_t,GPIO resource management and conflict detection
I2C Wrapper Interface,Hardware Interface,I2C Wrapper,ESP_IDF_FW_wrappers/i2c/,"Sensor Drivers, OLED Driver",F-HW;F-DAQ,SR-HW-002,Synchronous hardware I/O,i2c_config_t,I2C hardware interface abstraction
SPI Wrapper Interface,Hardware Interface,SPI Wrapper,ESP_IDF_FW_wrappers/spi/,"Sensor Drivers, SD Card Driver",F-HW;F-DAQ;F-DATA,SR-HW-002,Synchronous hardware I/O,spi_config_t,SPI hardware interface abstraction
UART Wrapper Interface,Hardware Interface,UART Wrapper,ESP_IDF_FW_wrappers/uart/,Sensor Drivers,F-HW;F-DAQ,SR-HW-002,Synchronous hardware I/O,uart_config_t,UART hardware interface abstraction
ADC Wrapper Interface,Hardware Interface,ADC Wrapper,ESP_IDF_FW_wrappers/adc/,Sensor Drivers,F-HW;F-DAQ,SR-HW-002,Synchronous hardware I/O,adc_config_t,ADC hardware interface abstraction
WiFi Wrapper Interface,Hardware Interface,WiFi Wrapper,ESP_IDF_FW_wrappers/wifi/,Network Stack,F-COM;F-SEC,SR-COM-002;SR-COM-004,Asynchronous network I/O,wifi_config_t,WiFi hardware interface abstraction
Security Manager Interface,API,Security Manager,application_layer/security/,All components for security enforcement,F-SEC,SR-SEC-001;SR-SEC-002;SR-SEC-003;SR-SEC-004,Synchronous API calls,security_violation_type_t;security_policy_t;security_status_t,Security policy enforcement and violation handling
Encryption Engine Interface,API,Encryption Engine,application_layer/security/crypto/,"Security Manager, OTA Manager, Persistence",F-SEC,SR-SEC-002;SR-SEC-003,Synchronous cryptographic operations,key_type_t,Cryptographic operations and key management
Machine Constant Manager Interface,API,Machine Constant Manager,application_layer/business_stack/machine_constant_manager/,"All components requiring configuration",F-DQC;F-SYS,SR-DQC-004;SR-DQC-005,Synchronous API calls,machine_constants_t;mc_validation_result_t,Machine constants management and validation
OTA Manager Interface,API,OTA Manager,application_layer/business_stack/fw_upgrader/,"Main Hub APIs, State Manager",F-OTA,SR-OTA-001;SR-OTA-002;SR-OTA-003;SR-OTA-004;SR-OTA-005,Synchronous API calls,ota_request_t;ota_status_t;firmware_info_t,Over-the-air firmware update management
Logger Interface,Utility,Logger,utils/logger/,All components for debug logging,All Features (cross-cutting),SR-DIAG-002,Synchronous logging calls,log_level_t;log_output_t,Debug and diagnostic logging utility
Time Utils Interface,Utility,Time Utils,utils/time_utils/,"Sensor Manager, Diagnostics Task",F-DAQ;F-DIAG,SR-DAQ-004,Synchronous utility calls,uint64_t (timestamp),Time and timestamp utility functions
SD Card Driver Interface,Hardware Interface,SD Card Driver,drivers/SDcard/,Persistence,F-DATA,SR-DATA-001,Synchronous storage I/O,sd_card_config_t,SD card storage interface
NVM Driver Interface,Hardware Interface,NVM Driver,drivers/nvm/,Persistence,F-DATA;F-SEC,SR-DATA-001;SR-SEC-006,Synchronous storage I/O,nvm_config_t,Non-volatile memory interface
Actuator Manager Interface,API,Actuator Manager,application_layer/business_stack/actuator_manager/,Main Hub APIs,F-SYS,SR-SYS-004,Synchronous API calls,actuator_command_t;actuator_status_t,Actuator control and status management
HMI Interface,API,HMI,application_layer/hmi/,"State Manager, Diagnostics Task",F-SYS,SR-SYS-004,Synchronous API calls,hmi_display_data_t;button_event_t,Human-machine interface for local interaction
Task Abstraction Interface,OSAL,Task Abstraction,os/task/,All task-based components,All Features,N/A,RTOS abstraction,task_handle_t;task_config_t,FreeRTOS task abstraction layer
Software Timer Interface,OSAL,Software Timer,os/swtimer/,Components requiring timers,All Features,N/A,RTOS abstraction,timer_handle_t;timer_config_t,FreeRTOS software timer abstraction
1 Interface_Name Interface_Type Provider_Component Provider_Location Used_By_Components Software_Features System_Requirements Communication_Pattern Data_Types Description
2 State Manager Interface API State Manager application_layer/business_stack/STM/ All components requiring state awareness F-SYS;F-OTA;F-PWR SR-SYS-001;SR-SYS-002;SR-SYS-003 Synchronous API calls system_state_t;transition_reason_t;state_listener_t System state machine management and coordination
3 Event System Interface Event Bus Event System application_layer/business_stack/event_system/ All components for inter-component communication F-SYS;F-DAQ;F-COM;F-DIAG SR-SYS-002;SR-COM-005 Asynchronous publish/subscribe event_type_t;event_handler_t Cross-component event-based communication
4 Sensor Manager Interface API Sensor Manager application_layer/business_stack/sensor_manager/ Data Pool, Main Hub APIs, Diagnostics F-DAQ;F-DQC SR-DAQ-001;SR-DAQ-002;SR-DAQ-003;SR-DAQ-004;SR-DAQ-005 Synchronous API calls sensor_data_record_t;sensor_state_t;machine_constants_t Sensor lifecycle and data acquisition management
5 Sensor Abstraction Layer Interface Hardware Abstraction Sensor Abstraction Layer drivers/sensor_abstraction/ Sensor Manager F-HW;F-DAQ SR-HW-001;SR-HW-002 Synchronous API calls sensor_metadata_t;calibration_data_t Hardware abstraction for sensor access
6 Data Pool Interface API Data Pool application_layer/DP_stack/data_pool/ Main Hub APIs, Persistence, Diagnostics F-DATA;F-DAQ;F-COM SR-DATA-002;SR-PERF-003 Synchronous API calls sensor_data_record_t;system_state_t Runtime data storage and access
7 Persistence Interface API Persistence application_layer/DP_stack/persistence/ All components requiring persistent storage F-DATA;F-DIAG;F-DQC;F-OTA SR-DATA-001;SR-DATA-002;SR-DATA-003;SR-DATA-004;SR-DATA-005 Synchronous API calls sensor_data_record_t;diagnostic_event_t;machine_constants_t Persistent storage abstraction and management
8 Main Hub APIs Interface Communication Protocol Main Hub APIs application_layer/business_stack/main_hub_apis/ Event System (for data transmission triggers) F-COM SR-COM-001;SR-COM-002;SR-COM-003 Asynchronous network communication main_hub_request_t;connection_status_t Main Hub communication protocol implementation
9 Network Stack Interface Network Protocol Network Stack drivers/network_stack/ Main Hub APIs, OTA Manager F-COM;F-SEC;F-OTA SR-COM-002;SR-COM-004;SR-COM-005 Asynchronous network I/O tls_config_t;network_status_t Network protocol and connectivity management
10 Diagnostics Task Interface API Diagnostics Task application_layer/diag_task/ Error Handler, Engineering Tools F-DIAG SR-DIAG-001;SR-DIAG-002;SR-DIAG-003;SR-DIAG-004 Synchronous API calls diagnostic_event_t;diagnostic_filter_t;system_health_t Diagnostic event collection and management
11 Error Handler Interface API Error Handler application_layer/error_handler/ All components for error reporting F-PWR;F-DIAG;F-SYS SR-PWR-003;SR-PWR-004;SR-DIAG-001 Synchronous API calls error_code_t;diagnostic_severity_t;error_statistics_t Error classification and escalation management
12 GPIO Manager Interface Hardware Abstraction GPIO Manager drivers/gpio_manager/ All components requiring GPIO access F-HW SR-HW-002;SR-HW-003 Synchronous API calls gpio_function_t;gpio_config_t;gpio_conflict_t GPIO resource management and conflict detection
13 I2C Wrapper Interface Hardware Interface I2C Wrapper ESP_IDF_FW_wrappers/i2c/ Sensor Drivers, OLED Driver F-HW;F-DAQ SR-HW-002 Synchronous hardware I/O i2c_config_t I2C hardware interface abstraction
14 SPI Wrapper Interface Hardware Interface SPI Wrapper ESP_IDF_FW_wrappers/spi/ Sensor Drivers, SD Card Driver F-HW;F-DAQ;F-DATA SR-HW-002 Synchronous hardware I/O spi_config_t SPI hardware interface abstraction
15 UART Wrapper Interface Hardware Interface UART Wrapper ESP_IDF_FW_wrappers/uart/ Sensor Drivers F-HW;F-DAQ SR-HW-002 Synchronous hardware I/O uart_config_t UART hardware interface abstraction
16 ADC Wrapper Interface Hardware Interface ADC Wrapper ESP_IDF_FW_wrappers/adc/ Sensor Drivers F-HW;F-DAQ SR-HW-002 Synchronous hardware I/O adc_config_t ADC hardware interface abstraction
17 WiFi Wrapper Interface Hardware Interface WiFi Wrapper ESP_IDF_FW_wrappers/wifi/ Network Stack F-COM;F-SEC SR-COM-002;SR-COM-004 Asynchronous network I/O wifi_config_t WiFi hardware interface abstraction
18 Security Manager Interface API Security Manager application_layer/security/ All components for security enforcement F-SEC SR-SEC-001;SR-SEC-002;SR-SEC-003;SR-SEC-004 Synchronous API calls security_violation_type_t;security_policy_t;security_status_t Security policy enforcement and violation handling
19 Encryption Engine Interface API Encryption Engine application_layer/security/crypto/ Security Manager, OTA Manager, Persistence F-SEC SR-SEC-002;SR-SEC-003 Synchronous cryptographic operations key_type_t Cryptographic operations and key management
20 Machine Constant Manager Interface API Machine Constant Manager application_layer/business_stack/machine_constant_manager/ All components requiring configuration F-DQC;F-SYS SR-DQC-004;SR-DQC-005 Synchronous API calls machine_constants_t;mc_validation_result_t Machine constants management and validation
21 OTA Manager Interface API OTA Manager application_layer/business_stack/fw_upgrader/ Main Hub APIs, State Manager F-OTA SR-OTA-001;SR-OTA-002;SR-OTA-003;SR-OTA-004;SR-OTA-005 Synchronous API calls ota_request_t;ota_status_t;firmware_info_t Over-the-air firmware update management
22 Logger Interface Utility Logger utils/logger/ All components for debug logging All Features (cross-cutting) SR-DIAG-002 Synchronous logging calls log_level_t;log_output_t Debug and diagnostic logging utility
23 Time Utils Interface Utility Time Utils utils/time_utils/ Sensor Manager, Diagnostics Task F-DAQ;F-DIAG SR-DAQ-004 Synchronous utility calls uint64_t (timestamp) Time and timestamp utility functions
24 SD Card Driver Interface Hardware Interface SD Card Driver drivers/SDcard/ Persistence F-DATA SR-DATA-001 Synchronous storage I/O sd_card_config_t SD card storage interface
25 NVM Driver Interface Hardware Interface NVM Driver drivers/nvm/ Persistence F-DATA;F-SEC SR-DATA-001;SR-SEC-006 Synchronous storage I/O nvm_config_t Non-volatile memory interface
26 Actuator Manager Interface API Actuator Manager application_layer/business_stack/actuator_manager/ Main Hub APIs F-SYS SR-SYS-004 Synchronous API calls actuator_command_t;actuator_status_t Actuator control and status management
27 HMI Interface API HMI application_layer/hmi/ State Manager, Diagnostics Task F-SYS SR-SYS-004 Synchronous API calls hmi_display_data_t;button_event_t Human-machine interface for local interaction
28 Task Abstraction Interface OSAL Task Abstraction os/task/ All task-based components All Features N/A RTOS abstraction task_handle_t;task_config_t FreeRTOS task abstraction layer
29 Software Timer Interface OSAL Software Timer os/swtimer/ Components requiring timers All Features N/A RTOS abstraction timer_handle_t;timer_config_t FreeRTOS software timer abstraction

444
system_arch_final/traceability/interface_info/interface_traceability.md Normal file
View File

@@ -0,0 +1,444 @@
# Software Interface Traceability
# ASF Sensor Hub Interface Mapping
**Document Type:** Interface Traceability Documentation
**Version:** 1.0
**Date:** 2025-01-19
## Overview
This document provides complete traceability mapping for all software interfaces in the ASF Sensor Hub system, showing relationships between interfaces, their component providers, software features, and system requirements.
## Interface Categories
### API Interfaces
Public programming interfaces provided by components for other components to use.
### Event Interfaces
Event-based communication interfaces using the publish/subscribe pattern.
### Hardware Interfaces
Low-level hardware abstraction interfaces for peripheral access.
### Communication Interfaces
Network and protocol interfaces for external communication.
### Utility Interfaces
Cross-cutting utility interfaces used by multiple components.
## Interface Details
### Core System Interfaces
#### State Manager Interface
**Provider Component:** State Manager (`application_layer/business_stack/STM/`)
**Interface Type:** API
**Software Features:** F-SYS, F-OTA, F-PWR
**System Requirements:** SR-SYS-001, SR-SYS-002, SR-SYS-003
**Public Functions:**
```c
system_state_t stm_getCurrentState(void);
bool stm_isStateValid(system_state_t state);
bool stm_requestTransition(system_state_t target_state, transition_reason_t reason);
bool stm_validateTransition(system_state_t from, system_state_t to);
bool stm_initiateTeardown(teardown_reason_t reason);
bool stm_isTeardownComplete(void);
bool stm_registerStateListener(state_listener_t listener);
```
**Used By:** All components requiring state awareness
**Communication Pattern:** Synchronous API calls
**Data Types:** `system_state_t`, `transition_reason_t`, `state_listener_t`
#### Event System Interface
**Provider Component:** Event System (`application_layer/business_stack/event_system/`)
**Interface Type:** Event Bus
**Software Features:** F-SYS, F-DAQ, F-COM, F-DIAG
**System Requirements:** SR-SYS-002, SR-COM-005
**Public Functions:**
```c
bool event_publish(event_type_t type, void* payload, size_t payload_size);
bool event_subscribe(event_type_t type, event_handler_t handler);
bool event_unsubscribe(event_type_t type, event_handler_t handler);
```
**Used By:** All components for inter-component communication
**Communication Pattern:** Asynchronous publish/subscribe
**Data Types:** `event_type_t`, `event_handler_t`
### Sensor Management Interfaces
#### Sensor Manager Interface
**Provider Component:** Sensor Manager (`application_layer/business_stack/sensor_manager/`)
**Interface Type:** API
**Software Features:** F-DAQ, F-DQC
**System Requirements:** SR-DAQ-001, SR-DAQ-002, SR-DAQ-003, SR-DAQ-004, SR-DAQ-005
**Public Functions:**
```c
bool sensorMgr_initialize(void);
bool sensorMgr_loadConfiguration(const machine_constants_t* mc);
bool sensorMgr_detectSensors(void);
bool sensorMgr_startAcquisition(void);
bool sensorMgr_stopAcquisition(void);
bool sensorMgr_enableSensor(uint8_t sensor_id);
bool sensorMgr_disableSensor(uint8_t sensor_id);
bool sensorMgr_getLatestData(uint8_t sensor_id, sensor_data_record_t* record);
bool sensorMgr_getAllSensorData(sensor_data_record_t* records, size_t* count);
sensor_state_t sensorMgr_getSensorState(uint8_t sensor_id);
```
**Used By:** Data Pool, Main Hub APIs, Diagnostics
**Communication Pattern:** Synchronous API calls
**Data Types:** `sensor_data_record_t`, `sensor_state_t`, `machine_constants_t`
#### Sensor Abstraction Layer Interface
**Provider Component:** Sensor Abstraction Layer (`drivers/sensor_abstraction/`)
**Interface Type:** Hardware Abstraction
**Software Features:** F-HW, F-DAQ
**System Requirements:** SR-HW-001, SR-HW-002
**Public Functions:**
```c
bool sal_initializeSensor(uint8_t sensor_id);
bool sal_enableSensor(uint8_t sensor_id);
bool sal_disableSensor(uint8_t sensor_id);
bool sal_readSensor(uint8_t sensor_id, float* value);
bool sal_calibrateSensor(uint8_t sensor_id, const calibration_data_t* cal_data);
bool sal_validateReading(uint8_t sensor_id, float value);
bool sal_performHealthCheck(uint8_t sensor_id);
bool sal_getSensorMetadata(uint8_t sensor_id, sensor_metadata_t* metadata);
sensor_state_t sal_getSensorState(uint8_t sensor_id);
```
**Used By:** Sensor Manager
**Communication Pattern:** Synchronous API calls
**Data Types:** `sensor_metadata_t`, `calibration_data_t`
### Data Management Interfaces
#### Data Pool Interface
**Provider Component:** Data Pool (`application_layer/DP_stack/data_pool/`)
**Interface Type:** API
**Software Features:** F-DATA, F-DAQ, F-COM
**System Requirements:** SR-DATA-002, SR-PERF-003
**Public Functions:**
```c
bool dataPool_initialize(void);
bool dataPool_updateSensorData(uint8_t sensor_id, const sensor_data_record_t* record);
bool dataPool_getLatestData(uint8_t sensor_id, sensor_data_record_t* record);
bool dataPool_getAllSensorData(sensor_data_record_t* records, size_t* count);
bool dataPool_getSystemState(system_state_t* state);
bool dataPool_updateSystemState(system_state_t state);
```
**Used By:** Main Hub APIs, Persistence, Diagnostics
**Communication Pattern:** Synchronous API calls
**Data Types:** `sensor_data_record_t`, `system_state_t`
#### Persistence Interface
**Provider Component:** Persistence (`application_layer/DP_stack/persistence/`)
**Interface Type:** API
**Software Features:** F-DATA, F-DIAG, F-DQC, F-OTA
**System Requirements:** SR-DATA-001, SR-DATA-002, SR-DATA-003, SR-DATA-004, SR-DATA-005
**Public Functions:**
```c
bool persistence_writeSensorData(const sensor_data_record_t* record);
bool persistence_writeDiagnostic(const diagnostic_event_t* event);
bool persistence_writeMachineConstants(const machine_constants_t* mc);
bool persistence_readSensorData(sensor_data_record_t* records, size_t* count);
bool persistence_readDiagnostics(diagnostic_event_t* events, size_t* count);
bool persistence_readMachineConstants(machine_constants_t* mc);
bool persistence_flushCriticalData(void);
bool persistence_isFlushComplete(void);
```
**Used By:** All components requiring persistent storage
**Communication Pattern:** Synchronous API calls
**Data Types:** `sensor_data_record_t`, `diagnostic_event_t`, `machine_constants_t`
### Communication Interfaces
#### Main Hub APIs Interface
**Provider Component:** Main Hub APIs (`application_layer/business_stack/main_hub_apis/`)
**Interface Type:** Communication Protocol
**Software Features:** F-COM
**System Requirements:** SR-COM-001, SR-COM-002, SR-COM-003
**Public Functions:**
```c
bool mainHubAPI_initialize(void);
bool mainHubAPI_connect(const char* hub_address);
bool mainHubAPI_sendSensorData(const sensor_data_record_t* records, size_t count);
bool mainHubAPI_sendDiagnosticData(const diagnostic_event_t* events, size_t count);
bool mainHubAPI_handleRequest(const main_hub_request_t* request);
bool mainHubAPI_getConnectionStatus(connection_status_t* status);
bool mainHubAPI_disconnect(void);
```
**Used By:** Event System (for data transmission triggers)
**Communication Pattern:** Asynchronous network communication
**Data Types:** `main_hub_request_t`, `connection_status_t`
#### Network Stack Interface
**Provider Component:** Network Stack (`drivers/network_stack/`)
**Interface Type:** Network Protocol
**Software Features:** F-COM, F-SEC, F-OTA
**System Requirements:** SR-COM-002, SR-COM-004, SR-COM-005
**Public Functions:**
```c
bool networkStack_initialize(void);
bool networkStack_connect(const char* ssid, const char* password);
bool networkStack_disconnect(void);
bool networkStack_sendData(const uint8_t* data, size_t size);
bool networkStack_receiveData(uint8_t* buffer, size_t* size);
bool networkStack_setupTLS(const tls_config_t* config);
bool networkStack_getStatus(network_status_t* status);
```
**Used By:** Main Hub APIs, OTA Manager
**Communication Pattern:** Asynchronous network I/O
**Data Types:** `tls_config_t`, `network_status_t`
### Diagnostic Interfaces
#### Diagnostics Task Interface
**Provider Component:** Diagnostics Task (`application_layer/diag_task/`)
**Interface Type:** API
**Software Features:** F-DIAG
**System Requirements:** SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004
**Public Functions:**
```c
bool diagTask_initialize(void);
bool diagTask_start(void);
bool diagTask_stop(void);
bool diagTask_reportEvent(const diagnostic_event_t* event);
bool diagTask_getEvents(const diagnostic_filter_t* filter,
diagnostic_event_t* events, size_t* count);
bool diagTask_clearEvents(const diagnostic_filter_t* filter);
bool diagTask_getSystemHealth(system_health_t* health);
session_id_t diagTask_createSession(session_type_t type);
bool diagTask_authenticateSession(session_id_t session, const auth_credentials_t* creds);
```
**Used By:** Error Handler, Engineering Tools
**Communication Pattern:** Synchronous API calls
**Data Types:** `diagnostic_event_t`, `diagnostic_filter_t`, `system_health_t`
#### Error Handler Interface
**Provider Component:** Error Handler (`application_layer/error_handler/`)
**Interface Type:** API
**Software Features:** F-PWR, F-DIAG, F-SYS
**System Requirements:** SR-PWR-003, SR-PWR-004, SR-DIAG-001
**Public Functions:**
```c
bool errorHandler_reportError(component_id_t source, error_code_t code,
const char* description, const uint8_t* context_data);
bool errorHandler_reportWarning(component_id_t source, warning_code_t code,
const char* description);
bool errorHandler_reportInfo(component_id_t source, info_code_t code,
const char* description);
diagnostic_severity_t errorHandler_classifyError(error_code_t code);
bool errorHandler_getErrorStatistics(error_statistics_t* stats);
```
**Used By:** All components for error reporting
**Communication Pattern:** Synchronous API calls
**Data Types:** `error_code_t`, `diagnostic_severity_t`, `error_statistics_t`
### Hardware Abstraction Interfaces
#### GPIO Manager Interface
**Provider Component:** GPIO Manager (`drivers/gpio_manager/`)
**Interface Type:** Hardware Abstraction
**Software Features:** F-HW
**System Requirements:** SR-HW-002, SR-HW-003
**Public Functions:**
```c
bool gpioMgr_initialize(void);
bool gpioMgr_reservePin(uint8_t gpio_num, gpio_function_t function,
const char* component_name);
bool gpioMgr_releasePin(uint8_t gpio_num);
bool gpioMgr_configurePin(uint8_t gpio_num, const gpio_config_t* config);
bool gpioMgr_validateGPIOMap(void);
bool gpioMgr_detectConflicts(gpio_conflict_t* conflicts, size_t* count);
```
**Used By:** All components requiring GPIO access
**Communication Pattern:** Synchronous API calls
**Data Types:** `gpio_function_t`, `gpio_config_t`, `gpio_conflict_t`
#### I2C Wrapper Interface
**Provider Component:** I2C Wrapper (`ESP_IDF_FW_wrappers/i2c/`)
**Interface Type:** Hardware Interface
**Software Features:** F-HW, F-DAQ
**System Requirements:** SR-HW-002
**Public Functions:**
```c
bool hw_i2c_initialize(uint8_t port, const i2c_config_t* config);
bool hw_i2c_write(uint8_t port, uint8_t device_addr, const uint8_t* data, size_t len);
bool hw_i2c_read(uint8_t port, uint8_t device_addr, uint8_t* data, size_t len);
bool hw_i2c_write_read(uint8_t port, uint8_t device_addr,
const uint8_t* write_data, size_t write_len,
uint8_t* read_data, size_t read_len);
bool hw_i2c_scan_devices(uint8_t port, uint8_t* found_devices, size_t* count);
```
**Used By:** Sensor Drivers, OLED Driver
**Communication Pattern:** Synchronous hardware I/O
**Data Types:** `i2c_config_t`
### Security Interfaces
#### Security Manager Interface
**Provider Component:** Security Manager (`application_layer/security/`)
**Interface Type:** API
**Software Features:** F-SEC
**System Requirements:** SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004
**Public Functions:**
```c
bool secMgr_initialize(void);
bool secMgr_isSecurityEnabled(void);
security_status_t secMgr_getSecurityStatus(void);
bool secMgr_reportViolation(security_violation_type_t type,
const char* source, const uint8_t* context);
bool secMgr_setSecurityPolicy(const security_policy_t* policy);
bool secMgr_enforceSecurityPolicy(void);
```
**Used By:** All components for security enforcement
**Communication Pattern:** Synchronous API calls
**Data Types:** `security_violation_type_t`, `security_policy_t`, `security_status_t`
#### Encryption Engine Interface
**Provider Component:** Encryption Engine (`application_layer/security/crypto/`)
**Interface Type:** API
**Software Features:** F-SEC
**System Requirements:** SR-SEC-002, SR-SEC-003
**Public Functions:**
```c
bool crypto_encrypt(const uint8_t* plaintext, size_t plaintext_len,
const uint8_t* key, uint8_t* ciphertext, size_t* ciphertext_len);
bool crypto_decrypt(const uint8_t* ciphertext, size_t ciphertext_len,
const uint8_t* key, uint8_t* plaintext, size_t* plaintext_len);
bool crypto_sha256(const uint8_t* data, size_t data_len, uint8_t* hash);
bool crypto_generateKey(key_type_t type, uint8_t* key, size_t key_len);
```
**Used By:** Security Manager, OTA Manager, Persistence
**Communication Pattern:** Synchronous cryptographic operations
**Data Types:** `key_type_t`
### Utility Interfaces
#### Logger Interface
**Provider Component:** Logger (`utils/logger/`)
**Interface Type:** Utility
**Software Features:** All Features (cross-cutting)
**System Requirements:** SR-DIAG-002
**Public Functions:**
```c
bool logger_initialize(void);
void logger_log(log_level_t level, const char* tag, const char* format, ...);
bool logger_setLevel(log_level_t level);
bool logger_flush(void);
bool logger_setOutput(log_output_t output);
```
**Used By:** All components for debug logging
**Communication Pattern:** Synchronous logging calls
**Data Types:** `log_level_t`, `log_output_t`
#### Time Utils Interface
**Provider Component:** Time Utils (`utils/time_utils/`)
**Interface Type:** Utility
**Software Features:** F-DAQ, F-DIAG
**System Requirements:** SR-DAQ-004
**Public Functions:**
```c
bool timeUtils_initialize(void);
uint64_t timeUtils_getCurrentTimestamp(void);
bool timeUtils_formatTimestamp(uint64_t timestamp, char* buffer, size_t size);
bool timeUtils_setSystemTime(uint64_t timestamp);
bool timeUtils_getSystemTime(uint64_t* timestamp);
```
**Used By:** Sensor Manager, Diagnostics Task
**Communication Pattern:** Synchronous utility calls
**Data Types:** `uint64_t` (timestamp)
## Interface Usage Matrix
| Interface | Provider Component | Primary Users | Software Features | System Requirements |
|-----------|-------------------|---------------|-------------------|-------------------|
| State Manager API | State Manager | All Components | F-SYS, F-OTA, F-PWR | SR-SYS-001, SR-SYS-002, SR-SYS-003 |
| Event System | Event System | All Components | F-SYS, F-DAQ, F-COM, F-DIAG | SR-SYS-002, SR-COM-005 |
| Sensor Manager API | Sensor Manager | Data Pool, Main Hub APIs | F-DAQ, F-DQC | SR-DAQ-001 to SR-DAQ-005 |
| Data Pool API | Data Pool | Main Hub APIs, Persistence | F-DATA, F-DAQ, F-COM | SR-DATA-002, SR-PERF-003 |
| Persistence API | Persistence | All Data Producers | F-DATA, F-DIAG, F-DQC, F-OTA | SR-DATA-001 to SR-DATA-005 |
| Main Hub APIs | Main Hub APIs | Event System | F-COM | SR-COM-001, SR-COM-002, SR-COM-003 |
| Network Stack | Network Stack | Main Hub APIs, OTA Manager | F-COM, F-SEC, F-OTA | SR-COM-002, SR-COM-004, SR-COM-005 |
| Diagnostics API | Diagnostics Task | Error Handler, Engineering Tools | F-DIAG | SR-DIAG-001 to SR-DIAG-004 |
| Error Handler API | Error Handler | All Components | F-PWR, F-DIAG, F-SYS | SR-PWR-003, SR-PWR-004, SR-DIAG-001 |
| Security Manager API | Security Manager | All Components | F-SEC | SR-SEC-001 to SR-SEC-004 |
| Hardware Interfaces | ESP-IDF Wrappers | Sensor Drivers, Hardware Managers | F-HW, F-DAQ | SR-HW-002 |
| Logger | Logger | All Components | All Features | SR-DIAG-002 |
| Time Utils | Time Utils | Sensor Manager, Diagnostics | F-DAQ, F-DIAG | SR-DAQ-004 |
## Interface Communication Patterns
### Synchronous API Calls
- **Pattern:** Direct function calls with immediate return
- **Used By:** Most component APIs
- **Characteristics:** Blocking, immediate response, error handling via return codes
### Asynchronous Event Communication
- **Pattern:** Publish/subscribe with event queues
- **Used By:** Event System, cross-component notifications
- **Characteristics:** Non-blocking, decoupled, eventual consistency
### Hardware I/O Operations
- **Pattern:** Synchronous hardware transactions with timeouts
- **Used By:** Hardware wrapper interfaces
- **Characteristics:** Bounded timing, error detection, resource management
### Network Communication
- **Pattern:** Asynchronous network I/O with callbacks
- **Used By:** Network Stack, Main Hub APIs
- **Characteristics:** Non-blocking, connection management, protocol handling
## Interface Testing Strategy
### Unit Testing
- **Mock Interfaces:** Create mock implementations for isolated testing
- **Contract Testing:** Validate interface contracts and data types
- **Error Handling:** Test error conditions and edge cases
### Integration Testing
- **Interface Compatibility:** Test interface interactions between components
- **Data Flow:** Validate data flow through interface chains
- **Performance:** Test interface performance under load
### System Testing
- **End-to-End:** Test complete interface usage scenarios
- **Fault Injection:** Test interface behavior under failure conditions
- **Security:** Validate security aspects of interfaces
---
**Document Status:** Complete and Validated
**Last Updated:** 2025-01-19
**Next Review:** After interface implementation begins

3008
system_arch_final/traceability_export.csv Normal file
View File

File diff suppressed because one or more lines are too long