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

cleanup

Browse Source
This commit is contained in:
mahmamdouh
2026-01-26 12:49:12 +01:00
parent bedcd373f5
commit ff791564e4
243 changed files with 18986 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
draft/system_arch_final_old/.cursor Normal file
View File

@@ -0,0 +1,96 @@
# ASF Sensor Hub - Cursor Configuration
## Project Context
**Project Name:** ASF Sensor Hub (Sub-Hub)
**Target Platform:** ESP32-S3 microcontroller
**Framework:** ESP-IDF v5.4
**RTOS:** FreeRTOS (included in ESP-IDF)
**Language:** C/C++
**Domain:** Industrial / Agricultural Automation (Smart Poultry Farm)
## Global Conditions
### Hardware Platform
- **MCU:** ESP32-S3
- **CPU:** Dual-core Xtensa LX7, 240 MHz
- **Memory:** 512KB SRAM, 8MB Flash
- **Security:** Secure Boot V2, Flash Encryption (AES-256), eFuse
- **Connectivity:** Wi-Fi 802.11n (2.4 GHz), ESP-NOW, Bluetooth (optional)
### Software Framework
- **Framework:** ESP-IDF v5.4
- **RTOS:** FreeRTOS
- **Language:** C/C++ (C++17 standard)
- **Build System:** CMake
- **Toolchain:** ESP-IDF toolchain
### Communication Stack
- **Physical/Link:** Wi-Fi 802.11n (2.4 GHz)
- **Application Protocol:** MQTT over TLS 1.2
- **Peer-to-Peer:** ESP-NOW
- **Payload Encoding:** CBOR (Binary, versioned)
- **Security:** Mutual TLS (mTLS) with X.509 certificates
### Security Requirements
- **Secure Boot:** Secure Boot V2 (mandatory for production)
- **Flash Encryption:** AES-256 (hardware-accelerated)
- **Communication:** TLS 1.2 with mutual authentication (mTLS)
- **Key Storage:** eFuse or encrypted flash
- **Anti-Rollback:** eFuse-based version protection
### Storage
- **Primary Storage:** SD Card (FAT32, SDMMC 4-bit)
- **Configuration Storage:** NVS (Encrypted, 64KB)
- **Firmware Storage:** Flash partitions (A/B partitioning: ota_0, ota_1)
### System Architecture
- **Architecture Style:** Layered, Event-Driven, Component-Based
- **State Management:** Finite State Machine (11 states)
- **Communication:** Event-driven publish/subscribe
- **Persistence:** DP (Data Persistence) component abstraction
### Development Constraints
- **No Direct Hardware Access:** Application layer must use abstraction layers
- **State-Aware Execution:** All features must respect system state
- **Non-Blocking Operations:** Critical paths must be non-blocking
- **Deterministic Behavior:** Time-critical tasks must have bounded execution time
- **Memory Management:** Minimal dynamic allocation in critical paths
### Standards Compliance
- **Requirements:** ISO/IEC/IEEE 29148 (SRS)
- **Industrial Standards:** IEC 61499 (conceptual), ISA-95 (conceptual)
- **Security:** Industry-standard secure boot and encryption
### Key Documents
- **Features:** `Features.md` and `[XXX] Feature Files.md`
- **State Machine:** `System_State_Machine_Specification.md`
- **Failure Handling:** `Failure_Handling_Model.md`
- **SRS:** `System Design/SRS/SRS.md`
- **Architecture:** `software design/components/ARCHITECTURE.md`
- **Component Specs:** `software design/components/.../COMPONENT_SPEC.md`
### Important Notes
- This is an **industrial embedded system**, not consumer IoT
- **Reliability > Convenience**
- **Security is mandatory**
- **OTA must be fail-safe**
- **Power loss is expected** (brownout detection required)
- **SD card failure must be assumed** (fallback mode required)
### Development Guidelines
- Follow **Cross-Feature Constraints** (`Cross-Feature Constraints.md`)
- Respect **System State Machine** (`System_State_Machine_Specification.md`)
- Implement **Failure Handling Model** (`Failure_Handling_Model.md`)
- Use **Component Specifications** for API definitions
- Maintain **Traceability** to System Requirements (SR-*) and Software Requirements (SWR-*)
### Testing Requirements
- **Unit Tests:** Required for all components
- **Integration Tests:** Required for feature interactions
- **HIL/System Tests:** Required for system-level validation
- **V&V Matrix:** `System Design/SRS/VV_Matrix.md` defines verification methods
---
**Use this context when generating code, documentation, or making architectural decisions.**

120
draft/system_arch_final_old/Cross-Feature Constraints.md Normal file
View File

@@ -0,0 +1,120 @@
## 1\. Purpose
This document defines **cross-feature constraints** that apply across multiple system features and components. These constraints ensure consistent behavior, prevent architectural violations, and reduce integration risk.
Cross-feature constraints are **mandatory rules** that all future software design and implementation must comply with.
## 2\. Architectural Constraints
### CFC-ARCH-01: Layered Architecture Enforcement
* Application logic shall not access hardware directly.
* All hardware access shall be performed via Drivers and OSAL layers.
* Persistence access shall only be performed through the DP component.
**Impacted Features:**
DAQ, DQC, DATA, DIAG, SYS, OTA, SEC
### CFC-ARCH-02: State-Aware Feature Execution
* All features shall be aware of the current system state.
* Features shall not execute actions that are invalid for the current state.
**Examples:**
* DAQ shall not start sampling during OTA\_UPDATE.
* Communication shall be limited during TEARDOWN.
**Impacted Features:**
SYS, DAQ, COM, OTA, DATA
## 3\. Concurrency & Timing Constraints
### CFC-TIME-01: Non-Blocking Operation
* Sensor acquisition, communication, and UI updates shall be non-blocking.
* Blocking operations shall be isolated in controlled system services (e.g., persistence task).
**Impacted Features:**
DAQ, COM, SYS
### CFC-TIME-02: Deterministic Task Behavior
* Time-critical tasks (sensor acquisition, watchdog servicing) shall have deterministic execution time.
* Dynamic memory allocation during runtime shall be minimized or prohibited in critical paths.
**Impacted Features:**
DAQ, SYS, DIAG
## 4\. Data & Persistence Constraints
### CFC-DATA-01: Single Source of Truth
* Runtime and persistent data shall be owned and managed by the DP component.
* No feature shall maintain private persistent copies of shared system data.
**Impacted Features:**
DATA, DAQ, DIAG, SYS, OTA
### CFC-DATA-02: Data Consistency During Transitions
* No data write operations shall occur during teardown unless explicitly authorized by the System Manager.
* Persistence completion shall be confirmed before state transitions.
**Impacted Features:**
SYS, DATA, OTA
## 5\. Security Constraints
### CFC-SEC-01: Security First Initialization
* Secure boot and flash protection shall be enabled before any application-level logic executes.
**Impacted Features:**
SEC, SYS
### CFC-SEC-02: Encrypted Channels Only
* OTA, diagnostics, and data transmission shall only occur over encrypted and authenticated channels.
**Impacted Features:**
COM, OTA, DIAG, SEC
## 6\. HMI & Debug Constraints
### CFC-HMI-01: Read-Only Local UI
* The OLED HMI shall not allow configuration changes that affect system safety or security.
* Configuration updates shall only be accepted via authenticated communication channels.
**Impacted Features:**
SYS, SEC
### CFC-DBG-01: Debug Isolation
* Debug and engineering sessions shall not interfere with normal system operation.
* Debug commands shall respect system state restrictions.
**Impacted Features:**
SYS, DIAG, SEC

373
draft/system_arch_final_old/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.**

359
draft/system_arch_final_old/Features.md Normal file
View File

@@ -0,0 +1,359 @@
# **ASF Sensor Hub – Feature Definition Document**
*(Global, Feature-Based, Architecture-Neutral)*
This document defines the **system features** of the ASF Sensor Hub subsystem, organized by functional categories.
It is intended to be used as:
* A **feature baseline** in ALM
* Input to **system requirements derivation**
* Reference for **architecture and software design**
* Traceability anchor to IEC 61508 / IEC 61499 style decomposition later
> ⚠️ **Important Scope Note**
> This document covers **ONLY the Sensor Hub (Sub-Hub)** based on **ESP32-S3**.
> Main Hub, Cloud, Farm Control Logic are **explicitly out of scope**.
---
## **1. System Context Overview**
The ASF Sensor Hub is a **distributed sensing node** deployed inside a poultry house.
Its primary responsibilities are:
* Acquisition of multiple environmental sensors
* Local preprocessing and validation of sensor data
* Persistent storage of data and configuration
* Secure communication with a Main Hub
* Support for diagnostics, maintenance, and OTA updates
* Safe operation under fault conditions
The Sensor Hub operates as an **autonomous embedded system** with defined lifecycle states.
---
## **2. Feature Categorization Overview**
The system features are grouped into the following categories:
1. **Sensor Data Acquisition Features**
2. **Data Quality & Calibration Features**
3. **Communication Features**
4. **Diagnostics & Health Monitoring Features**
5. **Persistence & Data Management Features**
6. **Firmware Update (OTA) Features**
7. **Security & Safety Features**
8. **System Management Features**
Each feature is described at a **functional level** (WHAT the system does, not HOW).
---
## **3. Sensor Data Acquisition Features**
### **F-DAQ-01: Multi-Sensor Data Acquisition**
The system provides the capability to acquire data from multiple environmental sensors connected to the Sensor Hub hardware.
Supported sensor types include:
* Temperature
* Humidity
* Carbon Dioxide (CO₂)
* Ammonia (NH₃)
* Volatile Organic Compounds (VOC)
* Particulate Matter (PM)
* Light Intensity
---
### **F-DAQ-02: High-Frequency Sampling and Local Filtering**
The system provides local preprocessing of sensor data by:
* Sampling each sensor multiple times per acquisition cycle
* Applying a fast local filtering mechanism
* Producing a single validated value per sensor per cycle
Filtering algorithms are **pluggable and configurable**.
---
### **F-DAQ-03: Timestamped Sensor Data Generation**
The system provides timestamped sensor data using a synchronized local time source.
Each sensor record includes:
* Sensor identifier
* Measured value
* Timestamp
* Data validity status
---
## **4. Data Quality & Calibration Features**
### **F-DQC-01: Automatic Sensor Detection**
The system provides automatic detection of sensor presence based on dedicated hardware detection signals.
Key characteristics:
* Each sensor slot is type-specific
* Sensor presence is detected during initialization and runtime
* Only detected sensors are initialized and sampled
---
### **F-DQC-02: Sensor Type Enforcement**
The system enforces sensor-slot compatibility to prevent incorrect sensor usage.
Each physical slot:
* Accepts only one sensor type
* Is mapped to a predefined sensor class in software
---
### **F-DQC-03: Sensor Failure Detection**
The system provides detection of sensor failures, including:
* Communication errors
* Out-of-range values
* Non-responsive sensors
Detected failures are classified and reported.
---
### **F-DQC-04: Machine Constants & Calibration Management**
The system provides a Machine Constants (MC) mechanism responsible for:
* Defining installed sensor types
* Holding sensor calibration parameters
* Defining communication parameters
* Defining system identity parameters
MC data is persistent and reloadable.
---
## **5. Communication Features**
### **F-COM-01: Main Hub Communication**
The system provides bidirectional communication with a Main Hub to:
* Send sensor data
* Send diagnostics information
* Receive configuration updates
* Receive firmware updates
---
### **F-COM-02: On-Demand Data Broadcasting**
The system provides on-demand transmission of the most recent sensor dataset upon request from the Main Hub.
---
### **F-COM-03: Peer Sensor Hub Communication**
The system provides limited peer-to-peer communication between Sensor Hubs for:
* Connectivity checks
* Time synchronization support
* Basic status exchange
This feature is **on-demand and optional**.
---
## **6. Diagnostics & Health Monitoring Features**
### **F-DIAG-01: Diagnostic Code Management**
The system provides structured diagnostics with:
* Diagnostic codes
* Severity levels
* Root cause hierarchy
* Timestamping
---
### **F-DIAG-02: Diagnostic Data Storage**
The system provides persistent storage of diagnostic events for post-analysis.
---
### **F-DIAG-03: Diagnostic Session**
The system provides a diagnostic session allowing engineers to:
* Retrieve diagnostic data
* Inspect system health
* Clear diagnostic records
---
## **7. Persistence & Data Management Features**
### **F-DATA-01: Persistent Sensor Data Storage**
The system provides persistent storage of sensor data in non-volatile memory (SD Card).
---
### **F-DATA-02: Data Persistence Abstraction (DP Component)**
The system provides a Data Persistence (DP) component responsible for:
* Abstracting storage media (SD / NVM)
* Managing write/read operations
* Ensuring data integrity
---
### **F-DATA-03: Safe Data Handling During State Transitions**
The system ensures that all critical data is safely stored before:
* Firmware update
* Configuration update
* System teardown
* Reset or restart
---
## **8. Firmware Update (OTA) Features**
### **F-OTA-01: OTA Update Negotiation**
The system provides an OTA handshake mechanism with the Main Hub to:
* Acknowledge update availability
* Signal readiness for update
---
### **F-OTA-02: Firmware Reception and Storage**
The system provides secure reception of firmware images and temporary storage on SD Card.
---
### **F-OTA-03: Firmware Integrity Validation**
The system validates firmware integrity using checksum or CRC before activation.
---
### **F-OTA-04: Safe Firmware Activation**
The system provides controlled firmware flashing and rollback-safe activation.
---
## **9. Security & Safety Features**
### **F-SEC-01: Secure Boot**
The system provides secure boot functionality to ensure only authenticated firmware is executed.
---
### **F-SEC-02: Secure Flash Storage**
The system provides encrypted flash storage for sensitive assets.
---
### **F-SEC-03: Encrypted Communication**
The system provides encrypted communication channels for all external data exchange.
---
## **10. System Management Features**
### **F-SYS-01: System State Management**
The system provides explicit lifecycle states including:
* Initialization
* Normal Operation
* Degraded Operation
* Update Mode
* Fault Mode
* Teardown Mode
---
### **F-SYS-02: Controlled Teardown Mechanism**
The system provides a controlled teardown mechanism that:
* Stops sensor acquisition
* Flushes all critical data
* Ensures persistent storage consistency
* Prepares the system for update or shutdown
---
### **F-SYS-03: Status Indication**
The system provides visual status indicators:
* Green: Normal operation
* Yellow: Warning state
* Red: Fatal error state
---
### **F-SYS-04: Debug & Engineering Sessions**
The system provides engineering access sessions allowing:
* Log inspection
* MC file inspection and update
* Command execution
* Controlled debugging
---
## **11. Feature Relationship Overview (High-Level)**
```
Sensor Acquisition
↓
Data Quality & Calibration
↓
Data Persistence
↓
Communication
↓
Diagnostics & System Management
↓
OTA / Security / Safety
```
* **Machine Constants** affect:
* Sensor initialization
* Calibration
* Communication
* **Diagnostics** span all features
* **Teardown** is a cross-cutting mechanism triggered by:
* OTA
* MC update
* Fatal faults
---

224
draft/system_arch_final_old/Migration_and_Updates_Log.md Normal file
View File

@@ -0,0 +1,224 @@
# Migration and Updates Log
**Date:** 2025-01-19
**Version:** 2.0
**Purpose:** Document what was moved, what was updated, and what actions are still needed
## 1. What Was Moved
All feature documentation files were copied from `System Design/Features/` to `System Design/system_arch_final/`:
### 1.1 Feature Files (Copied)
- ✅ `Features.md` – Main feature catalog
- ✅ `[DAQ] Sensor Data Acquisition Features.md`
- ✅ `[DQC] Data Quality & Calibration Features.md`
- ✅ `[COM] Communication Features.md`
- ✅ `[DIAG] Diagnostics & Health Monitoring Features.md`
- ✅ `[DATA] Persistence & Data Management Features.md`
- ✅ `[OTA] Firmware Update (OTA) Features.md`
- ✅ `[SEC] Security & Safety Features.md`
- ✅ `[SYS] System Management Features.md`
- ✅ `Cross-Feature Constraints.md`
- ✅ `System Assumptions & Limitations.md`
### 1.2 Supporting Documents (Referenced, Not Copied)
These documents remain in their original locations and are referenced from the system architecture documentation:
- `System Design/System_State_Machine_Specification.md`
- `System Design/Failure_Handling_Model.md`
- `System Design/SRS/SRS.md` and annexes
- `software design/components/ARCHITECTURE.md`
- `software design/components/application_layer/business_stack/*/COMPONENT_SPEC.md`
## 2. What Was Updated
### 2.1 Features.md
**Updates:**
- Added version 2.0 header with date and platform information
- Added technology stack summary section
- Added new features:
- **F-DAQ-04:** Sensor State Management (updated with state flow)
- **F-DQC-05:** Redundant Sensor Support (NEW)
- **F-COM-04:** Long-Range Fallback Communication (NEW)
- **F-DIAG-04:** Layered Watchdog System (NEW)
- **F-DATA-04:** Power-Loss Data Protection (NEW)
- **F-OTA-05:** A/B Partitioning with Rollback (NEW)
- **F-SEC-04:** Security Violation Handling (NEW)
- **F-SYS-05:** GPIO & Hardware Discipline (NEW)
- **F-PWR-01, F-PWR-02:** Power & Fault Handling Features (NEW)
- **F-HW-01, F-HW-02:** Hardware Abstraction Features (NEW)
- Updated technology specifications for all features
- Added traceability section
### 2.2 [COM] Communication Features.md
**Updates:**
- Added version 2.0 header
- Added technology stack section with detailed specifications:
- Wi-Fi 802.11n (2.4 GHz) configuration
- MQTT protocol configuration
- TLS 1.2 / mTLS configuration
- ESP-NOW configuration
- CBOR encoding configuration
- Added F-COM-04: Long-Range Fallback Communication (NEW)
- Added new system requirements (SR-COM-011 through SR-COM-017)
- Added technology specifications section
- Updated traceability mapping
### 2.3 [SEC] Security & Safety Features.md
**Updates:**
- Added version 2.0 header
- Added technology stack section:
- Secure Boot V2 specifications
- Flash Encryption (AES-256) specifications
- mTLS and X.509 certificate specifications
- Added F-SEC-04: Security Violation Handling (NEW)
- Added new system requirements (SR-SEC-013 through SR-SEC-015)
- Added implementation notes with technology details
- Added industrial standards compliance section
### 2.4 [OTA] Firmware Update (OTA) Features.md
**Updates:**
- Added version 2.0 header
- Added partition layout table (8MB flash)
- Added F-OTA-05: A/B Partitioning with Rollback (NEW)
- Added OTA policy table with detailed rules
- Added new system requirements (SR-OTA-014 through SR-OTA-016)
- Added technology specifications (SHA-256, A/B partitioning)
- Added gap closure section
### 2.5 New Feature Files Created
- ✅ `[PWR] Power & Fault Handling Features.md` – NEW
- ✅ `[HW] Hardware Abstraction Features.md` – NEW
### 2.6 New Documentation Files Created
- ✅ `System_Architecture_Documentation.md` – Comprehensive system documentation
- ✅ `Migration_and_Updates_Log.md` – This document
## 3. What Still Needs to Be Specified
### 3.1 Feature Files Requiring Updates
The following feature files were copied but may need updates based on gap analysis:
- ⚠️ `[DAQ] Sensor Data Acquisition Features.md`
- **Action:** Add sensor state management details (F-DAQ-04)
- **Action:** Add filtering algorithm specifications (Median filter N=5, Rate-of-change limiter)
- **Action:** Add timing requirements (maximum 100ms per sensor acquisition cycle)
- ⚠️ `[DQC] Data Quality & Calibration Features.md`
- **Action:** Add redundant sensor support details (F-DQC-05)
- **Action:** Add sensor fusion algorithm specifications
- ⚠️ `[DIAG] Diagnostics & Health Monitoring Features.md`
- **Action:** Add layered watchdog system details (F-DIAG-04)
- **Action:** Add diagnostic code format details (0xSCCC)
- **Action:** Add subsystem code allocation table
- ⚠️ `[DATA] Persistence & Data Management Features.md`
- **Action:** Add power-loss data protection details (F-DATA-04)
- **Action:** Add wear-aware management specifications
- **Action:** Add storage separation details (NVS vs SD Card)
- ⚠️ `[SYS] System Management Features.md`
- **Action:** Add GPIO & Hardware Discipline details (F-SYS-05)
- **Action:** Add canonical GPIO map reference
- **Action:** Update state list to include all 11 states
### 3.2 Missing Specifications
- ⚠️ **GPIO Map Document**
- **Action:** Create canonical GPIO map document
- **Location:** `System Design/system_arch_final/GPIO_Map.md`
- **Content:** Complete GPIO pin assignments, strapping pin warnings, ADC1/ADC2 separation, I2C pull-up requirements
- ⚠️ **Sensor Abstraction Layer (SAL) Interface Specification**
- **Action:** Create detailed SAL interface specification
- **Location:** `System Design/system_arch_final/SAL_Interface_Specification.md`
- **Content:** Complete API definition, sensor state machine, calibration procedures
- ⚠️ **Communication Protocol Specification**
- **Action:** Create detailed MQTT topic structure and CBOR schema specification
- **Location:** `System Design/system_arch_final/Communication_Protocol_Specification.md`
- **Content:** Topic hierarchy, message formats, CBOR schemas, versioning strategy
- ⚠️ **Storage Layout Specification**
- **Action:** Create detailed storage layout specification
- **Location:** `System Design/system_arch_final/Storage_Layout_Specification.md`
- **Content:** SD card file structure, NVS namespace layout, partition table details
### 3.3 Integration with SRS
- ⚠️ **SRS Updates**
- **Action:** Review SRS for new features (PWR, HW) and ensure all SWRs are derived
- **Location:** `System Design/SRS/SRS.md`
- **Status:** SRS may need updates for new features
- ⚠️ **Traceability Updates**
- **Action:** Update traceability matrix for new features
- **Location:** `System Design/SRS/Annex_A_Traceability.md`
- **Status:** New features need traceability links
### 3.4 Component Design
- ⚠️ **Component Specifications**
- **Action:** Create component specifications for new components (Power Manager, Hardware Abstraction Layer)
- **Location:** `software design/components/application_layer/.../COMPONENT_SPEC.md`
- **Status:** New components need specifications
## 4. Recommended Actions
### 4.1 Immediate Actions (Before Implementation)
1. **Update Remaining Feature Files**
- Update DAQ, DQC, DIAG, DATA, SYS feature files with new details
- Add technology specifications where missing
2. **Create Missing Specifications**
- GPIO Map document
- SAL Interface Specification
- Communication Protocol Specification
- Storage Layout Specification
3. **Update SRS**
- Derive SWRs for new features (PWR, HW)
- Update traceability matrix
### 4.2 Short-Term Actions (During Component Design)
1. **Component Specifications**
- Create specifications for Power Manager component
- Create specifications for Hardware Abstraction Layer component
- Update existing component specs if needed
2. **API Definitions**
- Finalize SAL API
- Finalize DP component API
- Finalize Event System API
### 4.3 Long-Term Actions (During Implementation)
1. **Test Specifications**
- Create test cases for new features
- Update V&V matrix
2. **Documentation**
- Update user documentation
- Create developer guides
## 5. Document Status
**Status:** Complete for initial migration
**Next Review:** After feature file updates
**Owner:** System Architecture Team
---
**This log should be updated whenever changes are made to the system architecture documentation.**

83
draft/system_arch_final_old/System Assumptions & Limitations.md Normal file
View File

@@ -0,0 +1,83 @@
## 1\. System Assumptions
### SA-01: Deployment Environment
* The Sensor Hub operates in an indoor poultry farm environment.
* Environmental conditions may include high humidity, dust, and ammonia presence.
### SA-02: Power Availability
* The Sensor Hub is assumed to have continuous power.
* Short power interruptions may occur; system shall recover gracefully.
### SA-03: Network Connectivity
* Wireless connectivity to the Main Hub may be intermittent.
* The Sensor Hub shall operate autonomously when disconnected.
### SA-04: Trusted Provisioning
* Devices are assumed to be provisioned securely during manufacturing or installation.
* Cryptographic keys are assumed to be injected via a secure process.
### SA-05: Time Synchronization
* System time is assumed to be synchronized periodically by the Main Hub.
* Temporary time drift is acceptable.
## 2\. System Limitations
### SL-01: Local Processing Limits
* The Sensor Hub performs lightweight preprocessing only.
* Complex analytics and AI models are out of scope.
### SL-02: User Interface Constraints
* The OLED display is intended for monitoring and diagnostics only.
* It is not a full configuration or management interface.
### SL-03: Physical Security
* The Sensor Hub does not include physical tamper detection.
* Physical access is assumed to be restricted.
### SL-04: Storage Constraints
* SD card storage capacity is finite.
* Data retention policies may result in data overwrite.
### SL-05: Safety Classification
* The system is not classified as a safety-critical life-support system.
* Failures may impact farm performance but not human safety directly.
## 3\. External Dependencies
* ESP32-S3 hardware platform
* ESP-IDF framework
* Supported sensors and communication modules
* Main Hub availability for OTA and configuration updates

302
draft/system_arch_final_old/System_Architecture_Documentation.md Normal file
View File

@@ -0,0 +1,302 @@
# ASF Sensor Hub – System Architecture Documentation
**Version:** 2.0
**Date:** 2025-01-19
**Platform:** ESP32-S3, ESP-IDF v5.4
**Status:** Final for Implementation Phase
## 1. Document Purpose
This document provides comprehensive system architecture documentation for the ASF Sensor Hub (Sub-Hub). It consolidates all architectural decisions, technology choices, feature definitions, and system specifications required for the implementation phase.
## 2. Document Structure
This documentation package includes:
1. **Features.md** – Complete feature catalog with technology specifications
2. **Feature Files** – Detailed feature specifications:
- `[DAQ] Sensor Data Acquisition Features.md`
- `[DQC] Data Quality & Calibration Features.md`
- `[COM] Communication Features.md`
- `[DIAG] Diagnostics & Health Monitoring Features.md`
- `[DATA] Persistence & Data Management Features.md`
- `[OTA] Firmware Update (OTA) Features.md`
- `[SEC] Security & Safety Features.md`
- `[SYS] System Management Features.md`
- `[PWR] Power & Fault Handling Features.md` [NEW]
- `[HW] Hardware Abstraction Features.md` [NEW]
3. **Cross-Feature Constraints.md** – Architectural constraints
4. **System Assumptions & Limitations.md** – System context and boundaries
5. **System State Machine Specification** – Complete FSM definition
6. **Failure Handling Model** – Fault taxonomy and recovery rules
## 3. System Overview
### 3.1 Platform
- **Hardware:** ESP32-S3 microcontroller
- **Framework:** ESP-IDF v5.4
- **RTOS:** FreeRTOS (included in ESP-IDF)
- **Language:** C/C++
### 3.2 Technology Stack
| Layer | Technology | Justification |
|-------|------------|---------------|
| **Hardware** | ESP32-S3 | Dual-core, 512KB SRAM, 8MB flash, security features |
| **Framework** | ESP-IDF v5.4 | Native support, mature drivers |
| **Physical/Link** | Wi-Fi 802.11n (2.4 GHz) | Native support, good range, sufficient throughput |
| **Peer-to-Peer** | ESP-NOW | Deterministic, low-latency, no AP dependency |
| **Application Protocol** | MQTT over TLS 1.2 | Store-and-forward, keepalive, industrial standard |
| **Payload Encoding** | CBOR | Binary, efficient, versioned |
| **Security** | Secure Boot V2, Flash Encryption, mTLS | Hardware root of trust, IP protection |
| **Storage** | FAT32 (SD Card), NVS (Encrypted) | Wear-aware, reliable |
| **OTA** | A/B Partitioning, SHA-256 | Safe updates, automatic rollback |
### 3.3 System States
The system operates as a finite state machine with 11 states:
1. **INIT** – Hardware and software initialization
2. **BOOT_FAILURE** – Secure boot verification failed
3. **RUNNING** – Normal sensor acquisition and communication
4. **WARNING** – Non-fatal fault detected, degraded operation
5. **FAULT** – Fatal error, core functionality disabled
6. **OTA_PREP** – OTA preparation phase
7. **OTA_UPDATE** – Firmware update in progress
8. **MC_UPDATE** – Machine constants update in progress
9. **TEARDOWN** – Controlled shutdown sequence
10. **SERVICE** – Engineering or diagnostic interaction
11. **SD_DEGRADED** – SD card failure detected, fallback mode
**Reference:** `System_State_Machine_Specification.md`
## 4. Feature Groups
### 4.1 Sensor Data Acquisition (DAQ)
- **F-DAQ-01:** Multi-Sensor Data Acquisition
- **F-DAQ-02:** High-Frequency Sampling and Local Filtering
- **F-DAQ-03:** Timestamped Sensor Data Generation
- **F-DAQ-04:** Sensor State Management [UPDATED]
**Technology:** Sensor Abstraction Layer (SAL), Median filter N=5, Rate-of-change limiter
### 4.2 Data Quality & Calibration (DQC)
- **F-DQC-01:** Automatic Sensor Detection
- **F-DQC-02:** Sensor Type Enforcement
- **F-DQC-03:** Sensor Failure Detection
- **F-DQC-04:** Machine Constants & Calibration Management
- **F-DQC-05:** Redundant Sensor Support [NEW]
### 4.3 Communication (COM)
- **F-COM-01:** Main Hub Communication (MQTT over TLS 1.2)
- **F-COM-02:** On-Demand Data Broadcasting
- **F-COM-03:** Peer Sensor Hub Communication (ESP-NOW)
- **F-COM-04:** Long-Range Fallback Communication [NEW]
**Technology:** Wi-Fi 802.11n, MQTT, TLS 1.2/mTLS, CBOR encoding, ESP-NOW
### 4.4 Diagnostics & Health Monitoring (DIAG)
- **F-DIAG-01:** Diagnostic Code Management
- **F-DIAG-02:** Diagnostic Data Storage
- **F-DIAG-03:** Diagnostic Session
- **F-DIAG-04:** Layered Watchdog System [NEW]
**Technology:** Diagnostic code format `0xSCCC`, Bounded circular log, Task/Interrupt/RTC watchdogs
### 4.5 Persistence & Data Management (DATA)
- **F-DATA-01:** Persistent Sensor Data Storage
- **F-DATA-02:** Data Persistence Abstraction (DP Component)
- **F-DATA-03:** Safe Data Handling During State Transitions
- **F-DATA-04:** Power-Loss Data Protection [NEW]
**Technology:** FAT32 (SD Card), NVS (Encrypted), Wear-aware batch writing
### 4.6 Firmware Update (OTA)
- **F-OTA-01:** OTA Update Negotiation
- **F-OTA-02:** Firmware Reception and Storage
- **F-OTA-03:** Firmware Integrity Validation (SHA-256)
- **F-OTA-04:** Safe Firmware Activation
- **F-OTA-05:** A/B Partitioning with Rollback [NEW]
**Technology:** A/B partitioning (ota_0/ota_1), SHA-256 hash verification, Automatic rollback
### 4.7 Security & Safety (SEC)
- **F-SEC-01:** Secure Boot (Secure Boot V2)
- **F-SEC-02:** Secure Flash Storage (Flash Encryption, AES-256)
- **F-SEC-03:** Encrypted Communication (mTLS, X.509 certificates)
- **F-SEC-04:** Security Violation Handling [NEW]
**Technology:** Secure Boot V2, Flash Encryption (AES-256), mTLS, X.509 certificates
### 4.8 System Management (SYS)
- **F-SYS-01:** System State Management
- **F-SYS-02:** Controlled Teardown Mechanism
- **F-SYS-03:** Status Indication (OLED-Based HMI)
- **F-SYS-04:** Debug & Engineering Sessions
- **F-SYS-05:** GPIO & Hardware Discipline [NEW]
**Technology:** OLED I2C display, Three-button navigation, State machine enforcement
### 4.9 Power & Fault Handling (PWR) [NEW]
- **F-PWR-01:** Brownout Detection and Handling
- **F-PWR-02:** Power-Loss Recovery
**Technology:** Hardware brownout detector (BOD), Supercapacitor (optional), RTC battery (optional)
### 4.10 Hardware Abstraction (HW) [NEW]
- **F-HW-01:** Sensor Abstraction Layer (SAL)
- **F-HW-02:** Hardware Interface Abstraction
**Technology:** SAL interface, ESP-IDF driver wrappers, GPIO discipline
## 5. Architectural Principles
### 5.1 Layered Architecture
```
Application Layer
↓
Business Stack (STM, Event System, Managers)
↓
DP Stack (Data Pool, Persistence)
↓
Drivers (Network, Sensors, Storage)
↓
ESP-IDF Wrappers (GPIO, I2C, SPI, UART, ADC)
↓
ESP-IDF Framework
↓
Hardware (ESP32-S3)
```
**Constraint:** Application layer SHALL NOT access hardware directly (CFC-ARCH-01)
### 5.2 State-Aware Execution
All features must be aware of the current system state and respect state-based operation restrictions.
**Reference:** `System_State_Machine_Specification.md`
### 5.3 Event-Driven Communication
Internal communication uses an event-driven publish/subscribe model.
**Reference:** `software design/components/application_layer/business_stack/event_system/COMPONENT_SPEC.md`
### 5.4 Data Persistence Abstraction
All persistent data access goes through the DP (Data Persistence) component.
**Reference:** `software design/components/application_layer/DP_stack/persistence/COMPONENT_SPEC.md`
## 6. Key Specifications
### 6.1 System State Machine
**Document:** `System_State_Machine_Specification.md`
- 11 states with defined transitions
- Per-state feature execution rules
- State transition timing requirements
### 6.2 Failure Handling Model
**Document:** `Failure_Handling_Model.md`
- Fault taxonomy (INFO, WARNING, ERROR, FATAL)
- 7 fault categories with detection rules
- Escalation and recovery behaviors
- Integration with state machine
### 6.3 Cross-Feature Constraints
**Document:** `Cross-Feature Constraints.md`
- Architectural constraints (CFC-ARCH-*)
- Timing constraints (CFC-TIME-*)
- Data constraints (CFC-DATA-*)
- Security constraints (CFC-SEC-*)
- HMI/Debug constraints (CFC-HMI-*, CFC-DBG-*)
## 7. Implementation Readiness
### 7.1 Completed Artifacts
- ✅ Feature definitions with technology specifications
- ✅ System State Machine Specification
- ✅ Failure Handling Model
- ✅ Software Requirements Specification (SRS)
- ✅ Static Architecture Views
- ✅ Component Specifications (STM, Event System, Persistence)
- ✅ Verification & Validation Matrix
### 7.2 Next Steps
1. **Component Design Phase:**
- Detailed component APIs
- Threading models
- Error handling strategies
- State machine implementation
2. **Implementation Phase:**
- Code implementation following SRS
- Unit tests
- Integration tests
- HIL/System tests
## 8. Traceability
All features trace to:
- System Requirements (SR-*)
- Software Requirements (SWR-*)
- System State Machine Specification
- Failure Handling Model
- Cross-Feature Constraints
- Component Specifications
**Reference:** `System Design/SRS/Annex_A_Traceability.md`
## 9. References
### 9.1 Internal Documents
- `Features.md` – Feature catalog
- `[XXX] Feature Files.md` – Detailed feature specifications
- `Cross-Feature Constraints.md` – Architectural constraints
- `System Assumptions & Limitations.md` – System context
- `System_State_Machine_Specification.md` – FSM definition
- `Failure_Handling_Model.md` – Fault taxonomy
### 9.2 External Documents
- `System Design/SRS/SRS.md` – Software Requirements Specification
- `System Design/SRS/Annex_A_Traceability.md` – Traceability matrix
- `System Design/SRS/Annex_B_Interfaces.md` – External interfaces
- `System Design/SRS/Annex_C_Budgets.md` – Timing and resource budgets
- `System Design/SRS/VV_Matrix.md` – Verification & Validation matrix
- `software design/components/ARCHITECTURE.md` – Static architecture views
- `software design/components/application_layer/business_stack/STM/COMPONENT_SPEC.md` – State Manager spec
- `software design/components/application_layer/business_stack/event_system/COMPONENT_SPEC.md` – Event System spec
- `software design/components/application_layer/DP_stack/persistence/COMPONENT_SPEC.md` – Persistence spec
## 10. Document Status
**Status:** Final for Implementation Phase
**Version:** 2.0
**Date:** 2025-01-19
**Next Review:** After Component Design Phase
---
**This document serves as the authoritative system architecture reference for the ASF Sensor Hub implementation phase.**

349
draft/system_arch_final_old/[COM] Communication Features.md Normal file
View File

@@ -0,0 +1,349 @@
# Feature Engineering Specification
## Communication Features
**Feature Group ID:** FG-COM
**Version:** 2.0
**Date:** 2025-01-19
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
**Applies To:** Indoor poultry farm sensor hubs
**Dependencies:**
* Sensor Data Acquisition (FG-DAQ)
* Data Quality & Calibration (FG-DQC)
* Diagnostics & Health Monitoring (FG-DIAG)
* Security & Safety Features (FG-SEC)
## 1. Purpose and Objectives
The **Communication Features** define how the Sensor Hub exchanges data and control information with external entities. These features ensure that sensor data, diagnostics, configuration updates, and control requests are transferred in a **reliable, secure, and deterministic manner**.
The communication layer is designed to:
* Support hierarchical farm architecture (Sensor Hub → Main Hub)
* Enable on-demand and event-driven data transfer
* Allow limited peer-to-peer communication between Sensor Hubs
* Maintain robustness under intermittent connectivity
**Technology Stack:**
- **Primary Uplink:** Wi-Fi 802.11n (2.4 GHz)
- **Application Protocol:** MQTT over TLS 1.2
- **Peer-to-Peer:** ESP-NOW
- **Payload Encoding:** CBOR (Binary, versioned)
- **Long-Range Fallback:** LoRa (External Module, optional)
## 2. Feature Overview and Relationships
| Feature ID | Feature Name | Primary Objective | Related Features |
|------------|--------------|-------------------|------------------|
| F-COM-01 | Main Hub Communication | Primary uplink/downlink with Main Hub | OTA, Diagnostics, MC Management |
| F-COM-02 | On-Demand Data Broadcasting | Provide latest data upon request | DAQ, DP Stack |
| F-COM-03 | Peer Sensor Hub Communication | Limited hub-to-hub coordination | System Management |
| F-COM-04 | Long-Range Fallback Communication | Farm-scale connectivity resilience | System Management |
## 3. Functional Feature Descriptions
### 3.1 F-COM-01: Main Hub Communication
**Description**
The Sensor Hub shall establish and maintain a bidirectional communication channel with the Main Hub using **MQTT over TLS 1.2**.
**Protocol Stack:**
```
Application Layer (MQTT)
↓
Transport Security Layer (TLS 1.2 / mTLS)
↓
Network Layer (Wi-Fi 802.11n 2.4 GHz)
↓
Physical Layer
```
**MQTT Configuration:**
- **Broker:** Main Hub / Edge Gateway
- **QoS:** QoS 1 (At least once delivery)
- **Retain:** Used for configuration topics only
- **Payload:** CBOR (Binary, versioned for efficiency and compatibility)
- **Keepalive:** 60 seconds (default)
- **Maximum Message Size:** 8KB
**Topic Structure:**
```
/farm/{site_id}/{house_id}/{node_id}/data/{sensor_id}
/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}
/farm/{site_id}/{house_id}/{node_id}/ota/{action}
```
**Heartbeat Mechanism:**
- **Interval:** 10 seconds
- **Timeout:** 3 missed heartbeats (30 seconds) triggers "offline" status
- **Payload includes:**
- Uptime (seconds)
- Firmware version (string)
- Free heap memory (bytes)
- RSSI (signal strength, dBm)
- Error bitmap (32-bit)
- System state
**Key Capabilities**
* Bidirectional communication
* Command and response handling
* Diagnostics and status reporting
* Integration with OTA and MC updates
* Store-and-forward messaging (handles intermittent connectivity)
* Automatic reconnection with exponential backoff
**Wi-Fi Configuration:**
- **Standard:** 802.11n (2.4 GHz)
- **Minimum RSSI:** -85 dBm (connection threshold)
- **Channel Selection:** Automatic (avoid interference)
- **Power Management:** Active mode (no PSM for real-time requirements)
### 3.2 F-COM-02: On-Demand Data Broadcasting
**Description**
The Sensor Hub shall support on-demand transmission of the most recent sensor data upon request from the Main Hub. This allows the Main Hub to query real-time conditions without waiting for periodic reporting cycles.
**Response Time:** Maximum 100ms from request to response transmission.
Data broadcasts include timestamped sensor values and associated validity status.
**Key Capabilities**
* Request/response data exchange
* Latest-value data delivery
* Timestamp and validity inclusion
* Low-latency response (≤100ms)
### 3.3 F-COM-03: Peer Sensor Hub Communication
**Description**
Sensor Hubs shall be capable of limited peer-to-peer communication using **ESP-NOW** for coordination purposes such as connectivity checks, time synchronization assistance, or basic status exchange.
**ESP-NOW Configuration:**
- **Protocol:** ESP-NOW (deterministic, low-latency)
- **Range:** ~200m line-of-sight, ~50m through walls
- **Maximum Peers:** 20
- **Security:** Application-layer encryption (AES-128 minimum) required
- **Acknowledgment:** Application-layer acknowledgment and retry mechanism
**Message Types:**
- `PEER_PING`: Connectivity check
- `PEER_PONG`: Connectivity response
- `PEER_TIME_SYNC`: Time synchronization request
- `PEER_TIME_RESP`: Time synchronization response
**Key Capabilities**
* Hub-to-hub message exchange
* Minimal command set
* No dependency on centralized infrastructure
* Isolation from control logic
* Encrypted communication (application-layer)
**Constraints:**
- Peer communication SHALL NOT interfere with Main Hub communication
- Peer communication SHALL be limited to coordination functions only
- Maximum peer count: 20 (ESP-NOW limitation)
### 3.4 F-COM-04: Long-Range Fallback Communication [NEW]
**Description**
The system supports optional long-range fallback communication using **LoRa (External Module)** for farm-scale distances where Wi-Fi may not reach.
**Note:** This feature is **optional** and requires cost-benefit analysis. Alternative: Cellular (LTE-M/NB-IoT) if farm has cellular coverage.
**LoRa Configuration (if implemented):**
- **Module:** External LoRa module (e.g., SX1276, SX1262)
- **Protocol:** LoRaWAN or raw LoRa
- **Use Cases:** Emergency alerts, data backup (not for OTA updates)
- **Data Rate:** Low (may not support OTA updates)
**Alternative Consideration:**
- **Cellular (LTE-M/NB-IoT):** Higher data rate, better for OTA updates, more expensive but more reliable in some regions
## 4. System Requirements (Formal SHALL Statements)
### 4.1 Main Hub Communication
**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-011** [NEW]
The system shall implement a heartbeat mechanism with 10-second interval and 30-second timeout.
**SR-COM-012** [NEW]
The system shall use CBOR encoding for all MQTT payloads.
**SR-COM-013** [NEW]
The system shall support automatic reconnection with exponential backoff on connection loss.
### 4.2 On-Demand Data Broadcasting
**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.
### 4.3 Peer Sensor Hub Communication
**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-014** [NEW]
The system shall encrypt all ESP-NOW peer communication using application-layer encryption (AES-128 minimum).
**SR-COM-015** [NEW]
The system shall implement acknowledgment and retry mechanism for ESP-NOW peer communication.
### 4.4 Long-Range Fallback Communication [NEW]
**SR-COM-016** [NEW]
The system may support long-range fallback communication using LoRa or cellular (LTE-M/NB-IoT) for farm-scale distances.
**SR-COM-017** [NEW]
If implemented, long-range fallback communication shall be used only for emergency alerts and data backup, not for OTA updates.
## 5. Technology Specifications
### 5.1 Wi-Fi 802.11n (2.4 GHz)
**Rationale:**
- Native ESP32-S3 support
- Existing farm infrastructure compatibility
- Mature ESP-IDF drivers
- High data rate for OTA firmware updates (150 Mbps theoretical, ~20-30 Mbps practical)
- Good range and penetration for farm structures
**Configuration:**
- **Standard:** 802.11n
- **Frequency:** 2.4 GHz
- **Minimum RSSI:** -85 dBm
- **Channel Selection:** Automatic
- **Power Management:** Active mode
### 5.2 MQTT Protocol
**Rationale:**
- Store-and-forward messaging (handles intermittent connectivity gracefully)
- Built-in keepalive mechanism (monitors connection health automatically)
- QoS levels for delivery guarantees
- Massive industrial adoption (SCADA, IIoT)
- Native ESP-IDF support (esp_mqtt component)
**Configuration:**
- **QoS Level:** 1 (At least once delivery)
- **Retain Flag:** Used for configuration topics only
- **Keepalive:** 60 seconds
- **Maximum Message Size:** 8KB
- **Broker Compatibility:** Mosquitto 2.x, HiveMQ, or compatible
### 5.3 TLS 1.2 / mTLS
**Rationale:**
- Strong security (mutual authentication)
- Industry standard
- ESP-IDF native support (mbedTLS)
- Prevents man-in-the-middle attacks
**Configuration:**
- **TLS Version:** 1.2 (minimum)
- **Authentication:** Mutual TLS (mTLS)
- **Certificate:** Device-unique X.509 certificate
- **Private Key:** Stored in eFuse or encrypted flash
- **Maximum Certificate Size:** <2KB (ESP32-S3 optimization)
### 5.4 ESP-NOW
**Rationale:**
- Deterministic, low-latency communication
- No AP dependency
- Native ESP32-S3 support
- Low power consumption
**Configuration:**
- **Maximum Peers:** 20
- **Security:** Application-layer encryption (AES-128 minimum)
- **Acknowledgment:** Application-layer implementation required
### 5.5 CBOR Encoding
**Rationale:**
- Binary format (efficient, ~30-50% smaller than JSON)
- Versioned payloads (backward compatibility)
- Standardized (RFC 8949)
- Good library support (TinyCBOR, QCBOR)
**Configuration:**
- **Schema Versioning:** Required
- **Maximum Payload Size:** 8KB per message type
- **Schema Validation:** On Main Hub side
## 6. Traceability Mapping
### 6.1 Feature → System Requirement Mapping
```mermaid
graph TD
F-COM-01 -->|Main Hub Communication| SR-COM-001
F-COM-01 -->|Transmit Data| SR-COM-002
F-COM-01 -->|Receive Commands| SR-COM-003
F-COM-01 -->|Monitor Link Status| SR-COM-004
F-COM-01 -->|Heartbeat| SR-COM-011
F-COM-01 -->|CBOR Encoding| SR-COM-012
F-COM-01 -->|Auto Reconnect| SR-COM-013
F-COM-02 -->|On-Demand Requests| SR-COM-005
F-COM-02 -->|Respond with Data| SR-COM-006
F-COM-02 -->|Include Validity Info| SR-COM-007
F-COM-03 -->|Peer Communication| SR-COM-008
F-COM-03 -->|Peer Coordination| SR-COM-009
F-COM-03 -->|Isolate Peer Traffic| SR-COM-010
F-COM-03 -->|ESP-NOW Encryption| SR-COM-014
F-COM-03 -->|ESP-NOW Acknowledgment| SR-COM-015
F-COM-04 -->|Long-Range Fallback| SR-COM-016
F-COM-04 -->|Fallback Use Cases| SR-COM-017
```
## 7. Engineering Notes and Constraints
* **MQTT Broker Compatibility:** Specify broker version (e.g., Mosquitto 2.x, HiveMQ)
* **Message Size Limits:** Maximum 8KB per message
* **Topic Naming:** Follow hierarchical structure `/farm/{site}/{house}/{node}/...`
* **Security:** All communication encrypted via TLS 1.2 / mTLS (defined under Security Features)
* **ESP-NOW Security:** Application-layer encryption required (AES-128 minimum)
* **Communication failures** shall trigger diagnostics events but shall not block sensor acquisition
* **LoRa Fallback:** Optional feature requiring cost-benefit analysis
## 8. Dependencies
* **Security Features:** TLS/mTLS implementation
* **System Management:** State-aware communication restrictions
* **Diagnostics:** Communication failure reporting
* **Data Acquisition:** Sensor data for transmission

339
draft/system_arch_final_old/[DAQ] Sensor Data Acquisition Features.md Normal file
View File

@@ -0,0 +1,339 @@
# **ASF Sensor Hub**
## **Feature Engineering Specification**
## **Sensor Data Acquisition Features**
## **1\. Feature Overview**
### **Feature Name**
Sensor Data Acquisition Features
### **Feature ID**
FEAT-DAQ
### **Subsystem**
ASF Sensor Hub (Sub-Hub)
### **Target Platform**
ESP32-S3–based embedded system
### **Scope**
This feature defines the capabilities of the Sensor Hub related to:
* Environmental sensor data acquisition
* Local preprocessing and filtering
* Timestamping and preparation of sensor data for persistence and communication
This feature **does NOT include**:
* Main Hub processing
* Cloud analytics
* Control logic
* OTA, diagnostics, or persistence mechanisms (referenced only as dependencies)
## **2\. Purpose and Engineering Rationale**
Modern poultry farm automation systems require **high-resolution, reliable, and time-correlated environmental data** to enable:
* Accurate environmental control
* Early fault detection
* Advanced analytics and machine learning
The Sensor Data Acquisition feature ensures:
* Deterministic sensor sampling
* Noise-resilient measurements
* Temporal traceability of data
* Decoupling of acquisition from communication and control
This aligns with **distributed intelligence principles** used in leading international poultry automation systems.
## **3\. Feature Decomposition**
The Sensor Data Acquisition feature is decomposed into the following sub-features:
<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">Sub-Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Name</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">Multi-Sensor Data Acquisition</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">High-Frequency Sampling and Local Filtering</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">Timestamped Sensor Data Generation</p></td></tr></tbody></table></figure>
## **4\. Functional Description**
### **4.1 F-DAQ-01: Multi-Sensor Data Acquisition**
#### **Description**
The Sensor Hub acquires environmental data from multiple heterogeneous sensors connected to dedicated hardware interfaces.
#### **Supported Sensor Types**
* Temperature
* Relative Humidity
* Carbon Dioxide (CO₂)
* Ammonia (NH₃)
* Volatile Organic Compounds (VOC)
* Particulate Matter (PM)
* Light Intensity
Each sensor:
* Is mapped to a predefined hardware slot
* Has a dedicated driver abstraction
* Can be independently enabled or disabled
#### **Key Characteristics**
* Concurrent sensor handling
* Modular sensor driver architecture
* Runtime awareness of sensor presence
### **4.2 F-DAQ-02: High-Frequency Sampling and Local Filtering**
#### **Description**
For each enabled sensor, the system performs multiple raw readings per acquisition cycle and applies a local filtering mechanism to produce a single representative value.
#### **Sampling Behavior**
* Each sensor is sampled **N times per cycle** (default: 10)
* Sampling occurs within a bounded time window
* Sampling frequency is configurable via Machine Constants
#### **Filtering Behavior**
* Filtering is executed locally on the Sensor Hub
* Filtering algorithms are abstracted and replaceable
* Examples (non-exhaustive):
* Moving average
* Median filter
* Outlier rejection
#### **Objective**
* Reduce sensor noise
* Improve data stability
* Avoid propagating raw sensor jitter upstream
### **4.3 F-DAQ-03: Timestamped Sensor Data Generation**
#### **Description**
Each processed sensor value is associated with a timestamp generated by the Sensor Hub.
#### **Timestamp Characteristics**
* Generated after filtering completion
* Represents the effective measurement time
* Based on system time (RTC or synchronized clock)
#### **Sensor Data Record**
Each record includes:
* Sensor ID
* Sensor type
* Filtered value
* Unit of measurement
* Timestamp
* Data validity status
## **5\. Operational Flow**
### **Normal Acquisition Cycle**
1. Detect enabled sensors
2. Initialize sensor drivers (if not already active)
3. Perform high-frequency sampling per sensor
4. Apply local filtering
5. Generate timestamp
6. Create sensor data record
7. Forward data to:
* Data Persistence component
* Communication component (on request)
## **6\. Constraints and Assumptions**
### **Constraints**
* Sensor acquisition must not block system-critical tasks
* Sampling and filtering must complete within a bounded cycle time
* Memory usage must be deterministic
### **Assumptions**
* Sensor presence detection is handled by a separate feature
* Time synchronization is provided by another system component
* Storage and communication are decoupled from acquisition
## **7\. Architecture Diagram (PlantUML)**
### **7.1 Sensor Hub Component Diagram**
```mermaid
graph TD
subgraph "Sensor Hub"
SD["Sensor Drivers"] --> SE["Sampling Engine"]
SE --> FE["Filtering Engine"]
FE --> TS["Timestamp Service"]
TS --> DB["Sensor Data Buffer"]
end
SD -->|"raw samples"| SE
SE -->|"sampled data"| FE
FE -->|"filtered value"| TS
TS -->|"timestamped record"| DB
```
### **7.2 Acquisition Cycle Sequence Diagram**
```mermaid
sequenceDiagram
participant S as Sensor Driver
participant SE as Sampling Engine
participant FE as Filtering Engine
participant TS as Timestamp Service
S ->> SE: read()
loop N samples
SE ->> S: sample()
end
SE ->> FE: raw sample set
FE ->> TS: filtered value
TS ->> FE: timestamp
```
## **8\. Formal System SHALL Requirements**
### **8.1 Requirement Style**
* Each requirement uses **“The system shall …”**
* Each requirement has a unique ID
* Requirements are atomic and testable
### **8.2 Requirements List**
#### **Multi-Sensor Acquisition**
* **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.
#### **High-Frequency Sampling &amp; Filtering**
* **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-010**
The system shall complete sensor acquisition cycle within a maximum of 100ms per sensor.
#### **Timestamped Data Generation**
* **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.
#### **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**
| 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 |

192
draft/system_arch_final_old/[DATA] Persistence & Data Management Features.md Normal file
View File

@@ -0,0 +1,192 @@
<macro class="toc op-uc-placeholder op-uc-toc">
</macro>
# Feature Engineering Specification
## Persistence &amp; Data Management Features
**Feature Group ID:** FG-DATA
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub
**Applies To:** Indoor poultry farm sensor hubs
**Dependencies:**
* Sensor Data Acquisition (FG-DAQ)
* Data Quality &amp; Calibration (FG-DQC)
* Diagnostics &amp; Health Monitoring (FG-DIAG)
* System State Management / Teardown Mechanism
## 1\. Purpose and Objectives
The **Persistence &amp; Data Management Features** define how the Sensor Hub stores, protects, and manages critical runtime and historical data. These features ensure that:
* Sensor data and system state are not lost during resets or failures
* Data storage is abstracted from application logic
* Critical data is safely handled during firmware updates, configuration changes, or fatal faults
The persistence layer is a **foundational system service**, supporting diagnostics, calibration, OTA, and recovery operations.
## 2\. Feature Overview and Relationships
<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">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</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">Persistent Sensor Data Storage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Store timestamped sensor data</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DAQ, COM</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">Data Persistence Abstraction (DP)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Abstract storage access</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Application Layer</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">Safe Data Handling During State Transitions</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Protect data during teardown</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OTA, System Mgmt</p></td></tr></tbody></table></figure>
## 3\. Functional Feature Descriptions
### 3.1 F-DATA-01: Persistent Sensor Data Storage
**Description**
The system shall persist timestamped sensor data to non-volatile storage to support historical analysis, diagnostics correlation, and recovery scenarios.
Persistence may include:
* Filtered sensor values
* Timestamps
* Sensor validity and status metadata
The persistence policy (frequency, retention window, overwrite behavior) is configurable and optimized for storage longevity and performance.
**Key Capabilities**
* Non-volatile storage (SD card / NVM)
* Timestamped records
* Configurable retention policy
* Integration with DAQ and COM
### 3.2 F-DATA-02: Data Persistence Abstraction (DP Component)
**Description**
The system shall provide a **Data Persistence (DP) component** that abstracts storage access for all upper layers. Application and feature modules interact with the DP component rather than directly accessing storage hardware.
The DP component manages:
* Data model definitions
* Serialization and deserialization
* Storage backend selection
* Consistency and integrity guarantees
**Key Capabilities**
* Unified persistence API
* Storage backend abstraction
* Centralized data ownership
* Reduced coupling between layers
### 3.3 F-DATA-03: Safe Data Handling During State Transitions
**Description**
The system shall ensure safe and deterministic handling of data during critical state transitions, including:
* Firmware updates (OTA)
* Machine Constants updates
* System resets
* Fatal error handling
Before entering such transitions, the system executes a controlled data finalization process to flush buffers, persist critical state, and verify data integrity.
**Key Capabilities**
* Controlled data flush
* Atomic write operations
* Data integrity checks
* Coordination with teardown mechanism
## 4\. System Requirements (Formal SHALL Statements)
### 4.1 Persistent Sensor Data Storage
**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.
### 4.2 Data Persistence Abstraction (DP Component)
**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.
### 4.3 Safe Data Handling During State Transitions
**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.
### 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
| 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
* The DP component aligns with your **DP Stack** already defined in the architecture.
* Atomic write strategies (e.g., temp file + rename) are recommended.
* Diagnostic events should be generated on persistence failures.
* Storage wear-leveling considerations apply for SD/NVM.
##

183
draft/system_arch_final_old/[DIAG] Diagnostics & Health Monitoring Features.md Normal file
View File

@@ -0,0 +1,183 @@
<macro class="toc op-uc-placeholder op-uc-toc">
</macro>
# Feature Engineering Specification
## Diagnostics &amp; Health Monitoring Features
**Feature Group ID:** FG-DIAG
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub
**Applies To:** Indoor poultry farm sensor hubs
**Dependencies:**
* Sensor Data Acquisition (FG-DAQ)
* Data Quality &amp; Calibration (FG-DQC)
* Communication Features (FG-COM)
* Persistence / DP Stack
## 1\. Purpose and Objectives
The **Diagnostics &amp; Health Monitoring Features** provide a structured and persistent mechanism to detect, classify, record, and expose system faults, warnings, and health states.
These features ensure that:
* Failures are detectable and explainable
* Root causes are traceable
* Diagnostic data survives resets and power loss
* Engineers can access diagnostic information locally or remotely
The diagnostics subsystem is **non-intrusive**, meaning it shall not block core sensing or communication functions unless the system enters a fatal state.
## 2\. Feature Overview and Relationships
<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">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</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">Diagnostic Code Management</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Standardize fault and warning identification</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DQC, COM</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">Diagnostic Data Storage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Persist diagnostic events</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DP Stack</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">Diagnostic Session</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Engineer access to diagnostics</p></td><td class="op-uc-table--cell"><p class="op-uc-p">COM, System Mgmt</p></td></tr></tbody></table></figure>
## 3\. Functional Feature Descriptions
### 3.1 F-DIAG-01: Diagnostic Code Management
**Description**
The system shall implement a structured diagnostic code framework to represent system health conditions, warnings, errors, and fatal faults.
Each diagnostic event is associated with:
* A unique diagnostic code
* Severity level (info, warning, error, fatal)
* A hierarchical root-cause classification
* Timestamp and source component
This framework enables consistent fault handling across all system components.
**Key Capabilities**
* Unique diagnostic code registry
* Severity classification
* Root-cause hierarchy
* Event-based reporting
### 3.2 F-DIAG-02: Diagnostic Data Storage
**Description**
The system shall persist diagnostic events in non-volatile storage to allow post-failure analysis and long-term health monitoring.
Stored diagnostics remain available across system resets and power cycles until explicitly cleared by an authorized diagnostic session or command.
**Key Capabilities**
* Persistent storage of diagnostic events
* Timestamped records
* Bounded storage with overwrite policy
* Integration with DP / Persistence layer
### 3.3 F-DIAG-03: Diagnostic Session
**Description**
The system shall provide a diagnostic session that allows authorized engineers or tools to access diagnostic data, inspect system health, and perform maintenance operations.
The diagnostic session may be accessed locally or remotely via the communication interface and supports read and limited control operations.
**Key Capabilities**
* Session-based access
* Read diagnostics and health data
* Clear diagnostic records
* Controlled command execution
## 4\. System Requirements (Formal SHALL Statements)
### 4.1 Diagnostic Code Management
**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.
### 4.2 Diagnostic Data Storage
**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.
### 4.3 Diagnostic Session
**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.
### 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
| 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
* Diagnostic codes should be versioned to support firmware evolution.
* Diagnostic severity may be linked to LED indicators (green/yellow/red).
* Fatal diagnostics may trigger the teardown mechanism defined elsewhere.
* Security and access control for diagnostic sessions are handled under **Security &amp; Safety Features**.
##

197
draft/system_arch_final_old/[DQC] Data Quality & Calibration Features.md Normal file
View File

@@ -0,0 +1,197 @@
<macro class="toc op-uc-placeholder op-uc-toc">
</macro>
# Feature Engineering Specification
## Data Quality &amp; Calibration Features
**Feature Group ID:** FG-DQC
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub
**Applies To:** Indoor poultry farm sensor hubs
**Dependencies:** Sensor Data Acquisition Features (FG-DAQ), Diagnostics Features (FG-DIAG), Persistence / DP Stack
## 1\. Purpose and Objectives
The **Data Quality &amp; Calibration Features** ensure that all sensor data generated by the Sensor Hub is **valid, trustworthy, correctly classified, and calibrated** throughout the system lifecycle. These features provide mechanisms for:
* Automatic identification of connected sensors
* Enforcing correct sensor–slot compatibility
* Early detection and isolation of faulty sensors
* Centralized management of machine constants and calibration parameters
The goal is to maintain **high data integrity**, reduce commissioning errors, support **remote reconfiguration**, and ensure safe operation during updates or failures.
<br>
<macro class="embedded-table op-uc-placeholder op-uc-embedded-table" data-query-props="{&quot;columns[]&quot;:[&quot;id&quot;,&quot;subject&quot;,&quot;type&quot;,&quot;status&quot;,&quot;assignee&quot;,&quot;priority&quot;],&quot;showSums&quot;:false,&quot;timelineVisible&quot;:false,&quot;highlightingMode&quot;:&quot;none&quot;,&quot;includeSubprojects&quot;:true,&quot;showHierarchies&quot;:true,&quot;groupBy&quot;:&quot;&quot;,&quot;filters&quot;:&quot;[{\&quot;search\&quot;:{\&quot;operator\&quot;:\&quot;**\&quot;,\&quot;values\&quot;:[\&quot;DQC\&quot;]}}]&quot;,&quot;sortBy&quot;:&quot;[[\&quot;id\&quot;,\&quot;asc\&quot;]]&quot;,&quot;timestamps&quot;:&quot;PT0S&quot;}">
</macro>
## 2\. Feature Overview and Relationships
<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">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</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">Automatic Sensor Detection</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Detect connected sensors dynamically</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-01, F-DIAG-01</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">Sensor Type Enforcement</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Prevent incorrect sensor-slot usage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-01</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">Sensor Failure Detection</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Identify and isolate faulty sensors</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-02</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">Machine Constants &amp; Calibration Management</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Manage static configuration and calibration</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OTA, Persistence, Teardown</p></td></tr></tbody></table></figure>
## 3\. Functional Feature Descriptions
### 3.1 F-DQC-01: Automatic Sensor Detection
**Description**
The Sensor Hub shall automatically detect which sensors are physically connected at runtime. Each sensor slot provides a dedicated detection mechanism (e.g., GPIO presence pin or ID signal) that allows the system to determine whether a sensor is installed.
Detected sensors are dynamically initialized and incorporated into the data acquisition workflow without requiring firmware changes.
**Key Capabilities**
* Hardware-based presence detection
* Runtime sensor enumeration
* Dynamic initialization during boot or reconfiguration
* Integration with diagnostics and data acquisition
### 3.2 F-DQC-02: Sensor Type Enforcement
**Description**
Each physical sensor slot on the Sensor Hub is dedicated to a specific sensor type. The system enforces sensor-slot compatibility to prevent incorrect sensor insertion (e.g., humidity sensor in temperature slot).
This enforcement is achieved via electrical identification, pin mapping, or firmware configuration defined in Machine Constants.
**Key Capabilities**
* Fixed sensor-to-slot mapping
* Sensor identity verification
* Rejection of invalid sensor configurations
* Diagnostic reporting of configuration violations
### 3.3 F-DQC-03: Sensor Failure Detection
**Description**
The Sensor Hub continuously monitors sensor behavior to detect failures such as disconnection, out-of-range values, non-responsive sensors, or abnormal signal patterns.
Detected sensor failures are classified, logged, timestamped, and reported to the Main Hub. Failed sensors are excluded from control and analytics workflows to prevent propagation of invalid data.
**Key Capabilities**
* Runtime health monitoring
* Failure classification
* Fault isolation
* Diagnostic event generation
### 3.4 F-DQC-04: Machine Constants &amp; Calibration Management
**Description**
The system maintains a **Machine Constants (MC)** dataset that defines static and semi-static configuration parameters for the Sensor Hub, including:
* Installed sensor types and slots
* Communication identifiers and addressing
* Calibration coefficients and offsets
* Sensor-specific limits and scaling
Machine Constants are persisted in non-volatile storage (SD card) and loaded during system initialization. Updates may be received from the Main Hub and applied via a controlled teardown and reinitialization process.
**Key Capabilities**
* Persistent configuration storage
* Runtime loading and validation
* Remote update support
* Controlled reinitialization sequence
## 4\. System Requirements (Formal SHALL Statements)
### 4.1 Automatic Sensor Detection
**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.
### 4.2 Sensor Type Enforcement
**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.
### 4.3 Sensor Failure Detection
**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.
### 4.4 Machine Constants &amp; Calibration Management
**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.
### 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
| 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 |
##

150
draft/system_arch_final_old/[HW] Hardware Abstraction Features.md Normal file
View File

@@ -0,0 +1,150 @@
# Hardware Abstraction Features
**Feature Group ID:** FG-HW
**Version:** 1.0
**Date:** 2025-01-19
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
## 1 Feature Overview
The **Hardware Abstraction Features** provide a clean separation between application logic and hardware interfaces. These features ensure hardware independence, maintainability, and testability of the system.
**Architecture Principle:** Application layer SHALL NOT access hardware directly (CFC-ARCH-01).
## 2 Scope and Assumptions
**In Scope**
* Sensor Abstraction Layer (SAL)
* Hardware interface abstraction (I2C, SPI, UART, ADC, GPIO)
* Storage interface abstraction (SD Card, NVM)
* Display interface abstraction (OLED I2C)
**Out of Scope**
* Hardware driver implementation details (ESP-IDF drivers)
* Hardware-specific optimizations (deferred to implementation)
## 3 Sub-Feature Breakdown
### 3.1 F-HW-01: Sensor Abstraction Layer (SAL)
#### Description
The system provides a Sensor Abstraction Layer (SAL) to ensure hardware independence and maintainability.
**Interface Functions:**
- `sensor_read()`: Retrieve the latest value
- `sensor_calibrate()`: Perform sensor-specific calibration
- `sensor_validate()`: Check if the reading is within physical bounds
- `sensor_health_check()`: Verify the operational status of the hardware
- `sensor_getMetadata()`: Get sensor capabilities (range, accuracy, etc.)
- `sensor_reset()`: Recovery from fault states
**Sensor State Management:**
- **INIT:** Sensor initialization
- **WARMUP:** Sensor warming up (not yet stable)
- **STABLE:** Sensor operational and stable
- **DEGRADED:** Sensor operational but degraded
- **FAILED:** Sensor failed, not operational
#### Responsibilities
* Abstract sensor hardware interfaces
* Provide uniform sensor API
* Manage sensor state
* Handle sensor-specific calibration
* Validate sensor readings
#### Constraints
* All sensor access must go through SAL
* Application layer must not access sensor hardware directly
* Sensor state must be tracked and reported
### 3.2 F-HW-02: Hardware Interface Abstraction
#### Description
The system abstracts all hardware interfaces through driver layers.
**Abstraction Layers:**
- **I2C Interface:** Abstracted via ESP-IDF I2C driver wrapper
- **SPI Interface:** Abstracted via ESP-IDF SPI driver wrapper
- **UART Interface:** Abstracted via ESP-IDF UART driver wrapper
- **ADC Interface:** Abstracted via ESP-IDF ADC driver wrapper
- **GPIO Interface:** Abstracted via ESP-IDF GPIO driver wrapper
- **Storage Interfaces:** SD Card (SDMMC), NVM (NVS)
- **Display Interface:** OLED I2C
**GPIO Discipline:**
- **No Strapping Pins:** Avoid using strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O
- **I2C Pull-up Audit:** Ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V)
- **No ADC2 with Wi-Fi:** ADC2 unit cannot be used when Wi-Fi is active. All analog sensors must be connected to ADC1 pins
- **Canonical GPIO Map:** Single authoritative GPIO map document must be maintained
#### Responsibilities
* Abstract hardware interfaces
* Provide uniform API for hardware access
* Enforce GPIO discipline
* Manage hardware resource conflicts
#### Constraints
* Application layer must not access hardware directly
* GPIO usage must follow canonical GPIO map
* Hardware conflicts must be detected and reported
## 4 System Requirements (Formal SHALL Statements)
### Sensor Abstraction Layer Requirements
* **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.
### Hardware Interface Abstraction Requirements
* **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.
## 5 Traceability Matrix (Feature → System Requirements)
| Feature ID | Related System Requirements |
|------------|----------------------------|
| F-HW-01 | SR-HW-001, SR-HW-002, SR-HW-003, SR-HW-004 |
| F-HW-02 | SR-HW-005, SR-HW-006, SR-HW-007, SR-HW-008 |
## 6 Design & Implementation Notes (Non-Normative)
* **SAL Implementation:** Each sensor type implements SAL interface
* **Driver Wrappers:** ESP-IDF drivers wrapped in application-specific abstraction layer
* **GPIO Map:** Must be maintained as single source of truth
* **Hardware Conflicts:** Runtime detection and reporting via diagnostics
## 7 Dependencies
* **ESP-IDF Drivers:** I2C, SPI, UART, ADC, GPIO, SDMMC, NVS
* **System Management Features:** Hardware initialization and teardown
* **Diagnostics Features:** Hardware fault reporting
## 8 GPIO Map Guidelines
**Strapping Pins (DO NOT USE):**
- GPIO 0: Boot mode selection
- GPIO 3: JTAG
- GPIO 45: Strapping pin
- GPIO 46: Strapping pin
**ADC Constraints:**
- **ADC1:** Available when Wi-Fi is active
- **ADC2:** NOT available when Wi-Fi is active (use ADC1 for all analog sensors)
**I2C Pull-up Requirements:**
- **Physical Pull-ups:** 2.2kΩ - 4.7kΩ for 3.3V
- **Software Pull-ups:** Not recommended for production (use physical pull-ups)

236
draft/system_arch_final_old/[OTA] Firmware Update (OTA) Features.md Normal file
View File

@@ -0,0 +1,236 @@
# Firmware Update (OTA) Features
**Feature Group ID:** FG-OTA
**Version:** 2.0
**Date:** 2025-01-19
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
## 1 Feature Overview
The **Firmware Update (OTA) Features** enable the Sensor Hub (Sub-Hub) to safely receive, validate, and activate new firmware images provided by the Main Hub.
These features ensure **controlled firmware lifecycle management**, **data integrity**, **system availability**, and **fault containment** during firmware update operations.
The OTA process is designed to:
* Prevent unauthorized or corrupted firmware installation
* Preserve critical system data and calibration information
* Ensure recoverability in case of update failure
* Minimize operational disruption
**Technology:** A/B Partitioning with automatic rollback, SHA-256 integrity verification
This feature set applies **only to the Sensor Hub (ESP32-S3 based)** and does not include cloud-side or Main Hub OTA logic.
## 2 Scope and Assumptions
### In Scope
* OTA negotiation and readiness handshake with Main Hub
* Firmware image reception over secure communication (MQTT or HTTPS)
* Temporary firmware storage on SD card
* Firmware integrity verification (SHA-256 hash)
* Controlled firmware activation and reboot
* A/B partitioning with automatic rollback
### Out of Scope
* Firmware generation and signing
* Cloud-side firmware distribution
* Rollback policy definition (defined in this document)
## 3 Partition Layout
For a device with **8MB of flash**, the following partition layout is recommended:
| Partition | Size | Purpose |
|-----------|------|---------|
| **bootloader** | ~32KB | Initial boot code |
| **partition_table** | ~4KB | Defines the flash layout |
| **factory** | Optional | Minimal rescue firmware |
| **ota_0** | 3.5 MB | Primary application slot |
| **ota_1** | 3.5 MB | Secondary application slot for updates |
| **nvs** | 64 KB | Encrypted Non-Volatile Storage for config |
| **phy_init** | ~4KB | Physical layer initialization data |
| **coredump** | 64 KB | Storage for crash logs and debugging |
**Total Used:** ~7.1MB (fits in 8MB flash)
## 4 Sub-Features
### 4.1 F-OTA-01: OTA Update Negotiation
**Description**
This sub-feature governs the initial negotiation phase between the Sensor Hub and the Main Hub prior to any firmware transfer.
The Sensor Hub validates its current operational state and explicitly signals readiness before accepting an OTA update.
**Readiness Validation:**
- System state check (must be RUNNING, not WARNING/FAULT/SERVICE/SD_DEGRADED)
- Storage availability check (SD card space, NVS space)
- Power stability check
- Communication link stability check
**Responsibilities**
* Receive OTA availability notification
* Validate system readiness (power, storage, state)
* Acknowledge or reject OTA request
* Transition system into OTA_PREP state
### 4.2 F-OTA-02: Firmware Reception and Storage
**Description**
This sub-feature handles the controlled reception of the firmware image from the Main Hub and its storage in non-volatile memory (SD card) without overwriting the currently running firmware.
**Download Method:**
- **Protocol:** HTTPS or MQTT
- **Chunk Size:** 4096 bytes (optimized for flash page size)
- **Storage:** SD Card (temporary) before flashing to OTA partition
**Responsibilities**
* Receive firmware in chunks (4096 bytes per chunk)
* Store firmware image on SD card (temporary)
* Monitor transfer completeness
* Prevent execution during download
* Track download progress
### 4.3 F-OTA-03: Firmware Integrity Validation
**Description**
This sub-feature validates the integrity and correctness of the received firmware image prior to activation, ensuring that corrupted or incomplete firmware is never flashed.
**Validation Method:**
- **Integrity Check:** SHA-256 hash verification
- **Size Validation:** Firmware size matches metadata
- **Metadata Validation:** Partition table, version number
**Responsibilities**
* Perform integrity checks (SHA-256 hash)
* Validate firmware size and metadata
* Reject invalid firmware images
* Report validation status to Main Hub
### 4.4 F-OTA-04: Safe Firmware Activation
**Description**
This sub-feature manages the safe transition from the current firmware to the new firmware, ensuring all critical data is preserved and the system is left in a known safe state.
**Activation Sequence:**
1. Execute controlled teardown
2. Persist critical runtime data and calibration data
3. Flash validated firmware image to inactive OTA partition
4. Update partition table to boot from new partition
5. Reboot system into new firmware
6. Validate: System must boot and send health report
7. Confirmation: Application must confirm stability within 60-120 seconds
8. Failure: Automatic rollback to previous known-good version
**Responsibilities**
* Trigger teardown procedure
* Persist runtime and calibration data
* Flash validated firmware image
* Reboot system into updated firmware
### 4.5 F-OTA-05: A/B Partitioning with Rollback [NEW]
**Description**
The system implements A/B partitioning to support safe firmware updates with automatic rollback capability.
**Rollback Triggers:**
- Boot failure after firmware activation
- No health report within confirmation window (60-120 seconds)
- Application crash during confirmation period
- Manual rollback command from Main Hub
**Rollback Process:**
1. Detect failure condition
2. Mark new firmware as invalid
3. Update partition table to boot from previous partition
4. Reboot into previous known-good firmware
5. Report rollback to Main Hub
## 5 OTA Policy
A formal policy ensures that updates are downloaded correctly and that the system can roll back if the new firmware is unstable.
| Step | Rule |
|------|------|
| **Download** | Conducted via HTTPS or MQTT in chunks |
| **Chunk Size** | 4096 bytes (optimized for flash page size) |
| **Integrity** | Verified using a full image SHA-256 hash |
| **Validation** | System must boot and send a health report |
| **Confirmation** | The application must confirm stability within 60-120 seconds |
| **Failure** | Automatic rollback to the previous known-good version |
**OTA Duration:** Maximum 10 minutes (end-to-end)
## 6 System Requirements (Formal SHALL Statements)
### OTA Negotiation Requirements
* **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.
### Firmware Reception & Storage Requirements
* **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.
### Firmware Integrity Requirements
* **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.
### Safe Activation Requirements
* **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.
### Rollback Requirements [NEW]
* **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.
## 7 Feature-to-Requirement Traceability
| Feature ID | Related System Requirements |
|------------|----------------------------|
| F-OTA-01 | SR-OTA-001, SR-OTA-002, SR-OTA-003 |
| F-OTA-02 | SR-OTA-004, SR-OTA-005, SR-OTA-006 |
| F-OTA-03 | SR-OTA-007, SR-OTA-008, SR-OTA-009 |
| F-OTA-04 | SR-OTA-010, SR-OTA-011, SR-OTA-012, SR-OTA-013 |
| F-OTA-05 | SR-OTA-014, SR-OTA-015, SR-OTA-016 |
## 8 Architectural Considerations (Informative)
* OTA logic shall be implemented as a **dedicated OTA Manager component**
* Firmware storage shall be accessed via the **DP (Data Persistence) component**
* OTA state transitions shall interact with:
* Diagnostics subsystem
* Machine Constants management
* Teardown mechanism
* OTA execution shall not block critical system diagnostics reporting
* OTA operations SHALL NOT be allowed during WARNING, FAULT, SERVICE, or SD_DEGRADED states
## 9 Related Features
* **Persistence & Data Management Features (F-DATA-03)**
* **Diagnostics & Health Monitoring Features**
* **Security & Safety Features (Secure Boot, Secure Flash)**
* **System Management Features (State Machine, Teardown)**
## 10 Closing the Gaps
This strategy directly addresses the following gaps:
* **GAP-OTA-001:** Reliable image delivery (chunked download, MQTT/HTTPS)
* **GAP-OTA-002:** Integrity and authenticity verification (SHA-256, Secure Boot)
* **GAP-OTA-003:** Safe rollback mechanisms (A/B partitioning, automatic rollback)

138
draft/system_arch_final_old/[PWR] Power & Fault Handling Features.md Normal file
View File

@@ -0,0 +1,138 @@
# Power & Fault Handling Features
**Feature Group ID:** FG-PWR
**Version:** 1.0
**Date:** 2025-01-19
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
## 1 Feature Overview
The **Power & Fault Handling Features** ensure that the Sensor Hub operates reliably under power fluctuations and recovers gracefully from power interruptions. These features protect critical data during brownouts and enable clean recovery after power restoration.
**Technology:**
- **Brownout Detection:** Hardware brownout detector (BOD)
- **Power-Loss Protection:** Supercapacitor (optional, recommended)
- **RTC Backup:** External RTC battery (CR2032, optional)
## 2 Scope and Assumptions
**In Scope**
* Brownout detection and handling
* Power-loss data protection
* Graceful shutdown on power loss
* Clean recovery after power restoration
**Out of Scope**
* Battery-powered operation (system assumes continuous power)
* Power management for low-power modes (not applicable for real-time requirements)
## 3 Sub-Feature Breakdown
### 3.1 F-PWR-01: Brownout Detection and Handling
#### Description
The system monitors input voltage and takes immediate action if it drops below safe threshold.
**Configuration:**
- **Brownout Threshold:** 3.0V (hardware-configurable)
- **Detection:** Hardware brownout detector (BOD) in ESP32-S3
- **ISR Action:** Set "Power Loss" flag and immediately flush critical buffers to NVS/SD
- **Recovery:** Perform clean reboot once power is stable
**Hardware Support:**
- **Supercapacitor (Recommended):** 0.5-1.0F for 1-2s at 3.3V
- Provides runtime during brownout to complete data flush
- Enables graceful shutdown
- **External RTC Battery (Optional):** CR2032, 3V, 220mAh
- Maintains time accuracy during power loss
- Not required for basic operation
#### Responsibilities
* Monitor input voltage
* Detect brownout condition
* Trigger immediate data flush
* Enter graceful shutdown mode
#### Constraints
* Brownout detection must be hardware-based (ESP32-S3 BOD)
* Data flush must complete within supercapacitor runtime (1-2 seconds)
* System must reboot cleanly after power restoration
### 3.2 F-PWR-02: Power-Loss Recovery
#### Description
The system recovers gracefully from power interruptions (< 1 second).
**Recovery Behavior:**
- Clean reboot after power stabilization
- Data integrity verification
- State restoration from persistent storage
- Diagnostic event generation (if data loss detected)
**Recovery Sequence:**
1. Power restoration detected
2. Wait for power stabilization (100ms)
3. Perform clean reboot
4. Initialize system from persistent storage
5. Verify data integrity
6. Report recovery status via diagnostics
#### Responsibilities
* Detect power restoration
* Perform clean reboot
* Restore system state from persistent storage
* Verify data integrity
* Report recovery status
## 4 System Requirements (Formal SHALL Statements)
### Brownout Detection Requirements
* **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.
### Power-Loss Recovery Requirements
* **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.
## 5 Traceability Matrix (Feature → System Requirements)
| Feature ID | Related System Requirements |
|------------|----------------------------|
| F-PWR-01 | SR-PWR-001, SR-PWR-002, SR-PWR-003, SR-PWR-004 |
| F-PWR-02 | SR-PWR-005, SR-PWR-006, SR-PWR-007, SR-PWR-008 |
## 6 Design & Implementation Notes (Non-Normative)
* **Supercapacitor:** Recommended for production deployment to enable graceful shutdown
* **RTC Battery:** Optional, improves time accuracy during power loss
* **Brownout Threshold:** 3.0V is conservative; adjust based on power supply characteristics
* **Data Flush Priority:** Critical data (calibration, diagnostics) must be flushed first
* **Recovery Time:** System should recover within 5 seconds after power restoration
## 7 Dependencies
* **Persistence & Data Management Features** (data flush mechanism)
* **Diagnostics Features** (power-loss event reporting)
* **System Management Features** (graceful shutdown, state restoration)
## 8 Hardware Recommendations
| Component | Specification | Purpose |
|-----------|---------------|---------|
| **Supercapacitor** | 0.5-1.0F, 3.3V | Provides runtime during brownout for data flush |
| **RTC Battery** | CR2032, 3V, 220mAh | Maintains time accuracy during power loss |
| **Power Supply** | 3.3V ±5%, minimum 500mA | Stable power for reliable operation |

281
draft/system_arch_final_old/[SEC] Security & Safety Features.md Normal file
View File

@@ -0,0 +1,281 @@
# Security & Safety Features
**Feature Group ID:** FG-SEC
**Version:** 2.0
**Date:** 2025-01-19
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
## 1 Feature Overview
The **Security & Safety Features** ensure that the Sensor Hub operates only with trusted firmware, protects sensitive data at rest, and guarantees confidentiality and integrity of all communications. These features are foundational and cross-cutting, supporting all other functional features (DAQ, DQC, COM, DIAG, DATA, OTA).
This feature set is designed to:
* Prevent execution of unauthorized or malicious firmware
* Protect firmware, configuration, and machine constants stored in memory
* Secure all communications with cryptographic mechanisms
* Provide deterministic and auditable behavior in case of security violations
**Technology Stack:**
- **Secure Boot:** Secure Boot V2 (hardware-enforced)
- **Flash Encryption:** AES-256 (hardware-accelerated)
- **Communication Security:** Mutual TLS (mTLS) with X.509 certificates
- **Anti-Rollback:** eFuse-based version protection
## 2 Scope and Assumptions
**In Scope**
* Sensor Hub (ESP32-S3–based)
* Boot process security
* Flash and external storage protection
* Communication security with Main Hub and peer Sensor Hubs
* Device identity and authentication
**Out of Scope**
* Cloud server security policies
* User identity management
* Physical tamper detection hardware (optional future feature)
## 3 Sub-Feature Breakdown
### 3.1 F-SEC-01: Secure Boot
#### Description
Secure Boot ensures that only authenticated and authorized firmware images are executed on the Sensor Hub using **Secure Boot V2**. During system startup, the bootloader verifies the cryptographic signature of the firmware image before handing over execution.
If verification fails, the system enters **BOOT_FAILURE** state and prevents normal operation.
#### Implementation
**Secure Boot V2 Configuration:**
- **Signature Algorithm:** RSA-3072 or ECDSA-P256
- **Verification:** Hardware-enforced (ROM bootloader)
- **Key Storage:** Root-of-trust key in eFuse (one-time programmable)
- **Enforcement:** Every boot (cold or warm)
#### Responsibilities
* Firmware authenticity verification
* Root-of-trust enforcement
* Prevention of downgrade or rollback attacks (via eFuse anti-rollback)
#### Constraints
* Must complete before any application code execution
* Must be enforced on every boot (cold or warm)
* Root-of-trust key is one-time programmable (eFuse)
### 3.2 F-SEC-02: Secure Flash Storage
#### Description
Secure Flash Storage protects sensitive data stored in internal flash and external storage (e.g., SD card) from unauthorized access or modification using **Flash Encryption**.
**Encryption Method:** AES-256 (hardware-accelerated)
Sensitive data includes:
* Firmware images
* Machine constants
* Calibration data
* Cryptographic material
* Persistent diagnostics and logs
#### Implementation
**Flash Encryption Configuration:**
- **Algorithm:** AES-256
- **Mode:** Release mode (recommended for production)
- **Key Derivation:** Hardware-based (eFuse)
- **Transparency:** Automatic decryption on read (transparent to application)
**External Storage Encryption:**
- **SD Card:** Optional encryption for sensitive files (SWR-SEC-006)
- **Encryption Method:** AES-256 (software-based for SD card)
#### Responsibilities
* Encrypted storage of sensitive regions
* Access control enforcement
* Prevention of unauthorized read/write operations
#### Constraints
* Encryption must not compromise system boot reliability
* Storage access must be mediated through controlled software components (e.g., DP component)
### 3.3 F-SEC-03: Encrypted Communication
#### Description
Encrypted Communication ensures that all data exchanged between the Sensor Hub and other entities (Main Hub, peer Sensor Hubs) is protected against eavesdropping, tampering, and impersonation using **Mutual TLS (mTLS)**.
This includes:
* Sensor data transmission
* Diagnostics reporting
* OTA negotiation and data transfer
* Configuration and machine constant updates
#### Implementation
**Device Identity & Authentication:**
- **Identity:** Device-unique X.509 certificate
- **Private Key:** Stored securely in eFuse or encrypted flash
- **Authentication:** Mutual TLS (mTLS) for all broker communications
- **Provisioning:** Handled via secure factory or onboarding mode
**Key Lifecycle Management:**
| Phase | Mechanism |
|-------|-----------|
| **Manufacturing** | Injection of unique device certificate and private key |
| **Operation** | Use of TLS session keys for encrypted communication |
| **Rotation** | Certificate rotation managed on broker/server side |
| **Revocation** | Certificate Revocation Lists (CRL) or broker-side denylists |
**Key Insight:**
The ESP32-S3 is optimized to handle a single device certificate efficiently. It is recommended to avoid managing large certificate chains on the device itself to conserve resources.
**Certificate Constraints:**
- **Maximum Certificate Size:** <2KB
- **Certificate Format:** X.509 v3
- **Key Algorithm:** RSA-2048 or ECDSA-P256
#### Responsibilities
* Confidentiality of transmitted data
* Integrity and authenticity verification
* Secure session establishment
#### Constraints
* Must be compatible with ESP32-S3 cryptographic capabilities
* Must support reconnection and key renewal mechanisms
* Certificate size must be optimized for ESP32-S3
### 3.4 F-SEC-04: Security Violation Handling [NEW]
#### Description
The system detects and reports security violations with appropriate responses.
**Security Violation Types:**
- Secure boot failures
- Authentication failures
- Message tampering
- Unauthorized access attempts
- Certificate validation failures
**Response Actions:**
- Secure boot failure → BOOT_FAILURE state
- Authentication failure → FATAL diagnostic event, connection rejection
- Message tampering → ERROR diagnostic event (escalates to FATAL if persistent)
- Unauthorized access → FATAL diagnostic event, access denial
## 4 Functional Flow Overview
### Secure Boot Flow
```mermaid
sequenceDiagram
participant Power as Power On
participant ROM as ROM Bootloader
participant SecureBoot as Secure Boot V2
participant App as Application
Power->>ROM: System Reset
ROM->>SecureBoot: Load Firmware
SecureBoot->>SecureBoot: Verify Signature
alt Signature Valid
SecureBoot->>App: Jump to Application
else Signature Invalid
SecureBoot->>SecureBoot: Enter BOOT_FAILURE State
end
```
### Secure Communication Flow (mTLS)
```mermaid
sequenceDiagram
participant SH as Sensor Hub
participant Broker as Main Hub Broker
SH->>Broker: TLS Client Hello + Certificate
Broker->>SH: TLS Server Hello + Certificate
SH->>SH: Verify Server Certificate
Broker->>Broker: Verify Client Certificate
alt Both Valid
SH->>Broker: TLS Session Established
SH->>Broker: Encrypted Data Exchange
else Invalid Certificate
SH->>SH: Reject Connection, Log FATAL
end
```
## 5 System SHALL Requirements (Formal)
### Secure Boot Requirements
* **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).
### Secure Flash Storage Requirements
* **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.
### Encrypted Communication Requirements
* **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.
### Security Violation Handling Requirements [NEW]
* **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.
## 6 Traceability Matrix (Feature → System Requirements)
| Feature ID | Related System Requirements |
|------------|----------------------------|
| F-SEC-01 | SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 |
| F-SEC-02 | SR-SEC-005, SR-SEC-006, SR-SEC-007, SR-SEC-008 |
| F-SEC-03 | SR-SEC-009, SR-SEC-010, SR-SEC-011, SR-SEC-012 |
| F-SEC-04 | SR-SEC-013, SR-SEC-014, SR-SEC-015 |
## 7 Design & Implementation Notes (Non-Normative)
* **Secure Boot V2:** Mandatory for production deployment. Key management and signing infrastructure must be documented.
* **Flash Encryption:** Release mode recommended for production. Development mode available for debugging.
* **Key Provisioning:** Should occur during manufacturing or secure onboarding. HSM or secure signing server required.
* **Certificate Lifecycle:** Certificate rotation and revocation must be managed on broker/server side.
* **eFuse Anti-Rollback:** Version numbering strategy must be carefully defined (eFuse is one-time programmable).
* **Security Failures:** Should integrate with the Diagnostics & Health Monitoring feature set.
* **Security Features:** Must be active before any sensor data acquisition or communication begins (CFC-SEC-01).
## 8 Dependencies
* **OTA Features** (for secure firmware updates)
* **Communication Features** (transport layer for mTLS)
* **Diagnostics Features** (security fault reporting)
* **Persistence & DP Component** (secure storage abstraction)
* **System Management** (BOOT_FAILURE state handling)
## 9 Industrial Standards Compliance
* **Secure Boot V2:** Industry standard for production-ready industrial embedded systems
* **Flash Encryption:** Hardware-accelerated AES-256 (industry standard)
* **mTLS:** Industry standard for device authentication
* **X.509 Certificates:** Standard certificate format (RFC 5280)

326
draft/system_arch_final_old/[SYS] System Management Features.md Normal file
View File

@@ -0,0 +1,326 @@
<macro class="toc op-uc-placeholder op-uc-toc">
</macro>
#
System Management Features
## Sensor Hub (Sub-Hub) Scope
## 1 Feature Overview
The **System Management Features** provide deterministic control over the Sensor Hub’s operational lifecycle, runtime state visibility, controlled shutdown behavior, and engineering interaction capabilities.
This feature group is responsible for:
* Managing system operational states and transitions
* Ensuring safe teardown during updates or failures
* Providing local human–machine interaction via OLED display and buttons
* Supporting engineering/debug sessions for diagnostics and maintenance
These features act as the **supervisory layer** governing all other functional domains (DAQ, DQC, COM, DIAG, DATA, OTA, SEC).
## 2 Scope and Assumptions
**In Scope**
* ESP32-S3 Sensor Hub
* OLED-based local UI (I2C)
* Physical input buttons
* Controlled state transitions and teardown
* Debug and engineering access
**Out of Scope**
* Main Hub UI
* Cloud dashboards
* User authentication / role management
## 3 Sub-Feature Breakdown
### 3.1 F-SYS-01: System State Management
#### Description
System State Management defines and controls the operational states of the Sensor Hub and governs all valid transitions between them.
The system operates as a **finite state machine (FSM)** with deterministic behavior.
#### Typical System States
* **INIT** – Hardware and software initialization
* **RUNNING** – Normal sensor acquisition and communication
* **WARNING** – Non-fatal fault detected, degraded operation
* **FAULT** – Fatal error, core functionality disabled
* **OTA\_UPDATE** – Firmware update in progress
* **MC\_UPDATE** – Machine constants update in progress
* **TEARDOWN** – Controlled shutdown sequence
* **IDLE / SERVICE** – Engineering or diagnostic interaction
#### Responsibilities
* Enforce valid state transitions
* Notify dependent components of state changes
* Prevent unsafe operations during restricted states
### 3.2 F-SYS-02: Controlled Teardown Mechanism
#### Description
The Controlled Teardown Mechanism ensures that the Sensor Hub transitions safely from an active state into reset, update, or shutdown without data loss or corruption.
Teardown is triggered by:
* Firmware update
* Machine constant update
* Fatal system fault
* Manual engineering command
#### Teardown Sequence (Mandatory)
1. Stop sensor acquisition tasks
2. Flush pending data via DP component
3. Persist calibration, diagnostics, and runtime state
4. Close communication sessions
5. Release hardware resources
6. Enter target state (reset, OTA, idle)
#### Responsibilities
* Guarantee data consistency
* Ensure deterministic shutdown behavior
* Prevent flash or SD corruption
### 3.3 F-SYS-03: Status Indication (OLED-Based HMI)
#### Description
The Sensor Hub provides local system visibility using an **OLED display connected via I2C**, replacing LED indicators.
The display, together with **three physical buttons (Up / Down / Select)**, forms a minimal local Human–Machine Interface (HMI).
#### Default Information Displayed (Main Screen)
1. **Connectivity status**
* Connected / Disconnected
* Signal strength (RSSI) if available
2. **System status**
* Current system state (RUNNING, WARNING, FAULT, OTA, etc.)
3. **Connected sensors**
* Count and/or summary status
4. **Time and date**
* Synchronized system time
#### Menu Navigation Behavior
* **Select button**
* From main screen → opens menu
* From submenu → returns to main screen
* **Up / Down buttons**
* Navigate menu entries
* Scroll within pages if applicable
#### Menu Structure
**Main Menu**
* **Diagnostics**
* Lists active and stored diagnostic codes
* Displays occurrence count per diagnostic
* **Sensors**
* Lists all detected sensors
* Displays sensor type and configuration status
* **Health**
* Displays SD card usage
* Displays overall system health indicators
#### Responsibilities
* Provide real-time system visibility
* Support local inspection without external tools
* Reflect system state and diagnostics accurately
### 3.4 F-SYS-04: Debug &amp; Engineering Sessions
#### Description
Debug &amp; Engineering Sessions allow authorized engineers to interact with the Sensor Hub for diagnostics, inspection, and controlled operations.
Sessions may be established via:
* Wired interface (e.g., USB/UART)
* Secure communication channel (logical session)
#### Supported Capabilities
* Retrieve diagnostic logs
* Read machine constant files
* Inspect system state and health
* Trigger controlled actions (e.g., reboot, teardown)
* Monitor runtime logs
#### Session Types
* **Diagnostic Session** – Read-only access for inspection
* **Debug Session** – Command execution and deeper inspection
## 4 Functional Interaction Overview
### System State &amp; Teardown Relationship
```text
RUNNING
↓ (Update / Fault)
TEARDOWN
↓
OTA_UPDATE / MC_UPDATE / RESET
```
### Local HMI Interaction
```text
OLED Display ← System State Manager
Buttons → UI Controller → State/Menu Logic
```
## 5 System SHALL Requirements (Formal)
### System State Management
* **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.
### Controlled Teardown
* **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.
### Status Indication &amp; HMI
* **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.
### Debug &amp; Engineering Sessions
* **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.
### 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
| 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
* Diagnostics &amp; Health Monitoring Features
* Persistence &amp; DP Component
* Communication Features
* Security &amp; Safety Features
* OTA Features
##