diff --git a/System Design/system_arch_final/.cursor b/System Design/system_arch_final/.cursor new file mode 100644 index 0000000..29e9991 --- /dev/null +++ b/System Design/system_arch_final/.cursor @@ -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.** diff --git a/System Design/system_arch_final/Cross-Feature Constraints.md b/System Design/system_arch_final/Cross-Feature Constraints.md new file mode 100644 index 0000000..298aad2 --- /dev/null +++ b/System Design/system_arch_final/Cross-Feature Constraints.md @@ -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 \ No newline at end of file diff --git a/System Design/system_arch_final/Features.md b/System Design/system_arch_final/Features.md new file mode 100644 index 0000000..83878f5 --- /dev/null +++ b/System Design/system_arch_final/Features.md @@ -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 + +--- + diff --git a/System Design/system_arch_final/Migration_and_Updates_Log.md b/System Design/system_arch_final/Migration_and_Updates_Log.md new file mode 100644 index 0000000..5eb93af --- /dev/null +++ b/System Design/system_arch_final/Migration_and_Updates_Log.md @@ -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.** diff --git a/System Design/system_arch_final/System Assumptions & Limitations.md b/System Design/system_arch_final/System Assumptions & Limitations.md new file mode 100644 index 0000000..421c992 --- /dev/null +++ b/System Design/system_arch_final/System Assumptions & Limitations.md @@ -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 \ No newline at end of file diff --git a/System Design/system_arch_final/System_Architecture_Documentation.md b/System Design/system_arch_final/System_Architecture_Documentation.md new file mode 100644 index 0000000..fc09b5c --- /dev/null +++ b/System Design/system_arch_final/System_Architecture_Documentation.md @@ -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.** diff --git a/System Design/system_arch_final/[COM] Communication Features.md b/System Design/system_arch_final/[COM] Communication Features.md new file mode 100644 index 0000000..0616b2c --- /dev/null +++ b/System Design/system_arch_final/[COM] Communication Features.md @@ -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 diff --git a/System Design/system_arch_final/[DAQ] Sensor Data Acquisition Features.md b/System Design/system_arch_final/[DAQ] Sensor Data Acquisition Features.md new file mode 100644 index 0000000..59d155b --- /dev/null +++ b/System Design/system_arch_final/[DAQ] Sensor Data Acquisition Features.md @@ -0,0 +1,320 @@ +# **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: + +

Sub-Feature ID

Name

F-DAQ-01

Multi-Sensor Data Acquisition

F-DAQ-02

High-Frequency Sampling and Local Filtering

F-DAQ-03

Timestamped Sensor Data Generation

+ +## **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** + +* **REQ-DAQ-001** + The system shall support acquisition of data from multiple environmental sensor types simultaneously. + +* **REQ-DAQ-002** + The system shall provide a dedicated software driver abstraction for each supported sensor type. + +* **REQ-DAQ-003** + The system shall acquire sensor data only from sensors detected as present and enabled. + + +#### **High-Frequency Sampling & Filtering** + +* **REQ-DAQ-004** + The system shall sample each enabled sensor multiple times within a single acquisition cycle. + +* **REQ-DAQ-005** + The system shall apply a local filtering mechanism to raw sensor samples to produce a single representative value. + +* **REQ-DAQ-006** + The system shall allow configuration of sampling count and filtering parameters via system configuration data. + + +#### **Timestamped Data Generation** + +* **REQ-DAQ-007** + The system shall associate each processed sensor value with a timestamp. + +* **REQ-DAQ-008** + The system shall generate timestamps after completion of filtering. + +* **REQ-DAQ-009** + The system shall include sensor identifier, sensor type, value, unit, timestamp, and validity status in each sensor data record. + + +## **9\. Feature-to-Requirement Traceability** + +

Feature ID

Requirement IDs

F-DAQ-01

REQ-DAQ-001, REQ-DAQ-002, REQ-DAQ-003

F-DAQ-02

REQ-DAQ-004, REQ-DAQ-005, REQ-DAQ-006

F-DAQ-03

REQ-DAQ-007, REQ-DAQ-008, REQ-DAQ-009

\ No newline at end of file diff --git a/System Design/system_arch_final/[DATA] Persistence & Data Management Features.md b/System Design/system_arch_final/[DATA] Persistence & Data Management Features.md new file mode 100644 index 0000000..a748f80 --- /dev/null +++ b/System Design/system_arch_final/[DATA] Persistence & Data Management Features.md @@ -0,0 +1,173 @@ + + + +# Feature Engineering Specification + +## Persistence & 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 & Calibration (FG-DQC) + +* Diagnostics & Health Monitoring (FG-DIAG) + +* System State Management / Teardown Mechanism + + +## 1\. Purpose and Objectives + +The **Persistence & 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 + +

Feature ID

Feature Name

Primary Objective

Related Features

F-DATA-01

Persistent Sensor Data Storage

Store timestamped sensor data

DAQ, COM

F-DATA-02

Data Persistence Abstraction (DP)

Abstract storage access

Application Layer

F-DATA-03

Safe Data Handling During State Transitions

Protect data during teardown

OTA, System Mgmt

+ +## 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. + +## 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

+ +## 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. + + +## \ No newline at end of file diff --git a/System Design/system_arch_final/[DIAG] Diagnostics & Health Monitoring Features.md b/System Design/system_arch_final/[DIAG] Diagnostics & Health Monitoring Features.md new file mode 100644 index 0000000..0107792 --- /dev/null +++ b/System Design/system_arch_final/[DIAG] Diagnostics & Health Monitoring Features.md @@ -0,0 +1,167 @@ + + + +# Feature Engineering Specification + +## Diagnostics & 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 & Calibration (FG-DQC) + +* Communication Features (FG-COM) + +* Persistence / DP Stack + + +## 1\. Purpose and Objectives + +The **Diagnostics & 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 + +

Feature ID

Feature Name

Primary Objective

Related Features

F-DIAG-01

Diagnostic Code Management

Standardize fault and warning identification

DQC, COM

F-DIAG-02

Diagnostic Data Storage

Persist diagnostic events

DP Stack

F-DIAG-03

Diagnostic Session

Engineer access to diagnostics

COM, System Mgmt

+ +## 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. + +## 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

+ +## 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 & Safety Features**. + + +## \ No newline at end of file diff --git a/System Design/system_arch_final/[DQC] Data Quality & Calibration Features.md b/System Design/system_arch_final/[DQC] Data Quality & Calibration Features.md new file mode 100644 index 0000000..3d429a0 --- /dev/null +++ b/System Design/system_arch_final/[DQC] Data Quality & Calibration Features.md @@ -0,0 +1,180 @@ + + + +# Feature Engineering Specification + +## Data Quality & 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 & 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. + +
+ + + + +## 2\. Feature Overview and Relationships + +

Feature ID

Feature Name

Primary Objective

Related Features

F-DQC-01

Automatic Sensor Detection

Detect connected sensors dynamically

F-DAQ-01, F-DIAG-01

F-DQC-02

Sensor Type Enforcement

Prevent incorrect sensor-slot usage

F-DQC-01

F-DQC-03

Sensor Failure Detection

Identify and isolate faulty sensors

F-DIAG-02

F-DQC-04

Machine Constants & Calibration Management

Manage static configuration and calibration

OTA, Persistence, Teardown

+ +## 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 & 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 & 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. + +## 5\. Traceability Summary + +

Feature ID

System Requirements

F-DQC-01

SR-DQC-001 → SR-DQC-003

F-DQC-02

SR-DQC-004 → SR-DQC-006

F-DQC-03

SR-DQC-007 → SR-DQC-010

F-DQC-04

SR-DQC-011 → SR-DQC-015

+ +## \ No newline at end of file diff --git a/System Design/system_arch_final/[HW] Hardware Abstraction Features.md b/System Design/system_arch_final/[HW] Hardware Abstraction Features.md new file mode 100644 index 0000000..bafbf19 --- /dev/null +++ b/System Design/system_arch_final/[HW] Hardware Abstraction Features.md @@ -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) diff --git a/System Design/system_arch_final/[OTA] Firmware Update (OTA) Features.md b/System Design/system_arch_final/[OTA] Firmware Update (OTA) Features.md new file mode 100644 index 0000000..26f2daf --- /dev/null +++ b/System Design/system_arch_final/[OTA] Firmware Update (OTA) Features.md @@ -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) diff --git a/System Design/system_arch_final/[PWR] Power & Fault Handling Features.md b/System Design/system_arch_final/[PWR] Power & Fault Handling Features.md new file mode 100644 index 0000000..45c069d --- /dev/null +++ b/System Design/system_arch_final/[PWR] Power & Fault Handling Features.md @@ -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 | diff --git a/System Design/system_arch_final/[SEC] Security & Safety Features.md b/System Design/system_arch_final/[SEC] Security & Safety Features.md new file mode 100644 index 0000000..d329004 --- /dev/null +++ b/System Design/system_arch_final/[SEC] Security & Safety Features.md @@ -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) diff --git a/System Design/system_arch_final/[SYS] System Management Features.md b/System Design/system_arch_final/[SYS] System Management Features.md new file mode 100644 index 0000000..5dfe099 --- /dev/null +++ b/System Design/system_arch_final/[SYS] System Management Features.md @@ -0,0 +1,314 @@ + + + +# +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 & Engineering Sessions + +#### Description + +Debug & 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 & 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 & 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 & 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. + + +## 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

+ +## 7 Dependencies + +* Diagnostics & Health Monitoring Features + +* Persistence & DP Component + +* Communication Features + +* Security & Safety Features + +* OTA Features + + +## \ No newline at end of file