cleanup
This commit is contained in:
114
system_design/Cleanup_Summary.md
Normal file
114
system_design/Cleanup_Summary.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Project Cleanup Summary
|
||||
|
||||
**Date:** 2025-01-19
|
||||
**Purpose:** Reorganize System Design documentation to eliminate duplicates and create clean structure
|
||||
|
||||
## Actions Taken
|
||||
|
||||
### 1. Created New Structure
|
||||
|
||||
Created `System Design/system_design/` with organized subdirectories:
|
||||
- `features/` - All feature specifications
|
||||
- `specifications/` - System specifications (State Machine, Failure Handling, Review Checklist)
|
||||
- `SRS/` - Software Requirements Specification and annexes
|
||||
- `analysis/` - Gap analysis and engineering review reports
|
||||
|
||||
### 2. Files Moved/Consolidated
|
||||
|
||||
#### Features Folder
|
||||
- ✅ All 10 feature .md files from `system_arch_final/`
|
||||
- ✅ `Features.md` (main catalog)
|
||||
- ✅ `Cross-Feature Constraints.md`
|
||||
- ✅ `System Assumptions & Limitations.md`
|
||||
- ✅ `System_Requirements_Traceability.csv` (NEW - complete feature-to-SR mapping)
|
||||
|
||||
#### Specifications Folder
|
||||
- ✅ `System_State_Machine_Specification.md`
|
||||
- ✅ `Failure_Handling_Model.md`
|
||||
- ✅ `System Review Checklist.md`
|
||||
|
||||
#### SRS Folder
|
||||
- ✅ All SRS documents and annexes (kept as-is)
|
||||
- ✅ `Traceability_SWRS.csv` (kept)
|
||||
|
||||
#### Analysis Folder
|
||||
- ✅ `Gap_Analysis_and_Solutions.md` (CONSOLIDATED from multiple gap analysis documents)
|
||||
- ✅ `Engineering_Review_Report.md` (from `engineering review report2.md`)
|
||||
|
||||
#### Root Level
|
||||
- ✅ `system_requirementsand_and_traceability.csv` (kept - original system requirements)
|
||||
- ✅ `README.md` (NEW - documentation index)
|
||||
|
||||
### 3. Files Removed/Deprecated
|
||||
|
||||
The following folders/files are now deprecated (can be removed after verification):
|
||||
- ❌ `System Design/Features/` (old location, superseded by `system_design/features/`)
|
||||
- ❌ `System Design/system_arch_final/` (temporary location, content moved)
|
||||
- ❌ `System Design/Creating Gap Analysis and Solutions Documentation/` (consolidated into `analysis/`)
|
||||
- ❌ `System Design/Gap Analysis and Solutions Documentation/` (consolidated)
|
||||
- ❌ `System Design/Engineering Review Report.md` (superseded by `analysis/Engineering_Review_Report.md`)
|
||||
|
||||
### 4. New Files Created
|
||||
|
||||
1. **`features/System_Requirements_Traceability.csv`**
|
||||
- Complete mapping of all 39 features to 139 system requirements
|
||||
- Includes feature IDs, names, groups, and requirement descriptions
|
||||
- Format: Feature_ID, Feature_Name, Feature_Group, Sub_Feature_ID, Sub_Feature_Name, System_Requirement_ID, System_Requirement_Description
|
||||
|
||||
2. **`analysis/Gap_Analysis_and_Solutions.md`**
|
||||
- Consolidated gap analysis from multiple documents
|
||||
- Includes executive summary, gap matrix, technology validation, and recommendations
|
||||
|
||||
3. **`README.md`**
|
||||
- Complete documentation index
|
||||
- Directory structure overview
|
||||
- Quick reference tables
|
||||
|
||||
## Final Structure
|
||||
|
||||
```
|
||||
System Design/
|
||||
└── system_design/ # Clean, organized structure
|
||||
├── features/ # 10 feature files + CSV
|
||||
├── specifications/ # 3 core specifications
|
||||
├── SRS/ # 6 SRS documents
|
||||
├── analysis/ # 2 analysis documents
|
||||
├── system_requirementsand_and_traceability.csv
|
||||
├── README.md
|
||||
└── Cleanup_Summary.md # This file
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- ✅ All feature files in `features/` folder
|
||||
- ✅ CSV file with system requirements traceability created
|
||||
- ✅ All specifications organized in `specifications/` folder
|
||||
- ✅ SRS documents preserved in `SRS/` folder
|
||||
- ✅ Gap analysis consolidated in `analysis/` folder
|
||||
- ✅ README.md created for navigation
|
||||
- ✅ No duplicate documents in new structure
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Verify** all files are accessible in new locations
|
||||
2. **Remove** deprecated folders after verification:
|
||||
- `System Design/Features/`
|
||||
- `System Design/system_arch_final/`
|
||||
- `System Design/Creating Gap Analysis and Solutions Documentation/`
|
||||
- `System Design/Gap Analysis and Solutions Documentation/`
|
||||
3. **Update** any external references to old file paths
|
||||
4. **Archive** old folders if needed for history
|
||||
|
||||
## Statistics
|
||||
|
||||
- **Features:** 39 features across 10 groups
|
||||
- **System Requirements:** 139 SR-* requirements
|
||||
- **Feature Files:** 10 .md files + 1 CSV
|
||||
- **Specifications:** 3 core documents
|
||||
- **SRS Documents:** 6 documents (main + 5 annexes)
|
||||
- **Analysis Documents:** 2 consolidated documents
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ Cleanup Complete
|
||||
**New Structure:** Ready for use
|
||||
237
system_design/Project_Structure_Guide.md
Normal file
237
system_design/Project_Structure_Guide.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# ASF Sensor Hub - Project Structure Guide
|
||||
|
||||
**Version:** 2.0
|
||||
**Date:** 2025-01-19
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the clean, organized structure of the System Design documentation. All duplicates have been removed, and only the latest versions are maintained.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
System Design/
|
||||
└── system_design/ # Main system design folder
|
||||
│
|
||||
├── features/ # Feature specifications (14 files)
|
||||
│ ├── 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
|
||||
│ ├── [PWR] Power & Fault Handling Features.md
|
||||
│ ├── [HW] Hardware Abstraction Features.md
|
||||
│ ├── Cross-Feature Constraints.md
|
||||
│ ├── System Assumptions & Limitations.md
|
||||
│ └── System_Requirements_Traceability.csv # Feature → SR mapping
|
||||
│
|
||||
├── specifications/ # Core system specifications (3 files)
|
||||
│ ├── System_State_Machine_Specification.md
|
||||
│ ├── Failure_Handling_Model.md
|
||||
│ └── System Review Checklist.md
|
||||
│
|
||||
├── SRS/ # Software Requirements Specification (6 files)
|
||||
│ ├── SRS.md # Main SRS document
|
||||
│ ├── Annex_A_Traceability.md
|
||||
│ ├── Annex_B_Interfaces.md
|
||||
│ ├── Annex_C_Budgets.md
|
||||
│ ├── VV_Matrix.md # Verification & Validation matrix
|
||||
│ └── Traceability_SWRS.csv # SWR traceability
|
||||
│
|
||||
├── analysis/ # Analysis and review documents (2 files)
|
||||
│ ├── Gap_Analysis_and_Solutions.md
|
||||
│ └── Engineering_Review_Report.md
|
||||
│
|
||||
├── system_requirementsand_and_traceability.csv # Original system requirements
|
||||
├── README.md # Documentation index
|
||||
├── Cleanup_Summary.md # Cleanup actions taken
|
||||
└── Project_Structure_Guide.md # This file
|
||||
```
|
||||
|
||||
## File Descriptions
|
||||
|
||||
### Features Folder (`features/`)
|
||||
|
||||
**Purpose:** Contains all feature specifications with system requirements
|
||||
|
||||
**Key Files:**
|
||||
- `Features.md` - Main feature catalog with overview of all 39 features
|
||||
- `[XXX] Feature Files.md` - Detailed specifications for each feature group
|
||||
- `System_Requirements_Traceability.csv` - **Complete mapping of 39 features to 139 system requirements**
|
||||
- Columns: Feature_ID, Feature_Name, Feature_Group, Sub_Feature_ID, Sub_Feature_Name, System_Requirement_ID, System_Requirement_Description
|
||||
- `Cross-Feature Constraints.md` - Architectural constraints across features
|
||||
- `System Assumptions & Limitations.md` - System context and boundaries
|
||||
|
||||
**Statistics:**
|
||||
- 10 feature groups (DAQ, DQC, COM, DIAG, DATA, OTA, SEC, SYS, PWR, HW)
|
||||
- 39 features total
|
||||
- 139 system requirements (SR-*)
|
||||
|
||||
### Specifications Folder (`specifications/`)
|
||||
|
||||
**Purpose:** Core system specifications
|
||||
|
||||
**Files:**
|
||||
- `System_State_Machine_Specification.md` - Complete FSM with 11 states, transitions, and per-state feature execution rules
|
||||
- `Failure_Handling_Model.md` - Fault taxonomy (INFO, WARNING, ERROR, FATAL), escalation, and recovery behaviors
|
||||
- `System Review Checklist.md` - Gate criteria for implementation readiness
|
||||
|
||||
### SRS Folder (`SRS/`)
|
||||
|
||||
**Purpose:** Software Requirements Specification (ISO/IEC/IEEE 29148 compliant)
|
||||
|
||||
**Files:**
|
||||
- `SRS.md` - Main SRS with over 200 Software Requirements (SWR-*)
|
||||
- `Annex_A_Traceability.md` - Bidirectional traceability (Feature → SR → SWR → Component → Test)
|
||||
- `Annex_B_Interfaces.md` - External interfaces specification
|
||||
- `Annex_C_Budgets.md` - Timing and resource budgets
|
||||
- `VV_Matrix.md` - Verification & Validation matrix mapping SWRs to test methods
|
||||
- `Traceability_SWRS.csv` - SWR traceability data
|
||||
|
||||
### Analysis Folder (`analysis/`)
|
||||
|
||||
**Purpose:** Analysis and review documents
|
||||
|
||||
**Files:**
|
||||
- `Gap_Analysis_and_Solutions.md` - **Consolidated gap analysis** with:
|
||||
- Executive summary
|
||||
- Gap & solution matrix
|
||||
- Technology stack validation
|
||||
- Critical action items
|
||||
- Risk assessment
|
||||
- `Engineering_Review_Report.md` - Architecture review findings and recommendations
|
||||
|
||||
### Root Level Files
|
||||
|
||||
- `system_requirementsand_and_traceability.csv` - Original system requirements (kept for reference)
|
||||
- `README.md` - Documentation index and quick reference
|
||||
- `Cleanup_Summary.md` - Summary of cleanup actions
|
||||
- `Project_Structure_Guide.md` - This file
|
||||
|
||||
## CSV Files
|
||||
|
||||
### 1. `features/System_Requirements_Traceability.csv`
|
||||
|
||||
**Purpose:** Complete traceability between Features and System Requirements
|
||||
|
||||
**Columns:**
|
||||
- `Feature_ID` - Feature identifier (e.g., F-DAQ-01)
|
||||
- `Feature_Name` - Feature name
|
||||
- `Feature_Group` - Feature group (DAQ, DQC, COM, etc.)
|
||||
- `Sub_Feature_ID` - Same as Feature_ID (for consistency)
|
||||
- `Sub_Feature_Name` - Same as Feature_Name
|
||||
- `System_Requirement_ID` - System requirement ID (e.g., SR-DAQ-001)
|
||||
- `System_Requirement_Description` - Full requirement text
|
||||
|
||||
**Usage:** Use this file to:
|
||||
- Find all system requirements for a feature
|
||||
- Find which feature(s) a system requirement belongs to
|
||||
- Generate traceability reports
|
||||
- Perform impact analysis
|
||||
|
||||
### 2. `SRS/Traceability_SWRS.csv`
|
||||
|
||||
**Purpose:** Software Requirements traceability
|
||||
|
||||
**Usage:** Links Software Requirements (SWR-*) to System Requirements (SR-*)
|
||||
|
||||
### 3. `system_requirementsand_and_traceability.csv`
|
||||
|
||||
**Purpose:** Original system requirements database
|
||||
|
||||
**Usage:** Reference for original system requirements structure
|
||||
|
||||
## Document Relationships
|
||||
|
||||
```
|
||||
Features.md
|
||||
↓
|
||||
[XXX] Feature Files.md
|
||||
↓
|
||||
System_Requirements_Traceability.csv (Features → SR-*)
|
||||
↓
|
||||
SRS.md (SR-* → SWR-*)
|
||||
↓
|
||||
Traceability_SWRS.csv (SWR-* traceability)
|
||||
↓
|
||||
VV_Matrix.md (SWR-* → Test Methods)
|
||||
```
|
||||
|
||||
## Quick Access Guide
|
||||
|
||||
### I need to find...
|
||||
|
||||
**A feature specification:**
|
||||
→ `features/[XXX] Feature Files.md`
|
||||
|
||||
**System requirements for a feature:**
|
||||
→ `features/System_Requirements_Traceability.csv` (filter by Feature_ID)
|
||||
|
||||
**The system state machine:**
|
||||
→ `specifications/System_State_Machine_Specification.md`
|
||||
|
||||
**Failure handling rules:**
|
||||
→ `specifications/Failure_Handling_Model.md`
|
||||
|
||||
**Software requirements:**
|
||||
→ `SRS/SRS.md`
|
||||
|
||||
**Gap analysis:**
|
||||
→ `analysis/Gap_Analysis_and_Solutions.md`
|
||||
|
||||
**Architecture review:**
|
||||
→ `analysis/Engineering_Review_Report.md`
|
||||
|
||||
**Traceability information:**
|
||||
→ `features/System_Requirements_Traceability.csv` (Features → SR)
|
||||
→ `SRS/Annex_A_Traceability.md` (Full traceability chain)
|
||||
→ `SRS/Traceability_SWRS.csv` (SWR traceability)
|
||||
|
||||
## Deprecated Locations
|
||||
|
||||
The following locations are **deprecated** and can be removed after verification:
|
||||
|
||||
- ❌ `System Design/Features/` → Use `system_design/features/`
|
||||
- ❌ `System Design/system_arch_final/` → Content moved to `system_design/`
|
||||
- ❌ `System Design/Creating Gap Analysis and Solutions Documentation/` → Consolidated into `analysis/`
|
||||
- ❌ `System Design/Gap Analysis and Solutions Documentation/` → Consolidated into `analysis/`
|
||||
- ❌ `System Design/Engineering Review Report.md` → Use `analysis/Engineering_Review_Report.md`
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. Create feature file in `features/` folder
|
||||
2. Update `features/Features.md` with new feature
|
||||
3. Add system requirements to feature file
|
||||
4. Update `features/System_Requirements_Traceability.csv` with new entries
|
||||
|
||||
### Updating System Requirements
|
||||
|
||||
1. Update feature file with new/updated requirements
|
||||
2. Update `features/System_Requirements_Traceability.csv`
|
||||
3. Update `SRS/SRS.md` if software requirements are affected
|
||||
4. Update traceability documents
|
||||
|
||||
### Adding New Specifications
|
||||
|
||||
1. Add specification file to `specifications/` folder
|
||||
2. Update `README.md` if needed
|
||||
|
||||
## Statistics
|
||||
|
||||
- **Total Files:** 27 files
|
||||
- **Feature Files:** 14 files (10 feature specs + 4 supporting docs)
|
||||
- **Specification Files:** 3 files
|
||||
- **SRS Files:** 6 files
|
||||
- **Analysis Files:** 2 files
|
||||
- **CSV Files:** 3 files
|
||||
- **Documentation Files:** 2 files (README, guides)
|
||||
|
||||
---
|
||||
|
||||
**This structure eliminates duplicates and provides a single source of truth for all system design documentation.**
|
||||
126
system_design/README.md
Normal file
126
system_design/README.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# ASF Sensor Hub - System Design Documentation
|
||||
|
||||
**Version:** 2.0
|
||||
**Date:** 2025-01-19
|
||||
**Status:** Final for Implementation Phase
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
system_design/
|
||||
├── features/ # Feature specifications
|
||||
│ ├── 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
|
||||
│ ├── [PWR] Power & Fault Handling Features.md
|
||||
│ ├── [HW] Hardware Abstraction Features.md
|
||||
│ ├── Cross-Feature Constraints.md
|
||||
│ ├── System Assumptions & Limitations.md
|
||||
│ └── System_Requirements_Traceability.csv # Feature → SR mapping
|
||||
│
|
||||
├── specifications/ # System specifications
|
||||
│ ├── System_State_Machine_Specification.md
|
||||
│ ├── Failure_Handling_Model.md
|
||||
│ └── System Review Checklist.md
|
||||
│
|
||||
├── SRS/ # Software Requirements Specification
|
||||
│ ├── SRS.md # Main SRS document
|
||||
│ ├── Annex_A_Traceability.md
|
||||
│ ├── Annex_B_Interfaces.md
|
||||
│ ├── Annex_C_Budgets.md
|
||||
│ ├── VV_Matrix.md # Verification & Validation matrix
|
||||
│ └── Traceability_SWRS.csv # SWR traceability
|
||||
│
|
||||
├── analysis/ # Analysis and review documents
|
||||
│ ├── Gap_Analysis_and_Solutions.md
|
||||
│ └── Engineering_Review_Report.md
|
||||
│
|
||||
├── system_requirementsand_and_traceability.csv # Original system requirements
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Document Overview
|
||||
|
||||
### Features (`features/`)
|
||||
|
||||
Contains all feature specifications with system requirements:
|
||||
- **10 feature groups** (DAQ, DQC, COM, DIAG, DATA, OTA, SEC, SYS, PWR, HW)
|
||||
- **39 features** total
|
||||
- **139 system requirements** (SR-*)
|
||||
- **System_Requirements_Traceability.csv** - Complete feature-to-requirement mapping
|
||||
|
||||
### Specifications (`specifications/`)
|
||||
|
||||
Core system specifications:
|
||||
- **System State Machine** - 11 states with transition rules
|
||||
- **Failure Handling Model** - Fault taxonomy and recovery behaviors
|
||||
- **System Review Checklist** - Gate criteria for implementation
|
||||
|
||||
### SRS (`SRS/`)
|
||||
|
||||
Software Requirements Specification (ISO/IEC/IEEE 29148 compliant):
|
||||
- **Main SRS** - Over 200 Software Requirements (SWR-*)
|
||||
- **Annexes** - Traceability, Interfaces, Budgets
|
||||
- **V&V Matrix** - Verification methods for all requirements
|
||||
|
||||
### Analysis (`analysis/`)
|
||||
|
||||
Analysis and review documents:
|
||||
- **Gap Analysis and Solutions** - Consolidated gap analysis with solutions
|
||||
- **Engineering Review Report** - Architecture review findings
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Feature Groups
|
||||
|
||||
| Group | Features | System Requirements |
|
||||
|-------|----------|---------------------|
|
||||
| DAQ | 4 | 13 |
|
||||
| DQC | 5 | 18 |
|
||||
| COM | 4 | 17 |
|
||||
| DIAG | 4 | 14 |
|
||||
| DATA | 4 | 13 |
|
||||
| OTA | 5 | 16 |
|
||||
| SEC | 4 | 15 |
|
||||
| SYS | 5 | 17 |
|
||||
| PWR | 2 | 8 |
|
||||
| HW | 2 | 8 |
|
||||
| **TOTAL** | **39** | **139** |
|
||||
|
||||
### System 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
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- **Hardware:** ESP32-S3
|
||||
- **Framework:** ESP-IDF v5.4
|
||||
- **Communication:** Wi-Fi 802.11n, MQTT over TLS 1.2, ESP-NOW
|
||||
- **Security:** Secure Boot V2, Flash Encryption (AES-256), mTLS
|
||||
- **Storage:** FAT32 (SD Card), NVS (Encrypted)
|
||||
- **OTA:** A/B Partitioning, SHA-256
|
||||
|
||||
## Document Status
|
||||
|
||||
**Status:** Final for Implementation Phase
|
||||
**Next Phase:** Component Design → Implementation
|
||||
|
||||
---
|
||||
|
||||
**For questions or updates, refer to the individual feature specifications or system specifications.**
|
||||
132
system_design/SRS/Annex_A_Traceability.md
Normal file
132
system_design/SRS/Annex_A_Traceability.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# Annex A: Software Requirements Traceability Matrix
|
||||
|
||||
**Document:** SRS Annex A
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
|
||||
## Purpose
|
||||
|
||||
This annex provides complete traceability between:
|
||||
- Features → System Requirements (SR) → Software Requirements (SWR) → Components → Tests
|
||||
|
||||
## Traceability Matrix Structure
|
||||
|
||||
| Feature ID | System Requirement ID | Software Requirement ID | Component | Test ID |
|
||||
|------------|----------------------|------------------------|-----------|---------|
|
||||
| F-SYS-01 | SR-SYS-001 | SWR-SYS-001 | STM (State Manager) | T-SYS-001 |
|
||||
| F-SYS-01 | SR-SYS-001 | SWR-SYS-002 | STM | T-SYS-002 |
|
||||
| F-SYS-01 | SR-SYS-002 | SWR-SYS-003 | STM | T-SYS-003 |
|
||||
| F-SYS-01 | SR-SYS-003 | SWR-SYS-004 | STM, Event System | T-SYS-004 |
|
||||
| F-SYS-02 | SR-SYS-004 | SWR-SYS-005 | STM | T-SYS-005 |
|
||||
| F-SYS-02 | SR-SYS-005 | SWR-SYS-006 | STM, Persistence | T-SYS-006 |
|
||||
| F-SYS-02 | SR-SYS-006 | SWR-SYS-007 | STM, Persistence | T-SYS-007 |
|
||||
| F-SYS-03 | SR-SYS-007 | SWR-SYS-008 | HMI (OLED Driver) | T-SYS-008 |
|
||||
| F-SYS-03 | SR-SYS-008 | SWR-SYS-009 | HMI | T-SYS-009 |
|
||||
| F-SYS-03 | SR-SYS-009 | SWR-SYS-010 | HMI | T-SYS-010 |
|
||||
| F-SYS-03 | SR-SYS-010 | SWR-SYS-011 | HMI, Diagnostics | T-SYS-011 |
|
||||
| F-SYS-04 | SR-SYS-011 | SWR-SYS-012 | Debug Session Manager | T-SYS-012 |
|
||||
| F-SYS-04 | SR-SYS-012 | SWR-SYS-013 | Debug Session Manager | T-SYS-013 |
|
||||
| F-SYS-04 | SR-SYS-013 | SWR-SYS-014 | Debug Session Manager, Security | T-SYS-014 |
|
||||
| F-SYS-04 | SR-SYS-013 | SWR-SYS-015 | Debug Session Manager | T-SYS-015 |
|
||||
| F-DAQ-01 | SR-DAQ-001 | SWR-DAQ-001 | Sensor Manager | T-DAQ-001 |
|
||||
| F-DAQ-01 | SR-DAQ-002 | SWR-DAQ-002 | Sensor Manager | T-DAQ-002 |
|
||||
| F-DAQ-01 | SR-DAQ-003 | SWR-DAQ-003 | Sensor Manager, Sensor Drivers | T-DAQ-003 |
|
||||
| F-DAQ-01 | SR-DAQ-004 | SWR-DAQ-004 | Sensor Manager | T-DAQ-004 |
|
||||
| F-DAQ-02 | SR-DAQ-005 | SWR-DAQ-005 | Sensor Manager | T-DAQ-005 |
|
||||
| F-DAQ-02 | SR-DAQ-006 | SWR-DAQ-006 | Sensor Manager | T-DAQ-006 |
|
||||
| F-DAQ-02 | SR-DAQ-007 | SWR-DAQ-007 | Sensor Manager | T-DAQ-007 |
|
||||
| F-DAQ-03 | SR-DAQ-008 | SWR-DAQ-008 | Sensor Manager, Time Utils | T-DAQ-008 |
|
||||
| F-DAQ-03 | SR-DAQ-009 | SWR-DAQ-009 | Sensor Manager | T-DAQ-009 |
|
||||
| F-DAQ-03 | SR-DAQ-010 | SWR-DAQ-010 | Sensor Manager, Data Pool | T-DAQ-010 |
|
||||
| F-DQC-01 | SR-DQC-001 | SWR-DQC-001 | Sensor Manager, Sensor Drivers | T-DQC-001 |
|
||||
| F-DQC-01 | SR-DQC-002 | SWR-DQC-002 | Sensor Manager | T-DQC-002 |
|
||||
| F-DQC-01 | SR-DQC-003 | SWR-DQC-003 | Sensor Manager | T-DQC-003 |
|
||||
| F-DQC-02 | SR-DQC-004 | SWR-DQC-004 | Sensor Manager | T-DQC-004 |
|
||||
| F-DQC-02 | SR-DQC-005 | SWR-DQC-005 | Sensor Manager | T-DQC-005 |
|
||||
| F-DQC-02 | SR-DQC-006 | SWR-DQC-006 | Sensor Manager, Diagnostics | T-DQC-006 |
|
||||
| F-DQC-03 | SR-DQC-007 | SWR-DQC-007 | Sensor Manager | T-DQC-007 |
|
||||
| F-DQC-03 | SR-DQC-008 | SWR-DQC-008 | Sensor Manager | T-DQC-008 |
|
||||
| F-DQC-03 | SR-DQC-009 | SWR-DQC-009 | Sensor Manager | T-DQC-009 |
|
||||
| F-DQC-03 | SR-DQC-010 | SWR-DQC-010 | Sensor Manager, Communication | T-DQC-010 |
|
||||
| F-DQC-04 | SR-DQC-011 | SWR-DQC-011 | Machine Constant Manager | T-DQC-011 |
|
||||
| F-DQC-04 | SR-DQC-012 | SWR-DQC-012 | Machine Constant Manager, Persistence | T-DQC-012 |
|
||||
| F-DQC-04 | SR-DQC-013 | SWR-DQC-013 | Machine Constant Manager | T-DQC-013 |
|
||||
| F-DQC-04 | SR-DQC-014 | SWR-DQC-014 | Machine Constant Manager, Communication | T-DQC-014 |
|
||||
| F-DQC-04 | SR-DQC-015 | SWR-DQC-015 | Machine Constant Manager, STM | T-DQC-015 |
|
||||
| F-COM-01 | SR-COM-001 | SWR-COM-001 | Main Hub APIs, Network Stack | T-COM-001 |
|
||||
| F-COM-01 | SR-COM-002 | SWR-COM-002 | Main Hub APIs | T-COM-002 |
|
||||
| F-COM-01 | SR-COM-003 | SWR-COM-003 | Main Hub APIs | T-COM-003 |
|
||||
| F-COM-01 | SR-COM-004 | SWR-COM-004 | Network Stack | T-COM-004 |
|
||||
| F-COM-02 | SR-COM-005 | SWR-COM-005 | Main Hub APIs | T-COM-005 |
|
||||
| F-COM-02 | SR-COM-006 | SWR-COM-006 | Main Hub APIs, Data Pool | T-COM-006 |
|
||||
| F-COM-02 | SR-COM-007 | SWR-COM-007 | Main Hub APIs | T-COM-007 |
|
||||
| F-COM-03 | SR-COM-008 | SWR-COM-008 | Network Stack | T-COM-008 |
|
||||
| F-COM-03 | SR-COM-009 | SWR-COM-009 | Network Stack | T-COM-009 |
|
||||
| F-COM-03 | SR-COM-010 | SWR-COM-009 | Network Stack | T-COM-010 |
|
||||
| F-DIAG-01 | SR-DIAG-001 | SWR-DIAG-001 | Diagnostics Task | T-DIAG-001 |
|
||||
| F-DIAG-01 | SR-DIAG-002 | SWR-DIAG-002 | Diagnostics Task | T-DIAG-002 |
|
||||
| F-DIAG-01 | SR-DIAG-003 | SWR-DIAG-003 | Diagnostics Task | T-DIAG-003 |
|
||||
| F-DIAG-01 | SR-DIAG-004 | SWR-DIAG-004 | Diagnostics Task | T-DIAG-004 |
|
||||
| F-DIAG-02 | SR-DIAG-005 | SWR-DIAG-005 | Diagnostics Task, Persistence | T-DIAG-005 |
|
||||
| F-DIAG-02 | SR-DIAG-006 | SWR-DIAG-006 | Diagnostics Task, Persistence | T-DIAG-006 |
|
||||
| F-DIAG-02 | SR-DIAG-007 | SWR-DIAG-007 | Diagnostics Task, Persistence | T-DIAG-007 |
|
||||
| F-DIAG-03 | SR-DIAG-008 | SWR-DIAG-008 | Diagnostics Task | T-DIAG-008 |
|
||||
| F-DIAG-03 | SR-DIAG-009 | SWR-DIAG-009 | Diagnostics Task | T-DIAG-009 |
|
||||
| F-DIAG-03 | SR-DIAG-010 | SWR-DIAG-010 | Diagnostics Task | T-DIAG-010 |
|
||||
| F-DIAG-03 | SR-DIAG-011 | SWR-DIAG-011 | Diagnostics Task | T-DIAG-011 |
|
||||
| F-DATA-01 | SR-DATA-001 | SWR-DATA-001 | Persistence | T-DATA-001 |
|
||||
| F-DATA-01 | SR-DATA-002 | SWR-DATA-002 | Persistence | T-DATA-002 |
|
||||
| F-DATA-01 | SR-DATA-003 | SWR-DATA-003 | Persistence | T-DATA-003 |
|
||||
| F-DATA-02 | SR-DATA-004 | SWR-DATA-004 | Persistence | T-DATA-004 |
|
||||
| F-DATA-02 | SR-DATA-005 | SWR-DATA-005 | Persistence | T-DATA-005 |
|
||||
| F-DATA-02 | SR-DATA-006 | SWR-DATA-006 | Persistence | T-DATA-006 |
|
||||
| F-DATA-03 | SR-DATA-007 | SWR-DATA-007 | Persistence, STM | T-DATA-007 |
|
||||
| F-DATA-03 | SR-DATA-008 | SWR-DATA-008 | Persistence, OTA Manager | T-DATA-008 |
|
||||
| F-DATA-03 | SR-DATA-009 | SWR-DATA-009 | Persistence, STM | T-DATA-009 |
|
||||
| F-OTA-01 | SR-OTA-001 | SWR-OTA-001 | OTA Manager | T-OTA-001 |
|
||||
| F-OTA-01 | SR-OTA-002 | SWR-OTA-002 | OTA Manager | T-OTA-002 |
|
||||
| F-OTA-01 | SR-OTA-003 | SWR-OTA-003 | OTA Manager | T-OTA-003 |
|
||||
| F-OTA-02 | SR-OTA-004 | SWR-OTA-004 | OTA Manager, Network Stack | T-OTA-004 |
|
||||
| F-OTA-02 | SR-OTA-005 | SWR-OTA-005 | OTA Manager, Persistence | T-OTA-005 |
|
||||
| F-OTA-02 | SR-OTA-006 | SWR-OTA-006 | OTA Manager | T-OTA-006 |
|
||||
| F-OTA-03 | SR-OTA-007 | SWR-OTA-007 | OTA Manager, Security | T-OTA-007 |
|
||||
| F-OTA-03 | SR-OTA-008 | SWR-OTA-008 | OTA Manager | T-OTA-008 |
|
||||
| F-OTA-03 | SR-OTA-009 | SWR-OTA-009 | OTA Manager, Communication | T-OTA-009 |
|
||||
| F-OTA-04 | SR-OTA-010 | SWR-OTA-010 | OTA Manager, STM | T-OTA-010 |
|
||||
| F-OTA-04 | SR-OTA-011 | SWR-OTA-011 | OTA Manager, Persistence | T-OTA-011 |
|
||||
| F-OTA-04 | SR-OTA-012 | SWR-OTA-012 | OTA Manager | T-OTA-012 |
|
||||
| F-OTA-04 | SR-OTA-013 | SWR-OTA-013 | OTA Manager | T-OTA-013 |
|
||||
| F-SEC-01 | SR-SEC-001 | SWR-SEC-001 | Security (Secure Boot) | T-SEC-001 |
|
||||
| F-SEC-01 | SR-SEC-002 | SWR-SEC-002 | Security (Secure Boot) | T-SEC-002 |
|
||||
| F-SEC-01 | SR-SEC-003 | SWR-SEC-003 | Security (Secure Boot), STM | T-SEC-003 |
|
||||
| F-SEC-01 | SR-SEC-004 | SWR-SEC-004 | Security (Secure Boot) | T-SEC-004 |
|
||||
| F-SEC-02 | SR-SEC-005 | SWR-SEC-005 | Security (Flash Encryption) | T-SEC-005 |
|
||||
| F-SEC-02 | SR-SEC-006 | SWR-SEC-006 | Security (Flash Encryption), Persistence | T-SEC-006 |
|
||||
| F-SEC-02 | SR-SEC-007 | SWR-SEC-007 | Security (Key Management) | T-SEC-007 |
|
||||
| F-SEC-02 | SR-SEC-008 | SWR-SEC-008 | Security (Data Integrity) | T-SEC-008 |
|
||||
| F-SEC-03 | SR-SEC-009 | SWR-SEC-009 | Security (Communication Encryption) | T-SEC-009 |
|
||||
| F-SEC-03 | SR-SEC-010 | SWR-SEC-010 | Security (Message Integrity) | T-SEC-010 |
|
||||
| F-SEC-03 | SR-SEC-011 | SWR-SEC-011 | Security (OTA Encryption) | T-SEC-011 |
|
||||
| F-SEC-03 | SR-SEC-012 | SWR-SEC-012 | Security, Diagnostics | T-SEC-012 |
|
||||
|
||||
## Component Abbreviations
|
||||
|
||||
- **STM:** State Manager (System Management)
|
||||
- **HMI:** Human-Machine Interface (OLED + Buttons)
|
||||
- **Sensor Manager:** Sensor acquisition and management
|
||||
- **Machine Constant Manager:** Machine constants management
|
||||
- **Main Hub APIs:** Main Hub communication interface
|
||||
- **Network Stack:** Low-level network communication
|
||||
- **Diagnostics Task:** Diagnostics and health monitoring
|
||||
- **Error Handler:** Fault classification and escalation
|
||||
- **Persistence:** Data Persistence component
|
||||
- **OTA Manager:** Firmware update management
|
||||
- **Security:** Security and safety features
|
||||
- **Event System:** Cross-component event communication
|
||||
- **Data Pool:** Runtime data storage
|
||||
|
||||
## Notes
|
||||
|
||||
- Test IDs (T-*) are placeholders for future test specification
|
||||
- Component assignments are preliminary and may be refined during detailed design
|
||||
- Some SWRs may map to multiple components (e.g., SWR-SYS-004 requires STM and Event System)
|
||||
236
system_design/SRS/Annex_B_Interfaces.md
Normal file
236
system_design/SRS/Annex_B_Interfaces.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Annex B: External Interface Specifications
|
||||
|
||||
**Document:** SRS Annex B
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
|
||||
## Purpose
|
||||
|
||||
This annex defines the external interfaces between the Sensor Hub and external entities (Main Hub, sensors, storage, HMI).
|
||||
|
||||
## 1. Main Hub Communication Interface
|
||||
|
||||
### 1.1 Protocol Stack
|
||||
|
||||
```
|
||||
Application Layer (Sensor Hub APIs)
|
||||
↓
|
||||
Transport Security Layer (TLS/DTLS)
|
||||
↓
|
||||
Network Layer (Wi-Fi / Zigbee / LoRa)
|
||||
↓
|
||||
Physical Layer
|
||||
```
|
||||
|
||||
### 1.2 Message Format
|
||||
|
||||
**Request Message Structure:**
|
||||
```c
|
||||
typedef struct {
|
||||
uint8_t message_type; // REQ_DATA, REQ_STATUS, REQ_DIAG, CMD_CONFIG, CMD_OTA
|
||||
uint16_t message_id; // Unique request ID
|
||||
uint32_t timestamp; // Request timestamp
|
||||
uint16_t payload_length; // Payload length in bytes
|
||||
uint8_t payload[]; // Message-specific payload
|
||||
uint32_t checksum; // Message integrity checksum
|
||||
} main_hub_request_t;
|
||||
```
|
||||
|
||||
**Response Message Structure:**
|
||||
```c
|
||||
typedef struct {
|
||||
uint8_t message_type; // RESP_DATA, RESP_STATUS, RESP_DIAG, ACK, NACK
|
||||
uint16_t message_id; // Matching request ID
|
||||
uint8_t status_code; // SUCCESS, ERROR, TIMEOUT
|
||||
uint32_t timestamp; // Response timestamp
|
||||
uint16_t payload_length; // Payload length in bytes
|
||||
uint8_t payload[]; // Message-specific payload
|
||||
uint32_t checksum; // Message integrity checksum
|
||||
} main_hub_response_t;
|
||||
```
|
||||
|
||||
### 1.3 Message Types
|
||||
|
||||
| Message Type | Direction | Purpose | Payload |
|
||||
|--------------|-----------|---------|---------|
|
||||
| `REQ_DATA` | Main Hub → Sensor Hub | Request latest sensor data | None |
|
||||
| `RESP_DATA` | Sensor Hub → Main Hub | Sensor data response | Sensor data records |
|
||||
| `REQ_STATUS` | Main Hub → Sensor Hub | Request system status | None |
|
||||
| `RESP_STATUS` | Sensor Hub → Main Hub | System status response | Status information |
|
||||
| `REQ_DIAG` | Main Hub → Sensor Hub | Request diagnostic data | Diagnostic filter |
|
||||
| `RESP_DIAG` | Sensor Hub → Main Hub | Diagnostic data response | Diagnostic events |
|
||||
| `CMD_CONFIG` | Main Hub → Sensor Hub | Configuration update | Configuration data |
|
||||
| `CMD_OTA` | Main Hub → Sensor Hub | OTA update request | OTA metadata |
|
||||
| `ACK` | Sensor Hub → Main Hub | Acknowledgment | None or status |
|
||||
| `NACK` | Sensor Hub → Main Hub | Negative acknowledgment | Error code |
|
||||
|
||||
### 1.4 Communication Requirements
|
||||
|
||||
- **Encryption:** All messages SHALL be encrypted using TLS/DTLS
|
||||
- **Authentication:** All messages SHALL be authenticated
|
||||
- **Integrity:** All messages SHALL include integrity checksums
|
||||
- **Timeout:** Request timeout: 5 seconds
|
||||
- **Retry:** Maximum 3 retries with exponential backoff
|
||||
|
||||
## 2. Sensor Interfaces
|
||||
|
||||
### 2.1 Supported Protocols
|
||||
|
||||
| Protocol | Sensor Types | Interface |
|
||||
|----------|--------------|-----------|
|
||||
| I2C | Temperature, Humidity, CO2, NH3, VOC, Light | I2C bus (configurable pins) |
|
||||
| SPI | Particulate matter sensors | SPI bus (configurable pins) |
|
||||
| UART | Some sensor modules | UART (configurable pins) |
|
||||
| Analog | Analog sensors | ADC channels |
|
||||
|
||||
### 2.2 Sensor Detection Signal
|
||||
|
||||
Each sensor slot SHALL provide a dedicated GPIO pin for presence detection:
|
||||
- **High (3.3V):** Sensor present
|
||||
- **Low (0V):** Sensor absent
|
||||
|
||||
### 2.3 Sensor Data Format
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint8_t sensor_id; // Unique sensor identifier
|
||||
uint8_t sensor_type; // TEMP, HUM, CO2, NH3, VOC, PM, LIGHT
|
||||
float value; // Filtered sensor value
|
||||
uint8_t unit; // Unit code (C, RH, PPM, LUX, etc.)
|
||||
uint64_t timestamp_us; // Timestamp in microseconds
|
||||
uint8_t validity_status; // VALID, INVALID, DEGRADED, FAILED
|
||||
uint8_t sample_count; // Number of samples used for filtering
|
||||
} sensor_data_record_t;
|
||||
```
|
||||
|
||||
## 3. Storage Interfaces
|
||||
|
||||
### 3.1 SD Card Interface
|
||||
|
||||
**File System:** FAT32
|
||||
**Mount Point:** `/sdcard`
|
||||
|
||||
**Directory Structure:**
|
||||
```
|
||||
/sdcard/
|
||||
├── sensor_data/
|
||||
│ └── YYYYMMDD_HHMMSS.dat
|
||||
├── diagnostics/
|
||||
│ └── diag_log.dat
|
||||
├── machine_constants/
|
||||
│ └── mc.dat
|
||||
└── ota/
|
||||
└── firmware.bin
|
||||
```
|
||||
|
||||
**File Naming Convention:**
|
||||
- Sensor data: `YYYYMMDD_HHMMSS.dat` (timestamp-based)
|
||||
- Diagnostics: `diag_log.dat` (circular log)
|
||||
- Machine constants: `mc.dat` (single file)
|
||||
- OTA firmware: `firmware.bin` (temporary)
|
||||
|
||||
### 3.2 NVM (Non-Volatile Memory) Interface
|
||||
|
||||
**Storage Areas:**
|
||||
- **Machine Constants:** 4KB
|
||||
- **System Configuration:** 2KB
|
||||
- **Diagnostic Log (circular):** 8KB
|
||||
- **OTA Metadata:** 1KB
|
||||
|
||||
**Access Method:** ESP-IDF NVS (Non-Volatile Storage) API
|
||||
|
||||
## 4. HMI Interfaces
|
||||
|
||||
### 4.1 OLED Display Interface
|
||||
|
||||
**Protocol:** I2C
|
||||
**Address:** Configurable (default: 0x3C)
|
||||
**Display:** 128x64 pixels, monochrome
|
||||
|
||||
**Display Content:**
|
||||
- **Main Screen:** Connectivity, System State, Sensor Count, Time/Date
|
||||
- **Menu Screens:** Diagnostics, Sensors, Health
|
||||
|
||||
### 4.2 Button Interface
|
||||
|
||||
**Buttons:** 3 GPIO inputs (Up, Down, Select)
|
||||
|
||||
**Button Behavior:**
|
||||
- **Up:** Navigate menu up / Scroll up
|
||||
- **Down:** Navigate menu down / Scroll down
|
||||
- **Select:** Enter menu / Select item / Return to main screen
|
||||
|
||||
**Debouncing:** Hardware debouncing (10ms) + software debouncing (50ms)
|
||||
|
||||
## 5. Debug Interface
|
||||
|
||||
### 5.1 Physical Interface
|
||||
|
||||
**Protocol:** UART
|
||||
**Baud Rate:** 115200
|
||||
**Data Bits:** 8
|
||||
**Parity:** None
|
||||
**Stop Bits:** 1
|
||||
**Flow Control:** None
|
||||
|
||||
### 5.2 Debug Protocol
|
||||
|
||||
**Session Establishment:**
|
||||
1. Client sends authentication challenge
|
||||
2. Sensor Hub responds with challenge response
|
||||
3. Client sends session key (encrypted)
|
||||
4. Sensor Hub validates and establishes session
|
||||
|
||||
**Debug Commands:**
|
||||
- `READ_DIAG <filter>` - Read diagnostic events
|
||||
- `READ_STATUS` - Read system status
|
||||
- `READ_MC` - Read machine constants
|
||||
- `CLEAR_DIAG` - Clear diagnostic log
|
||||
- `REBOOT` - Reboot system
|
||||
- `TEARDOWN` - Initiate controlled teardown
|
||||
|
||||
**Security:** All debug sessions SHALL be authenticated. Unauthorized access SHALL be rejected and logged as a security violation.
|
||||
|
||||
## 6. Peer Sensor Hub Communication
|
||||
|
||||
### 6.1 Protocol
|
||||
|
||||
**Protocol:** Same as Main Hub communication (Wi-Fi / Zigbee / LoRa)
|
||||
**Message Types:** Limited to connectivity checks and time synchronization
|
||||
|
||||
### 6.2 Message Types
|
||||
|
||||
| Message Type | Purpose |
|
||||
|--------------|---------|
|
||||
| `PEER_PING` | Connectivity check |
|
||||
| `PEER_PONG` | Connectivity response |
|
||||
| `PEER_TIME_SYNC` | Time synchronization request |
|
||||
| `PEER_TIME_RESP` | Time synchronization response |
|
||||
|
||||
### 6.3 Requirements
|
||||
|
||||
- Peer communication SHALL NOT interfere with Main Hub communication
|
||||
- Peer communication SHALL be encrypted and authenticated
|
||||
- Peer communication SHALL be limited to coordination functions only
|
||||
|
||||
## 7. Interface Requirements Summary
|
||||
|
||||
| Interface | Protocol | Encryption | Authentication | Integrity |
|
||||
|-----------|----------|------------|----------------|-----------|
|
||||
| Main Hub | TLS/DTLS over Wi-Fi/Zigbee/LoRa | Yes | Yes | Yes |
|
||||
| Sensors | I2C/SPI/UART/Analog | No | No | No (hardware-level) |
|
||||
| SD Card | SPI (SD protocol) | Optional (SWR-SEC-006) | No | Yes (file system) |
|
||||
| NVM | ESP-IDF NVS | Optional (SWR-SEC-005) | No | Yes (NVS) |
|
||||
| OLED Display | I2C | No | No | No |
|
||||
| Buttons | GPIO | No | No | No |
|
||||
| Debug | UART | Yes | Yes | Yes |
|
||||
| Peer Sensor Hub | Same as Main Hub | Yes | Yes | Yes |
|
||||
|
||||
## 8. Traceability
|
||||
|
||||
- **SWR-IF-001:** Main Hub communication interface
|
||||
- **SWR-IF-002:** Sensor interfaces
|
||||
- **SWR-IF-003:** OLED display interface
|
||||
- **SWR-IF-004:** Button input interfaces
|
||||
- **SWR-IF-005:** Storage interfaces
|
||||
- **SWR-IF-006:** Debug interface
|
||||
230
system_design/SRS/Annex_C_Budgets.md
Normal file
230
system_design/SRS/Annex_C_Budgets.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# Annex C: Timing and Resource Budgets
|
||||
|
||||
**Document:** SRS Annex C
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
|
||||
## Purpose
|
||||
|
||||
This annex defines timing budgets, resource allocation limits, and performance constraints for the Sensor Hub software.
|
||||
|
||||
## 1. Timing Budgets
|
||||
|
||||
### 1.1 Sensor Acquisition Timing
|
||||
|
||||
| Operation | Maximum Duration | Justification |
|
||||
|-----------|------------------|---------------|
|
||||
| Single sensor sample (I2C) | 10ms | I2C transaction time |
|
||||
| Single sensor sample (SPI) | 5ms | SPI transaction time |
|
||||
| Single sensor sample (UART) | 20ms | UART transaction time |
|
||||
| Single sensor sample (Analog/ADC) | 1ms | ADC conversion time |
|
||||
| Filtering (10 samples) | 5ms | Local filtering computation |
|
||||
| Timestamp generation | 1ms | System time access |
|
||||
| Complete acquisition cycle (per sensor) | 100ms | Total per sensor (worst case) |
|
||||
| Complete acquisition cycle (all sensors) | 500ms | 5 sensors × 100ms (with overlap) |
|
||||
|
||||
### 1.2 State Transition Timing
|
||||
|
||||
| Transition | Maximum Duration | Justification |
|
||||
|------------|------------------|---------------|
|
||||
| `[*]` → `INIT` | 100ms | Power-on initialization |
|
||||
| `INIT` → `RUNNING` | 5s | Hardware init, secure boot, MC load |
|
||||
| `INIT` → `BOOT_FAILURE` | 2s | Secure boot verification |
|
||||
| `RUNNING` → `WARNING` | 50ms | Fault detection and state change |
|
||||
| `RUNNING` → `FAULT` | 50ms | Critical fault detection |
|
||||
| `RUNNING` → `OTA_PREP` | 100ms | OTA request processing |
|
||||
| `OTA_PREP` → `TEARDOWN` | 2s | Readiness validation |
|
||||
| `TEARDOWN` → `OTA_UPDATE` | 500ms | Data flush and resource release |
|
||||
| `TEARDOWN` → `INIT` | 500ms | Data flush and reset |
|
||||
| `OTA_UPDATE` → `RUNNING` | 10 minutes | Firmware transfer and flashing |
|
||||
| `RUNNING` → `SERVICE` | 100ms | Debug session establishment |
|
||||
| `SERVICE` → `RUNNING` | 50ms | Debug session closure |
|
||||
| `RUNNING` → `SD_DEGRADED` | 200ms | SD failure detection |
|
||||
|
||||
### 1.3 Communication Timing
|
||||
|
||||
| Operation | Maximum Duration | Justification |
|
||||
|------------|------------------|---------------|
|
||||
| Main Hub request processing | 100ms | Data retrieval and response |
|
||||
| Main Hub message transmission | 50ms | Network transmission (local) |
|
||||
| Main Hub message reception | 50ms | Network reception (local) |
|
||||
| Communication link failure detection | 30s | Heartbeat timeout |
|
||||
| OTA firmware chunk reception | 1s | Network transfer per chunk |
|
||||
| Peer Sensor Hub ping | 100ms | Connectivity check |
|
||||
|
||||
### 1.4 Persistence Timing
|
||||
|
||||
| Operation | Maximum Duration | Justification |
|
||||
|------------|------------------|---------------|
|
||||
| Sensor data write (SD card) | 50ms | File write operation |
|
||||
| Diagnostic event write (SD card) | 20ms | Log append operation |
|
||||
| Machine constants write (NVM) | 10ms | NVS write operation |
|
||||
| Data flush (all pending) | 200ms | Complete flush operation |
|
||||
| SD card failure detection | 500ms | File system check |
|
||||
|
||||
### 1.5 OTA Timing
|
||||
|
||||
| Operation | Maximum Duration | Justification |
|
||||
|------------|------------------|---------------|
|
||||
| OTA readiness validation | 2s | System state and resource check |
|
||||
| Firmware chunk reception | 1s | Network transfer per chunk |
|
||||
| Firmware integrity validation | 5s | Cryptographic verification |
|
||||
| Firmware flashing | 2 minutes | Flash write operation |
|
||||
| Complete OTA operation | 10 minutes | End-to-end OTA process |
|
||||
|
||||
### 1.6 Diagnostic Timing
|
||||
|
||||
| Operation | Maximum Duration | Justification |
|
||||
|------------|------------------|---------------|
|
||||
| Diagnostic event generation | 1ms | Event creation and classification |
|
||||
| Diagnostic event persistence | 20ms | Log write operation |
|
||||
| Diagnostic query processing | 50ms | Log read and filtering |
|
||||
| Fault escalation | 50ms | Severity check and state transition |
|
||||
|
||||
## 2. Resource Budgets
|
||||
|
||||
### 2.1 Memory (RAM) Budget
|
||||
|
||||
| Component | Allocation | Peak Usage | Monitoring Required |
|
||||
|-----------|------------|------------|---------------------|
|
||||
| System (RTOS, ESP-IDF) | 80KB | 100KB | Yes |
|
||||
| Sensor Manager | 20KB | 25KB | Yes |
|
||||
| Event System | 10KB | 15KB | Yes |
|
||||
| Data Pool | 15KB | 20KB | Yes |
|
||||
| Communication Stack | 30KB | 40KB | Yes |
|
||||
| Diagnostics | 10KB | 15KB | Yes |
|
||||
| Persistence | 15KB | 20KB | Yes |
|
||||
| OTA Manager | 20KB | 30KB | Yes |
|
||||
| Security | 10KB | 15KB | Yes |
|
||||
| System Management | 10KB | 15KB | Yes |
|
||||
| HMI | 5KB | 8KB | Yes |
|
||||
| **Total Allocated** | **225KB** | **283KB** | |
|
||||
| **Available (ESP32-S3)** | **512KB** | **512KB** | |
|
||||
| **Utilization** | **44%** | **55%** | |
|
||||
| **Safety Margin** | **56%** | **45%** | |
|
||||
|
||||
**Note:** Peak usage includes worst-case stack usage and temporary buffers. Actual runtime usage SHALL be monitored and maintained below 60% (307KB).
|
||||
|
||||
### 2.2 Flash (Program Memory) Budget
|
||||
|
||||
| Component | Allocation | Notes |
|
||||
|-----------|------------|-------|
|
||||
| Bootloader | 32KB | ESP-IDF bootloader |
|
||||
| Application Code | 1.5MB | Main application firmware |
|
||||
| OTA Partition 0 | 1.5MB | Primary firmware partition |
|
||||
| OTA Partition 1 | 1.5MB | Secondary firmware partition (for updates) |
|
||||
| NVS (Non-Volatile Storage) | 20KB | Configuration and MC storage |
|
||||
| SPIFFS/LittleFS | 500KB | File system (if used) |
|
||||
| **Total Used** | **5.052MB** | |
|
||||
| **Available (8MB Flash)** | **8MB** | |
|
||||
| **Utilization** | **63%** | |
|
||||
| **Safety Margin** | **37%** | |
|
||||
|
||||
### 2.3 CPU Utilization Budget
|
||||
|
||||
| Task | Priority | CPU Usage (Normal) | CPU Usage (Peak) | Notes |
|
||||
|------|----------|-------------------|------------------|-------|
|
||||
| Sensor Acquisition | High | 15% | 25% | Time-critical |
|
||||
| Communication | Medium | 10% | 20% | Network I/O |
|
||||
| Diagnostics | Low | 5% | 10% | Background |
|
||||
| Persistence | Medium | 5% | 15% | Storage I/O |
|
||||
| System Management | High | 5% | 10% | State management |
|
||||
| HMI | Low | 2% | 5% | Display updates |
|
||||
| Idle | - | 58% | 15% | System idle |
|
||||
| **Total** | - | **100%** | **100%** | |
|
||||
|
||||
**Requirement:** CPU utilization SHALL NOT exceed 80% during normal operation (SWR-PERF-005).
|
||||
|
||||
### 2.4 Storage (SD Card) Budget
|
||||
|
||||
| Data Type | Daily Write Volume | Retention Policy | Notes |
|
||||
|-----------|-------------------|------------------|-------|
|
||||
| Sensor Data | 50MB | 7 days (rolling) | 5 sensors × 1 sample/min × 24h |
|
||||
| Diagnostic Log | 5MB | 30 days (circular) | Bounded log with overwrite |
|
||||
| Machine Constants | 1KB | Permanent | Updated only on configuration change |
|
||||
| OTA Firmware | 2MB | Temporary | Deleted after successful update |
|
||||
| **Total Daily Writes** | **57MB** | | |
|
||||
| **SD Card Capacity** | **32GB** (typical) | | |
|
||||
| **Wear Level** | **Low** | | With wear-leveling |
|
||||
|
||||
**Requirement:** SD card writes SHALL be wear-aware to prevent premature failure (SWR-DATA-013).
|
||||
|
||||
### 2.5 Network Bandwidth Budget
|
||||
|
||||
| Operation | Bandwidth | Frequency | Daily Volume |
|
||||
|-----------|-----------|-----------|--------------|
|
||||
| Sensor Data Transmission | 1KB/packet | 1 packet/min | 1.44MB/day |
|
||||
| Diagnostic Reporting | 500B/packet | On-demand | Variable |
|
||||
| Status Updates | 200B/packet | 1 packet/5min | 57.6KB/day |
|
||||
| OTA Firmware Transfer | 2MB | On-demand | Variable |
|
||||
| **Total (Normal Operation)** | - | - | **~1.5MB/day** | |
|
||||
|
||||
**Note:** OTA transfers are infrequent and excluded from daily normal operation budget.
|
||||
|
||||
## 3. Performance Constraints
|
||||
|
||||
### 3.1 Real-Time Constraints
|
||||
|
||||
| Constraint | Requirement | Verification Method |
|
||||
|------------|-------------|---------------------|
|
||||
| Sensor acquisition determinism | ≤ 100ms per sensor | Timing measurement |
|
||||
| State transition determinism | ≤ 50ms (except INIT, TEARDOWN) | Timing measurement |
|
||||
| Communication response time | ≤ 100ms | End-to-end timing |
|
||||
| Data persistence latency | ≤ 200ms | Write operation timing |
|
||||
|
||||
### 3.2 Resource Constraints
|
||||
|
||||
| Resource | Limit | Monitoring | Action on Exceed |
|
||||
|----------|-------|------------|------------------|
|
||||
| RAM Usage | 60% (307KB) | Runtime monitoring | Enter WARNING state, reduce buffers |
|
||||
| CPU Usage | 80% | Runtime monitoring | Reduce task priorities, throttle operations |
|
||||
| SD Card Space | 10% free | File system check | Trigger data retention policy |
|
||||
| Flash Usage | 70% (5.6MB) | Build-time check | Optimize code size |
|
||||
|
||||
### 3.3 Quality Constraints
|
||||
|
||||
| Constraint | Requirement | Verification Method |
|
||||
|------------|-------------|---------------------|
|
||||
| Power loss recovery | < 1 second | Power interruption test |
|
||||
| SD card failure handling | Graceful degradation | SD card removal test |
|
||||
| OTA failure recovery | Rollback capability | OTA failure injection test |
|
||||
| Secure boot failure | BOOT_FAILURE state | Secure boot verification test |
|
||||
|
||||
## 4. Worst-Case Execution Time (WCET) Analysis
|
||||
|
||||
### 4.1 Critical Paths
|
||||
|
||||
**Sensor Acquisition Path:**
|
||||
```
|
||||
Sensor Read (10ms) × 10 samples = 100ms
|
||||
+ Filtering (5ms) = 105ms
|
||||
+ Timestamp (1ms) = 106ms
|
||||
WCET = 110ms (with 4ms margin)
|
||||
```
|
||||
|
||||
**State Transition Path:**
|
||||
```
|
||||
State validation (5ms)
|
||||
+ Component notification (10ms)
|
||||
+ State update (1ms)
|
||||
WCET = 20ms (with 30ms margin for 50ms requirement)
|
||||
```
|
||||
|
||||
**Data Persistence Path:**
|
||||
```
|
||||
Data serialization (10ms)
|
||||
+ File write (50ms)
|
||||
+ Verification (10ms)
|
||||
WCET = 80ms (with 120ms margin for 200ms requirement)
|
||||
```
|
||||
|
||||
## 5. Traceability
|
||||
|
||||
- **SWR-PERF-001:** Sensor acquisition cycle timing
|
||||
- **SWR-PERF-002:** State transition timing
|
||||
- **SWR-PERF-003:** Data persistence timing
|
||||
- **SWR-PERF-004:** OTA operation duration
|
||||
- **SWR-PERF-005:** CPU utilization limit
|
||||
- **SWR-PERF-006:** RAM usage limit
|
||||
- **SWR-PERF-007:** Main Hub response time
|
||||
- **SWR-PERF-008:** Communication link failure detection
|
||||
844
system_design/SRS/SRS.md
Normal file
844
system_design/SRS/SRS.md
Normal file
@@ -0,0 +1,844 @@
|
||||
# Software Requirements Specification (SRS)
|
||||
|
||||
**Document ID:** SRS-ASF-SensorHub-001
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
**Standard:** ISO/IEC/IEEE 29148:2018
|
||||
**Scope:** Sensor Hub (Sub-Hub) Software Requirements
|
||||
|
||||
## 1. Introduction
|
||||
|
||||
### 1.1 Purpose
|
||||
|
||||
This Software Requirements Specification (SRS) defines the software requirements for the ASF Sensor Hub (Sub-Hub) embedded system. This document provides a complete description of all software requirements, derived from system requirements and features, to enable implementation and verification.
|
||||
|
||||
### 1.2 Scope
|
||||
|
||||
This SRS covers:
|
||||
- Sensor Hub firmware running on ESP32-S3
|
||||
- All application-layer components and drivers
|
||||
- Interfaces to Main Hub, sensors, and storage
|
||||
- System state management, diagnostics, and security
|
||||
|
||||
This SRS explicitly excludes:
|
||||
- Main Hub firmware
|
||||
- Cloud services
|
||||
- Hardware design specifications
|
||||
- Manufacturing and deployment procedures
|
||||
|
||||
### 1.3 Definitions, Acronyms, and Abbreviations
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **DAQ** | Data Acquisition |
|
||||
| **DQC** | Data Quality & Calibration |
|
||||
| **DIAG** | Diagnostics & Health Monitoring |
|
||||
| **DP** | Data Persistence component |
|
||||
| **FSM** | Finite State Machine |
|
||||
| **MC** | Machine Constants |
|
||||
| **NVM** | Non-Volatile Memory |
|
||||
| **OTA** | Over-The-Air (firmware update) |
|
||||
| **SRS** | Software Requirements Specification |
|
||||
| **SR** | System Requirement |
|
||||
| **SWR** | Software Requirement |
|
||||
| **SWRS** | Software Requirements |
|
||||
|
||||
### 1.4 References
|
||||
|
||||
- ISO/IEC/IEEE 29148:2018 - Systems and software engineering - Life cycle processes - Requirements engineering
|
||||
- System Requirements: `System Design/system_requirementsand_and_traceability.csv`
|
||||
- Features: `System Design/Features/`
|
||||
- System State Machine: `System Design/System_State_Machine_Specification.md`
|
||||
- Failure Handling Model: `System Design/Failure_Handling_Model.md`
|
||||
- Cross-Feature Constraints: `System Design/Features/Cross-Feature Constraints.md`
|
||||
|
||||
### 1.5 Overview
|
||||
|
||||
This SRS is organized as follows:
|
||||
- **Section 2:** Overall Description (product perspective, functions, user characteristics, constraints)
|
||||
- **Section 3:** Specific Requirements (functional, interface, performance, design constraints, quality attributes)
|
||||
- **Annex A:** Software Requirements Traceability Matrix
|
||||
- **Annex B:** External Interface Specifications
|
||||
- **Annex C:** Timing and Resource Budgets
|
||||
|
||||
## 2. Overall Description
|
||||
|
||||
### 2.1 Product Perspective
|
||||
|
||||
The Sensor Hub is an embedded system component within the Distributed Intelligent Poultry Farm Environmental Control System (DIPFECS). It operates autonomously but communicates with a Main Hub for data transmission and configuration updates.
|
||||
|
||||
**System Context:**
|
||||
```
|
||||
[Sensors] → [Sensor Hub] ↔ [Main Hub] ↔ [Central Server]
|
||||
↓
|
||||
[SD Card / NVM]
|
||||
```
|
||||
|
||||
### 2.2 Product Functions
|
||||
|
||||
The Sensor Hub software provides the following major functions:
|
||||
|
||||
1. **Sensor Data Acquisition (DAQ)** - Multi-sensor sampling, filtering, timestamping
|
||||
2. **Data Quality & Calibration (DQC)** - Sensor detection, validation, calibration management
|
||||
3. **Communication (COM)** - Bidirectional communication with Main Hub and peer Sensor Hubs
|
||||
4. **Diagnostics & Health Monitoring (DIAG)** - Fault detection, classification, persistent logging
|
||||
5. **Persistence & Data Management (DATA)** - Non-volatile storage of sensor data and system state
|
||||
6. **Firmware Update (OTA)** - Secure over-the-air firmware updates
|
||||
7. **Security & Safety (SEC)** - Secure boot, encrypted storage, encrypted communication
|
||||
8. **System Management (SYS)** - State machine, teardown, HMI, debug sessions
|
||||
|
||||
### 2.3 User Characteristics
|
||||
|
||||
**Primary Users:**
|
||||
- **Farm Operators:** Monitor system status via OLED display
|
||||
- **Engineers:** Access diagnostic and debug sessions
|
||||
- **Main Hub:** Automated data collection and control
|
||||
|
||||
**User Assumptions:**
|
||||
- Farm operators have basic technical knowledge
|
||||
- Engineers have embedded systems expertise
|
||||
- Main Hub communication is automated
|
||||
|
||||
### 2.4 Constraints
|
||||
|
||||
#### 2.4.1 Hardware Constraints
|
||||
- ESP32-S3 microcontroller (dual-core, 512KB SRAM, 8MB flash)
|
||||
- Limited I/O pins for sensors and peripherals
|
||||
- SD card for external storage (subject to wear and failure)
|
||||
- Power: Continuous AC power (with brief interruptions)
|
||||
|
||||
#### 2.4.2 Software Constraints
|
||||
- ESP-IDF v5.4 framework
|
||||
- FreeRTOS for task scheduling
|
||||
- C/C++ programming languages
|
||||
- No dynamic memory allocation in critical paths
|
||||
|
||||
#### 2.4.3 Regulatory Constraints
|
||||
- Animal welfare regulations compliance
|
||||
- Environmental monitoring standards
|
||||
- Security requirements (encryption, authentication)
|
||||
|
||||
#### 2.4.4 Operational Constraints
|
||||
- Harsh environment (humidity, dust, ammonia)
|
||||
- Unattended operation (24/7)
|
||||
- Remote deployment (limited physical access)
|
||||
|
||||
### 2.5 Assumptions and Dependencies
|
||||
|
||||
**Assumptions:**
|
||||
- Sensors are pre-configured and compatible
|
||||
- Main Hub provides time synchronization
|
||||
- Cryptographic keys are securely provisioned
|
||||
- Power interruptions are brief (< 1 second)
|
||||
|
||||
**Dependencies:**
|
||||
- ESP-IDF framework availability and stability
|
||||
- Sensor driver availability
|
||||
- Main Hub communication protocol compatibility
|
||||
|
||||
## 3. Specific Requirements
|
||||
|
||||
### 3.1 Functional Requirements
|
||||
|
||||
#### 3.1.1 System State Management (SWR-SYS-001 through SWR-SYS-015)
|
||||
|
||||
**SWR-SYS-001:** The software SHALL implement a finite state machine (FSM) with the following states: INIT, BOOT_FAILURE, RUNNING, WARNING, FAULT, OTA_PREP, OTA_UPDATE, MC_UPDATE, TEARDOWN, SERVICE, SD_DEGRADED.
|
||||
|
||||
**Traceability:** SR-SYS-001
|
||||
|
||||
**SWR-SYS-002:** The software SHALL enforce valid state transitions as defined in the System State Machine Specification.
|
||||
|
||||
**Traceability:** SR-SYS-001
|
||||
|
||||
**SWR-SYS-003:** The software SHALL restrict feature operations based on the current system state according to per-state execution rules.
|
||||
|
||||
**Traceability:** SR-SYS-002
|
||||
|
||||
**SWR-SYS-004:** The software SHALL notify all registered components when a state transition occurs via the Event System.
|
||||
|
||||
**Traceability:** SR-SYS-003
|
||||
|
||||
**SWR-SYS-005:** The software SHALL execute a controlled teardown sequence before firmware updates, machine constant updates, or system resets.
|
||||
|
||||
**Traceability:** SR-SYS-004
|
||||
|
||||
**SWR-SYS-006:** The software SHALL persist all critical runtime data before completing a teardown sequence.
|
||||
|
||||
**Traceability:** SR-SYS-005
|
||||
|
||||
**SWR-SYS-007:** The software SHALL prevent data corruption during teardown and reset operations.
|
||||
|
||||
**Traceability:** SR-SYS-006
|
||||
|
||||
**SWR-SYS-008:** The software SHALL provide a local OLED display interface using I2C communication protocol.
|
||||
|
||||
**Traceability:** SR-SYS-007
|
||||
|
||||
**SWR-SYS-009:** The software SHALL display connectivity status, system state, connected sensor summary, and time/date on the OLED display.
|
||||
|
||||
**Traceability:** SR-SYS-008
|
||||
|
||||
**SWR-SYS-010:** The software SHALL provide menu navigation using Up, Down, and Select buttons.
|
||||
|
||||
**Traceability:** SR-SYS-009
|
||||
|
||||
**SWR-SYS-011:** The software SHALL provide diagnostic, sensor, and health information through the local OLED menu interface.
|
||||
|
||||
**Traceability:** SR-SYS-010
|
||||
|
||||
**SWR-SYS-012:** The software SHALL support diagnostic sessions for retrieving system status and diagnostic data.
|
||||
|
||||
**Traceability:** SR-SYS-011
|
||||
|
||||
**SWR-SYS-013:** The software SHALL support debug sessions allowing controlled engineering commands.
|
||||
|
||||
**Traceability:** SR-SYS-012
|
||||
|
||||
**SWR-SYS-014:** The software SHALL restrict debug session actions to authorized engineering access only.
|
||||
|
||||
**Traceability:** SR-SYS-013
|
||||
|
||||
**SWR-SYS-015:** The software SHALL ensure debug sessions do not interfere with normal sensor acquisition or communication operations.
|
||||
|
||||
**Traceability:** SR-SYS-013, CFC-DBG-01
|
||||
|
||||
#### 3.1.2 Sensor Data Acquisition (SWR-DAQ-001 through SWR-DAQ-015)
|
||||
|
||||
**SWR-DAQ-001:** The software SHALL support simultaneous acquisition of environmental data from multiple sensor types (temperature, humidity, CO2, NH3, VOC, particulate matter, light).
|
||||
|
||||
**Traceability:** SR-DAQ-001
|
||||
|
||||
**SWR-DAQ-002:** The software SHALL assign each supported sensor type to a predefined and unique hardware slot.
|
||||
|
||||
**Traceability:** SR-DAQ-002
|
||||
|
||||
**SWR-DAQ-003:** The software SHALL detect the physical presence of each sensor via a dedicated hardware detection signal prior to sensor initialization.
|
||||
|
||||
**Traceability:** SR-DAQ-003
|
||||
|
||||
**SWR-DAQ-004:** The software SHALL initialize and activate only sensors that are detected as present and enabled.
|
||||
|
||||
**Traceability:** SR-DAQ-004
|
||||
|
||||
**SWR-DAQ-005:** The software SHALL sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples per sensor per cycle).
|
||||
|
||||
**Traceability:** SR-DAQ-005
|
||||
|
||||
**SWR-DAQ-006:** The software SHALL apply a local filtering mechanism to raw sensor samples to produce a single filtered sensor value per acquisition cycle.
|
||||
|
||||
**Traceability:** SR-DAQ-006
|
||||
|
||||
**SWR-DAQ-007:** The software SHALL complete each sensor's sampling and filtering process within a bounded and deterministic time window (maximum 100ms per sensor).
|
||||
|
||||
**Traceability:** SR-DAQ-007, CFC-TIME-02
|
||||
|
||||
**SWR-DAQ-008:** The software SHALL generate a timestamp for each filtered sensor value upon completion of the acquisition and filtering process.
|
||||
|
||||
**Traceability:** SR-DAQ-008
|
||||
|
||||
**SWR-DAQ-009:** The software SHALL generate a timestamped sensor data record containing at minimum: sensor identifier, sensor type, filtered value, unit of measurement, timestamp, and data validity status.
|
||||
|
||||
**Traceability:** SR-DAQ-009
|
||||
|
||||
**SWR-DAQ-010:** The software SHALL maintain the most recent timestamped sensor data record in memory and make it available for persistence and on-demand communication requests.
|
||||
|
||||
**Traceability:** SR-DAQ-010
|
||||
|
||||
**SWR-DAQ-011:** The software SHALL NOT perform sensor acquisition during OTA_UPDATE, MC_UPDATE, or TEARDOWN states.
|
||||
|
||||
**Traceability:** CFC-ARCH-02
|
||||
|
||||
**SWR-DAQ-012:** The software SHALL perform sensor acquisition in a non-blocking manner.
|
||||
|
||||
**Traceability:** CFC-TIME-01
|
||||
|
||||
**SWR-DAQ-013:** The software SHALL use deterministic memory allocation for sensor acquisition buffers (no dynamic allocation in acquisition path).
|
||||
|
||||
**Traceability:** CFC-TIME-02
|
||||
|
||||
**SWR-DAQ-014:** The software SHALL publish sensor data updates via the Event System upon completion of each acquisition cycle.
|
||||
|
||||
**Traceability:** Architecture requirement
|
||||
|
||||
**SWR-DAQ-015:** The software SHALL exclude failed sensors from acquisition cycles as defined by the failure handling model.
|
||||
|
||||
**Traceability:** SR-DQC-009
|
||||
|
||||
#### 3.1.3 Data Quality & Calibration (SWR-DQC-001 through SWR-DQC-018)
|
||||
|
||||
**SWR-DQC-001:** The software SHALL detect the physical presence of each sensor using a dedicated hardware-based detection mechanism.
|
||||
|
||||
**Traceability:** SR-DQC-001
|
||||
|
||||
**SWR-DQC-002:** The software SHALL perform sensor presence detection during system startup and after any reinitialization or reconfiguration event.
|
||||
|
||||
**Traceability:** SR-DQC-002
|
||||
|
||||
**SWR-DQC-003:** The software SHALL initialize and activate only sensors that are detected as present.
|
||||
|
||||
**Traceability:** SR-DQC-003
|
||||
|
||||
**SWR-DQC-004:** The software SHALL assign each physical sensor slot to a predefined sensor type.
|
||||
|
||||
**Traceability:** SR-DQC-004
|
||||
|
||||
**SWR-DQC-005:** The software SHALL verify that a detected sensor matches the expected sensor type for its assigned slot.
|
||||
|
||||
**Traceability:** SR-DQC-005
|
||||
|
||||
**SWR-DQC-006:** The software SHALL reject and report any sensor-slot mismatch as a diagnostic event.
|
||||
|
||||
**Traceability:** SR-DQC-006
|
||||
|
||||
**SWR-DQC-007:** The software SHALL continuously monitor sensor responsiveness and signal validity during normal operation.
|
||||
|
||||
**Traceability:** SR-DQC-007
|
||||
|
||||
**SWR-DQC-008:** The software SHALL detect sensor failures including disconnection, non-responsiveness, and out-of-range measurement values.
|
||||
|
||||
**Traceability:** SR-DQC-008
|
||||
|
||||
**SWR-DQC-009:** The software SHALL mark detected faulty sensors as defective and exclude them from data acquisition and reporting.
|
||||
|
||||
**Traceability:** SR-DQC-009
|
||||
|
||||
**SWR-DQC-010:** The software SHALL report detected sensor failures to the Main Hub with timestamps and failure classification.
|
||||
|
||||
**Traceability:** SR-DQC-010
|
||||
|
||||
**SWR-DQC-011:** The software SHALL maintain a Machine Constants dataset defining sensor configuration, calibration parameters, and communication identifiers.
|
||||
|
||||
**Traceability:** SR-DQC-011
|
||||
|
||||
**SWR-DQC-012:** The software SHALL store the Machine Constants dataset in non-volatile storage.
|
||||
|
||||
**Traceability:** SR-DQC-012
|
||||
|
||||
**SWR-DQC-013:** The software SHALL load and apply the Machine Constants dataset during system initialization.
|
||||
|
||||
**Traceability:** SR-DQC-013
|
||||
|
||||
**SWR-DQC-014:** The software SHALL support remote updates of the Machine Constants dataset initiated by the Main Hub.
|
||||
|
||||
**Traceability:** SR-DQC-014
|
||||
|
||||
**SWR-DQC-015:** The software SHALL apply updated Machine Constants only after executing a controlled teardown and reinitialization procedure.
|
||||
|
||||
**Traceability:** SR-DQC-015
|
||||
|
||||
**SWR-DQC-016:** The software SHALL validate Machine Constants integrity before applying updates.
|
||||
|
||||
**Traceability:** SR-SEC-008
|
||||
|
||||
**SWR-DQC-017:** The software SHALL NOT perform sensor calibration during OTA_UPDATE, MC_UPDATE, or TEARDOWN states.
|
||||
|
||||
**Traceability:** CFC-ARCH-02
|
||||
|
||||
**SWR-DQC-018:** The software SHALL access Machine Constants only through the DP component.
|
||||
|
||||
**Traceability:** CFC-ARCH-01, CFC-DATA-01
|
||||
|
||||
#### 3.1.4 Communication (SWR-COM-001 through SWR-COM-015)
|
||||
|
||||
**SWR-COM-001:** The software SHALL support bidirectional communication between the Sensor Hub and the Main Hub.
|
||||
|
||||
**Traceability:** SR-COM-001
|
||||
|
||||
**SWR-COM-002:** The software SHALL transmit sensor data, diagnostics information, and system status to the Main Hub.
|
||||
|
||||
**Traceability:** SR-COM-002
|
||||
|
||||
**SWR-COM-003:** The software SHALL receive commands, configuration updates, and firmware update requests from the Main Hub.
|
||||
|
||||
**Traceability:** SR-COM-003
|
||||
|
||||
**SWR-COM-004:** The software SHALL monitor the status of the communication link with the Main Hub and report link availability and failure conditions.
|
||||
|
||||
**Traceability:** SR-COM-004
|
||||
|
||||
**SWR-COM-005:** The software SHALL support on-demand requests from the Main Hub for sensor data.
|
||||
|
||||
**Traceability:** SR-COM-005
|
||||
|
||||
**SWR-COM-006:** The software SHALL respond to on-demand data requests with the most recent timestamped sensor data.
|
||||
|
||||
**Traceability:** SR-COM-006
|
||||
|
||||
**SWR-COM-007:** The software SHALL include sensor status and data validity information in on-demand data responses.
|
||||
|
||||
**Traceability:** SR-COM-007
|
||||
|
||||
**SWR-COM-008:** The software SHALL support limited peer-to-peer communication between Sensor Hubs for connectivity checks and time synchronization.
|
||||
|
||||
**Traceability:** SR-COM-008, SR-COM-009
|
||||
|
||||
**SWR-COM-009:** The software SHALL ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations.
|
||||
|
||||
**Traceability:** SR-COM-010
|
||||
|
||||
**SWR-COM-010:** The software SHALL encrypt all communication with the Main Hub using authenticated encryption.
|
||||
|
||||
**Traceability:** SR-SEC-009, CFC-SEC-02
|
||||
|
||||
**SWR-COM-011:** The software SHALL ensure integrity and authenticity of all transmitted and received messages.
|
||||
|
||||
**Traceability:** SR-SEC-010
|
||||
|
||||
**SWR-COM-012:** The software SHALL limit communication operations during TEARDOWN state to session closure only.
|
||||
|
||||
**Traceability:** CFC-ARCH-02
|
||||
|
||||
**SWR-COM-013:** The software SHALL perform communication operations in a non-blocking manner.
|
||||
|
||||
**Traceability:** CFC-TIME-01
|
||||
|
||||
**SWR-COM-014:** The software SHALL report communication link failures as diagnostic events according to the failure handling model.
|
||||
|
||||
**Traceability:** SR-COM-004, Failure Handling Model
|
||||
|
||||
**SWR-COM-015:** The software SHALL detect and report communication security violations to the Main Hub.
|
||||
|
||||
**Traceability:** SR-SEC-012
|
||||
|
||||
#### 3.1.5 Diagnostics & Health Monitoring (SWR-DIAG-001 through SWR-DIAG-018)
|
||||
|
||||
**SWR-DIAG-001:** The software SHALL implement a diagnostic code framework for reporting system health conditions, warnings, errors, and fatal faults.
|
||||
|
||||
**Traceability:** SR-DIAG-001
|
||||
|
||||
**SWR-DIAG-002:** The software SHALL assign a unique diagnostic code to each detected fault or abnormal condition.
|
||||
|
||||
**Traceability:** SR-DIAG-002
|
||||
|
||||
**SWR-DIAG-003:** The software SHALL classify diagnostic codes by severity level (INFO, WARNING, ERROR, FATAL).
|
||||
|
||||
**Traceability:** SR-DIAG-003
|
||||
|
||||
**SWR-DIAG-004:** The software SHALL associate each diagnostic event with a timestamp and the originating system component.
|
||||
|
||||
**Traceability:** SR-DIAG-004
|
||||
|
||||
**SWR-DIAG-005:** The software SHALL persist diagnostic events in non-volatile storage.
|
||||
|
||||
**Traceability:** SR-DIAG-005
|
||||
|
||||
**SWR-DIAG-006:** The software SHALL retain diagnostic data across system resets and power cycles.
|
||||
|
||||
**Traceability:** SR-DIAG-006
|
||||
|
||||
**SWR-DIAG-007:** The software SHALL implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy.
|
||||
|
||||
**Traceability:** SR-DIAG-007
|
||||
|
||||
**SWR-DIAG-008:** The software SHALL provide a diagnostic session interface for accessing diagnostic and system health data.
|
||||
|
||||
**Traceability:** SR-DIAG-008
|
||||
|
||||
**SWR-DIAG-009:** The software SHALL allow authorized diagnostic sessions to retrieve stored diagnostic events.
|
||||
|
||||
**Traceability:** SR-DIAG-009
|
||||
|
||||
**SWR-DIAG-010:** The software SHALL allow authorized diagnostic sessions to clear stored diagnostic records.
|
||||
|
||||
**Traceability:** SR-DIAG-010
|
||||
|
||||
**SWR-DIAG-011:** The software SHALL ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations.
|
||||
|
||||
**Traceability:** SR-DIAG-011, CFC-DBG-01
|
||||
|
||||
**SWR-DIAG-012:** The software SHALL trigger state transitions based on diagnostic severity according to the failure handling model.
|
||||
|
||||
**Traceability:** Failure Handling Model, SR-SYS-002
|
||||
|
||||
**SWR-DIAG-013:** The software SHALL implement fault latching behavior as defined in the failure handling model.
|
||||
|
||||
**Traceability:** Failure Handling Model
|
||||
|
||||
**SWR-DIAG-014:** The software SHALL implement fault escalation rules as defined in the failure handling model.
|
||||
|
||||
**Traceability:** Failure Handling Model
|
||||
|
||||
**SWR-DIAG-015:** The software SHALL report WARNING, ERROR, and FATAL diagnostic events to the Main Hub.
|
||||
|
||||
**Traceability:** SR-COM-002
|
||||
|
||||
**SWR-DIAG-016:** The software SHALL provide diagnostic information through the local OLED menu interface.
|
||||
|
||||
**Traceability:** SR-SYS-010
|
||||
|
||||
**SWR-DIAG-017:** The software SHALL access diagnostic storage only through the DP component.
|
||||
|
||||
**Traceability:** CFC-ARCH-01, CFC-DATA-01
|
||||
|
||||
**SWR-DIAG-018:** The software SHALL NOT generate new diagnostic events during TEARDOWN state (except teardown-specific diagnostics).
|
||||
|
||||
**Traceability:** CFC-ARCH-02
|
||||
|
||||
#### 3.1.6 Persistence & Data Management (SWR-DATA-001 through SWR-DATA-015)
|
||||
|
||||
**SWR-DATA-001:** The software SHALL persist timestamped sensor data in non-volatile storage.
|
||||
|
||||
**Traceability:** SR-DATA-001
|
||||
|
||||
**SWR-DATA-002:** The software SHALL store sensor data together with sensor identifiers, timestamps, and validity status.
|
||||
|
||||
**Traceability:** SR-DATA-002
|
||||
|
||||
**SWR-DATA-003:** The software SHALL support configurable data retention and overwrite policies for persisted sensor data.
|
||||
|
||||
**Traceability:** SR-DATA-003
|
||||
|
||||
**SWR-DATA-004:** The software SHALL provide a Data Persistence (DP) component as the sole interface for persistent data access.
|
||||
|
||||
**Traceability:** SR-DATA-004, CFC-ARCH-01
|
||||
|
||||
**SWR-DATA-005:** The software SHALL prevent application and feature modules from directly accessing storage hardware.
|
||||
|
||||
**Traceability:** SR-DATA-005, CFC-ARCH-01
|
||||
|
||||
**SWR-DATA-006:** The DP component SHALL support serialization and deserialization of structured system data.
|
||||
|
||||
**Traceability:** SR-DATA-006
|
||||
|
||||
**SWR-DATA-007:** The software SHALL flush all critical runtime data to non-volatile storage before entering a controlled teardown or reset state.
|
||||
|
||||
**Traceability:** SR-DATA-007, SR-SYS-005
|
||||
|
||||
**SWR-DATA-008:** The software SHALL protect data integrity during firmware updates and machine constant updates.
|
||||
|
||||
**Traceability:** SR-DATA-008
|
||||
|
||||
**SWR-DATA-009:** The software SHALL verify successful data persistence before completing a system state transition.
|
||||
|
||||
**Traceability:** SR-DATA-009, CFC-DATA-02
|
||||
|
||||
**SWR-DATA-010:** The software SHALL NOT perform data write operations during TEARDOWN state unless explicitly authorized by the System Manager.
|
||||
|
||||
**Traceability:** CFC-DATA-02
|
||||
|
||||
**SWR-DATA-011:** The software SHALL ensure persistence completion is confirmed before state transitions.
|
||||
|
||||
**Traceability:** CFC-DATA-02
|
||||
|
||||
**SWR-DATA-012:** The software SHALL handle SD card failures gracefully by entering SD_DEGRADED state and disabling persistence writes.
|
||||
|
||||
**Traceability:** System State Machine Specification
|
||||
|
||||
**SWR-DATA-013:** The software SHALL implement wear-aware storage management to prevent premature SD card failure.
|
||||
|
||||
**Traceability:** Quality requirement
|
||||
|
||||
**SWR-DATA-014:** The software SHALL maintain a single source of truth for runtime and persistent data through the DP component.
|
||||
|
||||
**Traceability:** CFC-DATA-01
|
||||
|
||||
**SWR-DATA-015:** The software SHALL NOT allow features to maintain private persistent copies of shared system data.
|
||||
|
||||
**Traceability:** CFC-DATA-01
|
||||
|
||||
#### 3.1.7 Firmware Update (OTA) (SWR-OTA-001 through SWR-OTA-020)
|
||||
|
||||
**SWR-OTA-001:** The software SHALL support OTA update negotiation initiated by the Main Hub.
|
||||
|
||||
**Traceability:** SR-OTA-001
|
||||
|
||||
**SWR-OTA-002:** The software SHALL verify internal readiness conditions before accepting an OTA update request.
|
||||
|
||||
**Traceability:** SR-OTA-002
|
||||
|
||||
**SWR-OTA-003:** The software SHALL explicitly acknowledge or reject OTA update requests.
|
||||
|
||||
**Traceability:** SR-OTA-003
|
||||
|
||||
**SWR-OTA-004:** The software SHALL receive firmware images over the established communication interface.
|
||||
|
||||
**Traceability:** SR-OTA-004
|
||||
|
||||
**SWR-OTA-005:** The software SHALL store received firmware images in non-volatile storage prior to validation.
|
||||
|
||||
**Traceability:** SR-OTA-005
|
||||
|
||||
**SWR-OTA-006:** The software SHALL prevent overwriting the active firmware during firmware reception.
|
||||
|
||||
**Traceability:** SR-OTA-006
|
||||
|
||||
**SWR-OTA-007:** The software SHALL validate the integrity of received firmware images before activation.
|
||||
|
||||
**Traceability:** SR-OTA-007
|
||||
|
||||
**SWR-OTA-008:** The software SHALL reject firmware images that fail integrity validation.
|
||||
|
||||
**Traceability:** SR-OTA-008
|
||||
|
||||
**SWR-OTA-009:** The software SHALL report firmware validation and OTA status to the Main Hub.
|
||||
|
||||
**Traceability:** SR-OTA-009
|
||||
|
||||
**SWR-OTA-010:** The software SHALL execute a controlled teardown procedure prior to firmware activation.
|
||||
|
||||
**Traceability:** SR-OTA-010, SR-SYS-004
|
||||
|
||||
**SWR-OTA-011:** The software SHALL persist critical runtime data and calibration data before flashing new firmware.
|
||||
|
||||
**Traceability:** SR-OTA-011, SR-SYS-005
|
||||
|
||||
**SWR-OTA-012:** The software SHALL activate new firmware only after successful integrity validation.
|
||||
|
||||
**Traceability:** SR-OTA-012
|
||||
|
||||
**SWR-OTA-013:** The software SHALL reboot into the new firmware after successful activation.
|
||||
|
||||
**Traceability:** SR-OTA-013
|
||||
|
||||
**SWR-OTA-014:** The software SHALL use encrypted and authenticated communication channels for OTA firmware updates.
|
||||
|
||||
**Traceability:** SR-SEC-011, CFC-SEC-02
|
||||
|
||||
**SWR-OTA-015:** The software SHALL transition to OTA_PREP state upon accepting an OTA request.
|
||||
|
||||
**Traceability:** System State Machine Specification
|
||||
|
||||
**SWR-OTA-016:** The software SHALL NOT allow OTA operations during WARNING, FAULT, SERVICE, or SD_DEGRADED states.
|
||||
|
||||
**Traceability:** System State Machine Specification, CFC-ARCH-02
|
||||
|
||||
**SWR-OTA-017:** The software SHALL complete OTA operations within a maximum duration of 10 minutes.
|
||||
|
||||
**Traceability:** Quality requirement
|
||||
|
||||
**SWR-OTA-018:** The software SHALL handle OTA failures by transitioning to FAULT state and reporting the failure.
|
||||
|
||||
**Traceability:** System State Machine Specification, Failure Handling Model
|
||||
|
||||
**SWR-OTA-019:** The software SHALL protect active firmware from corruption during OTA operations.
|
||||
|
||||
**Traceability:** SR-OTA-006
|
||||
|
||||
**SWR-OTA-020:** The software SHALL verify firmware authenticity using secure boot mechanisms before execution.
|
||||
|
||||
**Traceability:** SR-SEC-001, SR-SEC-002
|
||||
|
||||
#### 3.1.8 Security & Safety (SWR-SEC-001 through SWR-SEC-020)
|
||||
|
||||
**SWR-SEC-001:** The software SHALL verify the authenticity of the firmware image before execution during every boot cycle.
|
||||
|
||||
**Traceability:** SR-SEC-001, CFC-SEC-01
|
||||
|
||||
**SWR-SEC-002:** The software SHALL prevent execution of firmware images that fail cryptographic verification.
|
||||
|
||||
**Traceability:** SR-SEC-002
|
||||
|
||||
**SWR-SEC-003:** The software SHALL enter BOOT_FAILURE state when secure boot verification fails.
|
||||
|
||||
**Traceability:** SR-SEC-003, System State Machine Specification
|
||||
|
||||
**SWR-SEC-004:** The software SHALL protect the root-of-trust against unauthorized modification.
|
||||
|
||||
**Traceability:** SR-SEC-004
|
||||
|
||||
**SWR-SEC-005:** The software SHALL protect sensitive data stored in internal flash memory from unauthorized access.
|
||||
|
||||
**Traceability:** SR-SEC-005
|
||||
|
||||
**SWR-SEC-006:** The software SHALL support encryption of sensitive data stored in external storage devices.
|
||||
|
||||
**Traceability:** SR-SEC-006
|
||||
|
||||
**SWR-SEC-007:** The software SHALL restrict access to cryptographic keys to authorized system components only.
|
||||
|
||||
**Traceability:** SR-SEC-007
|
||||
|
||||
**SWR-SEC-008:** The software SHALL ensure integrity of stored configuration, calibration, and machine constant data.
|
||||
|
||||
**Traceability:** SR-SEC-008
|
||||
|
||||
**SWR-SEC-009:** The software SHALL encrypt all communication with the Main Hub.
|
||||
|
||||
**Traceability:** SR-SEC-009, CFC-SEC-02
|
||||
|
||||
**SWR-SEC-010:** The software SHALL ensure integrity and authenticity of all transmitted and received messages.
|
||||
|
||||
**Traceability:** SR-SEC-010
|
||||
|
||||
**SWR-SEC-011:** The software SHALL use encrypted and authenticated communication channels for OTA firmware updates.
|
||||
|
||||
**Traceability:** SR-SEC-011, CFC-SEC-02
|
||||
|
||||
**SWR-SEC-012:** The software SHALL detect and report communication and security violations to the Main Hub.
|
||||
|
||||
**Traceability:** SR-SEC-012
|
||||
|
||||
**SWR-SEC-013:** The software SHALL enable secure boot and flash protection before any application-level logic executes.
|
||||
|
||||
**Traceability:** CFC-SEC-01
|
||||
|
||||
**SWR-SEC-014:** The software SHALL authenticate debug sessions before allowing debug operations.
|
||||
|
||||
**Traceability:** SR-SYS-013, CFC-DBG-01
|
||||
|
||||
**SWR-SEC-015:** The software SHALL NOT allow debug sessions to bypass security or safety mechanisms.
|
||||
|
||||
**Traceability:** CFC-DBG-01
|
||||
|
||||
**SWR-SEC-016:** The software SHALL report security violations as FATAL diagnostic events.
|
||||
|
||||
**Traceability:** Failure Handling Model
|
||||
|
||||
**SWR-SEC-017:** The software SHALL protect cryptographic keys during power loss and system resets.
|
||||
|
||||
**Traceability:** Quality requirement
|
||||
|
||||
**SWR-SEC-018:** The software SHALL implement secure session establishment for all external communication.
|
||||
|
||||
**Traceability:** SR-SEC-009
|
||||
|
||||
**SWR-SEC-019:** The software SHALL validate message integrity on every received message.
|
||||
|
||||
**Traceability:** SR-SEC-010
|
||||
|
||||
**SWR-SEC-020:** The software SHALL prevent downgrade attacks by verifying firmware version integrity.
|
||||
|
||||
**Traceability:** Quality requirement
|
||||
|
||||
### 3.2 Interface Requirements
|
||||
|
||||
#### 3.2.1 External Interfaces
|
||||
|
||||
**SWR-IF-001:** The software SHALL provide a communication interface to the Main Hub supporting bidirectional data exchange.
|
||||
|
||||
**Traceability:** SR-COM-001
|
||||
|
||||
**SWR-IF-002:** The software SHALL provide sensor interfaces supporting I2C, SPI, UART, and analog protocols.
|
||||
|
||||
**Traceability:** Architecture requirement
|
||||
|
||||
**SWR-IF-003:** The software SHALL provide an I2C interface for OLED display communication.
|
||||
|
||||
**Traceability:** SR-SYS-007
|
||||
|
||||
**SWR-IF-004:** The software SHALL provide GPIO interfaces for button inputs (Up, Down, Select).
|
||||
|
||||
**Traceability:** SR-SYS-009
|
||||
|
||||
**SWR-IF-005:** The software SHALL provide storage interfaces for SD card and NVM access.
|
||||
|
||||
**Traceability:** Architecture requirement
|
||||
|
||||
**SWR-IF-006:** The software SHALL provide a debug interface (UART/USB) for diagnostic and debug sessions.
|
||||
|
||||
**Traceability:** SR-SYS-011, SR-SYS-012
|
||||
|
||||
#### 3.2.2 Internal Interfaces
|
||||
|
||||
**SWR-IF-007:** The software SHALL provide an Event System interface for cross-component communication.
|
||||
|
||||
**Traceability:** Architecture requirement
|
||||
|
||||
**SWR-IF-008:** The software SHALL provide a Data Pool interface for runtime data access.
|
||||
|
||||
**Traceability:** Architecture requirement
|
||||
|
||||
**SWR-IF-009:** The software SHALL provide a Data Persistence (DP) component interface for persistent storage access.
|
||||
|
||||
**Traceability:** SR-DATA-004, CFC-ARCH-01
|
||||
|
||||
**SWR-IF-010:** The software SHALL provide a System State Manager interface for state queries and transitions.
|
||||
|
||||
**Traceability:** SR-SYS-001
|
||||
|
||||
**SWR-IF-011:** The software SHALL provide a Diagnostics interface for fault reporting and querying.
|
||||
|
||||
**Traceability:** SR-DIAG-001
|
||||
|
||||
**SWR-IF-012:** The software SHALL provide an Error Handler interface for fault classification and escalation.
|
||||
|
||||
**Traceability:** Failure Handling Model
|
||||
|
||||
### 3.3 Performance Requirements
|
||||
|
||||
**SWR-PERF-001:** The software SHALL complete sensor acquisition cycles within 100ms per sensor.
|
||||
|
||||
**Traceability:** SR-DAQ-007, CFC-TIME-02
|
||||
|
||||
**SWR-PERF-002:** The software SHALL complete state transitions within 50ms (except INIT → RUNNING: 5s, TEARDOWN: 500ms).
|
||||
|
||||
**Traceability:** System State Machine Specification
|
||||
|
||||
**SWR-PERF-003:** The software SHALL complete data persistence operations within 200ms.
|
||||
|
||||
**Traceability:** Quality requirement
|
||||
|
||||
**SWR-PERF-004:** The software SHALL complete OTA operations within 10 minutes.
|
||||
|
||||
**Traceability:** SWR-OTA-017
|
||||
|
||||
**SWR-PERF-005:** The software SHALL maintain CPU utilization below 80% during normal operation.
|
||||
|
||||
**Traceability:** Quality requirement
|
||||
|
||||
**SWR-PERF-006:** The software SHALL maintain RAM usage below 60% of available memory.
|
||||
|
||||
**Traceability:** Quality requirement
|
||||
|
||||
**SWR-PERF-007:** The software SHALL respond to Main Hub data requests within 100ms.
|
||||
|
||||
**Traceability:** SR-COM-005, SR-COM-006
|
||||
|
||||
**SWR-PERF-008:** The software SHALL detect communication link failures within 30 seconds.
|
||||
|
||||
**Traceability:** SR-COM-004
|
||||
|
||||
### 3.4 Design Constraints
|
||||
|
||||
**SWR-DESIGN-001:** The software SHALL NOT use dynamic memory allocation in sensor acquisition paths.
|
||||
|
||||
**Traceability:** CFC-TIME-02
|
||||
|
||||
**SWR-DESIGN-002:** The software SHALL implement all features as non-blocking operations.
|
||||
|
||||
**Traceability:** CFC-TIME-01
|
||||
|
||||
**SWR-DESIGN-003:** The software SHALL access hardware only through driver and OSAL layers.
|
||||
|
||||
**Traceability:** CFC-ARCH-01
|
||||
|
||||
**SWR-DESIGN-004:** The software SHALL access persistent storage only through the DP component.
|
||||
|
||||
**Traceability:** CFC-ARCH-01, CFC-DATA-01
|
||||
|
||||
**SWR-DESIGN-005:** The software SHALL respect system state restrictions for all operations.
|
||||
|
||||
**Traceability:** CFC-ARCH-02
|
||||
|
||||
**SWR-DESIGN-006:** The software SHALL use the Event System for all cross-component communication.
|
||||
|
||||
**Traceability:** Architecture requirement
|
||||
|
||||
### 3.5 Quality Attributes
|
||||
|
||||
**SWR-QUAL-001:** The software SHALL recover gracefully from power interruptions (< 1 second).
|
||||
|
||||
**Traceability:** System Assumptions
|
||||
|
||||
**SWR-QUAL-002:** The software SHALL handle SD card failures without system failure.
|
||||
|
||||
**Traceability:** System Limitations
|
||||
|
||||
**SWR-QUAL-003:** The software SHALL maintain data integrity during firmware updates.
|
||||
|
||||
**Traceability:** SR-DATA-008
|
||||
|
||||
**SWR-QUAL-004:** The software SHALL prevent unauthorized firmware execution.
|
||||
|
||||
**Traceability:** SR-SEC-001, SR-SEC-002
|
||||
|
||||
**SWR-QUAL-005:** The software SHALL provide deterministic behavior under all operational conditions.
|
||||
|
||||
**Traceability:** CFC-TIME-02
|
||||
|
||||
## 4. Annexes
|
||||
|
||||
See separate annex documents:
|
||||
- **Annex A:** Software Requirements Traceability Matrix (`Annex_A_Traceability.md`)
|
||||
- **Annex B:** External Interface Specifications (`Annex_B_Interfaces.md`)
|
||||
- **Annex C:** Timing and Resource Budgets (`Annex_C_Budgets.md`)
|
||||
168
system_design/SRS/Traceability_SWRS.csv
Normal file
168
system_design/SRS/Traceability_SWRS.csv
Normal file
@@ -0,0 +1,168 @@
|
||||
SWR_ID,Type,Status,Title,Description,SR_ID,Feature_ID,Component,Test_ID
|
||||
SWR-SYS-001,Software Requirement,Specified,FSM Implementation,The software SHALL implement a finite state machine (FSM) with the following states: INIT, BOOT_FAILURE, RUNNING, WARNING, FAULT, OTA_PREP, OTA_UPDATE, MC_UPDATE, TEARDOWN, SERVICE, SD_DEGRADED.,SR-SYS-001,F-SYS-01,STM,T-SYS-001
|
||||
SWR-SYS-002,Software Requirement,Specified,FSM Transition Enforcement,The software SHALL enforce valid state transitions as defined in the System State Machine Specification.,SR-SYS-001,F-SYS-01,STM,T-SYS-002
|
||||
SWR-SYS-003,Software Requirement,Specified,State-Based Operation Restriction,The software SHALL restrict feature operations based on the current system state according to per-state execution rules.,SR-SYS-002,F-SYS-01,STM,T-SYS-003
|
||||
SWR-SYS-004,Software Requirement,Specified,State Transition Notification,The software SHALL notify all registered components when a state transition occurs via the Event System.,SR-SYS-003,F-SYS-01,"STM, Event System",T-SYS-004
|
||||
SWR-SYS-005,Software Requirement,Specified,Controlled Teardown Execution,The software SHALL execute a controlled teardown sequence before firmware updates, machine constant updates, or system resets.,SR-SYS-004,F-SYS-02,STM,T-SYS-005
|
||||
SWR-SYS-006,Software Requirement,Specified,Critical Data Persistence Before Teardown,The software SHALL persist all critical runtime data before completing a teardown sequence.,SR-SYS-005,F-SYS-02,"STM, Persistence",T-SYS-006
|
||||
SWR-SYS-007,Software Requirement,Specified,Data Integrity Protection During Shutdown,The software SHALL prevent data corruption during teardown and reset operations.,SR-SYS-006,F-SYS-02,"STM, Persistence",T-SYS-007
|
||||
SWR-SYS-008,Software Requirement,Specified,OLED Display Interface,The software SHALL provide a local OLED display interface using I2C communication protocol.,SR-SYS-007,F-SYS-03,HMI,T-SYS-008
|
||||
SWR-SYS-009,Software Requirement,Specified,System Information Display,The software SHALL display connectivity status, system state, connected sensor summary, and time/date on the OLED display.,SR-SYS-008,F-SYS-03,HMI,T-SYS-009
|
||||
SWR-SYS-010,Software Requirement,Specified,Button-Based Menu Navigation,The software SHALL provide menu navigation using Up, Down, and Select buttons.,SR-SYS-009,F-SYS-03,HMI,T-SYS-010
|
||||
SWR-SYS-011,Software Requirement,Specified,Local Diagnostic and Health Menus,The software SHALL provide diagnostic, sensor, and health information through the local OLED menu interface.,SR-SYS-010,F-SYS-03,"HMI, Diagnostics",T-SYS-011
|
||||
SWR-SYS-012,Software Requirement,Specified,Diagnostic Session Support,The software SHALL support diagnostic sessions for retrieving system status and diagnostic data.,SR-SYS-011,F-SYS-04,Debug Session Manager,T-SYS-012
|
||||
SWR-SYS-013,Software Requirement,Specified,Debug Session Support,The software SHALL support debug sessions allowing controlled engineering commands.,SR-SYS-012,F-SYS-04,Debug Session Manager,T-SYS-013
|
||||
SWR-SYS-014,Software Requirement,Specified,Authorized Debug Access Control,The software SHALL restrict debug session actions to authorized engineering access only.,SR-SYS-013,F-SYS-04,"Debug Session Manager, Security",T-SYS-014
|
||||
SWR-SYS-015,Software Requirement,Specified,Non-Intrusive Debug Sessions,The software SHALL ensure debug sessions do not interfere with normal sensor acquisition or communication operations.,SR-SYS-013,F-SYS-04,Debug Session Manager,T-SYS-015
|
||||
SWR-DAQ-001,Software Requirement,Specified,Multi-Sensor Environmental Data Acquisition,The software SHALL support simultaneous acquisition of environmental data from multiple sensor types (temperature, humidity, CO2, NH3, VOC, particulate matter, light).,SR-DAQ-001,F-DAQ-01,Sensor Manager,T-DAQ-001
|
||||
SWR-DAQ-002,Software Requirement,Specified,Dedicated Sensor Slot Mapping,The software SHALL assign each supported sensor type to a predefined and unique hardware slot.,SR-DAQ-002,F-DAQ-01,Sensor Manager,T-DAQ-002
|
||||
SWR-DAQ-003,Software Requirement,Specified,Sensor Presence Detection,The software SHALL detect the physical presence of each sensor via a dedicated hardware detection signal prior to sensor initialization.,SR-DAQ-003,F-DAQ-01,"Sensor Manager, Sensor Drivers",T-DAQ-003
|
||||
SWR-DAQ-004,Software Requirement,Specified,Conditional Sensor Initialization,The software SHALL initialize and activate only sensors that are detected as present and enabled.,SR-DAQ-004,F-DAQ-01,Sensor Manager,T-DAQ-004
|
||||
SWR-DAQ-005,Software Requirement,Specified,High-Frequency Sensor Sampling,The software SHALL sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples per sensor per cycle).,SR-DAQ-005,F-DAQ-02,Sensor Manager,T-DAQ-005
|
||||
SWR-DAQ-006,Software Requirement,Specified,Local Sensor Data Filtering,The software SHALL apply a local filtering mechanism to raw sensor samples to produce a single filtered sensor value per acquisition cycle.,SR-DAQ-006,F-DAQ-02,Sensor Manager,T-DAQ-006
|
||||
SWR-DAQ-007,Software Requirement,Specified,Deterministic Sampling Window,The software SHALL complete each sensor's sampling and filtering process within a bounded and deterministic time window (maximum 100ms per sensor).,SR-DAQ-007,F-DAQ-02,Sensor Manager,T-DAQ-007
|
||||
SWR-DAQ-008,Software Requirement,Specified,Timestamp Generation for Sensor Data,The software SHALL generate a timestamp for each filtered sensor value upon completion of the acquisition and filtering process.,SR-DAQ-008,F-DAQ-03,"Sensor Manager, Time Utils",T-DAQ-008
|
||||
SWR-DAQ-009,Software Requirement,Specified,Timestamped Sensor Data Record Structure,The software SHALL generate a timestamped sensor data record containing at minimum: sensor identifier, sensor type, filtered value, unit of measurement, timestamp, and data validity status.,SR-DAQ-009,F-DAQ-03,Sensor Manager,T-DAQ-009
|
||||
SWR-DAQ-010,Software Requirement,Specified,Availability of Latest Sensor Data,The software SHALL maintain the most recent timestamped sensor data record in memory and make it available for persistence and on-demand communication requests.,SR-DAQ-010,F-DAQ-03,"Sensor Manager, Data Pool",T-DAQ-010
|
||||
SWR-DAQ-011,Software Requirement,Specified,State-Restricted Sensor Acquisition,The software SHALL NOT perform sensor acquisition during OTA_UPDATE, MC_UPDATE, or TEARDOWN states.,CFC-ARCH-02,F-DAQ-01,Sensor Manager,T-DAQ-011
|
||||
SWR-DAQ-012,Software Requirement,Specified,Non-Blocking Sensor Acquisition,The software SHALL perform sensor acquisition in a non-blocking manner.,CFC-TIME-01,F-DAQ-02,Sensor Manager,T-DAQ-012
|
||||
SWR-DAQ-013,Software Requirement,Specified,Deterministic Memory Allocation,The software SHALL use deterministic memory allocation for sensor acquisition buffers (no dynamic allocation in acquisition path).,CFC-TIME-02,F-DAQ-02,Sensor Manager,T-DAQ-013
|
||||
SWR-DAQ-014,Software Requirement,Specified,Sensor Data Event Publishing,The software SHALL publish sensor data updates via the Event System upon completion of each acquisition cycle.,Architecture Requirement,F-DAQ-03,"Sensor Manager, Event System",T-DAQ-014
|
||||
SWR-DAQ-015,Software Requirement,Specified,Failed Sensor Exclusion,The software SHALL exclude failed sensors from acquisition cycles as defined by the failure handling model.,SR-DQC-009,F-DAQ-01,Sensor Manager,T-DAQ-015
|
||||
SWR-DQC-001,Software Requirement,Specified,Detect Sensor Presence,The software SHALL detect the physical presence of each sensor using a dedicated hardware-based detection mechanism.,SR-DQC-001,F-DQC-01,"Sensor Manager, Sensor Drivers",T-DQC-001
|
||||
SWR-DQC-002,Software Requirement,Specified,Perform Sensor Detection During Initialization,The software SHALL perform sensor presence detection during system startup and after any reinitialization or reconfiguration event.,SR-DQC-002,F-DQC-01,Sensor Manager,T-DQC-002
|
||||
SWR-DQC-003,Software Requirement,Specified,Conditional Sensor Initialization,The software SHALL initialize and activate only sensors that are detected as present.,SR-DQC-003,F-DQC-01,Sensor Manager,T-DQC-003
|
||||
SWR-DQC-004,Software Requirement,Specified,Assign Fixed Sensor Slot Types,The software SHALL assign each physical sensor slot to a predefined sensor type.,SR-DQC-004,F-DQC-02,Sensor Manager,T-DQC-004
|
||||
SWR-DQC-005,Software Requirement,Specified,Verify Sensor Type Compatibility,The software SHALL verify that a detected sensor matches the expected sensor type for its assigned slot.,SR-DQC-005,F-DQC-02,Sensor Manager,T-DQC-005
|
||||
SWR-DQC-006,Software Requirement,Specified,Reject Invalid Sensor Configurations,The software SHALL reject and report any sensor-slot mismatch as a diagnostic event.,SR-DQC-006,F-DQC-02,"Sensor Manager, Diagnostics",T-DQC-006
|
||||
SWR-DQC-007,Software Requirement,Specified,Monitor Sensor Health,The software SHALL continuously monitor sensor responsiveness and signal validity during normal operation.,SR-DQC-007,F-DQC-03,Sensor Manager,T-DQC-007
|
||||
SWR-DQC-008,Software Requirement,Specified,Detect Sensor Failure Conditions,The software SHALL detect sensor failures including disconnection, non-responsiveness, and out-of-range measurement values.,SR-DQC-008,F-DQC-03,Sensor Manager,T-DQC-008
|
||||
SWR-DQC-009,Software Requirement,Specified,Isolate Failed Sensors,The software SHALL mark detected faulty sensors as defective and exclude them from data acquisition and reporting.,SR-DQC-009,F-DQC-03,Sensor Manager,T-DQC-009
|
||||
SWR-DQC-010,Software Requirement,Specified,Report Sensor Failures,The software SHALL report detected sensor failures to the Main Hub with timestamps and failure classification.,SR-DQC-010,F-DQC-03,"Sensor Manager, Communication",T-DQC-010
|
||||
SWR-DQC-011,Software Requirement,Specified,Maintain Machine Constants Dataset,The software SHALL maintain a Machine Constants dataset defining sensor configuration, calibration parameters, and communication identifiers.,SR-DQC-011,F-DQC-04,Machine Constant Manager,T-DQC-011
|
||||
SWR-DQC-012,Software Requirement,Specified,Persist Machine Constants,The software SHALL store the Machine Constants dataset in non-volatile storage.,SR-DQC-012,F-DQC-04,"Machine Constant Manager, Persistence",T-DQC-012
|
||||
SWR-DQC-013,Software Requirement,Specified,Load Machine Constants at Startup,The software SHALL load and apply the Machine Constants dataset during system initialization.,SR-DQC-013,F-DQC-04,Machine Constant Manager,T-DQC-013
|
||||
SWR-DQC-014,Software Requirement,Specified,Support Remote Machine Constants Update,The software SHALL support remote updates of the Machine Constants dataset initiated by the Main Hub.,SR-DQC-014,F-DQC-04,"Machine Constant Manager, Communication",T-DQC-014
|
||||
SWR-DQC-015,Software Requirement,Specified,Controlled Reinitialization After Update,The software SHALL apply updated Machine Constants only after executing a controlled teardown and reinitialization procedure.,SR-DQC-015,F-DQC-04,"Machine Constant Manager, STM",T-DQC-015
|
||||
SWR-DQC-016,Software Requirement,Specified,Machine Constants Integrity Validation,The software SHALL validate Machine Constants integrity before applying updates.,SR-SEC-008,F-DQC-04,"Machine Constant Manager, Security",T-DQC-016
|
||||
SWR-DQC-017,Software Requirement,Specified,State-Restricted Calibration,The software SHALL NOT perform sensor calibration during OTA_UPDATE, MC_UPDATE, or TEARDOWN states.,CFC-ARCH-02,F-DQC-04,Sensor Manager,T-DQC-017
|
||||
SWR-DQC-018,Software Requirement,Specified,Machine Constants Access via DP,The software SHALL access Machine Constants only through the DP component.,CFC-ARCH-01,F-DQC-04,"Machine Constant Manager, Persistence",T-DQC-018
|
||||
SWR-COM-001,Software Requirement,Specified,Bidirectional Main Hub Communication,The software SHALL support bidirectional communication between the Sensor Hub and the Main Hub.,SR-COM-001,F-COM-01,"Main Hub APIs, Network Stack",T-COM-001
|
||||
SWR-COM-002,Software Requirement,Specified,Transmit Data to Main Hub,The software SHALL transmit sensor data, diagnostics information, and system status to the Main Hub.,SR-COM-002,F-COM-01,Main Hub APIs,T-COM-002
|
||||
SWR-COM-003,Software Requirement,Specified,Receive Commands from Main Hub,The software SHALL receive commands, configuration updates, and firmware update requests from the Main Hub.,SR-COM-003,F-COM-01,Main Hub APIs,T-COM-003
|
||||
SWR-COM-004,Software Requirement,Specified,Monitor Communication Link Status,The software SHALL monitor the status of the communication link with the Main Hub and report link availability and failure conditions.,SR-COM-004,F-COM-01,Network Stack,T-COM-004
|
||||
SWR-COM-005,Software Requirement,Specified,Support On-Demand Data Requests,The software SHALL support on-demand requests from the Main Hub for sensor data.,SR-COM-005,F-COM-02,Main Hub APIs,T-COM-005
|
||||
SWR-COM-006,Software Requirement,Specified,Respond with Latest Sensor Data,The software SHALL respond to on-demand data requests with the most recent timestamped sensor data.,SR-COM-006,F-COM-02,"Main Hub APIs, Data Pool",T-COM-006
|
||||
SWR-COM-007,Software Requirement,Specified,Include Data Validity in Responses,The software SHALL include sensor status and data validity information in on-demand data responses.,SR-COM-007,F-COM-02,Main Hub APIs,T-COM-007
|
||||
SWR-COM-008,Software Requirement,Specified,Support Peer Sensor Hub Communication,The software SHALL support limited peer-to-peer communication between Sensor Hubs for connectivity checks and time synchronization.,SR-COM-008,F-COM-03,Network Stack,T-COM-008
|
||||
SWR-COM-009,Software Requirement,Specified,Isolate Peer Communication,The software SHALL ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations.,SR-COM-010,F-COM-03,Network Stack,T-COM-009
|
||||
SWR-COM-010,Software Requirement,Specified,Encrypted Main Hub Communication,The software SHALL encrypt all communication with the Main Hub using authenticated encryption.,SR-SEC-009,F-COM-01,"Network Stack, Security",T-COM-010
|
||||
SWR-COM-011,Software Requirement,Specified,Message Integrity and Authenticity,The software SHALL ensure integrity and authenticity of all transmitted and received messages.,SR-SEC-010,F-COM-01,"Network Stack, Security",T-COM-011
|
||||
SWR-COM-012,Software Requirement,Specified,State-Restricted Communication,The software SHALL limit communication operations during TEARDOWN state to session closure only.,CFC-ARCH-02,F-COM-01,Network Stack,T-COM-012
|
||||
SWR-COM-013,Software Requirement,Specified,Non-Blocking Communication,The software SHALL perform communication operations in a non-blocking manner.,CFC-TIME-01,F-COM-01,Network Stack,T-COM-013
|
||||
SWR-COM-014,Software Requirement,Specified,Communication Link Failure Reporting,The software SHALL report communication link failures as diagnostic events according to the failure handling model.,SR-COM-004,F-COM-01,"Network Stack, Diagnostics",T-COM-014
|
||||
SWR-COM-015,Software Requirement,Specified,Security Violation Reporting,The software SHALL detect and report communication security violations to the Main Hub.,SR-SEC-012,F-COM-01,"Network Stack, Security",T-COM-015
|
||||
SWR-DIAG-001,Software Requirement,Specified,Diagnostic Code Framework,The software SHALL implement a diagnostic code framework for reporting system health conditions, warnings, errors, and fatal faults.,SR-DIAG-001,F-DIAG-01,Diagnostics Task,T-DIAG-001
|
||||
SWR-DIAG-002,Software Requirement,Specified,Assign Unique Diagnostic Codes,The software SHALL assign a unique diagnostic code to each detected fault or abnormal condition.,SR-DIAG-002,F-DIAG-01,Diagnostics Task,T-DIAG-002
|
||||
SWR-DIAG-003,Software Requirement,Specified,Classify Diagnostic Severity,The software SHALL classify diagnostic codes by severity level (INFO, WARNING, ERROR, FATAL).,SR-DIAG-003,F-DIAG-01,Diagnostics Task,T-DIAG-003
|
||||
SWR-DIAG-004,Software Requirement,Specified,Timestamp and Source Diagnostics,The software SHALL associate each diagnostic event with a timestamp and the originating system component.,SR-DIAG-004,F-DIAG-01,Diagnostics Task,T-DIAG-004
|
||||
SWR-DIAG-005,Software Requirement,Specified,Persist Diagnostic Events,The software SHALL persist diagnostic events in non-volatile storage.,SR-DIAG-005,F-DIAG-02,"Diagnostics Task, Persistence",T-DIAG-005
|
||||
SWR-DIAG-006,Software Requirement,Specified,Retain Diagnostics Across Resets,The software SHALL retain diagnostic data across system resets and power cycles.,SR-DIAG-006,F-DIAG-02,"Diagnostics Task, Persistence",T-DIAG-006
|
||||
SWR-DIAG-007,Software Requirement,Specified,Bounded Diagnostic Storage,The software SHALL implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy.,SR-DIAG-007,F-DIAG-02,"Diagnostics Task, Persistence",T-DIAG-007
|
||||
SWR-DIAG-008,Software Requirement,Specified,Provide Diagnostic Session Interface,The software SHALL provide a diagnostic session interface for accessing diagnostic and system health data.,SR-DIAG-008,F-DIAG-03,Diagnostics Task,T-DIAG-008
|
||||
SWR-DIAG-009,Software Requirement,Specified,Retrieve Diagnostic Records,The software SHALL allow authorized diagnostic sessions to retrieve stored diagnostic events.,SR-DIAG-009,F-DIAG-03,Diagnostics Task,T-DIAG-009
|
||||
SWR-DIAG-010,Software Requirement,Specified,Clear Diagnostic Records,The software SHALL allow authorized diagnostic sessions to clear stored diagnostic records.,SR-DIAG-010,F-DIAG-03,Diagnostics Task,T-DIAG-010
|
||||
SWR-DIAG-011,Software Requirement,Specified,Non-Intrusive Diagnostic Sessions,The software SHALL ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations.,SR-DIAG-011,F-DIAG-03,Diagnostics Task,T-DIAG-011
|
||||
SWR-DIAG-012,Software Requirement,Specified,Fault-to-State Transition,The software SHALL trigger state transitions based on diagnostic severity according to the failure handling model.,Failure Handling Model,F-DIAG-01,"Diagnostics Task, Error Handler",T-DIAG-012
|
||||
SWR-DIAG-013,Software Requirement,Specified,Fault Latching Behavior,The software SHALL implement fault latching behavior as defined in the failure handling model.,Failure Handling Model,F-DIAG-01,Error Handler,T-DIAG-013
|
||||
SWR-DIAG-014,Software Requirement,Specified,Fault Escalation Rules,The software SHALL implement fault escalation rules as defined in the failure handling model.,Failure Handling Model,F-DIAG-01,Error Handler,T-DIAG-014
|
||||
SWR-DIAG-015,Software Requirement,Specified,Diagnostic Event Reporting to Main Hub,The software SHALL report WARNING, ERROR, and FATAL diagnostic events to the Main Hub.,SR-COM-002,F-DIAG-02,"Diagnostics Task, Communication",T-DIAG-015
|
||||
SWR-DIAG-016,Software Requirement,Specified,Diagnostic Information via HMI,The software SHALL provide diagnostic information through the local OLED menu interface.,SR-SYS-010,F-DIAG-03,"Diagnostics Task, HMI",T-DIAG-016
|
||||
SWR-DIAG-017,Software Requirement,Specified,Diagnostic Storage Access via DP,The software SHALL access diagnostic storage only through the DP component.,CFC-ARCH-01,F-DIAG-02,"Diagnostics Task, Persistence",T-DIAG-017
|
||||
SWR-DIAG-018,Software Requirement,Specified,State-Restricted Diagnostic Generation,The software SHALL NOT generate new diagnostic events during TEARDOWN state (except teardown-specific diagnostics).,CFC-ARCH-02,F-DIAG-01,Diagnostics Task,T-DIAG-018
|
||||
SWR-DATA-001,Software Requirement,Specified,Persistent Timestamped Sensor Data,The software SHALL persist timestamped sensor data in non-volatile storage.,SR-DATA-001,F-DATA-01,Persistence,T-DATA-001
|
||||
SWR-DATA-002,Software Requirement,Specified,Sensor Data Metadata Storage,The software SHALL store sensor data together with sensor identifiers, timestamps, and validity status.,SR-DATA-002,F-DATA-01,Persistence,T-DATA-002
|
||||
SWR-DATA-003,Software Requirement,Specified,Configurable Data Retention Policy,The software SHALL support configurable data retention and overwrite policies for persisted sensor data.,SR-DATA-003,F-DATA-01,Persistence,T-DATA-003
|
||||
SWR-DATA-004,Software Requirement,Specified,Data Persistence Component Interface,The software SHALL provide a Data Persistence (DP) component as the sole interface for persistent data access.,SR-DATA-004,F-DATA-02,Persistence,T-DATA-004
|
||||
SWR-DATA-005,Software Requirement,Specified,Storage Access Isolation,The software SHALL prevent application and feature modules from directly accessing storage hardware.,SR-DATA-005,F-DATA-02,Persistence,T-DATA-005
|
||||
SWR-DATA-006,Software Requirement,Specified,Structured Data Serialization,The DP component SHALL support serialization and deserialization of structured system data.,SR-DATA-006,F-DATA-02,Persistence,T-DATA-006
|
||||
SWR-DATA-007,Software Requirement,Specified,Data Flush Before Teardown,The software SHALL flush all critical runtime data to non-volatile storage before entering a controlled teardown or reset state.,SR-DATA-007,F-DATA-03,"Persistence, STM",T-DATA-007
|
||||
SWR-DATA-008,Software Requirement,Specified,Data Integrity During Updates,The software SHALL protect data integrity during firmware updates and machine constant updates.,SR-DATA-008,F-DATA-03,"Persistence, OTA Manager",T-DATA-008
|
||||
SWR-DATA-009,Software Requirement,Specified,Persistence Verification,The software SHALL verify successful data persistence before completing a system state transition.,SR-DATA-009,F-DATA-03,"Persistence, STM",T-DATA-009
|
||||
SWR-DATA-010,Software Requirement,Specified,State-Restricted Data Writes,The software SHALL NOT perform data write operations during TEARDOWN state unless explicitly authorized by the System Manager.,CFC-DATA-02,F-DATA-03,Persistence,T-DATA-010
|
||||
SWR-DATA-011,Software Requirement,Specified,Persistence Completion Confirmation,The software SHALL ensure persistence completion is confirmed before state transitions.,CFC-DATA-02,F-DATA-03,"Persistence, STM",T-DATA-011
|
||||
SWR-DATA-012,Software Requirement,Specified,SD Card Failure Handling,The software SHALL handle SD card failures gracefully by entering SD_DEGRADED state and disabling persistence writes.,System State Machine Specification,F-DATA-01,"Persistence, STM",T-DATA-012
|
||||
SWR-DATA-013,Software Requirement,Specified,Wear-Aware Storage Management,The software SHALL implement wear-aware storage management to prevent premature SD card failure.,Quality Requirement,F-DATA-01,Persistence,T-DATA-013
|
||||
SWR-DATA-014,Software Requirement,Specified,Single Source of Truth,The software SHALL maintain a single source of truth for runtime and persistent data through the DP component.,CFC-DATA-01,F-DATA-02,"Data Pool, Persistence",T-DATA-014
|
||||
SWR-DATA-015,Software Requirement,Specified,No Private Persistent Copies,The software SHALL NOT allow features to maintain private persistent copies of shared system data.,CFC-DATA-01,F-DATA-02,All Components,T-DATA-015
|
||||
SWR-OTA-001,Software Requirement,Specified,OTA Negotiation Support,The software SHALL support OTA update negotiation initiated by the Main Hub.,SR-OTA-001,F-OTA-01,OTA Manager,T-OTA-001
|
||||
SWR-OTA-002,Software Requirement,Specified,OTA Readiness Validation,The software SHALL verify internal readiness conditions before accepting an OTA update request.,SR-OTA-002,F-OTA-01,OTA Manager,T-OTA-002
|
||||
SWR-OTA-003,Software Requirement,Specified,OTA Acknowledgement,The software SHALL explicitly acknowledge or reject OTA update requests.,SR-OTA-003,F-OTA-01,OTA Manager,T-OTA-003
|
||||
SWR-OTA-004,Software Requirement,Specified,Firmware Reception,The software SHALL receive firmware images over the established communication interface.,SR-OTA-004,F-OTA-02,"OTA Manager, Network Stack",T-OTA-004
|
||||
SWR-OTA-005,Software Requirement,Specified,Firmware Temporary Storage,The software SHALL store received firmware images in non-volatile storage prior to validation.,SR-OTA-005,F-OTA-02,"OTA Manager, Persistence",T-OTA-005
|
||||
SWR-OTA-006,Software Requirement,Specified,Active Firmware Protection,The software SHALL prevent overwriting the active firmware during firmware reception.,SR-OTA-006,F-OTA-02,OTA Manager,T-OTA-006
|
||||
SWR-OTA-007,Software Requirement,Specified,Firmware Integrity Verification,The software SHALL validate the integrity of received firmware images before activation.,SR-OTA-007,F-OTA-03,"OTA Manager, Security",T-OTA-007
|
||||
SWR-OTA-008,Software Requirement,Specified,Firmware Rejection Handling,The software SHALL reject firmware images that fail integrity validation.,SR-OTA-008,F-OTA-03,OTA Manager,T-OTA-008
|
||||
SWR-OTA-009,Software Requirement,Specified,OTA Status Reporting,The software SHALL report firmware validation and OTA status to the Main Hub.,SR-OTA-009,F-OTA-03,"OTA Manager, Communication",T-OTA-009
|
||||
SWR-OTA-010,Software Requirement,Specified,OTA Teardown Execution,The software SHALL execute a controlled teardown procedure prior to firmware activation.,SR-OTA-010,F-OTA-04,"OTA Manager, STM",T-OTA-010
|
||||
SWR-OTA-011,Software Requirement,Specified,Data Persistence Before Flashing,The software SHALL persist critical runtime data and calibration data before flashing new firmware.,SR-OTA-011,F-OTA-04,"OTA Manager, Persistence",T-OTA-011
|
||||
SWR-OTA-012,Software Requirement,Specified,Controlled Firmware Activation,The software SHALL activate new firmware only after successful integrity validation.,SR-OTA-012,F-OTA-04,OTA Manager,T-OTA-012
|
||||
SWR-OTA-013,Software Requirement,Specified,OTA Reboot Execution,The software SHALL reboot into the new firmware after successful activation.,SR-OTA-013,F-OTA-04,OTA Manager,T-OTA-013
|
||||
SWR-OTA-014,Software Requirement,Specified,Encrypted OTA Communication,The software SHALL use encrypted and authenticated communication channels for OTA firmware updates.,SR-SEC-011,F-OTA-02,"OTA Manager, Security",T-OTA-014
|
||||
SWR-OTA-015,Software Requirement,Specified,OTA State Transition,The software SHALL transition to OTA_PREP state upon accepting an OTA request.,System State Machine Specification,F-OTA-01,"OTA Manager, STM",T-OTA-015
|
||||
SWR-OTA-016,Software Requirement,Specified,State-Restricted OTA Operations,The software SHALL NOT allow OTA operations during WARNING, FAULT, SERVICE, or SD_DEGRADED states.,System State Machine Specification,F-OTA-01,"OTA Manager, STM",T-OTA-016
|
||||
SWR-OTA-017,Software Requirement,Specified,OTA Duration Limit,The software SHALL complete OTA operations within a maximum duration of 10 minutes.,Quality Requirement,F-OTA-04,OTA Manager,T-OTA-017
|
||||
SWR-OTA-018,Software Requirement,Specified,OTA Failure Handling,The software SHALL handle OTA failures by transitioning to FAULT state and reporting the failure.,System State Machine Specification,F-OTA-04,"OTA Manager, STM",T-OTA-018
|
||||
SWR-OTA-019,Software Requirement,Specified,Active Firmware Corruption Protection,The software SHALL protect active firmware from corruption during OTA operations.,SR-OTA-006,F-OTA-02,OTA Manager,T-OTA-019
|
||||
SWR-OTA-020,Software Requirement,Specified,Firmware Authenticity Verification,The software SHALL verify firmware authenticity using secure boot mechanisms before execution.,SR-SEC-001,F-OTA-04,"OTA Manager, Security",T-OTA-020
|
||||
SWR-SEC-001,Software Requirement,Specified,Firmware Authenticity Verification,The software SHALL verify the authenticity of the firmware image before execution during every boot cycle.,SR-SEC-001,F-SEC-01,Security,T-SEC-001
|
||||
SWR-SEC-002,Software Requirement,Specified,Unauthorized Firmware Blocking,The software SHALL prevent execution of firmware images that fail cryptographic verification.,SR-SEC-002,F-SEC-01,Security,T-SEC-002
|
||||
SWR-SEC-003,Software Requirement,Specified,Secure Boot Failure Handling,The software SHALL enter BOOT_FAILURE state when secure boot verification fails.,SR-SEC-003,F-SEC-01,"Security, STM",T-SEC-003
|
||||
SWR-SEC-004,Software Requirement,Specified,Root-of-Trust Protection,The software SHALL protect the root-of-trust against unauthorized modification.,SR-SEC-004,F-SEC-01,Security,T-SEC-004
|
||||
SWR-SEC-005,Software Requirement,Specified,Flash Data Access Protection,The software SHALL protect sensitive data stored in internal flash memory from unauthorized access.,SR-SEC-005,F-SEC-02,Security,T-SEC-005
|
||||
SWR-SEC-006,Software Requirement,Specified,Encrypted External Storage,The software SHALL support encryption of sensitive data stored in external storage devices.,SR-SEC-006,F-SEC-02,"Security, Persistence",T-SEC-006
|
||||
SWR-SEC-007,Software Requirement,Specified,Cryptographic Key Isolation,The software SHALL restrict access to cryptographic keys to authorized system components only.,SR-SEC-007,F-SEC-02,Security,T-SEC-007
|
||||
SWR-SEC-008,Software Requirement,Specified,Stored Data Integrity Assurance,The software SHALL ensure integrity of stored configuration, calibration, and machine constant data.,SR-SEC-008,F-SEC-02,"Security, Persistence",T-SEC-008
|
||||
SWR-SEC-009,Software Requirement,Specified,Encrypted Main Hub Communication,The software SHALL encrypt all communication with the Main Hub.,SR-SEC-009,F-SEC-03,"Network Stack, Security",T-SEC-009
|
||||
SWR-SEC-010,Software Requirement,Specified,Message Integrity and Authenticity,The software SHALL ensure integrity and authenticity of all transmitted and received messages.,SR-SEC-010,F-SEC-03,"Network Stack, Security",T-SEC-010
|
||||
SWR-SEC-011,Software Requirement,Specified,Secure OTA Data Transfer,The software SHALL use encrypted and authenticated communication channels for OTA firmware updates.,SR-SEC-011,F-SEC-03,"OTA Manager, Security",T-SEC-011
|
||||
SWR-SEC-012,Software Requirement,Specified,Security Violation Reporting,The software SHALL detect and report communication and security violations to the Main Hub.,SR-SEC-012,F-SEC-03,"Security, Communication",T-SEC-012
|
||||
SWR-SEC-013,Software Requirement,Specified,Security First Initialization,The software SHALL enable secure boot and flash protection before any application-level logic executes.,CFC-SEC-01,F-SEC-01,Security,T-SEC-013
|
||||
SWR-SEC-014,Software Requirement,Specified,Debug Session Authentication,The software SHALL authenticate debug sessions before allowing debug operations.,SR-SYS-013,F-SEC-03,"Security, Debug Session Manager",T-SEC-014
|
||||
SWR-SEC-015,Software Requirement,Specified,Debug Security Bypass Prevention,The software SHALL NOT allow debug sessions to bypass security or safety mechanisms.,CFC-DBG-01,F-SEC-03,"Security, Debug Session Manager",T-SEC-015
|
||||
SWR-SEC-016,Software Requirement,Specified,Security Violation Diagnostic Reporting,The software SHALL report security violations as FATAL diagnostic events.,Failure Handling Model,F-SEC-01,"Security, Diagnostics",T-SEC-016
|
||||
SWR-SEC-017,Software Requirement,Specified,Cryptographic Key Protection,The software SHALL protect cryptographic keys during power loss and system resets.,Quality Requirement,F-SEC-02,Security,T-SEC-017
|
||||
SWR-SEC-018,Software Requirement,Specified,Secure Session Establishment,The software SHALL implement secure session establishment for all external communication.,SR-SEC-009,F-SEC-03,"Network Stack, Security",T-SEC-018
|
||||
SWR-SEC-019,Software Requirement,Specified,Message Integrity Validation,The software SHALL validate message integrity on every received message.,SR-SEC-010,F-SEC-03,"Network Stack, Security",T-SEC-019
|
||||
SWR-SEC-020,Software Requirement,Specified,Downgrade Attack Prevention,The software SHALL prevent downgrade attacks by verifying firmware version integrity.,Quality Requirement,F-SEC-01,"Security, OTA Manager",T-SEC-020
|
||||
SWR-IF-001,Software Requirement,Specified,Main Hub Communication Interface,The software SHALL provide a communication interface to the Main Hub supporting bidirectional data exchange.,SR-COM-001,F-COM-01,"Main Hub APIs, Network Stack",T-IF-001
|
||||
SWR-IF-002,Software Requirement,Specified,Sensor Interfaces,The software SHALL provide sensor interfaces supporting I2C, SPI, UART, and analog protocols.,Architecture Requirement,F-DAQ-01,Sensor Drivers,T-IF-002
|
||||
SWR-IF-003,Software Requirement,Specified,OLED Display Interface,The software SHALL provide an I2C interface for OLED display communication.,SR-SYS-007,F-SYS-03,HMI,T-IF-003
|
||||
SWR-IF-004,Software Requirement,Specified,Button Input Interfaces,The software SHALL provide GPIO interfaces for button inputs (Up, Down, Select).,SR-SYS-009,F-SYS-03,HMI,T-IF-004
|
||||
SWR-IF-005,Software Requirement,Specified,Storage Interfaces,The software SHALL provide storage interfaces for SD card and NVM access.,Architecture Requirement,F-DATA-01,"SD Card Driver, NVM Driver",T-IF-005
|
||||
SWR-IF-006,Software Requirement,Specified,Debug Interface,The software SHALL provide a debug interface (UART/USB) for diagnostic and debug sessions.,SR-SYS-011,F-SYS-04,"Debug Session Manager, UART Driver",T-IF-006
|
||||
SWR-IF-007,Software Requirement,Specified,Event System Interface,The software SHALL provide an Event System interface for cross-component communication.,Architecture Requirement,All Features,Event System,T-IF-007
|
||||
SWR-IF-008,Software Requirement,Specified,Data Pool Interface,The software SHALL provide a Data Pool interface for runtime data access.,Architecture Requirement,All Features,Data Pool,T-IF-008
|
||||
SWR-IF-009,Software Requirement,Specified,Data Persistence Interface,The software SHALL provide a Data Persistence (DP) component interface for persistent storage access.,SR-DATA-004,F-DATA-02,Persistence,T-IF-009
|
||||
SWR-IF-010,Software Requirement,Specified,System State Manager Interface,The software SHALL provide a System State Manager interface for state queries and transitions.,SR-SYS-001,F-SYS-01,STM,T-IF-010
|
||||
SWR-IF-011,Software Requirement,Specified,Diagnostics Interface,The software SHALL provide a Diagnostics interface for fault reporting and querying.,SR-DIAG-001,F-DIAG-01,Diagnostics Task,T-IF-011
|
||||
SWR-IF-012,Software Requirement,Specified,Error Handler Interface,The software SHALL provide an Error Handler interface for fault classification and escalation.,Failure Handling Model,All Features,Error Handler,T-IF-012
|
||||
SWR-PERF-001,Software Requirement,Specified,Sensor Acquisition Cycle Timing,The software SHALL complete sensor acquisition cycles within 100ms per sensor.,SR-DAQ-007,Sensor Acquisition,Sensor Manager,T-PERF-001
|
||||
SWR-PERF-002,Software Requirement,Specified,State Transition Timing,The software SHALL complete state transitions within 50ms (except INIT → RUNNING: 5s, TEARDOWN: 500ms).,System State Machine Specification,State Management,STM,T-PERF-002
|
||||
SWR-PERF-003,Software Requirement,Specified,Data Persistence Timing,The software SHALL complete data persistence operations within 200ms.,Quality Requirement,Data Persistence,Persistence,T-PERF-003
|
||||
SWR-PERF-004,Software Requirement,Specified,OTA Operation Duration,The software SHALL complete OTA operations within 10 minutes.,SWR-OTA-017,Firmware Update,OTA Manager,T-PERF-004
|
||||
SWR-PERF-005,Software Requirement,Specified,CPU Utilization Limit,The software SHALL maintain CPU utilization below 80% during normal operation.,Quality Requirement,System Performance,All Components,T-PERF-005
|
||||
SWR-PERF-006,Software Requirement,Specified,RAM Usage Limit,The software SHALL maintain RAM usage below 60% of available memory.,Quality Requirement,System Performance,All Components,T-PERF-006
|
||||
SWR-PERF-007,Software Requirement,Specified,Main Hub Response Time,The software SHALL respond to Main Hub data requests within 100ms.,SR-COM-005,Communication,"Main Hub APIs, Data Pool",T-PERF-007
|
||||
SWR-PERF-008,Software Requirement,Specified,Communication Link Failure Detection,The software SHALL detect communication link failures within 30 seconds.,SR-COM-004,Communication,Network Stack,T-PERF-008
|
||||
SWR-DESIGN-001,Software Requirement,Specified,No Dynamic Memory in Acquisition Path,The software SHALL NOT use dynamic memory allocation in sensor acquisition paths.,CFC-TIME-02,Sensor Acquisition,Sensor Manager,T-DESIGN-001
|
||||
SWR-DESIGN-002,Software Requirement,Specified,Non-Blocking Operations,The software SHALL implement all features as non-blocking operations.,CFC-TIME-01,All Features,All Components,T-DESIGN-002
|
||||
SWR-DESIGN-003,Software Requirement,Specified,Hardware Access via Drivers,The software SHALL access hardware only through driver and OSAL layers.,CFC-ARCH-01,All Features,All Components,T-DESIGN-003
|
||||
SWR-DESIGN-004,Software Requirement,Specified,Storage Access via DP,The software SHALL access persistent storage only through the DP component.,CFC-ARCH-01,All Features,All Components,T-DESIGN-004
|
||||
SWR-DESIGN-005,Software Requirement,Specified,State-Aware Operations,The software SHALL respect system state restrictions for all operations.,CFC-ARCH-02,All Features,All Components,T-DESIGN-005
|
||||
SWR-DESIGN-006,Software Requirement,Specified,Event System Communication,The software SHALL use the Event System for all cross-component communication.,Architecture Requirement,All Features,All Components,T-DESIGN-006
|
||||
SWR-QUAL-001,Software Requirement,Specified,Power Interruption Recovery,The software SHALL recover gracefully from power interruptions (< 1 second).,System Assumptions,System Reliability,All Components,T-QUAL-001
|
||||
SWR-QUAL-002,Software Requirement,Specified,SD Card Failure Handling,The software SHALL handle SD card failures without system failure.,System Limitations,Data Persistence,"Persistence, STM",T-QUAL-002
|
||||
SWR-QUAL-003,Software Requirement,Specified,Data Integrity During Updates,The software SHALL maintain data integrity during firmware updates.,SR-DATA-008,Data Integrity,"OTA Manager, Persistence",T-QUAL-003
|
||||
SWR-QUAL-004,Software Requirement,Specified,Unauthorized Firmware Prevention,The software SHALL prevent unauthorized firmware execution.,SR-SEC-001,Security,"Security, OTA Manager",T-QUAL-004
|
||||
SWR-QUAL-005,Software Requirement,Specified,Deterministic Behavior,The software SHALL provide deterministic behavior under all operational conditions.,CFC-TIME-02,System Reliability,All Components,T-QUAL-005
|
||||
|
Can't render this file because it has a wrong number of fields in line 2.
|
231
system_design/SRS/VV_Matrix.md
Normal file
231
system_design/SRS/VV_Matrix.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# Verification & Validation Matrix
|
||||
|
||||
**Document:** SRS V&V Matrix
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
|
||||
## Purpose
|
||||
|
||||
This document maps Software Requirements (SWR-*) to verification methods (unit tests, integration tests, HIL tests) and defines acceptance criteria for each requirement.
|
||||
|
||||
## Verification Methods
|
||||
|
||||
| Method | Description | Scope |
|
||||
|--------|-------------|-------|
|
||||
| **UT** | Unit Test | Single component, isolated |
|
||||
| **IT** | Integration Test | Multiple components, interactions |
|
||||
| **HIL** | Hardware-In-the-Loop Test | Full system, real hardware |
|
||||
| **REV** | Review | Design/code review, static analysis |
|
||||
| **ANAL** | Analysis | Timing analysis, resource analysis |
|
||||
|
||||
## Acceptance Criteria Format
|
||||
|
||||
- **Pass:** Requirement satisfied
|
||||
- **Fail:** Requirement not satisfied
|
||||
- **N/A:** Not applicable for this verification method
|
||||
|
||||
## V&V Matrix
|
||||
|
||||
### System Management Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-SYS-001 | FSM Implementation | ✓ | ✓ | ✓ | ✓ | - | All 11 states implemented, transitions validated |
|
||||
| SWR-SYS-002 | State Transition Enforcement | ✓ | ✓ | ✓ | ✓ | - | Invalid transitions rejected, valid transitions succeed |
|
||||
| SWR-SYS-003 | State-Based Operation Restriction | ✓ | ✓ | ✓ | ✓ | - | Operations blocked in invalid states |
|
||||
| SWR-SYS-004 | State Transition Notification | ✓ | ✓ | ✓ | - | - | All listeners notified within 50ms |
|
||||
| SWR-SYS-005 | Controlled Teardown Execution | ✓ | ✓ | ✓ | ✓ | - | Teardown completes within 500ms |
|
||||
| SWR-SYS-006 | Critical Data Persistence Before Teardown | ✓ | ✓ | ✓ | ✓ | - | All critical data flushed before teardown complete |
|
||||
| SWR-SYS-007 | Data Integrity Protection During Shutdown | ✓ | ✓ | ✓ | ✓ | - | No data corruption during teardown/reset |
|
||||
| SWR-SYS-008 | OLED Display Interface | ✓ | ✓ | ✓ | ✓ | - | OLED displays correctly via I2C |
|
||||
| SWR-SYS-009 | System Information Display | ✓ | ✓ | ✓ | - | - | All required information displayed |
|
||||
| SWR-SYS-010 | Button-Based Menu Navigation | ✓ | ✓ | ✓ | - | - | Menu navigation works correctly |
|
||||
| SWR-SYS-011 | Local Diagnostic and Health Menus | ✓ | ✓ | ✓ | - | - | Diagnostic/health info accessible via menu |
|
||||
| SWR-SYS-012 | Diagnostic Session Support | ✓ | ✓ | ✓ | ✓ | - | Diagnostic sessions functional |
|
||||
| SWR-SYS-013 | Debug Session Support | ✓ | ✓ | ✓ | ✓ | - | Debug sessions functional |
|
||||
| SWR-SYS-014 | Authorized Debug Access Control | ✓ | ✓ | ✓ | ✓ | - | Unauthorized access rejected |
|
||||
| SWR-SYS-015 | Non-Intrusive Debug Sessions | ✓ | ✓ | ✓ | - | - | Debug sessions don't interfere with normal operation |
|
||||
|
||||
### Data Acquisition Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-DAQ-001 | Multi-Sensor Environmental Data Acquisition | ✓ | ✓ | ✓ | ✓ | - | All sensor types supported |
|
||||
| SWR-DAQ-002 | Dedicated Sensor Slot Mapping | ✓ | ✓ | ✓ | ✓ | - | Each sensor type mapped to unique slot |
|
||||
| SWR-DAQ-003 | Sensor Presence Detection | ✓ | ✓ | ✓ | - | - | Presence detection works correctly |
|
||||
| SWR-DAQ-004 | Conditional Sensor Initialization | ✓ | ✓ | ✓ | - | - | Only present sensors initialized |
|
||||
| SWR-DAQ-005 | High-Frequency Sensor Sampling | ✓ | ✓ | ✓ | ✓ | ✓ | 10 samples per cycle (default) |
|
||||
| SWR-DAQ-006 | Local Sensor Data Filtering | ✓ | ✓ | ✓ | ✓ | - | Filtering produces single value |
|
||||
| SWR-DAQ-007 | Deterministic Sampling Window | ✓ | ✓ | ✓ | ✓ | ✓ | Sampling completes within 100ms per sensor |
|
||||
| SWR-DAQ-008 | Timestamp Generation for Sensor Data | ✓ | ✓ | ✓ | - | - | Timestamps generated correctly |
|
||||
| SWR-DAQ-009 | Timestamped Sensor Data Record Structure | ✓ | ✓ | ✓ | ✓ | - | Record contains all required fields |
|
||||
| SWR-DAQ-010 | Availability of Latest Sensor Data | ✓ | ✓ | ✓ | - | - | Latest data available in memory |
|
||||
| SWR-DAQ-011 | State-Restricted Sensor Acquisition | ✓ | ✓ | ✓ | - | - | Acquisition blocked in OTA_UPDATE, MC_UPDATE, TEARDOWN |
|
||||
| SWR-DAQ-012 | Non-Blocking Sensor Acquisition | ✓ | ✓ | ✓ | ✓ | ✓ | No blocking operations in acquisition path |
|
||||
| SWR-DAQ-013 | Deterministic Memory Allocation | ✓ | ✓ | ✓ | ✓ | ✓ | No dynamic allocation in acquisition path |
|
||||
| SWR-DAQ-014 | Sensor Data Event Publishing | ✓ | ✓ | ✓ | - | - | Events published via Event System |
|
||||
| SWR-DAQ-015 | Failed Sensor Exclusion | ✓ | ✓ | ✓ | - | - | Failed sensors excluded from acquisition |
|
||||
|
||||
### Data Quality & Calibration Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-DQC-001 | Detect Sensor Presence | ✓ | ✓ | ✓ | - | - | Presence detection works correctly |
|
||||
| SWR-DQC-002 | Perform Sensor Detection During Initialization | ✓ | ✓ | ✓ | - | - | Detection performed during init |
|
||||
| SWR-DQC-003 | Conditional Sensor Initialization | ✓ | ✓ | ✓ | - | - | Only present sensors initialized |
|
||||
| SWR-DQC-004 | Assign Fixed Sensor Slot Types | ✓ | ✓ | ✓ | ✓ | - | Each slot assigned to sensor type |
|
||||
| SWR-DQC-005 | Verify Sensor Type Compatibility | ✓ | ✓ | ✓ | - | - | Sensor-slot compatibility verified |
|
||||
| SWR-DQC-006 | Reject Invalid Sensor Configurations | ✓ | ✓ | ✓ | - | - | Invalid configurations rejected and reported |
|
||||
| SWR-DQC-007 | Monitor Sensor Health | ✓ | ✓ | ✓ | - | - | Sensor health monitored continuously |
|
||||
| SWR-DQC-008 | Detect Sensor Failure Conditions | ✓ | ✓ | ✓ | - | - | All failure conditions detected |
|
||||
| SWR-DQC-009 | Isolate Failed Sensors | ✓ | ✓ | ✓ | - | - | Failed sensors marked and excluded |
|
||||
| SWR-DQC-010 | Report Sensor Failures | ✓ | ✓ | ✓ | - | - | Failures reported to Main Hub |
|
||||
| SWR-DQC-011 | Maintain Machine Constants Dataset | ✓ | ✓ | ✓ | ✓ | - | MC dataset maintained correctly |
|
||||
| SWR-DQC-012 | Persist Machine Constants | ✓ | ✓ | ✓ | - | - | MC persisted to non-volatile storage |
|
||||
| SWR-DQC-013 | Load Machine Constants at Startup | ✓ | ✓ | ✓ | - | - | MC loaded during initialization |
|
||||
| SWR-DQC-014 | Support Remote Machine Constants Update | ✓ | ✓ | ✓ | - | - | Remote MC updates supported |
|
||||
| SWR-DQC-015 | Controlled Reinitialization After Update | ✓ | ✓ | ✓ | - | - | Reinitialization after MC update |
|
||||
| SWR-DQC-016 | Machine Constants Integrity Validation | ✓ | ✓ | ✓ | ✓ | - | MC integrity validated before apply |
|
||||
| SWR-DQC-017 | State-Restricted Calibration | ✓ | ✓ | ✓ | - | - | Calibration blocked in OTA_UPDATE, MC_UPDATE, TEARDOWN |
|
||||
| SWR-DQC-018 | Machine Constants Access via DP | ✓ | ✓ | ✓ | ✓ | - | MC accessed only via DP component |
|
||||
|
||||
### Communication Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-COM-001 | Bidirectional Main Hub Communication | ✓ | ✓ | ✓ | ✓ | - | Bidirectional communication functional |
|
||||
| SWR-COM-002 | Transmit Data to Main Hub | ✓ | ✓ | ✓ | - | - | Sensor data, diagnostics, status transmitted |
|
||||
| SWR-COM-003 | Receive Commands from Main Hub | ✓ | ✓ | ✓ | - | - | Commands, config updates, OTA requests received |
|
||||
| SWR-COM-004 | Monitor Communication Link Status | ✓ | ✓ | ✓ | - | - | Link status monitored and reported |
|
||||
| SWR-COM-005 | Support On-Demand Data Requests | ✓ | ✓ | ✓ | - | - | On-demand requests supported |
|
||||
| SWR-COM-006 | Respond with Latest Sensor Data | ✓ | ✓ | ✓ | ✓ | ✓ | Response within 100ms with latest data |
|
||||
| SWR-COM-007 | Include Data Validity in Responses | ✓ | ✓ | ✓ | - | - | Validity status included in responses |
|
||||
| SWR-COM-008 | Support Peer Sensor Hub Communication | ✓ | ✓ | ✓ | - | - | Peer communication supported |
|
||||
| SWR-COM-009 | Isolate Peer Communication | ✓ | ✓ | ✓ | - | - | Peer communication doesn't interfere |
|
||||
| SWR-COM-010 | Encrypted Main Hub Communication | ✓ | ✓ | ✓ | ✓ | - | All communication encrypted |
|
||||
| SWR-COM-011 | Message Integrity and Authenticity | ✓ | ✓ | ✓ | ✓ | - | Message integrity and authenticity verified |
|
||||
| SWR-COM-012 | State-Restricted Communication | ✓ | ✓ | ✓ | - | - | Communication limited during TEARDOWN |
|
||||
| SWR-COM-013 | Non-Blocking Communication | ✓ | ✓ | ✓ | ✓ | ✓ | Communication operations non-blocking |
|
||||
| SWR-COM-014 | Communication Link Failure Reporting | ✓ | ✓ | ✓ | - | - | Link failures reported as diagnostics |
|
||||
| SWR-COM-015 | Security Violation Reporting | ✓ | ✓ | ✓ | - | - | Security violations reported to Main Hub |
|
||||
|
||||
### Diagnostics Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-DIAG-001 | Diagnostic Code Framework | ✓ | ✓ | ✓ | ✓ | - | Diagnostic framework implemented |
|
||||
| SWR-DIAG-002 | Assign Unique Diagnostic Codes | ✓ | ✓ | ✓ | ✓ | - | Each fault has unique code |
|
||||
| SWR-DIAG-003 | Classify Diagnostic Severity | ✓ | ✓ | ✓ | ✓ | - | Severity classification correct |
|
||||
| SWR-DIAG-004 | Timestamp and Source Diagnostics | ✓ | ✓ | ✓ | - | - | Timestamp and source associated |
|
||||
| SWR-DIAG-005 | Persist Diagnostic Events | ✓ | ✓ | ✓ | - | - | Diagnostic events persisted |
|
||||
| SWR-DIAG-006 | Retain Diagnostics Across Resets | ✓ | ✓ | ✓ | - | - | Diagnostics retained after reset |
|
||||
| SWR-DIAG-007 | Bounded Diagnostic Storage | ✓ | ✓ | ✓ | ✓ | - | Storage bounded with overwrite policy |
|
||||
| SWR-DIAG-008 | Provide Diagnostic Session Interface | ✓ | ✓ | ✓ | ✓ | - | Diagnostic session interface provided |
|
||||
| SWR-DIAG-009 | Retrieve Diagnostic Records | ✓ | ✓ | ✓ | - | - | Diagnostic records retrievable |
|
||||
| SWR-DIAG-010 | Clear Diagnostic Records | ✓ | ✓ | ✓ | - | - | Diagnostic records clearable |
|
||||
| SWR-DIAG-011 | Non-Intrusive Diagnostic Sessions | ✓ | ✓ | ✓ | - | - | Sessions don't interfere with operation |
|
||||
| SWR-DIAG-012 | Fault-to-State Transition | ✓ | ✓ | ✓ | - | - | Faults trigger state transitions |
|
||||
| SWR-DIAG-013 | Fault Latching Behavior | ✓ | ✓ | ✓ | - | - | Fault latching works correctly |
|
||||
| SWR-DIAG-014 | Fault Escalation Rules | ✓ | ✓ | ✓ | - | - | Escalation rules implemented |
|
||||
| SWR-DIAG-015 | Diagnostic Event Reporting to Main Hub | ✓ | ✓ | ✓ | - | - | WARNING/ERROR/FATAL events reported |
|
||||
| SWR-DIAG-016 | Diagnostic Information via HMI | ✓ | ✓ | ✓ | - | - | Diagnostic info accessible via HMI |
|
||||
| SWR-DIAG-017 | Diagnostic Storage Access via DP | ✓ | ✓ | ✓ | ✓ | - | Diagnostics accessed only via DP |
|
||||
| SWR-DIAG-018 | State-Restricted Diagnostic Generation | ✓ | ✓ | ✓ | - | - | Diagnostics limited during TEARDOWN |
|
||||
|
||||
### Persistence Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-DATA-001 | Persistent Timestamped Sensor Data | ✓ | ✓ | ✓ | - | - | Sensor data persisted correctly |
|
||||
| SWR-DATA-002 | Sensor Data Metadata Storage | ✓ | ✓ | ✓ | ✓ | - | Metadata stored with sensor data |
|
||||
| SWR-DATA-003 | Configurable Data Retention Policy | ✓ | ✓ | ✓ | ✓ | - | Retention policy configurable |
|
||||
| SWR-DATA-004 | Data Persistence Component Interface | ✓ | ✓ | ✓ | ✓ | - | DP component is sole interface |
|
||||
| SWR-DATA-005 | Storage Access Isolation | ✓ | ✓ | ✓ | ✓ | - | No direct storage access from application |
|
||||
| SWR-DATA-006 | Structured Data Serialization | ✓ | ✓ | ✓ | ✓ | - | Serialization/deserialization works |
|
||||
| SWR-DATA-007 | Data Flush Before Teardown | ✓ | ✓ | ✓ | ✓ | - | Critical data flushed before teardown |
|
||||
| SWR-DATA-008 | Data Integrity During Updates | ✓ | ✓ | ✓ | ✓ | - | Data integrity maintained during updates |
|
||||
| SWR-DATA-009 | Persistence Verification | ✓ | ✓ | ✓ | ✓ | - | Persistence verified before state transitions |
|
||||
| SWR-DATA-010 | State-Restricted Data Writes | ✓ | ✓ | ✓ | - | - | Writes restricted during TEARDOWN |
|
||||
| SWR-DATA-011 | Persistence Completion Confirmation | ✓ | ✓ | ✓ | - | - | Completion confirmed before transitions |
|
||||
| SWR-DATA-012 | SD Card Failure Handling | ✓ | ✓ | ✓ | - | - | SD failures handled gracefully |
|
||||
| SWR-DATA-013 | Wear-Aware Storage Management | ✓ | ✓ | ✓ | ✓ | - | Wear-aware management implemented |
|
||||
| SWR-DATA-014 | Single Source of Truth | ✓ | ✓ | ✓ | ✓ | - | Single source of truth maintained |
|
||||
| SWR-DATA-015 | No Private Persistent Copies | ✓ | ✓ | ✓ | ✓ | - | No private persistent copies |
|
||||
|
||||
### OTA Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-OTA-001 | OTA Negotiation Support | ✓ | ✓ | ✓ | - | - | OTA negotiation supported |
|
||||
| SWR-OTA-002 | OTA Readiness Validation | ✓ | ✓ | ✓ | - | - | Readiness validated before acceptance |
|
||||
| SWR-OTA-003 | OTA Acknowledgement | ✓ | ✓ | ✓ | - | - | OTA requests acknowledged/rejected |
|
||||
| SWR-OTA-004 | Firmware Reception | ✓ | ✓ | ✓ | - | - | Firmware received over communication |
|
||||
| SWR-OTA-005 | Firmware Temporary Storage | ✓ | ✓ | ✓ | - | - | Firmware stored in non-volatile storage |
|
||||
| SWR-OTA-006 | Active Firmware Protection | ✓ | ✓ | ✓ | ✓ | - | Active firmware not overwritten |
|
||||
| SWR-OTA-007 | Firmware Integrity Verification | ✓ | ✓ | ✓ | ✓ | - | Firmware integrity validated |
|
||||
| SWR-OTA-008 | Firmware Rejection Handling | ✓ | ✓ | ✓ | - | - | Invalid firmware rejected |
|
||||
| SWR-OTA-009 | OTA Status Reporting | ✓ | ✓ | ✓ | - | - | OTA status reported to Main Hub |
|
||||
| SWR-OTA-010 | OTA Teardown Execution | ✓ | ✓ | ✓ | - | - | Teardown executed before activation |
|
||||
| SWR-OTA-011 | Data Persistence Before Flashing | ✓ | ✓ | ✓ | - | - | Critical data persisted before flashing |
|
||||
| SWR-OTA-012 | Controlled Firmware Activation | ✓ | ✓ | ✓ | ✓ | - | Firmware activated only after validation |
|
||||
| SWR-OTA-013 | OTA Reboot Execution | ✓ | ✓ | ✓ | - | - | System reboots into new firmware |
|
||||
| SWR-OTA-014 | Encrypted OTA Communication | ✓ | ✓ | ✓ | ✓ | - | OTA communication encrypted |
|
||||
| SWR-OTA-015 | OTA State Transition | ✓ | ✓ | ✓ | - | - | Transitions to OTA_PREP on request |
|
||||
| SWR-OTA-016 | State-Restricted OTA Operations | ✓ | ✓ | ✓ | - | - | OTA blocked in WARNING/FAULT/SERVICE/SD_DEGRADED |
|
||||
| SWR-OTA-017 | OTA Duration Limit | ✓ | ✓ | ✓ | ✓ | ✓ | OTA completes within 10 minutes |
|
||||
| SWR-OTA-018 | OTA Failure Handling | ✓ | ✓ | ✓ | - | - | OTA failures trigger FAULT state |
|
||||
| SWR-OTA-019 | Active Firmware Corruption Protection | ✓ | ✓ | ✓ | ✓ | - | Active firmware protected during OTA |
|
||||
| SWR-OTA-020 | Firmware Authenticity Verification | ✓ | ✓ | ✓ | ✓ | - | Firmware authenticity verified |
|
||||
|
||||
### Security Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-SEC-001 | Firmware Authenticity Verification | ✓ | ✓ | ✓ | ✓ | - | Firmware verified on every boot |
|
||||
| SWR-SEC-002 | Unauthorized Firmware Blocking | ✓ | ✓ | ✓ | ✓ | - | Unauthorized firmware blocked |
|
||||
| SWR-SEC-003 | Secure Boot Failure Handling | ✓ | ✓ | ✓ | - | - | BOOT_FAILURE state on secure boot failure |
|
||||
| SWR-SEC-004 | Root-of-Trust Protection | ✓ | ✓ | ✓ | ✓ | - | Root-of-trust protected |
|
||||
| SWR-SEC-005 | Flash Data Access Protection | ✓ | ✓ | ✓ | ✓ | - | Flash data access protected |
|
||||
| SWR-SEC-006 | Encrypted External Storage | ✓ | ✓ | ✓ | ✓ | - | External storage encrypted |
|
||||
| SWR-SEC-007 | Cryptographic Key Isolation | ✓ | ✓ | ✓ | ✓ | - | Keys isolated to authorized components |
|
||||
| SWR-SEC-008 | Stored Data Integrity Assurance | ✓ | ✓ | ✓ | ✓ | - | Stored data integrity ensured |
|
||||
| SWR-SEC-009 | Encrypted Main Hub Communication | ✓ | ✓ | ✓ | ✓ | - | All communication encrypted |
|
||||
| SWR-SEC-010 | Message Integrity and Authenticity | ✓ | ✓ | ✓ | ✓ | - | Message integrity and authenticity verified |
|
||||
| SWR-SEC-011 | Secure OTA Data Transfer | ✓ | ✓ | ✓ | ✓ | - | OTA data transfer encrypted |
|
||||
| SWR-SEC-012 | Security Violation Reporting | ✓ | ✓ | ✓ | - | - | Security violations reported |
|
||||
| SWR-SEC-013 | Security First Initialization | ✓ | ✓ | ✓ | ✓ | - | Secure boot enabled before application |
|
||||
| SWR-SEC-014 | Debug Session Authentication | ✓ | ✓ | ✓ | ✓ | - | Debug sessions authenticated |
|
||||
| SWR-SEC-015 | Debug Security Bypass Prevention | ✓ | ✓ | ✓ | ✓ | - | Debug cannot bypass security |
|
||||
| SWR-SEC-016 | Security Violation Diagnostic Reporting | ✓ | ✓ | ✓ | - | - | Security violations reported as FATAL |
|
||||
| SWR-SEC-017 | Cryptographic Key Protection | ✓ | ✓ | ✓ | ✓ | - | Keys protected during power loss |
|
||||
| SWR-SEC-018 | Secure Session Establishment | ✓ | ✓ | ✓ | ✓ | - | Secure sessions established |
|
||||
| SWR-SEC-019 | Message Integrity Validation | ✓ | ✓ | ✓ | ✓ | - | Message integrity validated on receive |
|
||||
| SWR-SEC-020 | Downgrade Attack Prevention | ✓ | ✓ | ✓ | ✓ | - | Downgrade attacks prevented |
|
||||
|
||||
### Performance Requirements
|
||||
|
||||
| SWR ID | Requirement | UT | IT | HIL | REV | ANAL | Acceptance Criteria |
|
||||
|--------|-------------|----|----|-----|-----|------|---------------------|
|
||||
| SWR-PERF-001 | Sensor Acquisition Cycle Timing | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 100ms per sensor |
|
||||
| SWR-PERF-002 | State Transition Timing | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 50ms (except INIT, TEARDOWN) |
|
||||
| SWR-PERF-003 | Data Persistence Timing | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 200ms |
|
||||
| SWR-PERF-004 | OTA Operation Duration | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 10 minutes |
|
||||
| SWR-PERF-005 | CPU Utilization Limit | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 80% during normal operation |
|
||||
| SWR-PERF-006 | RAM Usage Limit | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 60% of available memory |
|
||||
| SWR-PERF-007 | Main Hub Response Time | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 100ms |
|
||||
| SWR-PERF-008 | Communication Link Failure Detection | ✓ | ✓ | ✓ | ✓ | ✓ | ≤ 30 seconds |
|
||||
|
||||
## Test Coverage Summary
|
||||
|
||||
- **Total SWRs:** 200+
|
||||
- **Unit Test Coverage:** ~180 SWRs (90%)
|
||||
- **Integration Test Coverage:** ~190 SWRs (95%)
|
||||
- **HIL Test Coverage:** ~150 SWRs (75%)
|
||||
- **Review Coverage:** ~100 SWRs (50%)
|
||||
- **Analysis Coverage:** ~30 SWRs (15%)
|
||||
|
||||
## Traceability
|
||||
|
||||
- **SRS Section 3:** All functional requirements covered
|
||||
- **Annex C:** Timing and resource budgets verified
|
||||
- **Component Specifications:** Component-level tests defined
|
||||
275
system_design/analysis/Engineering_Review_Report.md
Normal file
275
system_design/analysis/Engineering_Review_Report.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# **ASF Sensor Hub - Senior Embedded Systems Architecture Review Report**
|
||||
|
||||
## **A. Executive Summary**
|
||||
|
||||
### **Overall System Maturity Level: 65%**
|
||||
- **Documentation Quality: 90%** - Exceptional architectural definition and requirements traceability
|
||||
- **Implementation Readiness: 40%** - Components are stubbed but lack functional implementation
|
||||
- **Cross-Feature Integration: 30%** - Critical architectural gaps in state management and feature interaction
|
||||
|
||||
### **Major Risks (Top 5)**
|
||||
1. **CRITICAL: Missing System State Machine** - No implementation of the defined FSM, risking undefined behavior during state transitions
|
||||
2. **CRITICAL: Event System Not Implemented** - Core architectural component for cross-feature communication is missing
|
||||
3. **MAJOR: OTA Safety Violations** - No teardown mechanism, no data persistence before flashing
|
||||
4. **MAJOR: Security Architecture Incomplete** - Secure boot and flash encryption not enforced
|
||||
5. **MAJOR: Real-Time Constraints Undefined** - No deterministic timing guarantees for sensor acquisition
|
||||
|
||||
### **Go/No-Go Recommendation: NO-GO**
|
||||
**Recommendation:** Do NOT proceed to implementation phase. **REQUIRES IMMEDIATE ARCHITECTURAL CLARIFICATION AND PROTOTYPING.**
|
||||
|
||||
## **B. Detailed Findings**
|
||||
|
||||
### **Architecture Review**
|
||||
|
||||
#### **Strengths**
|
||||
- **Layered Architecture Properly Defined** - Clear separation between Application, Drivers, OSAL, and HAL layers
|
||||
- **Component-Based Design** - Modular structure with well-defined interfaces
|
||||
- **Event-Driven Model Specified** - Appropriate for distributed embedded systems
|
||||
|
||||
#### **Critical Architectural Violations**
|
||||
1. **Event System Implementation MISSING** - Core architectural component not implemented
|
||||
- **Impact:** No cross-feature communication mechanism
|
||||
- **Severity:** CRITICAL
|
||||
|
||||
2. **System State Machine Implementation MISSING** - No FSM implementation despite being architecturally central
|
||||
- **Impact:** Undefined system behavior during state transitions
|
||||
- **Severity:** CRITICAL
|
||||
|
||||
3. **Data Persistence (DP) Component Stubbed** - No functional implementation
|
||||
- **Impact:** No data integrity during power loss or updates
|
||||
- **Severity:** MAJOR
|
||||
|
||||
4. **Hardware Abstraction Violations** - Application layer components directly include ESP-IDF headers
|
||||
- **Impact:** Platform lock-in, reduced testability
|
||||
- **Severity:** MAJOR
|
||||
|
||||
### **Requirements & Feature Consistency**
|
||||
|
||||
#### **Requirements Quality Assessment**
|
||||
- **Well-Structured:** 95% of requirements follow "SHALL" format
|
||||
- **Testable:** 90% of requirements are verifiable
|
||||
- **Traceable:** 100% linked to features via unique IDs
|
||||
|
||||
#### **Critical Gaps Identified**
|
||||
1. **Missing System States Definition**
|
||||
- Requirements reference states (INIT, RUNNING, OTA_UPDATE, etc.) but no complete state transition table exists
|
||||
- **Impact:** Undefined behavior during state changes
|
||||
|
||||
2. **Timing Requirements NOT SPECIFIED**
|
||||
- No deterministic timing bounds for sensor acquisition cycles
|
||||
- No maximum latency requirements for communication
|
||||
- **Impact:** Real-time behavior cannot be guaranteed
|
||||
|
||||
3. **Resource Constraints NOT DEFINED**
|
||||
- No CPU utilization limits specified
|
||||
- No memory usage bounds defined
|
||||
- No flash wear-out protection requirements
|
||||
- **Impact:** System may fail under resource pressure
|
||||
|
||||
#### **Requirements Conflicts**
|
||||
1. **Security vs. Performance Trade-off NOT RESOLVED**
|
||||
- Encrypted communication required but no performance impact analysis
|
||||
- **Impact:** May violate real-time constraints
|
||||
|
||||
2. **OTA Safety vs. Availability NOT BALANCED**
|
||||
- OTA requires controlled teardown but no maximum downtime specified
|
||||
- **Impact:** System may be unavailable for extended periods
|
||||
|
||||
### **Cross-Feature Interaction Review**
|
||||
|
||||
#### **DAQC ↔ DATA Interaction**
|
||||
- **CURRENT STATE:** No implementation of data flow from sensor acquisition to persistence
|
||||
- **RISK:** Sensor data lost during power failures
|
||||
- **RECOMMENDATION:** Implement DP component with guaranteed write-before-use
|
||||
|
||||
#### **OTA ↔ Persistence Interaction**
|
||||
- **CURRENT STATE:** OTA feature assumes teardown but no mechanism exists
|
||||
- **RISK:** Critical data corruption during firmware updates
|
||||
- **RECOMMENDATION:** Implement mandatory data flush before OTA activation
|
||||
|
||||
#### **OTA ↔ Security Interaction**
|
||||
- **CURRENT STATE:** OTA occurs over encrypted channels but secure boot not enforced
|
||||
- **RISK:** Malicious firmware installation possible
|
||||
- **RECOMMENDATION:** Implement secure boot verification before any OTA execution
|
||||
|
||||
#### **Diagnostics ↔ System State Management**
|
||||
- **CURRENT STATE:** Diagnostics component exists but no integration with system state
|
||||
- **RISK:** Diagnostic events may trigger invalid state transitions
|
||||
- **RECOMMENDATION:** Bind diagnostic severity levels to state transition triggers
|
||||
|
||||
#### **Debug Sessions ↔ Secure Boot**
|
||||
- **CURRENT STATE:** Debug access allowed but no security controls
|
||||
- **RISK:** Debug interface could bypass secure boot
|
||||
- **RECOMMENDATION:** Implement authenticated debug access with secure boot verification
|
||||
|
||||
### **ESP-IDF & RTOS Suitability**
|
||||
|
||||
#### **Task Model Assessment**
|
||||
- **APPROPRIATE:** RTOS-based design suitable for ESP32-S3
|
||||
- **CONCERN:** No task priority definition or scheduling analysis
|
||||
- **RECOMMENDATION:** Define task priorities and worst-case execution times
|
||||
|
||||
#### **ISR vs Task Responsibilities**
|
||||
- **NOT SPECIFIED:** No clear delineation between interrupt and task contexts
|
||||
- **RISK:** Blocking operations in ISRs could cause system lockup
|
||||
- **RECOMMENDATION:** Define ISR-to-task communication patterns
|
||||
|
||||
#### **Memory Management Risks**
|
||||
- **HIGH RISK:** Dynamic memory allocation in runtime paths not prohibited
|
||||
- **IMPACT:** Memory fragmentation and allocation failures possible
|
||||
- **RECOMMENDATION:** Static memory allocation for critical paths
|
||||
|
||||
#### **Flash/SD Card Wear Risks**
|
||||
- **NOT ADDRESSED:** No wear-leveling strategy defined
|
||||
- **IMPACT:** SD card failure after extended operation
|
||||
- **RECOMMENDATION:** Implement wear-aware storage management
|
||||
|
||||
#### **OTA Partitioning Implications**
|
||||
- **NOT ANALYZED:** ESP-IDF OTA partition strategy not evaluated against system requirements
|
||||
- **RISK:** Insufficient space for OTA updates
|
||||
- **RECOMMENDATION:** Define partition layout and OTA strategy
|
||||
|
||||
#### **Secure Boot & Flash Constraints**
|
||||
- **NOT IMPLEMENTED:** ESP32-S3 secure boot features not utilized
|
||||
- **IMPACT:** Firmware authenticity not guaranteed
|
||||
- **RECOMMENDATION:** Enable secure boot with hardware root-of-trust
|
||||
|
||||
### **Standards Readiness Assessment**
|
||||
|
||||
#### **IEC 61499 Alignment**
|
||||
- **READY:** Architecture follows event-driven principles
|
||||
- **GAP:** No function block definitions or event interface specifications
|
||||
- **ASSESSMENT:** Conceptually aligned but implementation details missing
|
||||
|
||||
#### **ISA-95 Alignment**
|
||||
- **READY:** Correctly positioned at Level 1-2 boundary
|
||||
- **GAP:** No formal interface definition with Level 3 (Main Hub)
|
||||
- **ASSESSMENT:** Architecturally sound but interface specifications incomplete
|
||||
|
||||
### **System Review Checklist Validation**
|
||||
|
||||
#### **PASSED ITEMS**
|
||||
- Feature coverage complete across DAQ, DQC, COM, DIAG, DATA, OTA, SEC, SYS domains
|
||||
- Requirements use "SHALL" format consistently
|
||||
- Unique requirement IDs assigned
|
||||
- Traceability to features established
|
||||
- Layered architecture properly defined
|
||||
- Hardware access isolated through drivers
|
||||
- Security constraints identified
|
||||
|
||||
#### **FAILED ITEMS**
|
||||
- **CRITICAL:** No system state machine implementation
|
||||
- **CRITICAL:** Event system not implemented
|
||||
- **MAJOR:** No teardown mechanism for OTA/configuration updates
|
||||
- **MAJOR:** Data persistence before teardown not guaranteed
|
||||
- **MAJOR:** Data integrity during updates not protected
|
||||
- **MAJOR:** Real-time constraints not bounded
|
||||
- **MAJOR:** Resource usage not limited
|
||||
- **MINOR:** Debug isolation not enforced
|
||||
- **MINOR:** HMI read-only constraint not technically enforced
|
||||
|
||||
#### **ITEMS NEEDING CLARIFICATION**
|
||||
- Maximum acceptable system downtime during OTA
|
||||
- Sensor acquisition cycle determinism requirements
|
||||
- Memory usage limits and monitoring
|
||||
- SD card failure recovery strategy
|
||||
- Time synchronization accuracy requirements
|
||||
|
||||
## **C. Missing / Risky Areas**
|
||||
|
||||
### **Missing System Requirements**
|
||||
1. **State Transition Timing Requirements** - Maximum time for state changes
|
||||
2. **Resource Utilization Limits** - CPU, memory, and storage bounds
|
||||
3. **Fault Recovery Time Requirements** - Maximum time to recover from failures
|
||||
4. **Data Retention Guarantees** - Minimum data persistence duration
|
||||
5. **Communication Latency Bounds** - Maximum acceptable delays
|
||||
|
||||
### **Missing System States**
|
||||
1. **BOOT_FAILURE State** - When secure boot verification fails
|
||||
2. **CALIBRATION_UPDATE State** - For machine constants updates
|
||||
3. **DIAGNOSTIC_MODE State** - For engineering diagnostics
|
||||
4. **LOW_POWER State** - For power conservation
|
||||
5. **FACTORY_RESET State** - For system reconfiguration
|
||||
|
||||
### **Missing Failure Handling**
|
||||
1. **SD Card Failure Recovery** - No strategy for storage medium failure
|
||||
2. **Communication Link Loss** - Extended disconnection handling not defined
|
||||
3. **Sensor Cascade Failure** - Multiple sensor failures handling
|
||||
4. **OTA Corruption Recovery** - Firmware image corruption during transfer
|
||||
5. **Time Synchronization Loss** - Clock drift management
|
||||
|
||||
### **Missing Documentation**
|
||||
1. **State Transition Diagrams** - Complete FSM with all transitions
|
||||
2. **Timing Budget Analysis** - End-to-end timing requirements
|
||||
3. **Resource Budget Allocation** - Memory and CPU allocation per component
|
||||
4. **Failure Mode Analysis** - FMEA for critical components
|
||||
5. **Interface Control Documents** - Detailed API specifications
|
||||
|
||||
## **D. Improvement Recommendations**
|
||||
|
||||
### **Immediate Actions (Pre-Implementation)**
|
||||
1. **Implement System State Machine** - Define and implement complete FSM with all states and transitions
|
||||
2. **Implement Event System** - Core communication backbone for cross-feature interaction
|
||||
3. **Define Timing Requirements** - Specify deterministic bounds for all time-critical operations
|
||||
4. **Implement Data Persistence** - Complete DP component with guaranteed data integrity
|
||||
|
||||
### **Architectural Clarifications Needed**
|
||||
1. **State Transition Rules** - Define which features can execute in which states
|
||||
2. **Failure Escalation Policy** - How faults propagate through the system
|
||||
3. **Resource Management Strategy** - Memory, CPU, and storage allocation policies
|
||||
4. **OTA Safety Protocol** - Complete procedure for fail-safe firmware updates
|
||||
|
||||
### **Implementation Priorities**
|
||||
1. **Phase 1:** Core infrastructure (State Machine, Event System, DP Component)
|
||||
2. **Phase 2:** Sensor acquisition and data quality features
|
||||
3. **Phase 3:** Communication and security features
|
||||
4. **Phase 4:** OTA and diagnostics features
|
||||
5. **Phase 5:** HMI and system management features
|
||||
|
||||
### **Quality Assurance Requirements**
|
||||
1. **Static Analysis Mandatory** - All code must pass MISRA C++ compliance
|
||||
2. **Unit Test Coverage >95%** - For all components except hardware interfaces
|
||||
3. **Integration Testing Required** - Cross-feature interaction validation
|
||||
4. **Performance Benchmarking** - Against defined timing and resource budgets
|
||||
|
||||
## **E. Generated Artifacts**
|
||||
|
||||
### **Recommended State Machine Diagram**
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> INIT
|
||||
INIT --> RUNNING: successful_init
|
||||
INIT --> FAULT: init_failure
|
||||
RUNNING --> OTA_UPDATE: ota_triggered
|
||||
RUNNING --> WARNING: minor_fault
|
||||
RUNNING --> FAULT: critical_fault
|
||||
WARNING --> RUNNING: fault_cleared
|
||||
WARNING --> FAULT: fault_escalated
|
||||
OTA_UPDATE --> RUNNING: ota_success
|
||||
OTA_UPDATE --> FAULT: ota_failure
|
||||
FAULT --> TEARDOWN: recovery_attempt
|
||||
TEARDOWN --> INIT: system_reset
|
||||
TEARDOWN --> [*]: power_down
|
||||
```
|
||||
|
||||
### **Critical Path Timing Budget**
|
||||
|
||||
| Operation | Maximum Time | Justification |
|
||||
|-----------|--------------|---------------|
|
||||
| Sensor Acquisition Cycle | 100ms | Real-time environmental monitoring |
|
||||
| State Transition | 50ms | Minimize system unavailability |
|
||||
| Data Persistence | 200ms | Prevent data loss during power failures |
|
||||
| OTA Teardown | 500ms | Balance safety with availability |
|
||||
| Secure Boot Verification | 2s | Hardware-enforced security |
|
||||
|
||||
### **Resource Allocation Budget**
|
||||
|
||||
| Resource | Maximum Usage | Monitoring Required |
|
||||
|----------|----------------|-------------------|
|
||||
| RAM (Runtime) | 60% | Yes |
|
||||
| Flash (Application) | 70% | Yes |
|
||||
| CPU (Peak) | 80% | Yes |
|
||||
| SD Card (Daily Writes) | 100MB | Yes |
|
||||
|
||||
**CONCLUSION:** The ASF Sensor Hub has excellent architectural foundations but requires significant implementation work before proceeding to full development. The current state represents architectural completeness without implementation readiness. Immediate focus must be on core infrastructure components (State Machine, Event System, Data Persistence) before feature implementation can safely proceed.
|
||||
253
system_design/analysis/Gap_Analysis_and_Solutions.md
Normal file
253
system_design/analysis/Gap_Analysis_and_Solutions.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# ASF Sensor Hub - Gap Analysis and Solutions
|
||||
|
||||
**Version:** 2.0
|
||||
**Date:** 2025-01-19
|
||||
**Status:** ✅ APPROVED with Minor Recommendations
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document consolidates the findings of the ASF gap analysis and the proposed industrial-grade solutions. The transition from a prototype to a production-ready system involves closing critical gaps in communication, security, reliability, and maintainability.
|
||||
|
||||
**Overall Rating:** ⭐⭐⭐⭐⭐ (4.7/5.0)
|
||||
|
||||
## Quick Assessment
|
||||
|
||||
| Category | Rating | Status |
|
||||
|----------|--------|--------|
|
||||
| **Communication Architecture** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
|
||||
| **Security Model** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
|
||||
| **OTA Strategy** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
|
||||
| **Sensor Data Acquisition** | ⭐⭐⭐⭐ | ✅ Good (redundancy needs review) |
|
||||
| **Data Persistence** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
|
||||
| **Diagnostics** | ⭐⭐⭐⭐ | ✅ Good (codes need completion) |
|
||||
| **Power Handling** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
|
||||
| **GPIO Discipline** | ⭐⭐⭐⭐⭐ | ✅ Excellent (map needs completion) |
|
||||
| **System Evolution** | ⭐⭐⭐⭐ | ✅ Good |
|
||||
|
||||
## Gap & Solution Matrix
|
||||
|
||||
| Arena | Identified Gaps | Proposed Industrial Solution |
|
||||
|-------|----------------|------------------------------|
|
||||
| **1. Communication** | Lack of versioning, raw sockets, unreliable peer-to-peer. | **MQTT over TLS 1.2** with **CBOR** payloads; **ESP-NOW** for deterministic P2P. |
|
||||
| **2. Security** | No hardware root of trust, weak device identity. | **Secure Boot V2**, **Flash Encryption**, and **mTLS** with unique device certificates. |
|
||||
| **3. OTA Updates** | Risk of "bricking," no integrity checks. | **A/B Partitioning** with automatic rollback and **SHA-256** verification. |
|
||||
| **4. Data Acquisition** | Tight coupling with hardware, no sensor validation. | **Sensor Abstraction Layer (SAL)**, redundant sensors, and explicit validity states. |
|
||||
| **5. Data Persistence** | SD card wear, risk of data loss on power failure. | **Batch writing**, **FAT32 SDMMC 4-bit**, and **Power-loss flush** mechanisms. |
|
||||
| **6. Diagnostics** | Limited visibility into fleet health. | **Standardized Diagnostic Codes (0xSCCC)** and **Layered Watchdogs**. |
|
||||
| **7. Power Handling** | Vulnerability to brownouts. | **Brownout detection (3.0V)** and hardware-backed graceful shutdown. |
|
||||
| **8. Hardware Discipline** | Potential pin conflicts, unreliable I2C. | **Strict GPIO mapping**, no strapping pins, and audited physical pull-ups. |
|
||||
| **9. System Evolution** | Prototype-level architecture. | **Industrial-grade framework** focusing on determinism and fault tolerance. |
|
||||
|
||||
## Technology Stack Validation
|
||||
|
||||
| Technology | Choice | Justification | Status |
|
||||
|------------|--------|---------------|--------|
|
||||
| Wi-Fi 802.11n | ✅ | Native support, good range, sufficient throughput | ✅ Approved |
|
||||
| MQTT | ✅ | Industry standard, store-and-forward, lightweight | ✅ Approved |
|
||||
| TLS 1.2 | ✅ | Strong security, ESP-IDF native | ✅ Approved |
|
||||
| ESP-NOW | ✅ | Deterministic P2P, low latency | ✅ Approved (needs encryption) |
|
||||
| CBOR | ✅ | Efficient binary encoding | ✅ Approved |
|
||||
| LoRa | ⚠️ | External module, low data rate | ⚠️ Needs justification |
|
||||
| Secure Boot V2 | ✅ | Hardware root of trust | ✅ Approved |
|
||||
| Flash Encryption | ✅ | IP protection, data security | ✅ Approved |
|
||||
| A/B Partitioning | ✅ | Safe OTA, rollback capability | ✅ Approved |
|
||||
|
||||
## Key Findings
|
||||
|
||||
### ✅ **EXCELLENT CHOICES** (No Changes Needed)
|
||||
|
||||
1. **MQTT over TLS 1.2** - Industry standard, perfect for industrial IoT
|
||||
2. **Secure Boot V2 + Flash Encryption** - Mandatory for production, well-implemented
|
||||
3. **A/B OTA Partitioning** - Safe, reliable, industry-proven
|
||||
4. **Sensor Abstraction Layer (SAL)** - Maintainable, testable, future-proof
|
||||
5. **Wear-Aware SD Card Strategy** - Prevents premature failure
|
||||
6. **Layered Watchdogs** - Multi-level protection
|
||||
7. **Brownout Detection** - Critical for farm environments
|
||||
|
||||
### ⚠️ **NEEDS CLARIFICATION** (5 Items)
|
||||
|
||||
1. **LoRa Fallback** - Is it truly needed? Cost-benefit analysis required
|
||||
2. **Redundant Sensors** - Define which parameters are critical (cost impact)
|
||||
3. **GPIO Map** - Complete the canonical mapping table
|
||||
4. **Diagnostic Codes** - Complete the code registry (0x6xxx, 0x7xxx, 0x8xxx missing)
|
||||
5. **OTA Health Check** - 60s may be too short (consider 120s)
|
||||
|
||||
### ✅ **MINOR RECOMMENDATIONS** (Enhancements)
|
||||
|
||||
1. Complete MQTT topic structure specification
|
||||
2. Define sensor fusion algorithm for redundant sensors
|
||||
3. Specify SD card file rotation policy
|
||||
4. Define certificate lifecycle management
|
||||
5. Specify maximum message sizes
|
||||
|
||||
## Critical Action Items
|
||||
|
||||
### Must Complete Before Implementation:
|
||||
|
||||
1. ✅ **GPIO Mapping Table** - Complete pin assignments
|
||||
2. ✅ **Diagnostic Code Registry** - Define all subsystem codes
|
||||
3. ✅ **MQTT Topic Structure** - Complete topic naming convention
|
||||
4. ✅ **Certificate Lifecycle** - Define provisioning, rotation, revocation
|
||||
5. ✅ **OTA Health Check Window** - Validate 60s or increase to 120s
|
||||
|
||||
### Should Complete During Design:
|
||||
|
||||
1. ⚠️ **Redundant Sensor Analysis** - Cost-benefit and criticality matrix
|
||||
2. ⚠️ **LoRa Justification** - Is it needed? Alternative analysis
|
||||
3. ⚠️ **Sensor Fusion Algorithm** - How to combine redundant sensor data
|
||||
4. ⚠️ **SD Card Rotation Policy** - File size limits, rotation frequency
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Severity | Mitigation Status |
|
||||
|------|----------|-------------------|
|
||||
| Incomplete GPIO Map | HIGH | ⚠️ Needs completion |
|
||||
| Missing Diagnostic Codes | MEDIUM | ⚠️ Needs completion |
|
||||
| LoRa Cost/Complexity | MEDIUM | ⚠️ Needs justification |
|
||||
| Redundant Sensor Cost | MEDIUM | ⚠️ Needs analysis |
|
||||
| OTA Health Check Timing | LOW | ⚠️ Needs validation |
|
||||
|
||||
## Final Recommendation
|
||||
|
||||
**✅ PROCEED WITH IMPLEMENTATION**
|
||||
|
||||
The proposed solutions are **technically sound** and **production-ready**. Address the **Critical Action Items** before starting implementation. The **Should Complete** items can be resolved during detailed design.
|
||||
|
||||
**Confidence Level:** **HIGH** (90%)
|
||||
|
||||
The architecture demonstrates **mature industrial engineering practices** and is suitable for **long-term field deployment**.
|
||||
|
||||
## Detailed Solutions
|
||||
|
||||
### 1. Communication Architecture
|
||||
|
||||
**Selected Technologies:**
|
||||
- **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)
|
||||
|
||||
**Rationale:**
|
||||
- MQTT provides store-and-forward messaging (handles intermittent connectivity)
|
||||
- Built-in keepalive mechanism (monitors connection health)
|
||||
- QoS levels for delivery guarantees
|
||||
- Massive industrial adoption (SCADA, IIoT)
|
||||
- Native ESP-IDF support
|
||||
|
||||
**Heartbeat Mechanism:**
|
||||
- Interval: 10 seconds
|
||||
- Timeout: 3 missed heartbeats (30 seconds) triggers offline status
|
||||
- Payload includes: Uptime, firmware version, free heap, RSSI, error bitmap
|
||||
|
||||
### 2. Security Model
|
||||
|
||||
**Root of Trust:**
|
||||
- **Secure Boot V2:** Ensures only digitally signed firmware can run
|
||||
- **Flash Encryption:** Protects firmware and sensitive data stored in flash
|
||||
- **eFuse-based Anti-rollback:** Prevents installation of older, vulnerable firmware
|
||||
|
||||
**Device Identity & Authentication:**
|
||||
- Device-unique X.509 certificate
|
||||
- Private key stored in eFuse or encrypted flash
|
||||
- Mutual TLS (mTLS) for all broker communications
|
||||
- Provisioning handled via secure factory or onboarding mode
|
||||
|
||||
**Key Lifecycle Management:**
|
||||
- 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
|
||||
|
||||
### 3. OTA Strategy
|
||||
|
||||
**Partition Layout (8MB Flash):**
|
||||
- `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)
|
||||
- `coredump`: 64 KB (Crash logs)
|
||||
|
||||
**OTA Policy:**
|
||||
- Download via HTTPS or MQTT in chunks (4096 bytes)
|
||||
- Integrity verified using full image SHA-256 hash
|
||||
- System must boot and send health report
|
||||
- Application must confirm stability within 60-120 seconds
|
||||
- Automatic rollback to previous known-good version on failure
|
||||
|
||||
### 4. Sensor Data Acquisition
|
||||
|
||||
**Sensor Abstraction Layer (SAL):**
|
||||
- Hardware independence
|
||||
- Uniform sensor API
|
||||
- Sensor state management (INIT, WARMUP, STABLE, DEGRADED, FAILED)
|
||||
- Sensor validation and health checks
|
||||
|
||||
**Redundant Sensor Support:**
|
||||
- Critical parameters (CO2, NH3) have two qualified sensor options
|
||||
- Sensor fusion algorithm to combine redundant data
|
||||
- Avoids common-mode failures
|
||||
|
||||
### 5. Data Persistence
|
||||
|
||||
**Storage Strategy:**
|
||||
- **File System:** FAT32
|
||||
- **Mode:** SDMMC 4-bit (for performance and reliability)
|
||||
- **Structure:** Circular time-bucket files (e.g., daily logs)
|
||||
- **Write Pattern:** Append-only to minimize directory updates
|
||||
- **Wear-Aware Management:** Batch writing to prevent SD card wear
|
||||
|
||||
**Power-Loss Protection:**
|
||||
- Brownout detection at 3.0V
|
||||
- Immediate flush of critical buffers to NVS/SD
|
||||
- Supercapacitor (0.5-1.0F) recommended for graceful shutdown
|
||||
|
||||
### 6. Diagnostics
|
||||
|
||||
**Diagnostic Code Format:**
|
||||
- Format: `0xSCCC`
|
||||
- **S:** Severity (1=Info, 2=Warning, 3=Error, 4=Critical)
|
||||
- **CCC:** Subsystem Code
|
||||
|
||||
**Subsystem Code Allocation:**
|
||||
- `0x1xxx` - Data Acquisition (DAQ)
|
||||
- `0x2xxx` - Communication (COM)
|
||||
- `0x3xxx` - Security (SEC)
|
||||
- `0x4xxx` - Over-the-Air Updates (OTA)
|
||||
- `0x5xxx` - Hardware (HW)
|
||||
- `0x6xxx` - System Management (SYS)
|
||||
- `0x7xxx` - Persistence (DATA)
|
||||
- `0x8xxx` - Diagnostics (DIAG)
|
||||
|
||||
**Layered Watchdog System:**
|
||||
- **Task WDT:** Detects deadlocks in FreeRTOS tasks (10 seconds)
|
||||
- **Interrupt WDT:** Detects hangs within ISRs (3 seconds)
|
||||
- **RTC WDT:** Final safety net for total system freezes (30 seconds)
|
||||
|
||||
### 7. Power Handling
|
||||
|
||||
**Brownout Detection:**
|
||||
- Hardware brownout detector (BOD) at 3.0V
|
||||
- ISR action: Set "Power Loss" flag and immediately flush critical buffers
|
||||
- Recovery: Clean reboot after power stabilization
|
||||
|
||||
**Hardware Support:**
|
||||
- Supercapacitor (0.5-1.0F for 1-2s at 3.3V) recommended
|
||||
- External RTC battery (CR2032, 3V, 220mAh) optional for time accuracy
|
||||
|
||||
### 8. Hardware Discipline
|
||||
|
||||
**GPIO Rules:**
|
||||
- **No Strapping Pins:** Avoid 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
|
||||
|
||||
## Conclusion
|
||||
|
||||
By implementing these solutions, the ASF project moves beyond a functional prototype into a robust, secure, and maintainable industrial product capable of reliable operation in demanding farm environments.
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
- `../features/` - Feature specifications
|
||||
- `../specifications/` - System specifications
|
||||
- `../SRS/` - Software Requirements Specification
|
||||
120
system_design/features/Cross-Feature Constraints.md
Normal file
120
system_design/features/Cross-Feature Constraints.md
Normal file
@@ -0,0 +1,120 @@
|
||||
## 1\. Purpose
|
||||
|
||||
This document defines **cross-feature constraints** that apply across multiple system features and components. These constraints ensure consistent behavior, prevent architectural violations, and reduce integration risk.
|
||||
|
||||
Cross-feature constraints are **mandatory rules** that all future software design and implementation must comply with.
|
||||
|
||||
## 2\. Architectural Constraints
|
||||
|
||||
### CFC-ARCH-01: Layered Architecture Enforcement
|
||||
|
||||
* Application logic shall not access hardware directly.
|
||||
|
||||
* All hardware access shall be performed via Drivers and OSAL layers.
|
||||
|
||||
* Persistence access shall only be performed through the DP component.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
DAQ, DQC, DATA, DIAG, SYS, OTA, SEC
|
||||
|
||||
### CFC-ARCH-02: State-Aware Feature Execution
|
||||
|
||||
* All features shall be aware of the current system state.
|
||||
|
||||
* Features shall not execute actions that are invalid for the current state.
|
||||
|
||||
|
||||
**Examples:**
|
||||
|
||||
* DAQ shall not start sampling during OTA\_UPDATE.
|
||||
|
||||
* Communication shall be limited during TEARDOWN.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
SYS, DAQ, COM, OTA, DATA
|
||||
|
||||
## 3\. Concurrency & Timing Constraints
|
||||
|
||||
### CFC-TIME-01: Non-Blocking Operation
|
||||
|
||||
* Sensor acquisition, communication, and UI updates shall be non-blocking.
|
||||
|
||||
* Blocking operations shall be isolated in controlled system services (e.g., persistence task).
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
DAQ, COM, SYS
|
||||
|
||||
### CFC-TIME-02: Deterministic Task Behavior
|
||||
|
||||
* Time-critical tasks (sensor acquisition, watchdog servicing) shall have deterministic execution time.
|
||||
|
||||
* Dynamic memory allocation during runtime shall be minimized or prohibited in critical paths.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
DAQ, SYS, DIAG
|
||||
|
||||
## 4\. Data & Persistence Constraints
|
||||
|
||||
### CFC-DATA-01: Single Source of Truth
|
||||
|
||||
* Runtime and persistent data shall be owned and managed by the DP component.
|
||||
|
||||
* No feature shall maintain private persistent copies of shared system data.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
DATA, DAQ, DIAG, SYS, OTA
|
||||
|
||||
### CFC-DATA-02: Data Consistency During Transitions
|
||||
|
||||
* No data write operations shall occur during teardown unless explicitly authorized by the System Manager.
|
||||
|
||||
* Persistence completion shall be confirmed before state transitions.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
SYS, DATA, OTA
|
||||
|
||||
## 5\. Security Constraints
|
||||
|
||||
### CFC-SEC-01: Security First Initialization
|
||||
|
||||
* Secure boot and flash protection shall be enabled before any application-level logic executes.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
SEC, SYS
|
||||
|
||||
### CFC-SEC-02: Encrypted Channels Only
|
||||
|
||||
* OTA, diagnostics, and data transmission shall only occur over encrypted and authenticated channels.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
COM, OTA, DIAG, SEC
|
||||
|
||||
## 6\. HMI & Debug Constraints
|
||||
|
||||
### CFC-HMI-01: Read-Only Local UI
|
||||
|
||||
* The OLED HMI shall not allow configuration changes that affect system safety or security.
|
||||
|
||||
* Configuration updates shall only be accepted via authenticated communication channels.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
SYS, SEC
|
||||
|
||||
### CFC-DBG-01: Debug Isolation
|
||||
|
||||
* Debug and engineering sessions shall not interfere with normal system operation.
|
||||
|
||||
* Debug commands shall respect system state restrictions.
|
||||
|
||||
|
||||
**Impacted Features:**
|
||||
SYS, DIAG, SEC
|
||||
359
system_design/features/Features.md
Normal file
359
system_design/features/Features.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# **ASF Sensor Hub – Feature Definition Document**
|
||||
|
||||
*(Global, Feature-Based, Architecture-Neutral)*
|
||||
|
||||
This document defines the **system features** of the ASF Sensor Hub subsystem, organized by functional categories.
|
||||
It is intended to be used as:
|
||||
|
||||
* A **feature baseline** in ALM
|
||||
* Input to **system requirements derivation**
|
||||
* Reference for **architecture and software design**
|
||||
* Traceability anchor to IEC 61508 / IEC 61499 style decomposition later
|
||||
|
||||
> ⚠️ **Important Scope Note**
|
||||
> This document covers **ONLY the Sensor Hub (Sub-Hub)** based on **ESP32-S3**.
|
||||
> Main Hub, Cloud, Farm Control Logic are **explicitly out of scope**.
|
||||
|
||||
---
|
||||
|
||||
## **1. System Context Overview**
|
||||
|
||||
The ASF Sensor Hub is a **distributed sensing node** deployed inside a poultry house.
|
||||
Its primary responsibilities are:
|
||||
|
||||
* Acquisition of multiple environmental sensors
|
||||
* Local preprocessing and validation of sensor data
|
||||
* Persistent storage of data and configuration
|
||||
* Secure communication with a Main Hub
|
||||
* Support for diagnostics, maintenance, and OTA updates
|
||||
* Safe operation under fault conditions
|
||||
|
||||
The Sensor Hub operates as an **autonomous embedded system** with defined lifecycle states.
|
||||
|
||||
---
|
||||
|
||||
## **2. Feature Categorization Overview**
|
||||
|
||||
The system features are grouped into the following categories:
|
||||
|
||||
1. **Sensor Data Acquisition Features**
|
||||
2. **Data Quality & Calibration Features**
|
||||
3. **Communication Features**
|
||||
4. **Diagnostics & Health Monitoring Features**
|
||||
5. **Persistence & Data Management Features**
|
||||
6. **Firmware Update (OTA) Features**
|
||||
7. **Security & Safety Features**
|
||||
8. **System Management Features**
|
||||
|
||||
Each feature is described at a **functional level** (WHAT the system does, not HOW).
|
||||
|
||||
---
|
||||
|
||||
## **3. Sensor Data Acquisition Features**
|
||||
|
||||
### **F-DAQ-01: Multi-Sensor Data Acquisition**
|
||||
|
||||
The system provides the capability to acquire data from multiple environmental sensors connected to the Sensor Hub hardware.
|
||||
|
||||
Supported sensor types include:
|
||||
|
||||
* Temperature
|
||||
* Humidity
|
||||
* Carbon Dioxide (CO₂)
|
||||
* Ammonia (NH₃)
|
||||
* Volatile Organic Compounds (VOC)
|
||||
* Particulate Matter (PM)
|
||||
* Light Intensity
|
||||
|
||||
---
|
||||
|
||||
### **F-DAQ-02: High-Frequency Sampling and Local Filtering**
|
||||
|
||||
The system provides local preprocessing of sensor data by:
|
||||
|
||||
* Sampling each sensor multiple times per acquisition cycle
|
||||
* Applying a fast local filtering mechanism
|
||||
* Producing a single validated value per sensor per cycle
|
||||
|
||||
Filtering algorithms are **pluggable and configurable**.
|
||||
|
||||
---
|
||||
|
||||
### **F-DAQ-03: Timestamped Sensor Data Generation**
|
||||
|
||||
The system provides timestamped sensor data using a synchronized local time source.
|
||||
|
||||
Each sensor record includes:
|
||||
|
||||
* Sensor identifier
|
||||
* Measured value
|
||||
* Timestamp
|
||||
* Data validity status
|
||||
|
||||
---
|
||||
|
||||
## **4. Data Quality & Calibration Features**
|
||||
|
||||
### **F-DQC-01: Automatic Sensor Detection**
|
||||
|
||||
The system provides automatic detection of sensor presence based on dedicated hardware detection signals.
|
||||
|
||||
Key characteristics:
|
||||
|
||||
* Each sensor slot is type-specific
|
||||
* Sensor presence is detected during initialization and runtime
|
||||
* Only detected sensors are initialized and sampled
|
||||
|
||||
---
|
||||
|
||||
### **F-DQC-02: Sensor Type Enforcement**
|
||||
|
||||
The system enforces sensor-slot compatibility to prevent incorrect sensor usage.
|
||||
|
||||
Each physical slot:
|
||||
|
||||
* Accepts only one sensor type
|
||||
* Is mapped to a predefined sensor class in software
|
||||
|
||||
---
|
||||
|
||||
### **F-DQC-03: Sensor Failure Detection**
|
||||
|
||||
The system provides detection of sensor failures, including:
|
||||
|
||||
* Communication errors
|
||||
* Out-of-range values
|
||||
* Non-responsive sensors
|
||||
|
||||
Detected failures are classified and reported.
|
||||
|
||||
---
|
||||
|
||||
### **F-DQC-04: Machine Constants & Calibration Management**
|
||||
|
||||
The system provides a Machine Constants (MC) mechanism responsible for:
|
||||
|
||||
* Defining installed sensor types
|
||||
* Holding sensor calibration parameters
|
||||
* Defining communication parameters
|
||||
* Defining system identity parameters
|
||||
|
||||
MC data is persistent and reloadable.
|
||||
|
||||
---
|
||||
|
||||
## **5. Communication Features**
|
||||
|
||||
### **F-COM-01: Main Hub Communication**
|
||||
|
||||
The system provides bidirectional communication with a Main Hub to:
|
||||
|
||||
* Send sensor data
|
||||
* Send diagnostics information
|
||||
* Receive configuration updates
|
||||
* Receive firmware updates
|
||||
|
||||
---
|
||||
|
||||
### **F-COM-02: On-Demand Data Broadcasting**
|
||||
|
||||
The system provides on-demand transmission of the most recent sensor dataset upon request from the Main Hub.
|
||||
|
||||
---
|
||||
|
||||
### **F-COM-03: Peer Sensor Hub Communication**
|
||||
|
||||
The system provides limited peer-to-peer communication between Sensor Hubs for:
|
||||
|
||||
* Connectivity checks
|
||||
* Time synchronization support
|
||||
* Basic status exchange
|
||||
|
||||
This feature is **on-demand and optional**.
|
||||
|
||||
---
|
||||
|
||||
## **6. Diagnostics & Health Monitoring Features**
|
||||
|
||||
### **F-DIAG-01: Diagnostic Code Management**
|
||||
|
||||
The system provides structured diagnostics with:
|
||||
|
||||
* Diagnostic codes
|
||||
* Severity levels
|
||||
* Root cause hierarchy
|
||||
* Timestamping
|
||||
|
||||
---
|
||||
|
||||
### **F-DIAG-02: Diagnostic Data Storage**
|
||||
|
||||
The system provides persistent storage of diagnostic events for post-analysis.
|
||||
|
||||
---
|
||||
|
||||
### **F-DIAG-03: Diagnostic Session**
|
||||
|
||||
The system provides a diagnostic session allowing engineers to:
|
||||
|
||||
* Retrieve diagnostic data
|
||||
* Inspect system health
|
||||
* Clear diagnostic records
|
||||
|
||||
---
|
||||
|
||||
## **7. Persistence & Data Management Features**
|
||||
|
||||
### **F-DATA-01: Persistent Sensor Data Storage**
|
||||
|
||||
The system provides persistent storage of sensor data in non-volatile memory (SD Card).
|
||||
|
||||
---
|
||||
|
||||
### **F-DATA-02: Data Persistence Abstraction (DP Component)**
|
||||
|
||||
The system provides a Data Persistence (DP) component responsible for:
|
||||
|
||||
* Abstracting storage media (SD / NVM)
|
||||
* Managing write/read operations
|
||||
* Ensuring data integrity
|
||||
|
||||
---
|
||||
|
||||
### **F-DATA-03: Safe Data Handling During State Transitions**
|
||||
|
||||
The system ensures that all critical data is safely stored before:
|
||||
|
||||
* Firmware update
|
||||
* Configuration update
|
||||
* System teardown
|
||||
* Reset or restart
|
||||
|
||||
---
|
||||
|
||||
## **8. Firmware Update (OTA) Features**
|
||||
|
||||
### **F-OTA-01: OTA Update Negotiation**
|
||||
|
||||
The system provides an OTA handshake mechanism with the Main Hub to:
|
||||
|
||||
* Acknowledge update availability
|
||||
* Signal readiness for update
|
||||
|
||||
---
|
||||
|
||||
### **F-OTA-02: Firmware Reception and Storage**
|
||||
|
||||
The system provides secure reception of firmware images and temporary storage on SD Card.
|
||||
|
||||
---
|
||||
|
||||
### **F-OTA-03: Firmware Integrity Validation**
|
||||
|
||||
The system validates firmware integrity using checksum or CRC before activation.
|
||||
|
||||
---
|
||||
|
||||
### **F-OTA-04: Safe Firmware Activation**
|
||||
|
||||
The system provides controlled firmware flashing and rollback-safe activation.
|
||||
|
||||
---
|
||||
|
||||
## **9. Security & Safety Features**
|
||||
|
||||
### **F-SEC-01: Secure Boot**
|
||||
|
||||
The system provides secure boot functionality to ensure only authenticated firmware is executed.
|
||||
|
||||
---
|
||||
|
||||
### **F-SEC-02: Secure Flash Storage**
|
||||
|
||||
The system provides encrypted flash storage for sensitive assets.
|
||||
|
||||
---
|
||||
|
||||
### **F-SEC-03: Encrypted Communication**
|
||||
|
||||
The system provides encrypted communication channels for all external data exchange.
|
||||
|
||||
---
|
||||
|
||||
## **10. System Management Features**
|
||||
|
||||
### **F-SYS-01: System State Management**
|
||||
|
||||
The system provides explicit lifecycle states including:
|
||||
|
||||
* Initialization
|
||||
* Normal Operation
|
||||
* Degraded Operation
|
||||
* Update Mode
|
||||
* Fault Mode
|
||||
* Teardown Mode
|
||||
|
||||
---
|
||||
|
||||
### **F-SYS-02: Controlled Teardown Mechanism**
|
||||
|
||||
The system provides a controlled teardown mechanism that:
|
||||
|
||||
* Stops sensor acquisition
|
||||
* Flushes all critical data
|
||||
* Ensures persistent storage consistency
|
||||
* Prepares the system for update or shutdown
|
||||
|
||||
---
|
||||
|
||||
### **F-SYS-03: Status Indication**
|
||||
|
||||
The system provides visual status indicators:
|
||||
|
||||
* Green: Normal operation
|
||||
* Yellow: Warning state
|
||||
* Red: Fatal error state
|
||||
|
||||
---
|
||||
|
||||
### **F-SYS-04: Debug & Engineering Sessions**
|
||||
|
||||
The system provides engineering access sessions allowing:
|
||||
|
||||
* Log inspection
|
||||
* MC file inspection and update
|
||||
* Command execution
|
||||
* Controlled debugging
|
||||
|
||||
---
|
||||
|
||||
## **11. Feature Relationship Overview (High-Level)**
|
||||
|
||||
```
|
||||
Sensor Acquisition
|
||||
↓
|
||||
Data Quality & Calibration
|
||||
↓
|
||||
Data Persistence
|
||||
↓
|
||||
Communication
|
||||
↓
|
||||
Diagnostics & System Management
|
||||
↓
|
||||
OTA / Security / Safety
|
||||
```
|
||||
|
||||
* **Machine Constants** affect:
|
||||
|
||||
* Sensor initialization
|
||||
* Calibration
|
||||
* Communication
|
||||
* **Diagnostics** span all features
|
||||
* **Teardown** is a cross-cutting mechanism triggered by:
|
||||
|
||||
* OTA
|
||||
* MC update
|
||||
* Fatal faults
|
||||
|
||||
---
|
||||
|
||||
83
system_design/features/System Assumptions & Limitations.md
Normal file
83
system_design/features/System Assumptions & Limitations.md
Normal file
@@ -0,0 +1,83 @@
|
||||
## 1\. System Assumptions
|
||||
|
||||
### SA-01: Deployment Environment
|
||||
|
||||
* The Sensor Hub operates in an indoor poultry farm environment.
|
||||
|
||||
* Environmental conditions may include high humidity, dust, and ammonia presence.
|
||||
|
||||
|
||||
### SA-02: Power Availability
|
||||
|
||||
* The Sensor Hub is assumed to have continuous power.
|
||||
|
||||
* Short power interruptions may occur; system shall recover gracefully.
|
||||
|
||||
|
||||
### SA-03: Network Connectivity
|
||||
|
||||
* Wireless connectivity to the Main Hub may be intermittent.
|
||||
|
||||
* The Sensor Hub shall operate autonomously when disconnected.
|
||||
|
||||
|
||||
### SA-04: Trusted Provisioning
|
||||
|
||||
* Devices are assumed to be provisioned securely during manufacturing or installation.
|
||||
|
||||
* Cryptographic keys are assumed to be injected via a secure process.
|
||||
|
||||
|
||||
### SA-05: Time Synchronization
|
||||
|
||||
* System time is assumed to be synchronized periodically by the Main Hub.
|
||||
|
||||
* Temporary time drift is acceptable.
|
||||
|
||||
|
||||
## 2\. System Limitations
|
||||
|
||||
### SL-01: Local Processing Limits
|
||||
|
||||
* The Sensor Hub performs lightweight preprocessing only.
|
||||
|
||||
* Complex analytics and AI models are out of scope.
|
||||
|
||||
|
||||
### SL-02: User Interface Constraints
|
||||
|
||||
* The OLED display is intended for monitoring and diagnostics only.
|
||||
|
||||
* It is not a full configuration or management interface.
|
||||
|
||||
|
||||
### SL-03: Physical Security
|
||||
|
||||
* The Sensor Hub does not include physical tamper detection.
|
||||
|
||||
* Physical access is assumed to be restricted.
|
||||
|
||||
|
||||
### SL-04: Storage Constraints
|
||||
|
||||
* SD card storage capacity is finite.
|
||||
|
||||
* Data retention policies may result in data overwrite.
|
||||
|
||||
|
||||
### SL-05: Safety Classification
|
||||
|
||||
* The system is not classified as a safety-critical life-support system.
|
||||
|
||||
* Failures may impact farm performance but not human safety directly.
|
||||
|
||||
|
||||
## 3\. External Dependencies
|
||||
|
||||
* ESP32-S3 hardware platform
|
||||
|
||||
* ESP-IDF framework
|
||||
|
||||
* Supported sensors and communication modules
|
||||
|
||||
* Main Hub availability for OTA and configuration updates
|
||||
140
system_design/features/System_Requirements_Traceability.csv
Normal file
140
system_design/features/System_Requirements_Traceability.csv
Normal file
@@ -0,0 +1,140 @@
|
||||
Feature_ID,Feature_Name,Feature_Group,Sub_Feature_ID,Sub_Feature_Name,System_Requirement_ID,System_Requirement_Description
|
||||
F-DAQ-01,Multi-Sensor Data Acquisition,DAQ,F-DAQ-01,Multi-Sensor Data Acquisition,SR-DAQ-001,"The system shall support acquisition of data from multiple environmental sensor types simultaneously."
|
||||
F-DAQ-01,Multi-Sensor Data Acquisition,DAQ,F-DAQ-01,Multi-Sensor Data Acquisition,SR-DAQ-002,"The system shall provide a dedicated software driver abstraction for each supported sensor type."
|
||||
F-DAQ-01,Multi-Sensor Data Acquisition,DAQ,F-DAQ-01,Multi-Sensor Data Acquisition,SR-DAQ-003,"The system shall acquire sensor data only from sensors detected as present and enabled."
|
||||
F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-004,"The system shall sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples)."
|
||||
F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-005,"The system shall apply a local filtering mechanism to raw sensor samples to produce a single representative value."
|
||||
F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-006,"The system shall allow configuration of sampling count and filtering parameters via system configuration data (Machine Constants)."
|
||||
F-DAQ-02,High-Frequency Sampling and Local Filtering,DAQ,F-DAQ-02,High-Frequency Sampling and Local Filtering,SR-DAQ-010,"The system shall complete sensor acquisition cycle within a maximum of 100ms per sensor."
|
||||
F-DAQ-03,Timestamped Sensor Data Generation,DAQ,F-DAQ-03,Timestamped Sensor Data Generation,SR-DAQ-007,"The system shall associate each processed sensor value with a timestamp."
|
||||
F-DAQ-03,Timestamped Sensor Data Generation,DAQ,F-DAQ-03,Timestamped Sensor Data Generation,SR-DAQ-008,"The system shall generate timestamps after completion of filtering."
|
||||
F-DAQ-03,Timestamped Sensor Data Generation,DAQ,F-DAQ-03,Timestamped Sensor Data Generation,SR-DAQ-009,"The system shall include sensor identifier, sensor type, value, unit, timestamp, and validity status in each sensor data record."
|
||||
F-DAQ-04,Sensor State Management,DAQ,F-DAQ-04,Sensor State Management,SR-DAQ-011,"The system shall track sensor operational states (INIT, WARMUP, STABLE, DEGRADED, FAILED)."
|
||||
F-DAQ-04,Sensor State Management,DAQ,F-DAQ-04,Sensor State Management,SR-DAQ-012,"The system shall never publish raw sensor values without an accompanying validity flag indicating the current state."
|
||||
F-DAQ-04,Sensor State Management,DAQ,F-DAQ-04,Sensor State Management,SR-DAQ-013,"The system shall enforce sensor warmup durations (CO2: 30 seconds, Temperature: 5 seconds, others: sensor-specific)."
|
||||
F-DQC-01,Automatic Sensor Detection,DQC,F-DQC-01,Automatic Sensor Detection,SR-DQC-001,"The system shall detect the presence of each sensor using a dedicated hardware detection mechanism."
|
||||
F-DQC-01,Automatic Sensor Detection,DQC,F-DQC-01,Automatic Sensor Detection,SR-DQC-002,"The system shall perform sensor presence detection during system startup and after any reinitialization event."
|
||||
F-DQC-01,Automatic Sensor Detection,DQC,F-DQC-01,Automatic Sensor Detection,SR-DQC-003,"The system shall initialize only those sensors that are detected as present."
|
||||
F-DQC-02,Sensor Type Enforcement,DQC,F-DQC-02,Sensor Type Enforcement,SR-DQC-004,"The system shall assign each sensor slot to a predefined sensor type."
|
||||
F-DQC-02,Sensor Type Enforcement,DQC,F-DQC-02,Sensor Type Enforcement,SR-DQC-005,"The system shall verify that the detected sensor matches the expected sensor type for the slot."
|
||||
F-DQC-02,Sensor Type Enforcement,DQC,F-DQC-02,Sensor Type Enforcement,SR-DQC-006,"The system shall reject and report any sensor-slot mismatch as a diagnostic event."
|
||||
F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-007,"The system shall continuously monitor sensor responsiveness and signal validity during operation."
|
||||
F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-008,"The system shall detect sensor failures including disconnection, non-responsiveness, and invalid measurement ranges."
|
||||
F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-009,"The system shall mark a failed sensor as defective and exclude it from data reporting."
|
||||
F-DQC-03,Sensor Failure Detection,DQC,F-DQC-03,Sensor Failure Detection,SR-DQC-010,"The system shall report detected sensor failures to the Main Hub with timestamps and failure classification."
|
||||
F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-011,"The system shall maintain a Machine Constants dataset defining sensor configuration, calibration parameters, and communication identifiers."
|
||||
F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-012,"The system shall persist the Machine Constants dataset in non-volatile storage."
|
||||
F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-013,"The system shall load and apply Machine Constants during system initialization."
|
||||
F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-014,"The system shall support remote updates of the Machine Constants dataset initiated by the Main Hub."
|
||||
F-DQC-04,Machine Constants & Calibration Management,DQC,F-DQC-04,Machine Constants & Calibration Management,SR-DQC-015,"The system shall apply updated Machine Constants only after executing a controlled teardown and reinitialization sequence."
|
||||
F-DQC-05,Redundant Sensor Support,DQC,F-DQC-05,Redundant Sensor Support,SR-DQC-016,"The system shall support redundant sensors for critical parameters (CO2, NH3) using different technologies or interfaces."
|
||||
F-DQC-05,Redundant Sensor Support,DQC,F-DQC-05,Redundant Sensor Support,SR-DQC-017,"The system shall implement sensor fusion algorithm to combine redundant sensor data (average, weighted, or voting mechanism)."
|
||||
F-DQC-05,Redundant Sensor Support,DQC,F-DQC-05,Redundant Sensor Support,SR-DQC-018,"The system shall ensure that every critical parameter has two qualified sensor options to avoid common-mode failures."
|
||||
F-COM-01,Main Hub Communication,COM,F-COM-01,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."
|
||||
F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-002,"The system shall transmit sensor data, diagnostics, and system status information to the Main Hub via MQTT."
|
||||
F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-003,"The system shall receive commands, configuration updates, and firmware update requests from the Main Hub via MQTT."
|
||||
F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-004,"The system shall monitor and report the communication link status with the Main Hub."
|
||||
F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-011,"The system shall implement a heartbeat mechanism with 10-second interval and 30-second timeout."
|
||||
F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-012,"The system shall use CBOR encoding for all MQTT payloads."
|
||||
F-COM-01,Main Hub Communication,COM,F-COM-01,Main Hub Communication,SR-COM-013,"The system shall support automatic reconnection with exponential backoff on connection loss."
|
||||
F-COM-02,On-Demand Data Broadcasting,COM,F-COM-02,On-Demand Data Broadcasting,SR-COM-005,"The system shall support on-demand requests from the Main Hub for sensor data."
|
||||
F-COM-02,On-Demand Data Broadcasting,COM,F-COM-02,On-Demand Data Broadcasting,SR-COM-006,"The system shall respond to on-demand data requests with the most recent timestamped sensor data within 100ms."
|
||||
F-COM-02,On-Demand Data Broadcasting,COM,F-COM-02,On-Demand Data Broadcasting,SR-COM-007,"The system shall include data validity and sensor status information in on-demand responses."
|
||||
F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-008,"The system shall support limited peer-to-peer communication between Sensor Hubs using ESP-NOW."
|
||||
F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-009,"The system shall allow peer communication for basic coordination functions such as connectivity checks or time synchronization."
|
||||
F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-010,"The system shall ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations."
|
||||
F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-014,"The system shall encrypt all ESP-NOW peer communication using application-layer encryption (AES-128 minimum)."
|
||||
F-COM-03,Peer Sensor Hub Communication,COM,F-COM-03,Peer Sensor Hub Communication,SR-COM-015,"The system shall implement acknowledgment and retry mechanism for ESP-NOW peer communication."
|
||||
F-COM-04,Long-Range Fallback Communication,COM,F-COM-04,Long-Range Fallback Communication,SR-COM-016,"The system may support long-range fallback communication using LoRa or cellular (LTE-M/NB-IoT) for farm-scale distances."
|
||||
F-COM-04,Long-Range Fallback Communication,COM,F-COM-04,Long-Range Fallback Communication,SR-COM-017,"If implemented, long-range fallback communication shall be used only for emergency alerts and data backup, not for OTA updates."
|
||||
F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-001,"The system shall implement a diagnostic code framework for reporting system health, warnings, errors, and fatal faults."
|
||||
F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-002,"The system shall assign a unique diagnostic code to each detected fault or abnormal condition."
|
||||
F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-003,"The system shall classify diagnostic codes by severity level."
|
||||
F-DIAG-01,Diagnostic Code Management,DIAG,F-DIAG-01,Diagnostic Code Management,SR-DIAG-004,"The system shall associate each diagnostic event with a timestamp and source component."
|
||||
F-DIAG-02,Diagnostic Data Storage,DIAG,F-DIAG-02,Diagnostic Data Storage,SR-DIAG-005,"The system shall persist diagnostic events in non-volatile storage."
|
||||
F-DIAG-02,Diagnostic Data Storage,DIAG,F-DIAG-02,Diagnostic Data Storage,SR-DIAG-006,"The system shall retain diagnostic data across system resets and power cycles."
|
||||
F-DIAG-02,Diagnostic Data Storage,DIAG,F-DIAG-02,Diagnostic Data Storage,SR-DIAG-007,"The system shall implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy."
|
||||
F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-008,"The system shall provide a diagnostic session interface for accessing diagnostic data."
|
||||
F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-009,"The system shall allow authorized diagnostic sessions to retrieve stored diagnostic events."
|
||||
F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-010,"The system shall allow authorized diagnostic sessions to clear diagnostic records."
|
||||
F-DIAG-03,Diagnostic Session,DIAG,F-DIAG-03,Diagnostic Session,SR-DIAG-011,"The system shall ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations."
|
||||
F-DIAG-04,Layered Watchdog System,DIAG,F-DIAG-04,Layered Watchdog System,SR-DIAG-012,"The system shall implement Task Watchdog (Task WDT) to detect deadlocks in FreeRTOS tasks with a baseline timeout of 10 seconds."
|
||||
F-DIAG-04,Layered Watchdog System,DIAG,F-DIAG-04,Layered Watchdog System,SR-DIAG-013,"The system shall implement Interrupt Watchdog (Interrupt WDT) to detect hangs within ISRs with a baseline timeout of 3 seconds."
|
||||
F-DIAG-04,Layered Watchdog System,DIAG,F-DIAG-04,Layered Watchdog System,SR-DIAG-014,"The system shall implement RTC Watchdog (RTC WDT) as a final safety net for total system freezes with a baseline timeout of 30 seconds."
|
||||
F-DATA-01,Persistent Sensor Data Storage,DATA,F-DATA-01,Persistent Sensor Data Storage,SR-DATA-001,"The system shall persist timestamped sensor data in non-volatile storage."
|
||||
F-DATA-01,Persistent Sensor Data Storage,DATA,F-DATA-01,Persistent Sensor Data Storage,SR-DATA-002,"The system shall store sensor data together with sensor identifiers, timestamps, and validity status."
|
||||
F-DATA-01,Persistent Sensor Data Storage,DATA,F-DATA-01,Persistent Sensor Data Storage,SR-DATA-003,"The system shall support configurable data retention and overwrite policies."
|
||||
F-DATA-02,Data Persistence Abstraction (DP Component),DATA,F-DATA-02,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."
|
||||
F-DATA-02,Data Persistence Abstraction (DP Component),DATA,F-DATA-02,Data Persistence Abstraction (DP Component),SR-DATA-005,"The system shall prevent application and feature modules from directly accessing storage hardware."
|
||||
F-DATA-02,Data Persistence Abstraction (DP Component),DATA,F-DATA-02,Data Persistence Abstraction (DP Component),SR-DATA-006,"The DP component shall support serialization and deserialization of structured system data."
|
||||
F-DATA-03,Safe Data Handling During State Transitions,DATA,F-DATA-03,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."
|
||||
F-DATA-03,Safe Data Handling During State Transitions,DATA,F-DATA-03,Safe Data Handling During State Transitions,SR-DATA-008,"The system shall protect data integrity during firmware updates and configuration changes."
|
||||
F-DATA-03,Safe Data Handling During State Transitions,DATA,F-DATA-03,Safe Data Handling During State Transitions,SR-DATA-009,"The system shall verify successful data persistence before completing a state transition."
|
||||
F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-010,"The system shall detect brownout conditions using hardware brownout detector (BOD) at 3.0V threshold."
|
||||
F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-011,"The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection."
|
||||
F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-012,"The system shall complete data flush operations within supercapacitor runtime (1-2 seconds) during brownout."
|
||||
F-DATA-04,Power-Loss Data Protection,DATA,F-DATA-04,Power-Loss Data Protection,SR-DATA-013,"The system shall implement wear-aware batch writing to prevent SD card wear."
|
||||
F-OTA-01,OTA Update Negotiation,OTA,F-OTA-01,OTA Update Negotiation,SR-OTA-001,"The system shall support OTA update negotiation initiated by the Main Hub."
|
||||
F-OTA-01,OTA Update Negotiation,OTA,F-OTA-01,OTA Update Negotiation,SR-OTA-002,"The system shall verify internal readiness before accepting an OTA update request."
|
||||
F-OTA-01,OTA Update Negotiation,OTA,F-OTA-01,OTA Update Negotiation,SR-OTA-003,"The system shall explicitly acknowledge or reject OTA requests."
|
||||
F-OTA-02,Firmware Reception and Storage,OTA,F-OTA-02,Firmware Reception and Storage,SR-OTA-004,"The system shall receive firmware images over the established communication channel (HTTPS or MQTT)."
|
||||
F-OTA-02,Firmware Reception and Storage,OTA,F-OTA-02,Firmware Reception and Storage,SR-OTA-005,"The system shall store received firmware images in non-volatile storage (SD card) prior to validation."
|
||||
F-OTA-02,Firmware Reception and Storage,OTA,F-OTA-02,Firmware Reception and Storage,SR-OTA-006,"The system shall prevent overwriting the active firmware during firmware reception."
|
||||
F-OTA-03,Firmware Integrity Validation,OTA,F-OTA-03,Firmware Integrity Validation,SR-OTA-007,"The system shall validate the integrity of the received firmware image before activation using SHA-256 hash."
|
||||
F-OTA-03,Firmware Integrity Validation,OTA,F-OTA-03,Firmware Integrity Validation,SR-OTA-008,"The system shall reject firmware images that fail integrity validation."
|
||||
F-OTA-03,Firmware Integrity Validation,OTA,F-OTA-03,Firmware Integrity Validation,SR-OTA-009,"The system shall report firmware validation results to the Main Hub."
|
||||
F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-010,"The system shall execute a controlled teardown before firmware activation."
|
||||
F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-011,"The system shall persist critical runtime data and calibration data prior to firmware flashing."
|
||||
F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-012,"The system shall activate new firmware only after successful integrity validation."
|
||||
F-OTA-04,Safe Firmware Activation,OTA,F-OTA-04,Safe Firmware Activation,SR-OTA-013,"The system shall reboot into the new firmware after successful activation."
|
||||
F-OTA-05,A/B Partitioning with Rollback,OTA,F-OTA-05,A/B Partitioning with Rollback,SR-OTA-014,"The system shall implement A/B partitioning for safe firmware updates."
|
||||
F-OTA-05,A/B Partitioning with Rollback,OTA,F-OTA-05,A/B Partitioning with Rollback,SR-OTA-015,"The system shall automatically rollback to previous firmware if new firmware fails validation or health check."
|
||||
F-OTA-05,A/B Partitioning with Rollback,OTA,F-OTA-05,A/B Partitioning with Rollback,SR-OTA-016,"The system shall report rollback events to the Main Hub."
|
||||
F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-001,"The system shall verify the authenticity of the firmware image before execution during every boot cycle using Secure Boot V2."
|
||||
F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-002,"The system shall prevent execution of firmware images that fail cryptographic verification."
|
||||
F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-003,"The system shall enter BOOT_FAILURE state upon secure boot verification failure."
|
||||
F-SEC-01,Secure Boot,SEC,F-SEC-01,Secure Boot,SR-SEC-004,"The system shall protect the root-of-trust against modification (eFuse protection)."
|
||||
F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-005,"The system shall protect sensitive data stored in internal flash memory from unauthorized access using Flash Encryption (AES-256)."
|
||||
F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-006,"The system shall support encryption of sensitive data stored in external storage devices (SD card)."
|
||||
F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-007,"The system shall restrict access to cryptographic keys to authorized system components only."
|
||||
F-SEC-02,Secure Flash Storage,SEC,F-SEC-02,Secure Flash Storage,SR-SEC-008,"The system shall ensure data integrity for stored configuration and machine constant files."
|
||||
F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-009,"The system shall encrypt all communication with the Main Hub using TLS 1.2 with mutual authentication (mTLS)."
|
||||
F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-010,"The system shall ensure integrity and authenticity of all received and transmitted messages."
|
||||
F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-011,"The system shall use secure communication channels for OTA firmware updates."
|
||||
F-SEC-03,Encrypted Communication,SEC,F-SEC-03,Encrypted Communication,SR-SEC-012,"The system shall detect and report communication security violations."
|
||||
F-SEC-04,Security Violation Handling,SEC,F-SEC-04,Security Violation Handling,SR-SEC-013,"The system shall report security violations as FATAL diagnostic events."
|
||||
F-SEC-04,Security Violation Handling,SEC,F-SEC-04,Security Violation Handling,SR-SEC-014,"The system shall implement eFuse-based anti-rollback to prevent downgrade attacks."
|
||||
F-SEC-04,Security Violation Handling,SEC,F-SEC-04,Security Violation Handling,SR-SEC-015,"The system shall protect cryptographic keys during power loss and system resets."
|
||||
F-SYS-01,System State Management,SYS,F-SYS-01,System State Management,SR-SYS-001,"The system shall implement a defined finite state machine for operational control."
|
||||
F-SYS-01,System State Management,SYS,F-SYS-01,System State Management,SR-SYS-002,"The system shall restrict operations based on the current system state."
|
||||
F-SYS-01,System State Management,SYS,F-SYS-01,System State Management,SR-SYS-003,"The system shall notify system components of state transitions."
|
||||
F-SYS-02,Controlled Teardown Mechanism,SYS,F-SYS-02,Controlled Teardown Mechanism,SR-SYS-004,"The system shall execute a controlled teardown sequence before firmware or machine constant updates."
|
||||
F-SYS-02,Controlled Teardown Mechanism,SYS,F-SYS-02,Controlled Teardown Mechanism,SR-SYS-005,"The system shall persist all critical runtime data before completing teardown."
|
||||
F-SYS-02,Controlled Teardown Mechanism,SYS,F-SYS-02,Controlled Teardown Mechanism,SR-SYS-006,"The system shall prevent data corruption during teardown and reset operations."
|
||||
F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-007,"The system shall provide a local OLED display using I2C communication."
|
||||
F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-008,"The system shall display connectivity status, system state, sensor summary, and time/date."
|
||||
F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-009,"The system shall provide menu navigation using Up, Down, and Select buttons."
|
||||
F-SYS-03,Status Indication (OLED-Based HMI),SYS,F-SYS-03,Status Indication (OLED-Based HMI),SR-SYS-010,"The system shall provide diagnostic, sensor, and health information via the local menu."
|
||||
F-SYS-04,Debug & Engineering Sessions,SYS,F-SYS-04,Debug & Engineering Sessions,SR-SYS-011,"The system shall support diagnostic sessions for retrieving logs and system status."
|
||||
F-SYS-04,Debug & Engineering Sessions,SYS,F-SYS-04,Debug & Engineering Sessions,SR-SYS-012,"The system shall support debug sessions for controlled engineering operations."
|
||||
F-SYS-04,Debug & Engineering Sessions,SYS,F-SYS-04,Debug & Engineering Sessions,SR-SYS-013,"The system shall restrict debug actions to authorized sessions only."
|
||||
F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-014,"The system shall enforce GPIO discipline by avoiding strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O."
|
||||
F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-015,"The system shall ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V)."
|
||||
F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-016,"The system shall use ADC1 for all analog sensors when Wi-Fi is active (ADC2 is not available with Wi-Fi)."
|
||||
F-SYS-05,GPIO & Hardware Discipline,SYS,F-SYS-05,GPIO & Hardware Discipline,SR-SYS-017,"The system shall maintain a canonical GPIO map document as a single source of truth."
|
||||
F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-001,"The system shall monitor input voltage and detect brownout conditions below 3.0V."
|
||||
F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-002,"The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection."
|
||||
F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-003,"The system shall enter graceful shutdown mode during brownout conditions."
|
||||
F-PWR-01,Brownout Detection and Handling,PWR,F-PWR-01,Brownout Detection and Handling,SR-PWR-004,"The system shall perform clean reboot after power stabilization."
|
||||
F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-005,"The system shall recover gracefully from power interruptions."
|
||||
F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-006,"The system shall verify data integrity after power restoration."
|
||||
F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-007,"The system shall restore system state from persistent storage after power restoration."
|
||||
F-PWR-02,Power-Loss Recovery,PWR,F-PWR-02,Power-Loss Recovery,SR-PWR-008,"The system shall report power-loss and recovery events via diagnostics."
|
||||
F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-001,"The system shall provide a Sensor Abstraction Layer (SAL) for all sensor access."
|
||||
F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-002,"The system shall prevent application layer from directly accessing sensor hardware."
|
||||
F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-003,"The system shall track sensor state (INIT, WARMUP, STABLE, DEGRADED, FAILED)."
|
||||
F-HW-01,Sensor Abstraction Layer (SAL),HW,F-HW-01,Sensor Abstraction Layer (SAL),SR-HW-004,"The system shall provide sensor validation and health check functions."
|
||||
F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-005,"The system shall abstract all hardware interfaces (I2C, SPI, UART, ADC, GPIO) through driver layers."
|
||||
F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-006,"The system shall enforce GPIO discipline (no strapping pins, proper pull-ups, ADC1/ADC2 separation)."
|
||||
F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-007,"The system shall maintain a canonical GPIO map document."
|
||||
F-HW-02,Hardware Interface Abstraction,HW,F-HW-02,Hardware Interface Abstraction,SR-HW-008,"The system shall detect and report hardware resource conflicts."
|
||||
|
349
system_design/features/[COM] Communication Features.md
Normal file
349
system_design/features/[COM] Communication Features.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# Feature Engineering Specification
|
||||
|
||||
## Communication Features
|
||||
|
||||
**Feature Group ID:** FG-COM
|
||||
**Version:** 2.0
|
||||
**Date:** 2025-01-19
|
||||
**Scope:** Sensor Hub (Sub-Hub only)
|
||||
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
|
||||
**Applies To:** Indoor poultry farm sensor hubs
|
||||
**Dependencies:**
|
||||
|
||||
* Sensor Data Acquisition (FG-DAQ)
|
||||
* Data Quality & Calibration (FG-DQC)
|
||||
* Diagnostics & Health Monitoring (FG-DIAG)
|
||||
* Security & Safety Features (FG-SEC)
|
||||
|
||||
## 1. Purpose and Objectives
|
||||
|
||||
The **Communication Features** define how the Sensor Hub exchanges data and control information with external entities. These features ensure that sensor data, diagnostics, configuration updates, and control requests are transferred in a **reliable, secure, and deterministic manner**.
|
||||
|
||||
The communication layer is designed to:
|
||||
|
||||
* Support hierarchical farm architecture (Sensor Hub → Main Hub)
|
||||
* Enable on-demand and event-driven data transfer
|
||||
* Allow limited peer-to-peer communication between Sensor Hubs
|
||||
* Maintain robustness under intermittent connectivity
|
||||
|
||||
**Technology Stack:**
|
||||
- **Primary Uplink:** Wi-Fi 802.11n (2.4 GHz)
|
||||
- **Application Protocol:** MQTT over TLS 1.2
|
||||
- **Peer-to-Peer:** ESP-NOW
|
||||
- **Payload Encoding:** CBOR (Binary, versioned)
|
||||
- **Long-Range Fallback:** LoRa (External Module, optional)
|
||||
|
||||
## 2. Feature Overview and Relationships
|
||||
|
||||
| Feature ID | Feature Name | Primary Objective | Related Features |
|
||||
|------------|--------------|-------------------|------------------|
|
||||
| F-COM-01 | Main Hub Communication | Primary uplink/downlink with Main Hub | OTA, Diagnostics, MC Management |
|
||||
| F-COM-02 | On-Demand Data Broadcasting | Provide latest data upon request | DAQ, DP Stack |
|
||||
| F-COM-03 | Peer Sensor Hub Communication | Limited hub-to-hub coordination | System Management |
|
||||
| F-COM-04 | Long-Range Fallback Communication | Farm-scale connectivity resilience | System Management |
|
||||
|
||||
## 3. Functional Feature Descriptions
|
||||
|
||||
### 3.1 F-COM-01: Main Hub Communication
|
||||
|
||||
**Description**
|
||||
The Sensor Hub shall establish and maintain a bidirectional communication channel with the Main Hub using **MQTT over TLS 1.2**.
|
||||
|
||||
**Protocol Stack:**
|
||||
```
|
||||
Application Layer (MQTT)
|
||||
↓
|
||||
Transport Security Layer (TLS 1.2 / mTLS)
|
||||
↓
|
||||
Network Layer (Wi-Fi 802.11n 2.4 GHz)
|
||||
↓
|
||||
Physical Layer
|
||||
```
|
||||
|
||||
**MQTT Configuration:**
|
||||
- **Broker:** Main Hub / Edge Gateway
|
||||
- **QoS:** QoS 1 (At least once delivery)
|
||||
- **Retain:** Used for configuration topics only
|
||||
- **Payload:** CBOR (Binary, versioned for efficiency and compatibility)
|
||||
- **Keepalive:** 60 seconds (default)
|
||||
- **Maximum Message Size:** 8KB
|
||||
|
||||
**Topic Structure:**
|
||||
```
|
||||
/farm/{site_id}/{house_id}/{node_id}/data/{sensor_id}
|
||||
/farm/{site_id}/{house_id}/{node_id}/status/heartbeat
|
||||
/farm/{site_id}/{house_id}/{node_id}/status/system
|
||||
/farm/{site_id}/{house_id}/{node_id}/cmd/{command_type}
|
||||
/farm/{site_id}/{house_id}/{node_id}/diag/{severity}
|
||||
/farm/{site_id}/{house_id}/{node_id}/ota/{action}
|
||||
```
|
||||
|
||||
**Heartbeat Mechanism:**
|
||||
- **Interval:** 10 seconds
|
||||
- **Timeout:** 3 missed heartbeats (30 seconds) triggers "offline" status
|
||||
- **Payload includes:**
|
||||
- Uptime (seconds)
|
||||
- Firmware version (string)
|
||||
- Free heap memory (bytes)
|
||||
- RSSI (signal strength, dBm)
|
||||
- Error bitmap (32-bit)
|
||||
- System state
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Bidirectional communication
|
||||
* Command and response handling
|
||||
* Diagnostics and status reporting
|
||||
* Integration with OTA and MC updates
|
||||
* Store-and-forward messaging (handles intermittent connectivity)
|
||||
* Automatic reconnection with exponential backoff
|
||||
|
||||
**Wi-Fi Configuration:**
|
||||
- **Standard:** 802.11n (2.4 GHz)
|
||||
- **Minimum RSSI:** -85 dBm (connection threshold)
|
||||
- **Channel Selection:** Automatic (avoid interference)
|
||||
- **Power Management:** Active mode (no PSM for real-time requirements)
|
||||
|
||||
### 3.2 F-COM-02: On-Demand Data Broadcasting
|
||||
|
||||
**Description**
|
||||
The Sensor Hub shall support on-demand transmission of the most recent sensor data upon request from the Main Hub. This allows the Main Hub to query real-time conditions without waiting for periodic reporting cycles.
|
||||
|
||||
**Response Time:** Maximum 100ms from request to response transmission.
|
||||
|
||||
Data broadcasts include timestamped sensor values and associated validity status.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Request/response data exchange
|
||||
* Latest-value data delivery
|
||||
* Timestamp and validity inclusion
|
||||
* Low-latency response (≤100ms)
|
||||
|
||||
### 3.3 F-COM-03: Peer Sensor Hub Communication
|
||||
|
||||
**Description**
|
||||
Sensor Hubs shall be capable of limited peer-to-peer communication using **ESP-NOW** for coordination purposes such as connectivity checks, time synchronization assistance, or basic status exchange.
|
||||
|
||||
**ESP-NOW Configuration:**
|
||||
- **Protocol:** ESP-NOW (deterministic, low-latency)
|
||||
- **Range:** ~200m line-of-sight, ~50m through walls
|
||||
- **Maximum Peers:** 20
|
||||
- **Security:** Application-layer encryption (AES-128 minimum) required
|
||||
- **Acknowledgment:** Application-layer acknowledgment and retry mechanism
|
||||
|
||||
**Message Types:**
|
||||
- `PEER_PING`: Connectivity check
|
||||
- `PEER_PONG`: Connectivity response
|
||||
- `PEER_TIME_SYNC`: Time synchronization request
|
||||
- `PEER_TIME_RESP`: Time synchronization response
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Hub-to-hub message exchange
|
||||
* Minimal command set
|
||||
* No dependency on centralized infrastructure
|
||||
* Isolation from control logic
|
||||
* Encrypted communication (application-layer)
|
||||
|
||||
**Constraints:**
|
||||
- Peer communication SHALL NOT interfere with Main Hub communication
|
||||
- Peer communication SHALL be limited to coordination functions only
|
||||
- Maximum peer count: 20 (ESP-NOW limitation)
|
||||
|
||||
### 3.4 F-COM-04: Long-Range Fallback Communication [NEW]
|
||||
|
||||
**Description**
|
||||
The system supports optional long-range fallback communication using **LoRa (External Module)** for farm-scale distances where Wi-Fi may not reach.
|
||||
|
||||
**Note:** This feature is **optional** and requires cost-benefit analysis. Alternative: Cellular (LTE-M/NB-IoT) if farm has cellular coverage.
|
||||
|
||||
**LoRa Configuration (if implemented):**
|
||||
- **Module:** External LoRa module (e.g., SX1276, SX1262)
|
||||
- **Protocol:** LoRaWAN or raw LoRa
|
||||
- **Use Cases:** Emergency alerts, data backup (not for OTA updates)
|
||||
- **Data Rate:** Low (may not support OTA updates)
|
||||
|
||||
**Alternative Consideration:**
|
||||
- **Cellular (LTE-M/NB-IoT):** Higher data rate, better for OTA updates, more expensive but more reliable in some regions
|
||||
|
||||
## 4. System Requirements (Formal SHALL Statements)
|
||||
|
||||
### 4.1 Main Hub Communication
|
||||
|
||||
**SR-COM-001**
|
||||
The system shall support bidirectional communication between the Sensor Hub and the Main Hub using MQTT over TLS 1.2.
|
||||
|
||||
**SR-COM-002**
|
||||
The system shall transmit sensor data, diagnostics, and system status information to the Main Hub via MQTT.
|
||||
|
||||
**SR-COM-003**
|
||||
The system shall receive commands, configuration updates, and firmware update requests from the Main Hub via MQTT.
|
||||
|
||||
**SR-COM-004**
|
||||
The system shall monitor and report the communication link status with the Main Hub.
|
||||
|
||||
**SR-COM-011** [NEW]
|
||||
The system shall implement a heartbeat mechanism with 10-second interval and 30-second timeout.
|
||||
|
||||
**SR-COM-012** [NEW]
|
||||
The system shall use CBOR encoding for all MQTT payloads.
|
||||
|
||||
**SR-COM-013** [NEW]
|
||||
The system shall support automatic reconnection with exponential backoff on connection loss.
|
||||
|
||||
### 4.2 On-Demand Data Broadcasting
|
||||
|
||||
**SR-COM-005**
|
||||
The system shall support on-demand requests from the Main Hub for sensor data.
|
||||
|
||||
**SR-COM-006**
|
||||
The system shall respond to on-demand data requests with the most recent timestamped sensor data within 100ms.
|
||||
|
||||
**SR-COM-007**
|
||||
The system shall include data validity and sensor status information in on-demand responses.
|
||||
|
||||
### 4.3 Peer Sensor Hub Communication
|
||||
|
||||
**SR-COM-008**
|
||||
The system shall support limited peer-to-peer communication between Sensor Hubs using ESP-NOW.
|
||||
|
||||
**SR-COM-009**
|
||||
The system shall allow peer communication for basic coordination functions such as connectivity checks or time synchronization.
|
||||
|
||||
**SR-COM-010**
|
||||
The system shall ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations.
|
||||
|
||||
**SR-COM-014** [NEW]
|
||||
The system shall encrypt all ESP-NOW peer communication using application-layer encryption (AES-128 minimum).
|
||||
|
||||
**SR-COM-015** [NEW]
|
||||
The system shall implement acknowledgment and retry mechanism for ESP-NOW peer communication.
|
||||
|
||||
### 4.4 Long-Range Fallback Communication [NEW]
|
||||
|
||||
**SR-COM-016** [NEW]
|
||||
The system may support long-range fallback communication using LoRa or cellular (LTE-M/NB-IoT) for farm-scale distances.
|
||||
|
||||
**SR-COM-017** [NEW]
|
||||
If implemented, long-range fallback communication shall be used only for emergency alerts and data backup, not for OTA updates.
|
||||
|
||||
## 5. Technology Specifications
|
||||
|
||||
### 5.1 Wi-Fi 802.11n (2.4 GHz)
|
||||
|
||||
**Rationale:**
|
||||
- Native ESP32-S3 support
|
||||
- Existing farm infrastructure compatibility
|
||||
- Mature ESP-IDF drivers
|
||||
- High data rate for OTA firmware updates (150 Mbps theoretical, ~20-30 Mbps practical)
|
||||
- Good range and penetration for farm structures
|
||||
|
||||
**Configuration:**
|
||||
- **Standard:** 802.11n
|
||||
- **Frequency:** 2.4 GHz
|
||||
- **Minimum RSSI:** -85 dBm
|
||||
- **Channel Selection:** Automatic
|
||||
- **Power Management:** Active mode
|
||||
|
||||
### 5.2 MQTT Protocol
|
||||
|
||||
**Rationale:**
|
||||
- Store-and-forward messaging (handles intermittent connectivity gracefully)
|
||||
- Built-in keepalive mechanism (monitors connection health automatically)
|
||||
- QoS levels for delivery guarantees
|
||||
- Massive industrial adoption (SCADA, IIoT)
|
||||
- Native ESP-IDF support (esp_mqtt component)
|
||||
|
||||
**Configuration:**
|
||||
- **QoS Level:** 1 (At least once delivery)
|
||||
- **Retain Flag:** Used for configuration topics only
|
||||
- **Keepalive:** 60 seconds
|
||||
- **Maximum Message Size:** 8KB
|
||||
- **Broker Compatibility:** Mosquitto 2.x, HiveMQ, or compatible
|
||||
|
||||
### 5.3 TLS 1.2 / mTLS
|
||||
|
||||
**Rationale:**
|
||||
- Strong security (mutual authentication)
|
||||
- Industry standard
|
||||
- ESP-IDF native support (mbedTLS)
|
||||
- Prevents man-in-the-middle attacks
|
||||
|
||||
**Configuration:**
|
||||
- **TLS Version:** 1.2 (minimum)
|
||||
- **Authentication:** Mutual TLS (mTLS)
|
||||
- **Certificate:** Device-unique X.509 certificate
|
||||
- **Private Key:** Stored in eFuse or encrypted flash
|
||||
- **Maximum Certificate Size:** <2KB (ESP32-S3 optimization)
|
||||
|
||||
### 5.4 ESP-NOW
|
||||
|
||||
**Rationale:**
|
||||
- Deterministic, low-latency communication
|
||||
- No AP dependency
|
||||
- Native ESP32-S3 support
|
||||
- Low power consumption
|
||||
|
||||
**Configuration:**
|
||||
- **Maximum Peers:** 20
|
||||
- **Security:** Application-layer encryption (AES-128 minimum)
|
||||
- **Acknowledgment:** Application-layer implementation required
|
||||
|
||||
### 5.5 CBOR Encoding
|
||||
|
||||
**Rationale:**
|
||||
- Binary format (efficient, ~30-50% smaller than JSON)
|
||||
- Versioned payloads (backward compatibility)
|
||||
- Standardized (RFC 8949)
|
||||
- Good library support (TinyCBOR, QCBOR)
|
||||
|
||||
**Configuration:**
|
||||
- **Schema Versioning:** Required
|
||||
- **Maximum Payload Size:** 8KB per message type
|
||||
- **Schema Validation:** On Main Hub side
|
||||
|
||||
## 6. Traceability Mapping
|
||||
|
||||
### 6.1 Feature → System Requirement Mapping
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
F-COM-01 -->|Main Hub Communication| SR-COM-001
|
||||
F-COM-01 -->|Transmit Data| SR-COM-002
|
||||
F-COM-01 -->|Receive Commands| SR-COM-003
|
||||
F-COM-01 -->|Monitor Link Status| SR-COM-004
|
||||
F-COM-01 -->|Heartbeat| SR-COM-011
|
||||
F-COM-01 -->|CBOR Encoding| SR-COM-012
|
||||
F-COM-01 -->|Auto Reconnect| SR-COM-013
|
||||
|
||||
F-COM-02 -->|On-Demand Requests| SR-COM-005
|
||||
F-COM-02 -->|Respond with Data| SR-COM-006
|
||||
F-COM-02 -->|Include Validity Info| SR-COM-007
|
||||
|
||||
F-COM-03 -->|Peer Communication| SR-COM-008
|
||||
F-COM-03 -->|Peer Coordination| SR-COM-009
|
||||
F-COM-03 -->|Isolate Peer Traffic| SR-COM-010
|
||||
F-COM-03 -->|ESP-NOW Encryption| SR-COM-014
|
||||
F-COM-03 -->|ESP-NOW Acknowledgment| SR-COM-015
|
||||
|
||||
F-COM-04 -->|Long-Range Fallback| SR-COM-016
|
||||
F-COM-04 -->|Fallback Use Cases| SR-COM-017
|
||||
```
|
||||
|
||||
## 7. Engineering Notes and Constraints
|
||||
|
||||
* **MQTT Broker Compatibility:** Specify broker version (e.g., Mosquitto 2.x, HiveMQ)
|
||||
* **Message Size Limits:** Maximum 8KB per message
|
||||
* **Topic Naming:** Follow hierarchical structure `/farm/{site}/{house}/{node}/...`
|
||||
* **Security:** All communication encrypted via TLS 1.2 / mTLS (defined under Security Features)
|
||||
* **ESP-NOW Security:** Application-layer encryption required (AES-128 minimum)
|
||||
* **Communication failures** shall trigger diagnostics events but shall not block sensor acquisition
|
||||
* **LoRa Fallback:** Optional feature requiring cost-benefit analysis
|
||||
|
||||
## 8. Dependencies
|
||||
|
||||
* **Security Features:** TLS/mTLS implementation
|
||||
* **System Management:** State-aware communication restrictions
|
||||
* **Diagnostics:** Communication failure reporting
|
||||
* **Data Acquisition:** Sensor data for transmission
|
||||
339
system_design/features/[DAQ] Sensor Data Acquisition Features.md
Normal file
339
system_design/features/[DAQ] Sensor Data Acquisition Features.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# **ASF Sensor Hub**
|
||||
|
||||
## **Feature Engineering Specification**
|
||||
|
||||
## **Sensor Data Acquisition Features**
|
||||
|
||||
## **1\. Feature Overview**
|
||||
|
||||
### **Feature Name**
|
||||
|
||||
Sensor Data Acquisition Features
|
||||
|
||||
### **Feature ID**
|
||||
|
||||
FEAT-DAQ
|
||||
|
||||
### **Subsystem**
|
||||
|
||||
ASF Sensor Hub (Sub-Hub)
|
||||
|
||||
### **Target Platform**
|
||||
|
||||
ESP32-S3–based embedded system
|
||||
|
||||
### **Scope**
|
||||
|
||||
This feature defines the capabilities of the Sensor Hub related to:
|
||||
|
||||
* Environmental sensor data acquisition
|
||||
|
||||
* Local preprocessing and filtering
|
||||
|
||||
* Timestamping and preparation of sensor data for persistence and communication
|
||||
|
||||
|
||||
This feature **does NOT include**:
|
||||
|
||||
* Main Hub processing
|
||||
|
||||
* Cloud analytics
|
||||
|
||||
* Control logic
|
||||
|
||||
* OTA, diagnostics, or persistence mechanisms (referenced only as dependencies)
|
||||
|
||||
|
||||
## **2\. Purpose and Engineering Rationale**
|
||||
|
||||
Modern poultry farm automation systems require **high-resolution, reliable, and time-correlated environmental data** to enable:
|
||||
|
||||
* Accurate environmental control
|
||||
|
||||
* Early fault detection
|
||||
|
||||
* Advanced analytics and machine learning
|
||||
|
||||
|
||||
The Sensor Data Acquisition feature ensures:
|
||||
|
||||
* Deterministic sensor sampling
|
||||
|
||||
* Noise-resilient measurements
|
||||
|
||||
* Temporal traceability of data
|
||||
|
||||
* Decoupling of acquisition from communication and control
|
||||
|
||||
|
||||
This aligns with **distributed intelligence principles** used in leading international poultry automation systems.
|
||||
|
||||
## **3\. Feature Decomposition**
|
||||
|
||||
The Sensor Data Acquisition feature is decomposed into the following sub-features:
|
||||
|
||||
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Sub-Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Name</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Multi-Sensor Data Acquisition</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">High-Frequency Sampling and Local Filtering</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Timestamped Sensor Data Generation</p></td></tr></tbody></table></figure>
|
||||
|
||||
## **4\. Functional Description**
|
||||
|
||||
### **4.1 F-DAQ-01: Multi-Sensor Data Acquisition**
|
||||
|
||||
#### **Description**
|
||||
|
||||
The Sensor Hub acquires environmental data from multiple heterogeneous sensors connected to dedicated hardware interfaces.
|
||||
|
||||
#### **Supported Sensor Types**
|
||||
|
||||
* Temperature
|
||||
|
||||
* Relative Humidity
|
||||
|
||||
* Carbon Dioxide (CO₂)
|
||||
|
||||
* Ammonia (NH₃)
|
||||
|
||||
* Volatile Organic Compounds (VOC)
|
||||
|
||||
* Particulate Matter (PM)
|
||||
|
||||
* Light Intensity
|
||||
|
||||
|
||||
Each sensor:
|
||||
|
||||
* Is mapped to a predefined hardware slot
|
||||
|
||||
* Has a dedicated driver abstraction
|
||||
|
||||
* Can be independently enabled or disabled
|
||||
|
||||
|
||||
#### **Key Characteristics**
|
||||
|
||||
* Concurrent sensor handling
|
||||
|
||||
* Modular sensor driver architecture
|
||||
|
||||
* Runtime awareness of sensor presence
|
||||
|
||||
|
||||
### **4.2 F-DAQ-02: High-Frequency Sampling and Local Filtering**
|
||||
|
||||
#### **Description**
|
||||
|
||||
For each enabled sensor, the system performs multiple raw readings per acquisition cycle and applies a local filtering mechanism to produce a single representative value.
|
||||
|
||||
#### **Sampling Behavior**
|
||||
|
||||
* Each sensor is sampled **N times per cycle** (default: 10)
|
||||
|
||||
* Sampling occurs within a bounded time window
|
||||
|
||||
* Sampling frequency is configurable via Machine Constants
|
||||
|
||||
|
||||
#### **Filtering Behavior**
|
||||
|
||||
* Filtering is executed locally on the Sensor Hub
|
||||
|
||||
* Filtering algorithms are abstracted and replaceable
|
||||
|
||||
* Examples (non-exhaustive):
|
||||
|
||||
* Moving average
|
||||
|
||||
* Median filter
|
||||
|
||||
* Outlier rejection
|
||||
|
||||
|
||||
#### **Objective**
|
||||
|
||||
* Reduce sensor noise
|
||||
|
||||
* Improve data stability
|
||||
|
||||
* Avoid propagating raw sensor jitter upstream
|
||||
|
||||
|
||||
### **4.3 F-DAQ-03: Timestamped Sensor Data Generation**
|
||||
|
||||
#### **Description**
|
||||
|
||||
Each processed sensor value is associated with a timestamp generated by the Sensor Hub.
|
||||
|
||||
#### **Timestamp Characteristics**
|
||||
|
||||
* Generated after filtering completion
|
||||
|
||||
* Represents the effective measurement time
|
||||
|
||||
* Based on system time (RTC or synchronized clock)
|
||||
|
||||
|
||||
#### **Sensor Data Record**
|
||||
|
||||
Each record includes:
|
||||
|
||||
* Sensor ID
|
||||
|
||||
* Sensor type
|
||||
|
||||
* Filtered value
|
||||
|
||||
* Unit of measurement
|
||||
|
||||
* Timestamp
|
||||
|
||||
* Data validity status
|
||||
|
||||
|
||||
## **5\. Operational Flow**
|
||||
|
||||
### **Normal Acquisition Cycle**
|
||||
|
||||
1. Detect enabled sensors
|
||||
|
||||
2. Initialize sensor drivers (if not already active)
|
||||
|
||||
3. Perform high-frequency sampling per sensor
|
||||
|
||||
4. Apply local filtering
|
||||
|
||||
5. Generate timestamp
|
||||
|
||||
6. Create sensor data record
|
||||
|
||||
7. Forward data to:
|
||||
|
||||
* Data Persistence component
|
||||
|
||||
* Communication component (on request)
|
||||
|
||||
|
||||
## **6\. Constraints and Assumptions**
|
||||
|
||||
### **Constraints**
|
||||
|
||||
* Sensor acquisition must not block system-critical tasks
|
||||
|
||||
* Sampling and filtering must complete within a bounded cycle time
|
||||
|
||||
* Memory usage must be deterministic
|
||||
|
||||
|
||||
### **Assumptions**
|
||||
|
||||
* Sensor presence detection is handled by a separate feature
|
||||
|
||||
* Time synchronization is provided by another system component
|
||||
|
||||
* Storage and communication are decoupled from acquisition
|
||||
|
||||
|
||||
## **7\. Architecture Diagram (PlantUML)**
|
||||
|
||||
### **7.1 Sensor Hub Component Diagram**
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Sensor Hub"
|
||||
SD["Sensor Drivers"] --> SE["Sampling Engine"]
|
||||
SE --> FE["Filtering Engine"]
|
||||
FE --> TS["Timestamp Service"]
|
||||
TS --> DB["Sensor Data Buffer"]
|
||||
end
|
||||
SD -->|"raw samples"| SE
|
||||
SE -->|"sampled data"| FE
|
||||
FE -->|"filtered value"| TS
|
||||
TS -->|"timestamped record"| DB
|
||||
```
|
||||
|
||||
### **7.2 Acquisition Cycle Sequence Diagram**
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant S as Sensor Driver
|
||||
participant SE as Sampling Engine
|
||||
participant FE as Filtering Engine
|
||||
participant TS as Timestamp Service
|
||||
S ->> SE: read()
|
||||
loop N samples
|
||||
SE ->> S: sample()
|
||||
end
|
||||
SE ->> FE: raw sample set
|
||||
FE ->> TS: filtered value
|
||||
TS ->> FE: timestamp
|
||||
```
|
||||
|
||||
## **8\. Formal System SHALL Requirements**
|
||||
|
||||
### **8.1 Requirement Style**
|
||||
|
||||
* Each requirement uses **“The system shall …”**
|
||||
|
||||
* Each requirement has a unique ID
|
||||
|
||||
* Requirements are atomic and testable
|
||||
|
||||
|
||||
### **8.2 Requirements List**
|
||||
|
||||
#### **Multi-Sensor Acquisition**
|
||||
|
||||
* **SR-DAQ-001**
|
||||
The system shall support acquisition of data from multiple environmental sensor types simultaneously.
|
||||
|
||||
* **SR-DAQ-002**
|
||||
The system shall provide a dedicated software driver abstraction for each supported sensor type.
|
||||
|
||||
* **SR-DAQ-003**
|
||||
The system shall acquire sensor data only from sensors detected as present and enabled.
|
||||
|
||||
|
||||
#### **High-Frequency Sampling & Filtering**
|
||||
|
||||
* **SR-DAQ-004**
|
||||
The system shall sample each enabled sensor multiple times within a single acquisition cycle (default: 10 samples).
|
||||
|
||||
* **SR-DAQ-005**
|
||||
The system shall apply a local filtering mechanism to raw sensor samples to produce a single representative value.
|
||||
|
||||
* **SR-DAQ-006**
|
||||
The system shall allow configuration of sampling count and filtering parameters via system configuration data (Machine Constants).
|
||||
|
||||
* **SR-DAQ-010**
|
||||
The system shall complete sensor acquisition cycle within a maximum of 100ms per sensor.
|
||||
|
||||
|
||||
#### **Timestamped Data Generation**
|
||||
|
||||
* **SR-DAQ-007**
|
||||
The system shall associate each processed sensor value with a timestamp.
|
||||
|
||||
* **SR-DAQ-008**
|
||||
The system shall generate timestamps after completion of filtering.
|
||||
|
||||
* **SR-DAQ-009**
|
||||
The system shall include sensor identifier, sensor type, value, unit, timestamp, and validity status in each sensor data record.
|
||||
|
||||
#### **Sensor State Management**
|
||||
|
||||
* **SR-DAQ-011**
|
||||
The system shall track sensor operational states (INIT, WARMUP, STABLE, DEGRADED, FAILED).
|
||||
|
||||
* **SR-DAQ-012**
|
||||
The system shall never publish raw sensor values without an accompanying validity flag indicating the current state.
|
||||
|
||||
* **SR-DAQ-013**
|
||||
The system shall enforce sensor warmup durations (CO2: 30 seconds, Temperature: 5 seconds, others: sensor-specific).
|
||||
|
||||
|
||||
## **9\. Feature-to-Requirement Traceability**
|
||||
|
||||
| Feature ID | System Requirements |
|
||||
|------------|---------------------|
|
||||
| F-DAQ-01 | SR-DAQ-001, SR-DAQ-002, SR-DAQ-003 |
|
||||
| F-DAQ-02 | SR-DAQ-004, SR-DAQ-005, SR-DAQ-006, SR-DAQ-010 |
|
||||
| F-DAQ-03 | SR-DAQ-007, SR-DAQ-008, SR-DAQ-009 |
|
||||
| F-DAQ-04 | SR-DAQ-011, SR-DAQ-012, SR-DAQ-013 |
|
||||
@@ -0,0 +1,192 @@
|
||||
<macro class="toc op-uc-placeholder op-uc-toc">
|
||||
</macro>
|
||||
|
||||
# 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
|
||||
|
||||
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Persistent Sensor Data Storage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Store timestamped sensor data</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DAQ, COM</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Data Persistence Abstraction (DP)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Abstract storage access</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Application Layer</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Safe Data Handling During State Transitions</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Protect data during teardown</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OTA, System Mgmt</p></td></tr></tbody></table></figure>
|
||||
|
||||
## 3\. Functional Feature Descriptions
|
||||
|
||||
### 3.1 F-DATA-01: Persistent Sensor Data Storage
|
||||
|
||||
**Description**
|
||||
The system shall persist timestamped sensor data to non-volatile storage to support historical analysis, diagnostics correlation, and recovery scenarios.
|
||||
|
||||
Persistence may include:
|
||||
|
||||
* Filtered sensor values
|
||||
|
||||
* Timestamps
|
||||
|
||||
* Sensor validity and status metadata
|
||||
|
||||
|
||||
The persistence policy (frequency, retention window, overwrite behavior) is configurable and optimized for storage longevity and performance.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Non-volatile storage (SD card / NVM)
|
||||
|
||||
* Timestamped records
|
||||
|
||||
* Configurable retention policy
|
||||
|
||||
* Integration with DAQ and COM
|
||||
|
||||
|
||||
### 3.2 F-DATA-02: Data Persistence Abstraction (DP Component)
|
||||
|
||||
**Description**
|
||||
The system shall provide a **Data Persistence (DP) component** that abstracts storage access for all upper layers. Application and feature modules interact with the DP component rather than directly accessing storage hardware.
|
||||
|
||||
The DP component manages:
|
||||
|
||||
* Data model definitions
|
||||
|
||||
* Serialization and deserialization
|
||||
|
||||
* Storage backend selection
|
||||
|
||||
* Consistency and integrity guarantees
|
||||
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Unified persistence API
|
||||
|
||||
* Storage backend abstraction
|
||||
|
||||
* Centralized data ownership
|
||||
|
||||
* Reduced coupling between layers
|
||||
|
||||
|
||||
### 3.3 F-DATA-03: Safe Data Handling During State Transitions
|
||||
|
||||
**Description**
|
||||
The system shall ensure safe and deterministic handling of data during critical state transitions, including:
|
||||
|
||||
* Firmware updates (OTA)
|
||||
|
||||
* Machine Constants updates
|
||||
|
||||
* System resets
|
||||
|
||||
* Fatal error handling
|
||||
|
||||
|
||||
Before entering such transitions, the system executes a controlled data finalization process to flush buffers, persist critical state, and verify data integrity.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Controlled data flush
|
||||
|
||||
* Atomic write operations
|
||||
|
||||
* Data integrity checks
|
||||
|
||||
* Coordination with teardown mechanism
|
||||
|
||||
|
||||
## 4\. System Requirements (Formal SHALL Statements)
|
||||
|
||||
### 4.1 Persistent Sensor Data Storage
|
||||
|
||||
**SR-DATA-001**
|
||||
The system shall persist timestamped sensor data in non-volatile storage.
|
||||
|
||||
**SR-DATA-002**
|
||||
The system shall store sensor data together with sensor identifiers, timestamps, and validity status.
|
||||
|
||||
**SR-DATA-003**
|
||||
The system shall support configurable data retention and overwrite policies.
|
||||
|
||||
### 4.2 Data Persistence Abstraction (DP Component)
|
||||
|
||||
**SR-DATA-004**
|
||||
The system shall provide a Data Persistence (DP) component as the sole interface for persistent data access.
|
||||
|
||||
**SR-DATA-005**
|
||||
The system shall prevent application and feature modules from directly accessing storage hardware.
|
||||
|
||||
**SR-DATA-006**
|
||||
The DP component shall support serialization and deserialization of structured system data.
|
||||
|
||||
### 4.3 Safe Data Handling During State Transitions
|
||||
|
||||
**SR-DATA-007**
|
||||
The system shall ensure that all critical runtime data is flushed to non-volatile storage before entering a controlled teardown or reset.
|
||||
|
||||
**SR-DATA-008**
|
||||
The system shall protect data integrity during firmware updates and configuration changes.
|
||||
|
||||
**SR-DATA-009**
|
||||
The system shall verify successful data persistence before completing a state transition.
|
||||
|
||||
### 4.4 Power-Loss Data Protection [NEW]
|
||||
|
||||
**SR-DATA-010**
|
||||
The system shall detect brownout conditions using hardware brownout detector (BOD) at 3.0V threshold.
|
||||
|
||||
**SR-DATA-011**
|
||||
The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection.
|
||||
|
||||
**SR-DATA-012**
|
||||
The system shall complete data flush operations within supercapacitor runtime (1-2 seconds) during brownout.
|
||||
|
||||
**SR-DATA-013**
|
||||
The system shall implement wear-aware batch writing to prevent SD card wear.
|
||||
|
||||
## 5\. Feature ↔ System Requirement Mapping
|
||||
|
||||
| Feature ID | System Requirements |
|
||||
|------------|---------------------|
|
||||
| F-DATA-01 | SR-DATA-001, SR-DATA-002, SR-DATA-003 |
|
||||
| F-DATA-02 | SR-DATA-004, SR-DATA-005, SR-DATA-006 |
|
||||
| F-DATA-03 | SR-DATA-007, SR-DATA-008, SR-DATA-009 |
|
||||
| F-DATA-04 | SR-DATA-010, SR-DATA-011, SR-DATA-012, SR-DATA-013 |
|
||||
|
||||
## 6\. Engineering Notes
|
||||
|
||||
* The DP component aligns with your **DP Stack** already defined in the architecture.
|
||||
|
||||
* Atomic write strategies (e.g., temp file + rename) are recommended.
|
||||
|
||||
* Diagnostic events should be generated on persistence failures.
|
||||
|
||||
* Storage wear-leveling considerations apply for SD/NVM.
|
||||
|
||||
|
||||
##
|
||||
@@ -0,0 +1,183 @@
|
||||
<macro class="toc op-uc-placeholder op-uc-toc">
|
||||
</macro>
|
||||
|
||||
# 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
|
||||
|
||||
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Diagnostic Code Management</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Standardize fault and warning identification</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DQC, COM</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Diagnostic Data Storage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Persist diagnostic events</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DP Stack</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Diagnostic Session</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Engineer access to diagnostics</p></td><td class="op-uc-table--cell"><p class="op-uc-p">COM, System Mgmt</p></td></tr></tbody></table></figure>
|
||||
|
||||
## 3\. Functional Feature Descriptions
|
||||
|
||||
### 3.1 F-DIAG-01: Diagnostic Code Management
|
||||
|
||||
**Description**
|
||||
The system shall implement a structured diagnostic code framework to represent system health conditions, warnings, errors, and fatal faults.
|
||||
|
||||
Each diagnostic event is associated with:
|
||||
|
||||
* A unique diagnostic code
|
||||
|
||||
* Severity level (info, warning, error, fatal)
|
||||
|
||||
* A hierarchical root-cause classification
|
||||
|
||||
* Timestamp and source component
|
||||
|
||||
|
||||
This framework enables consistent fault handling across all system components.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Unique diagnostic code registry
|
||||
|
||||
* Severity classification
|
||||
|
||||
* Root-cause hierarchy
|
||||
|
||||
* Event-based reporting
|
||||
|
||||
|
||||
### 3.2 F-DIAG-02: Diagnostic Data Storage
|
||||
|
||||
**Description**
|
||||
The system shall persist diagnostic events in non-volatile storage to allow post-failure analysis and long-term health monitoring.
|
||||
|
||||
Stored diagnostics remain available across system resets and power cycles until explicitly cleared by an authorized diagnostic session or command.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Persistent storage of diagnostic events
|
||||
|
||||
* Timestamped records
|
||||
|
||||
* Bounded storage with overwrite policy
|
||||
|
||||
* Integration with DP / Persistence layer
|
||||
|
||||
|
||||
### 3.3 F-DIAG-03: Diagnostic Session
|
||||
|
||||
**Description**
|
||||
The system shall provide a diagnostic session that allows authorized engineers or tools to access diagnostic data, inspect system health, and perform maintenance operations.
|
||||
|
||||
The diagnostic session may be accessed locally or remotely via the communication interface and supports read and limited control operations.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Session-based access
|
||||
|
||||
* Read diagnostics and health data
|
||||
|
||||
* Clear diagnostic records
|
||||
|
||||
* Controlled command execution
|
||||
|
||||
|
||||
## 4\. System Requirements (Formal SHALL Statements)
|
||||
|
||||
### 4.1 Diagnostic Code Management
|
||||
|
||||
**SR-DIAG-001**
|
||||
The system shall implement a diagnostic code framework for reporting system health, warnings, errors, and fatal faults.
|
||||
|
||||
**SR-DIAG-002**
|
||||
The system shall assign a unique diagnostic code to each detected fault or abnormal condition.
|
||||
|
||||
**SR-DIAG-003**
|
||||
The system shall classify diagnostic codes by severity level.
|
||||
|
||||
**SR-DIAG-004**
|
||||
The system shall associate each diagnostic event with a timestamp and source component.
|
||||
|
||||
### 4.2 Diagnostic Data Storage
|
||||
|
||||
**SR-DIAG-005**
|
||||
The system shall persist diagnostic events in non-volatile storage.
|
||||
|
||||
**SR-DIAG-006**
|
||||
The system shall retain diagnostic data across system resets and power cycles.
|
||||
|
||||
**SR-DIAG-007**
|
||||
The system shall implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy.
|
||||
|
||||
### 4.3 Diagnostic Session
|
||||
|
||||
**SR-DIAG-008**
|
||||
The system shall provide a diagnostic session interface for accessing diagnostic data.
|
||||
|
||||
**SR-DIAG-009**
|
||||
The system shall allow authorized diagnostic sessions to retrieve stored diagnostic events.
|
||||
|
||||
**SR-DIAG-010**
|
||||
The system shall allow authorized diagnostic sessions to clear diagnostic records.
|
||||
|
||||
**SR-DIAG-011**
|
||||
The system shall ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations.
|
||||
|
||||
### 4.4 Layered Watchdog System [NEW]
|
||||
|
||||
**SR-DIAG-012**
|
||||
The system shall implement Task Watchdog (Task WDT) to detect deadlocks in FreeRTOS tasks with a baseline timeout of 10 seconds.
|
||||
|
||||
**SR-DIAG-013**
|
||||
The system shall implement Interrupt Watchdog (Interrupt WDT) to detect hangs within ISRs with a baseline timeout of 3 seconds.
|
||||
|
||||
**SR-DIAG-014**
|
||||
The system shall implement RTC Watchdog (RTC WDT) as a final safety net for total system freezes with a baseline timeout of 30 seconds.
|
||||
|
||||
## 5\. Feature ↔ System Requirement Mapping
|
||||
|
||||
| Feature ID | System Requirements |
|
||||
|------------|---------------------|
|
||||
| F-DIAG-01 | SR-DIAG-001, SR-DIAG-002, SR-DIAG-003, SR-DIAG-004 |
|
||||
| F-DIAG-02 | SR-DIAG-005, SR-DIAG-006, SR-DIAG-007 |
|
||||
| F-DIAG-03 | SR-DIAG-008, SR-DIAG-009, SR-DIAG-010, SR-DIAG-011 |
|
||||
| F-DIAG-04 | SR-DIAG-012, SR-DIAG-013, SR-DIAG-014 |
|
||||
|
||||
## 6\. Engineering Notes
|
||||
|
||||
* Diagnostic codes should be versioned to support firmware evolution.
|
||||
|
||||
* Diagnostic severity may be linked to LED indicators (green/yellow/red).
|
||||
|
||||
* Fatal diagnostics may trigger the teardown mechanism defined elsewhere.
|
||||
|
||||
* Security and access control for diagnostic sessions are handled under **Security & Safety Features**.
|
||||
|
||||
|
||||
##
|
||||
@@ -0,0 +1,197 @@
|
||||
<macro class="toc op-uc-placeholder op-uc-toc">
|
||||
</macro>
|
||||
|
||||
# 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.
|
||||
|
||||
<br>
|
||||
|
||||
<macro class="embedded-table op-uc-placeholder op-uc-embedded-table" data-query-props="{"columns[]":["id","subject","type","status","assignee","priority"],"showSums":false,"timelineVisible":false,"highlightingMode":"none","includeSubprojects":true,"showHierarchies":true,"groupBy":"","filters":"[{\"search\":{\"operator\":\"**\",\"values\":[\"DQC\"]}}]","sortBy":"[[\"id\",\"asc\"]]","timestamps":"PT0S"}">
|
||||
</macro>
|
||||
|
||||
## 2\. Feature Overview and Relationships
|
||||
|
||||
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Automatic Sensor Detection</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Detect connected sensors dynamically</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DAQ-01, F-DIAG-01</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Sensor Type Enforcement</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Prevent incorrect sensor-slot usage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-01</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Sensor Failure Detection</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Identify and isolate faulty sensors</p></td><td class="op-uc-table--cell"><p class="op-uc-p">F-DIAG-02</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DQC-04</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Machine Constants & Calibration Management</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Manage static configuration and calibration</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OTA, Persistence, Teardown</p></td></tr></tbody></table></figure>
|
||||
|
||||
## 3\. Functional Feature Descriptions
|
||||
|
||||
### 3.1 F-DQC-01: Automatic Sensor Detection
|
||||
|
||||
**Description**
|
||||
The Sensor Hub shall automatically detect which sensors are physically connected at runtime. Each sensor slot provides a dedicated detection mechanism (e.g., GPIO presence pin or ID signal) that allows the system to determine whether a sensor is installed.
|
||||
|
||||
Detected sensors are dynamically initialized and incorporated into the data acquisition workflow without requiring firmware changes.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Hardware-based presence detection
|
||||
|
||||
* Runtime sensor enumeration
|
||||
|
||||
* Dynamic initialization during boot or reconfiguration
|
||||
|
||||
* Integration with diagnostics and data acquisition
|
||||
|
||||
|
||||
### 3.2 F-DQC-02: Sensor Type Enforcement
|
||||
|
||||
**Description**
|
||||
Each physical sensor slot on the Sensor Hub is dedicated to a specific sensor type. The system enforces sensor-slot compatibility to prevent incorrect sensor insertion (e.g., humidity sensor in temperature slot).
|
||||
|
||||
This enforcement is achieved via electrical identification, pin mapping, or firmware configuration defined in Machine Constants.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Fixed sensor-to-slot mapping
|
||||
|
||||
* Sensor identity verification
|
||||
|
||||
* Rejection of invalid sensor configurations
|
||||
|
||||
* Diagnostic reporting of configuration violations
|
||||
|
||||
|
||||
### 3.3 F-DQC-03: Sensor Failure Detection
|
||||
|
||||
**Description**
|
||||
The Sensor Hub continuously monitors sensor behavior to detect failures such as disconnection, out-of-range values, non-responsive sensors, or abnormal signal patterns.
|
||||
|
||||
Detected sensor failures are classified, logged, timestamped, and reported to the Main Hub. Failed sensors are excluded from control and analytics workflows to prevent propagation of invalid data.
|
||||
|
||||
**Key Capabilities**
|
||||
|
||||
* Runtime health monitoring
|
||||
|
||||
* Failure classification
|
||||
|
||||
* Fault isolation
|
||||
|
||||
* Diagnostic event generation
|
||||
|
||||
|
||||
### 3.4 F-DQC-04: Machine Constants & 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.
|
||||
|
||||
### 4.5 Redundant Sensor Support [NEW]
|
||||
|
||||
**SR-DQC-016**
|
||||
The system shall support redundant sensors for critical parameters (CO2, NH3) using different technologies or interfaces.
|
||||
|
||||
**SR-DQC-017**
|
||||
The system shall implement sensor fusion algorithm to combine redundant sensor data (average, weighted, or voting mechanism).
|
||||
|
||||
**SR-DQC-018**
|
||||
The system shall ensure that every critical parameter has two qualified sensor options to avoid common-mode failures.
|
||||
|
||||
## 5\. Traceability Summary
|
||||
|
||||
| Feature ID | System Requirements |
|
||||
|------------|---------------------|
|
||||
| F-DQC-01 | SR-DQC-001, SR-DQC-002, SR-DQC-003 |
|
||||
| F-DQC-02 | SR-DQC-004, SR-DQC-005, SR-DQC-006 |
|
||||
| F-DQC-03 | SR-DQC-007, SR-DQC-008, SR-DQC-009, SR-DQC-010 |
|
||||
| F-DQC-04 | SR-DQC-011, SR-DQC-012, SR-DQC-013, SR-DQC-014, SR-DQC-015 |
|
||||
| F-DQC-05 | SR-DQC-016, SR-DQC-017, SR-DQC-018 |
|
||||
|
||||
##
|
||||
150
system_design/features/[HW] Hardware Abstraction Features.md
Normal file
150
system_design/features/[HW] Hardware Abstraction Features.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Hardware Abstraction Features
|
||||
|
||||
**Feature Group ID:** FG-HW
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
**Scope:** Sensor Hub (Sub-Hub only)
|
||||
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
|
||||
|
||||
## 1 Feature Overview
|
||||
|
||||
The **Hardware Abstraction Features** provide a clean separation between application logic and hardware interfaces. These features ensure hardware independence, maintainability, and testability of the system.
|
||||
|
||||
**Architecture Principle:** Application layer SHALL NOT access hardware directly (CFC-ARCH-01).
|
||||
|
||||
## 2 Scope and Assumptions
|
||||
|
||||
**In Scope**
|
||||
|
||||
* Sensor Abstraction Layer (SAL)
|
||||
* Hardware interface abstraction (I2C, SPI, UART, ADC, GPIO)
|
||||
* Storage interface abstraction (SD Card, NVM)
|
||||
* Display interface abstraction (OLED I2C)
|
||||
|
||||
**Out of Scope**
|
||||
|
||||
* Hardware driver implementation details (ESP-IDF drivers)
|
||||
* Hardware-specific optimizations (deferred to implementation)
|
||||
|
||||
## 3 Sub-Feature Breakdown
|
||||
|
||||
### 3.1 F-HW-01: Sensor Abstraction Layer (SAL)
|
||||
|
||||
#### Description
|
||||
|
||||
The system provides a Sensor Abstraction Layer (SAL) to ensure hardware independence and maintainability.
|
||||
|
||||
**Interface Functions:**
|
||||
- `sensor_read()`: Retrieve the latest value
|
||||
- `sensor_calibrate()`: Perform sensor-specific calibration
|
||||
- `sensor_validate()`: Check if the reading is within physical bounds
|
||||
- `sensor_health_check()`: Verify the operational status of the hardware
|
||||
- `sensor_getMetadata()`: Get sensor capabilities (range, accuracy, etc.)
|
||||
- `sensor_reset()`: Recovery from fault states
|
||||
|
||||
**Sensor State Management:**
|
||||
- **INIT:** Sensor initialization
|
||||
- **WARMUP:** Sensor warming up (not yet stable)
|
||||
- **STABLE:** Sensor operational and stable
|
||||
- **DEGRADED:** Sensor operational but degraded
|
||||
- **FAILED:** Sensor failed, not operational
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Abstract sensor hardware interfaces
|
||||
* Provide uniform sensor API
|
||||
* Manage sensor state
|
||||
* Handle sensor-specific calibration
|
||||
* Validate sensor readings
|
||||
|
||||
#### Constraints
|
||||
|
||||
* All sensor access must go through SAL
|
||||
* Application layer must not access sensor hardware directly
|
||||
* Sensor state must be tracked and reported
|
||||
|
||||
### 3.2 F-HW-02: Hardware Interface Abstraction
|
||||
|
||||
#### Description
|
||||
|
||||
The system abstracts all hardware interfaces through driver layers.
|
||||
|
||||
**Abstraction Layers:**
|
||||
- **I2C Interface:** Abstracted via ESP-IDF I2C driver wrapper
|
||||
- **SPI Interface:** Abstracted via ESP-IDF SPI driver wrapper
|
||||
- **UART Interface:** Abstracted via ESP-IDF UART driver wrapper
|
||||
- **ADC Interface:** Abstracted via ESP-IDF ADC driver wrapper
|
||||
- **GPIO Interface:** Abstracted via ESP-IDF GPIO driver wrapper
|
||||
- **Storage Interfaces:** SD Card (SDMMC), NVM (NVS)
|
||||
- **Display Interface:** OLED I2C
|
||||
|
||||
**GPIO Discipline:**
|
||||
- **No Strapping Pins:** Avoid using strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O
|
||||
- **I2C Pull-up Audit:** Ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V)
|
||||
- **No ADC2 with Wi-Fi:** ADC2 unit cannot be used when Wi-Fi is active. All analog sensors must be connected to ADC1 pins
|
||||
- **Canonical GPIO Map:** Single authoritative GPIO map document must be maintained
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Abstract hardware interfaces
|
||||
* Provide uniform API for hardware access
|
||||
* Enforce GPIO discipline
|
||||
* Manage hardware resource conflicts
|
||||
|
||||
#### Constraints
|
||||
|
||||
* Application layer must not access hardware directly
|
||||
* GPIO usage must follow canonical GPIO map
|
||||
* Hardware conflicts must be detected and reported
|
||||
|
||||
## 4 System Requirements (Formal SHALL Statements)
|
||||
|
||||
### Sensor Abstraction Layer Requirements
|
||||
|
||||
* **SR-HW-001**: The system shall provide a Sensor Abstraction Layer (SAL) for all sensor access.
|
||||
* **SR-HW-002**: The system shall prevent application layer from directly accessing sensor hardware.
|
||||
* **SR-HW-003**: The system shall track sensor state (INIT, WARMUP, STABLE, DEGRADED, FAILED).
|
||||
* **SR-HW-004**: The system shall provide sensor validation and health check functions.
|
||||
|
||||
### Hardware Interface Abstraction Requirements
|
||||
|
||||
* **SR-HW-005**: The system shall abstract all hardware interfaces (I2C, SPI, UART, ADC, GPIO) through driver layers.
|
||||
* **SR-HW-006**: The system shall enforce GPIO discipline (no strapping pins, proper pull-ups, ADC1/ADC2 separation).
|
||||
* **SR-HW-007**: The system shall maintain a canonical GPIO map document.
|
||||
* **SR-HW-008**: The system shall detect and report hardware resource conflicts.
|
||||
|
||||
## 5 Traceability Matrix (Feature → System Requirements)
|
||||
|
||||
| Feature ID | Related System Requirements |
|
||||
|------------|----------------------------|
|
||||
| F-HW-01 | SR-HW-001, SR-HW-002, SR-HW-003, SR-HW-004 |
|
||||
| F-HW-02 | SR-HW-005, SR-HW-006, SR-HW-007, SR-HW-008 |
|
||||
|
||||
## 6 Design & Implementation Notes (Non-Normative)
|
||||
|
||||
* **SAL Implementation:** Each sensor type implements SAL interface
|
||||
* **Driver Wrappers:** ESP-IDF drivers wrapped in application-specific abstraction layer
|
||||
* **GPIO Map:** Must be maintained as single source of truth
|
||||
* **Hardware Conflicts:** Runtime detection and reporting via diagnostics
|
||||
|
||||
## 7 Dependencies
|
||||
|
||||
* **ESP-IDF Drivers:** I2C, SPI, UART, ADC, GPIO, SDMMC, NVS
|
||||
* **System Management Features:** Hardware initialization and teardown
|
||||
* **Diagnostics Features:** Hardware fault reporting
|
||||
|
||||
## 8 GPIO Map Guidelines
|
||||
|
||||
**Strapping Pins (DO NOT USE):**
|
||||
- GPIO 0: Boot mode selection
|
||||
- GPIO 3: JTAG
|
||||
- GPIO 45: Strapping pin
|
||||
- GPIO 46: Strapping pin
|
||||
|
||||
**ADC Constraints:**
|
||||
- **ADC1:** Available when Wi-Fi is active
|
||||
- **ADC2:** NOT available when Wi-Fi is active (use ADC1 for all analog sensors)
|
||||
|
||||
**I2C Pull-up Requirements:**
|
||||
- **Physical Pull-ups:** 2.2kΩ - 4.7kΩ for 3.3V
|
||||
- **Software Pull-ups:** Not recommended for production (use physical pull-ups)
|
||||
236
system_design/features/[OTA] Firmware Update (OTA) Features.md
Normal file
236
system_design/features/[OTA] Firmware Update (OTA) Features.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Firmware Update (OTA) Features
|
||||
|
||||
**Feature Group ID:** FG-OTA
|
||||
**Version:** 2.0
|
||||
**Date:** 2025-01-19
|
||||
**Scope:** Sensor Hub (Sub-Hub only)
|
||||
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
|
||||
|
||||
## 1 Feature Overview
|
||||
|
||||
The **Firmware Update (OTA) Features** enable the Sensor Hub (Sub-Hub) to safely receive, validate, and activate new firmware images provided by the Main Hub.
|
||||
These features ensure **controlled firmware lifecycle management**, **data integrity**, **system availability**, and **fault containment** during firmware update operations.
|
||||
|
||||
The OTA process is designed to:
|
||||
|
||||
* Prevent unauthorized or corrupted firmware installation
|
||||
* Preserve critical system data and calibration information
|
||||
* Ensure recoverability in case of update failure
|
||||
* Minimize operational disruption
|
||||
|
||||
**Technology:** A/B Partitioning with automatic rollback, SHA-256 integrity verification
|
||||
|
||||
This feature set applies **only to the Sensor Hub (ESP32-S3 based)** and does not include cloud-side or Main Hub OTA logic.
|
||||
|
||||
## 2 Scope and Assumptions
|
||||
|
||||
### In Scope
|
||||
|
||||
* OTA negotiation and readiness handshake with Main Hub
|
||||
* Firmware image reception over secure communication (MQTT or HTTPS)
|
||||
* Temporary firmware storage on SD card
|
||||
* Firmware integrity verification (SHA-256 hash)
|
||||
* Controlled firmware activation and reboot
|
||||
* A/B partitioning with automatic rollback
|
||||
|
||||
### Out of Scope
|
||||
|
||||
* Firmware generation and signing
|
||||
* Cloud-side firmware distribution
|
||||
* Rollback policy definition (defined in this document)
|
||||
|
||||
## 3 Partition Layout
|
||||
|
||||
For a device with **8MB of flash**, the following partition layout is recommended:
|
||||
|
||||
| Partition | Size | Purpose |
|
||||
|-----------|------|---------|
|
||||
| **bootloader** | ~32KB | Initial boot code |
|
||||
| **partition_table** | ~4KB | Defines the flash layout |
|
||||
| **factory** | Optional | Minimal rescue firmware |
|
||||
| **ota_0** | 3.5 MB | Primary application slot |
|
||||
| **ota_1** | 3.5 MB | Secondary application slot for updates |
|
||||
| **nvs** | 64 KB | Encrypted Non-Volatile Storage for config |
|
||||
| **phy_init** | ~4KB | Physical layer initialization data |
|
||||
| **coredump** | 64 KB | Storage for crash logs and debugging |
|
||||
|
||||
**Total Used:** ~7.1MB (fits in 8MB flash)
|
||||
|
||||
## 4 Sub-Features
|
||||
|
||||
### 4.1 F-OTA-01: OTA Update Negotiation
|
||||
|
||||
**Description**
|
||||
This sub-feature governs the initial negotiation phase between the Sensor Hub and the Main Hub prior to any firmware transfer.
|
||||
The Sensor Hub validates its current operational state and explicitly signals readiness before accepting an OTA update.
|
||||
|
||||
**Readiness Validation:**
|
||||
- System state check (must be RUNNING, not WARNING/FAULT/SERVICE/SD_DEGRADED)
|
||||
- Storage availability check (SD card space, NVS space)
|
||||
- Power stability check
|
||||
- Communication link stability check
|
||||
|
||||
**Responsibilities**
|
||||
|
||||
* Receive OTA availability notification
|
||||
* Validate system readiness (power, storage, state)
|
||||
* Acknowledge or reject OTA request
|
||||
* Transition system into OTA_PREP state
|
||||
|
||||
### 4.2 F-OTA-02: Firmware Reception and Storage
|
||||
|
||||
**Description**
|
||||
This sub-feature handles the controlled reception of the firmware image from the Main Hub and its storage in non-volatile memory (SD card) without overwriting the currently running firmware.
|
||||
|
||||
**Download Method:**
|
||||
- **Protocol:** HTTPS or MQTT
|
||||
- **Chunk Size:** 4096 bytes (optimized for flash page size)
|
||||
- **Storage:** SD Card (temporary) before flashing to OTA partition
|
||||
|
||||
**Responsibilities**
|
||||
|
||||
* Receive firmware in chunks (4096 bytes per chunk)
|
||||
* Store firmware image on SD card (temporary)
|
||||
* Monitor transfer completeness
|
||||
* Prevent execution during download
|
||||
* Track download progress
|
||||
|
||||
### 4.3 F-OTA-03: Firmware Integrity Validation
|
||||
|
||||
**Description**
|
||||
This sub-feature validates the integrity and correctness of the received firmware image prior to activation, ensuring that corrupted or incomplete firmware is never flashed.
|
||||
|
||||
**Validation Method:**
|
||||
- **Integrity Check:** SHA-256 hash verification
|
||||
- **Size Validation:** Firmware size matches metadata
|
||||
- **Metadata Validation:** Partition table, version number
|
||||
|
||||
**Responsibilities**
|
||||
|
||||
* Perform integrity checks (SHA-256 hash)
|
||||
* Validate firmware size and metadata
|
||||
* Reject invalid firmware images
|
||||
* Report validation status to Main Hub
|
||||
|
||||
### 4.4 F-OTA-04: Safe Firmware Activation
|
||||
|
||||
**Description**
|
||||
This sub-feature manages the safe transition from the current firmware to the new firmware, ensuring all critical data is preserved and the system is left in a known safe state.
|
||||
|
||||
**Activation Sequence:**
|
||||
1. Execute controlled teardown
|
||||
2. Persist critical runtime data and calibration data
|
||||
3. Flash validated firmware image to inactive OTA partition
|
||||
4. Update partition table to boot from new partition
|
||||
5. Reboot system into new firmware
|
||||
6. Validate: System must boot and send health report
|
||||
7. Confirmation: Application must confirm stability within 60-120 seconds
|
||||
8. Failure: Automatic rollback to previous known-good version
|
||||
|
||||
**Responsibilities**
|
||||
|
||||
* Trigger teardown procedure
|
||||
* Persist runtime and calibration data
|
||||
* Flash validated firmware image
|
||||
* Reboot system into updated firmware
|
||||
|
||||
### 4.5 F-OTA-05: A/B Partitioning with Rollback [NEW]
|
||||
|
||||
**Description**
|
||||
The system implements A/B partitioning to support safe firmware updates with automatic rollback capability.
|
||||
|
||||
**Rollback Triggers:**
|
||||
- Boot failure after firmware activation
|
||||
- No health report within confirmation window (60-120 seconds)
|
||||
- Application crash during confirmation period
|
||||
- Manual rollback command from Main Hub
|
||||
|
||||
**Rollback Process:**
|
||||
1. Detect failure condition
|
||||
2. Mark new firmware as invalid
|
||||
3. Update partition table to boot from previous partition
|
||||
4. Reboot into previous known-good firmware
|
||||
5. Report rollback to Main Hub
|
||||
|
||||
## 5 OTA Policy
|
||||
|
||||
A formal policy ensures that updates are downloaded correctly and that the system can roll back if the new firmware is unstable.
|
||||
|
||||
| Step | Rule |
|
||||
|------|------|
|
||||
| **Download** | Conducted via HTTPS or MQTT in chunks |
|
||||
| **Chunk Size** | 4096 bytes (optimized for flash page size) |
|
||||
| **Integrity** | Verified using a full image SHA-256 hash |
|
||||
| **Validation** | System must boot and send a health report |
|
||||
| **Confirmation** | The application must confirm stability within 60-120 seconds |
|
||||
| **Failure** | Automatic rollback to the previous known-good version |
|
||||
|
||||
**OTA Duration:** Maximum 10 minutes (end-to-end)
|
||||
|
||||
## 6 System Requirements (Formal SHALL Statements)
|
||||
|
||||
### OTA Negotiation Requirements
|
||||
|
||||
* **SR-OTA-001**: The system shall support OTA update negotiation initiated by the Main Hub.
|
||||
* **SR-OTA-002**: The system shall verify internal readiness before accepting an OTA update request.
|
||||
* **SR-OTA-003**: The system shall explicitly acknowledge or reject OTA requests.
|
||||
|
||||
### Firmware Reception & Storage Requirements
|
||||
|
||||
* **SR-OTA-004**: The system shall receive firmware images over the established communication channel (HTTPS or MQTT).
|
||||
* **SR-OTA-005**: The system shall store received firmware images in non-volatile storage (SD card) prior to validation.
|
||||
* **SR-OTA-006**: The system shall prevent overwriting the active firmware during firmware reception.
|
||||
|
||||
### Firmware Integrity Requirements
|
||||
|
||||
* **SR-OTA-007**: The system shall validate the integrity of the received firmware image before activation using SHA-256 hash.
|
||||
* **SR-OTA-008**: The system shall reject firmware images that fail integrity validation.
|
||||
* **SR-OTA-009**: The system shall report firmware validation results to the Main Hub.
|
||||
|
||||
### Safe Activation Requirements
|
||||
|
||||
* **SR-OTA-010**: The system shall execute a controlled teardown before firmware activation.
|
||||
* **SR-OTA-011**: The system shall persist critical runtime data and calibration data prior to firmware flashing.
|
||||
* **SR-OTA-012**: The system shall activate new firmware only after successful integrity validation.
|
||||
* **SR-OTA-013**: The system shall reboot into the new firmware after successful activation.
|
||||
|
||||
### Rollback Requirements [NEW]
|
||||
|
||||
* **SR-OTA-014**: The system shall implement A/B partitioning for safe firmware updates.
|
||||
* **SR-OTA-015**: The system shall automatically rollback to previous firmware if new firmware fails validation or health check.
|
||||
* **SR-OTA-016**: The system shall report rollback events to the Main Hub.
|
||||
|
||||
## 7 Feature-to-Requirement Traceability
|
||||
|
||||
| Feature ID | Related System Requirements |
|
||||
|------------|----------------------------|
|
||||
| F-OTA-01 | SR-OTA-001, SR-OTA-002, SR-OTA-003 |
|
||||
| F-OTA-02 | SR-OTA-004, SR-OTA-005, SR-OTA-006 |
|
||||
| F-OTA-03 | SR-OTA-007, SR-OTA-008, SR-OTA-009 |
|
||||
| F-OTA-04 | SR-OTA-010, SR-OTA-011, SR-OTA-012, SR-OTA-013 |
|
||||
| F-OTA-05 | SR-OTA-014, SR-OTA-015, SR-OTA-016 |
|
||||
|
||||
## 8 Architectural Considerations (Informative)
|
||||
|
||||
* OTA logic shall be implemented as a **dedicated OTA Manager component**
|
||||
* Firmware storage shall be accessed via the **DP (Data Persistence) component**
|
||||
* OTA state transitions shall interact with:
|
||||
* Diagnostics subsystem
|
||||
* Machine Constants management
|
||||
* Teardown mechanism
|
||||
* OTA execution shall not block critical system diagnostics reporting
|
||||
* OTA operations SHALL NOT be allowed during WARNING, FAULT, SERVICE, or SD_DEGRADED states
|
||||
|
||||
## 9 Related Features
|
||||
|
||||
* **Persistence & Data Management Features (F-DATA-03)**
|
||||
* **Diagnostics & Health Monitoring Features**
|
||||
* **Security & Safety Features (Secure Boot, Secure Flash)**
|
||||
* **System Management Features (State Machine, Teardown)**
|
||||
|
||||
## 10 Closing the Gaps
|
||||
|
||||
This strategy directly addresses the following gaps:
|
||||
* **GAP-OTA-001:** Reliable image delivery (chunked download, MQTT/HTTPS)
|
||||
* **GAP-OTA-002:** Integrity and authenticity verification (SHA-256, Secure Boot)
|
||||
* **GAP-OTA-003:** Safe rollback mechanisms (A/B partitioning, automatic rollback)
|
||||
138
system_design/features/[PWR] Power & Fault Handling Features.md
Normal file
138
system_design/features/[PWR] Power & Fault Handling Features.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Power & Fault Handling Features
|
||||
|
||||
**Feature Group ID:** FG-PWR
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-01-19
|
||||
**Scope:** Sensor Hub (Sub-Hub only)
|
||||
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
|
||||
|
||||
## 1 Feature Overview
|
||||
|
||||
The **Power & Fault Handling Features** ensure that the Sensor Hub operates reliably under power fluctuations and recovers gracefully from power interruptions. These features protect critical data during brownouts and enable clean recovery after power restoration.
|
||||
|
||||
**Technology:**
|
||||
- **Brownout Detection:** Hardware brownout detector (BOD)
|
||||
- **Power-Loss Protection:** Supercapacitor (optional, recommended)
|
||||
- **RTC Backup:** External RTC battery (CR2032, optional)
|
||||
|
||||
## 2 Scope and Assumptions
|
||||
|
||||
**In Scope**
|
||||
|
||||
* Brownout detection and handling
|
||||
* Power-loss data protection
|
||||
* Graceful shutdown on power loss
|
||||
* Clean recovery after power restoration
|
||||
|
||||
**Out of Scope**
|
||||
|
||||
* Battery-powered operation (system assumes continuous power)
|
||||
* Power management for low-power modes (not applicable for real-time requirements)
|
||||
|
||||
## 3 Sub-Feature Breakdown
|
||||
|
||||
### 3.1 F-PWR-01: Brownout Detection and Handling
|
||||
|
||||
#### Description
|
||||
|
||||
The system monitors input voltage and takes immediate action if it drops below safe threshold.
|
||||
|
||||
**Configuration:**
|
||||
- **Brownout Threshold:** 3.0V (hardware-configurable)
|
||||
- **Detection:** Hardware brownout detector (BOD) in ESP32-S3
|
||||
- **ISR Action:** Set "Power Loss" flag and immediately flush critical buffers to NVS/SD
|
||||
- **Recovery:** Perform clean reboot once power is stable
|
||||
|
||||
**Hardware Support:**
|
||||
- **Supercapacitor (Recommended):** 0.5-1.0F for 1-2s at 3.3V
|
||||
- Provides runtime during brownout to complete data flush
|
||||
- Enables graceful shutdown
|
||||
- **External RTC Battery (Optional):** CR2032, 3V, 220mAh
|
||||
- Maintains time accuracy during power loss
|
||||
- Not required for basic operation
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Monitor input voltage
|
||||
* Detect brownout condition
|
||||
* Trigger immediate data flush
|
||||
* Enter graceful shutdown mode
|
||||
|
||||
#### Constraints
|
||||
|
||||
* Brownout detection must be hardware-based (ESP32-S3 BOD)
|
||||
* Data flush must complete within supercapacitor runtime (1-2 seconds)
|
||||
* System must reboot cleanly after power restoration
|
||||
|
||||
### 3.2 F-PWR-02: Power-Loss Recovery
|
||||
|
||||
#### Description
|
||||
|
||||
The system recovers gracefully from power interruptions (< 1 second).
|
||||
|
||||
**Recovery Behavior:**
|
||||
- Clean reboot after power stabilization
|
||||
- Data integrity verification
|
||||
- State restoration from persistent storage
|
||||
- Diagnostic event generation (if data loss detected)
|
||||
|
||||
**Recovery Sequence:**
|
||||
1. Power restoration detected
|
||||
2. Wait for power stabilization (100ms)
|
||||
3. Perform clean reboot
|
||||
4. Initialize system from persistent storage
|
||||
5. Verify data integrity
|
||||
6. Report recovery status via diagnostics
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Detect power restoration
|
||||
* Perform clean reboot
|
||||
* Restore system state from persistent storage
|
||||
* Verify data integrity
|
||||
* Report recovery status
|
||||
|
||||
## 4 System Requirements (Formal SHALL Statements)
|
||||
|
||||
### Brownout Detection Requirements
|
||||
|
||||
* **SR-PWR-001**: The system shall monitor input voltage and detect brownout conditions below 3.0V.
|
||||
* **SR-PWR-002**: The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection.
|
||||
* **SR-PWR-003**: The system shall enter graceful shutdown mode during brownout conditions.
|
||||
* **SR-PWR-004**: The system shall perform clean reboot after power stabilization.
|
||||
|
||||
### Power-Loss Recovery Requirements
|
||||
|
||||
* **SR-PWR-005**: The system shall recover gracefully from power interruptions.
|
||||
* **SR-PWR-006**: The system shall verify data integrity after power restoration.
|
||||
* **SR-PWR-007**: The system shall restore system state from persistent storage after power restoration.
|
||||
* **SR-PWR-008**: The system shall report power-loss and recovery events via diagnostics.
|
||||
|
||||
## 5 Traceability Matrix (Feature → System Requirements)
|
||||
|
||||
| Feature ID | Related System Requirements |
|
||||
|------------|----------------------------|
|
||||
| F-PWR-01 | SR-PWR-001, SR-PWR-002, SR-PWR-003, SR-PWR-004 |
|
||||
| F-PWR-02 | SR-PWR-005, SR-PWR-006, SR-PWR-007, SR-PWR-008 |
|
||||
|
||||
## 6 Design & Implementation Notes (Non-Normative)
|
||||
|
||||
* **Supercapacitor:** Recommended for production deployment to enable graceful shutdown
|
||||
* **RTC Battery:** Optional, improves time accuracy during power loss
|
||||
* **Brownout Threshold:** 3.0V is conservative; adjust based on power supply characteristics
|
||||
* **Data Flush Priority:** Critical data (calibration, diagnostics) must be flushed first
|
||||
* **Recovery Time:** System should recover within 5 seconds after power restoration
|
||||
|
||||
## 7 Dependencies
|
||||
|
||||
* **Persistence & Data Management Features** (data flush mechanism)
|
||||
* **Diagnostics Features** (power-loss event reporting)
|
||||
* **System Management Features** (graceful shutdown, state restoration)
|
||||
|
||||
## 8 Hardware Recommendations
|
||||
|
||||
| Component | Specification | Purpose |
|
||||
|-----------|---------------|---------|
|
||||
| **Supercapacitor** | 0.5-1.0F, 3.3V | Provides runtime during brownout for data flush |
|
||||
| **RTC Battery** | CR2032, 3V, 220mAh | Maintains time accuracy during power loss |
|
||||
| **Power Supply** | 3.3V ±5%, minimum 500mA | Stable power for reliable operation |
|
||||
281
system_design/features/[SEC] Security & Safety Features.md
Normal file
281
system_design/features/[SEC] Security & Safety Features.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# Security & Safety Features
|
||||
|
||||
**Feature Group ID:** FG-SEC
|
||||
**Version:** 2.0
|
||||
**Date:** 2025-01-19
|
||||
**Scope:** Sensor Hub (Sub-Hub only)
|
||||
**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
|
||||
|
||||
## 1 Feature Overview
|
||||
|
||||
The **Security & Safety Features** ensure that the Sensor Hub operates only with trusted firmware, protects sensitive data at rest, and guarantees confidentiality and integrity of all communications. These features are foundational and cross-cutting, supporting all other functional features (DAQ, DQC, COM, DIAG, DATA, OTA).
|
||||
|
||||
This feature set is designed to:
|
||||
|
||||
* Prevent execution of unauthorized or malicious firmware
|
||||
* Protect firmware, configuration, and machine constants stored in memory
|
||||
* Secure all communications with cryptographic mechanisms
|
||||
* Provide deterministic and auditable behavior in case of security violations
|
||||
|
||||
**Technology Stack:**
|
||||
- **Secure Boot:** Secure Boot V2 (hardware-enforced)
|
||||
- **Flash Encryption:** AES-256 (hardware-accelerated)
|
||||
- **Communication Security:** Mutual TLS (mTLS) with X.509 certificates
|
||||
- **Anti-Rollback:** eFuse-based version protection
|
||||
|
||||
## 2 Scope and Assumptions
|
||||
|
||||
**In Scope**
|
||||
|
||||
* Sensor Hub (ESP32-S3–based)
|
||||
* Boot process security
|
||||
* Flash and external storage protection
|
||||
* Communication security with Main Hub and peer Sensor Hubs
|
||||
* Device identity and authentication
|
||||
|
||||
**Out of Scope**
|
||||
|
||||
* Cloud server security policies
|
||||
* User identity management
|
||||
* Physical tamper detection hardware (optional future feature)
|
||||
|
||||
## 3 Sub-Feature Breakdown
|
||||
|
||||
### 3.1 F-SEC-01: Secure Boot
|
||||
|
||||
#### Description
|
||||
|
||||
Secure Boot ensures that only authenticated and authorized firmware images are executed on the Sensor Hub using **Secure Boot V2**. During system startup, the bootloader verifies the cryptographic signature of the firmware image before handing over execution.
|
||||
|
||||
If verification fails, the system enters **BOOT_FAILURE** state and prevents normal operation.
|
||||
|
||||
#### Implementation
|
||||
|
||||
**Secure Boot V2 Configuration:**
|
||||
- **Signature Algorithm:** RSA-3072 or ECDSA-P256
|
||||
- **Verification:** Hardware-enforced (ROM bootloader)
|
||||
- **Key Storage:** Root-of-trust key in eFuse (one-time programmable)
|
||||
- **Enforcement:** Every boot (cold or warm)
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Firmware authenticity verification
|
||||
* Root-of-trust enforcement
|
||||
* Prevention of downgrade or rollback attacks (via eFuse anti-rollback)
|
||||
|
||||
#### Constraints
|
||||
|
||||
* Must complete before any application code execution
|
||||
* Must be enforced on every boot (cold or warm)
|
||||
* Root-of-trust key is one-time programmable (eFuse)
|
||||
|
||||
### 3.2 F-SEC-02: Secure Flash Storage
|
||||
|
||||
#### Description
|
||||
|
||||
Secure Flash Storage protects sensitive data stored in internal flash and external storage (e.g., SD card) from unauthorized access or modification using **Flash Encryption**.
|
||||
|
||||
**Encryption Method:** AES-256 (hardware-accelerated)
|
||||
|
||||
Sensitive data includes:
|
||||
|
||||
* Firmware images
|
||||
* Machine constants
|
||||
* Calibration data
|
||||
* Cryptographic material
|
||||
* Persistent diagnostics and logs
|
||||
|
||||
#### Implementation
|
||||
|
||||
**Flash Encryption Configuration:**
|
||||
- **Algorithm:** AES-256
|
||||
- **Mode:** Release mode (recommended for production)
|
||||
- **Key Derivation:** Hardware-based (eFuse)
|
||||
- **Transparency:** Automatic decryption on read (transparent to application)
|
||||
|
||||
**External Storage Encryption:**
|
||||
- **SD Card:** Optional encryption for sensitive files (SWR-SEC-006)
|
||||
- **Encryption Method:** AES-256 (software-based for SD card)
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Encrypted storage of sensitive regions
|
||||
* Access control enforcement
|
||||
* Prevention of unauthorized read/write operations
|
||||
|
||||
#### Constraints
|
||||
|
||||
* Encryption must not compromise system boot reliability
|
||||
* Storage access must be mediated through controlled software components (e.g., DP component)
|
||||
|
||||
### 3.3 F-SEC-03: Encrypted Communication
|
||||
|
||||
#### Description
|
||||
|
||||
Encrypted Communication ensures that all data exchanged between the Sensor Hub and other entities (Main Hub, peer Sensor Hubs) is protected against eavesdropping, tampering, and impersonation using **Mutual TLS (mTLS)**.
|
||||
|
||||
This includes:
|
||||
|
||||
* Sensor data transmission
|
||||
* Diagnostics reporting
|
||||
* OTA negotiation and data transfer
|
||||
* Configuration and machine constant updates
|
||||
|
||||
#### Implementation
|
||||
|
||||
**Device Identity & Authentication:**
|
||||
- **Identity:** Device-unique X.509 certificate
|
||||
- **Private Key:** Stored securely in eFuse or encrypted flash
|
||||
- **Authentication:** Mutual TLS (mTLS) for all broker communications
|
||||
- **Provisioning:** Handled via secure factory or onboarding mode
|
||||
|
||||
**Key Lifecycle Management:**
|
||||
|
||||
| Phase | Mechanism |
|
||||
|-------|-----------|
|
||||
| **Manufacturing** | Injection of unique device certificate and private key |
|
||||
| **Operation** | Use of TLS session keys for encrypted communication |
|
||||
| **Rotation** | Certificate rotation managed on broker/server side |
|
||||
| **Revocation** | Certificate Revocation Lists (CRL) or broker-side denylists |
|
||||
|
||||
**Key Insight:**
|
||||
The ESP32-S3 is optimized to handle a single device certificate efficiently. It is recommended to avoid managing large certificate chains on the device itself to conserve resources.
|
||||
|
||||
**Certificate Constraints:**
|
||||
- **Maximum Certificate Size:** <2KB
|
||||
- **Certificate Format:** X.509 v3
|
||||
- **Key Algorithm:** RSA-2048 or ECDSA-P256
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Confidentiality of transmitted data
|
||||
* Integrity and authenticity verification
|
||||
* Secure session establishment
|
||||
|
||||
#### Constraints
|
||||
|
||||
* Must be compatible with ESP32-S3 cryptographic capabilities
|
||||
* Must support reconnection and key renewal mechanisms
|
||||
* Certificate size must be optimized for ESP32-S3
|
||||
|
||||
### 3.4 F-SEC-04: Security Violation Handling [NEW]
|
||||
|
||||
#### Description
|
||||
|
||||
The system detects and reports security violations with appropriate responses.
|
||||
|
||||
**Security Violation Types:**
|
||||
- Secure boot failures
|
||||
- Authentication failures
|
||||
- Message tampering
|
||||
- Unauthorized access attempts
|
||||
- Certificate validation failures
|
||||
|
||||
**Response Actions:**
|
||||
- Secure boot failure → BOOT_FAILURE state
|
||||
- Authentication failure → FATAL diagnostic event, connection rejection
|
||||
- Message tampering → ERROR diagnostic event (escalates to FATAL if persistent)
|
||||
- Unauthorized access → FATAL diagnostic event, access denial
|
||||
|
||||
## 4 Functional Flow Overview
|
||||
|
||||
### Secure Boot Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Power as Power On
|
||||
participant ROM as ROM Bootloader
|
||||
participant SecureBoot as Secure Boot V2
|
||||
participant App as Application
|
||||
|
||||
Power->>ROM: System Reset
|
||||
ROM->>SecureBoot: Load Firmware
|
||||
SecureBoot->>SecureBoot: Verify Signature
|
||||
alt Signature Valid
|
||||
SecureBoot->>App: Jump to Application
|
||||
else Signature Invalid
|
||||
SecureBoot->>SecureBoot: Enter BOOT_FAILURE State
|
||||
end
|
||||
```
|
||||
|
||||
### Secure Communication Flow (mTLS)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant SH as Sensor Hub
|
||||
participant Broker as Main Hub Broker
|
||||
|
||||
SH->>Broker: TLS Client Hello + Certificate
|
||||
Broker->>SH: TLS Server Hello + Certificate
|
||||
SH->>SH: Verify Server Certificate
|
||||
Broker->>Broker: Verify Client Certificate
|
||||
alt Both Valid
|
||||
SH->>Broker: TLS Session Established
|
||||
SH->>Broker: Encrypted Data Exchange
|
||||
else Invalid Certificate
|
||||
SH->>SH: Reject Connection, Log FATAL
|
||||
end
|
||||
```
|
||||
|
||||
## 5 System SHALL Requirements (Formal)
|
||||
|
||||
### Secure Boot Requirements
|
||||
|
||||
* **SR-SEC-001**: The system shall verify the authenticity of the firmware image before execution during every boot cycle using Secure Boot V2.
|
||||
* **SR-SEC-002**: The system shall prevent execution of firmware images that fail cryptographic verification.
|
||||
* **SR-SEC-003**: The system shall enter BOOT_FAILURE state upon secure boot verification failure.
|
||||
* **SR-SEC-004**: The system shall protect the root-of-trust against modification (eFuse protection).
|
||||
|
||||
### Secure Flash Storage Requirements
|
||||
|
||||
* **SR-SEC-005**: The system shall protect sensitive data stored in internal flash memory from unauthorized access using Flash Encryption (AES-256).
|
||||
* **SR-SEC-006**: The system shall support encryption of sensitive data stored in external storage devices (SD card).
|
||||
* **SR-SEC-007**: The system shall restrict access to cryptographic keys to authorized system components only.
|
||||
* **SR-SEC-008**: The system shall ensure data integrity for stored configuration and machine constant files.
|
||||
|
||||
### Encrypted Communication Requirements
|
||||
|
||||
* **SR-SEC-009**: The system shall encrypt all communication with the Main Hub using TLS 1.2 with mutual authentication (mTLS).
|
||||
* **SR-SEC-010**: The system shall ensure integrity and authenticity of all received and transmitted messages.
|
||||
* **SR-SEC-011**: The system shall use secure communication channels for OTA firmware updates.
|
||||
* **SR-SEC-012**: The system shall detect and report communication security violations.
|
||||
|
||||
### Security Violation Handling Requirements [NEW]
|
||||
|
||||
* **SR-SEC-013**: The system shall report security violations as FATAL diagnostic events.
|
||||
* **SR-SEC-014**: The system shall implement eFuse-based anti-rollback to prevent downgrade attacks.
|
||||
* **SR-SEC-015**: The system shall protect cryptographic keys during power loss and system resets.
|
||||
|
||||
## 6 Traceability Matrix (Feature → System Requirements)
|
||||
|
||||
| Feature ID | Related System Requirements |
|
||||
|------------|----------------------------|
|
||||
| F-SEC-01 | SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 |
|
||||
| F-SEC-02 | SR-SEC-005, SR-SEC-006, SR-SEC-007, SR-SEC-008 |
|
||||
| F-SEC-03 | SR-SEC-009, SR-SEC-010, SR-SEC-011, SR-SEC-012 |
|
||||
| F-SEC-04 | SR-SEC-013, SR-SEC-014, SR-SEC-015 |
|
||||
|
||||
## 7 Design & Implementation Notes (Non-Normative)
|
||||
|
||||
* **Secure Boot V2:** Mandatory for production deployment. Key management and signing infrastructure must be documented.
|
||||
* **Flash Encryption:** Release mode recommended for production. Development mode available for debugging.
|
||||
* **Key Provisioning:** Should occur during manufacturing or secure onboarding. HSM or secure signing server required.
|
||||
* **Certificate Lifecycle:** Certificate rotation and revocation must be managed on broker/server side.
|
||||
* **eFuse Anti-Rollback:** Version numbering strategy must be carefully defined (eFuse is one-time programmable).
|
||||
* **Security Failures:** Should integrate with the Diagnostics & Health Monitoring feature set.
|
||||
* **Security Features:** Must be active before any sensor data acquisition or communication begins (CFC-SEC-01).
|
||||
|
||||
## 8 Dependencies
|
||||
|
||||
* **OTA Features** (for secure firmware updates)
|
||||
* **Communication Features** (transport layer for mTLS)
|
||||
* **Diagnostics Features** (security fault reporting)
|
||||
* **Persistence & DP Component** (secure storage abstraction)
|
||||
* **System Management** (BOOT_FAILURE state handling)
|
||||
|
||||
## 9 Industrial Standards Compliance
|
||||
|
||||
* **Secure Boot V2:** Industry standard for production-ready industrial embedded systems
|
||||
* **Flash Encryption:** Hardware-accelerated AES-256 (industry standard)
|
||||
* **mTLS:** Industry standard for device authentication
|
||||
* **X.509 Certificates:** Standard certificate format (RFC 5280)
|
||||
326
system_design/features/[SYS] System Management Features.md
Normal file
326
system_design/features/[SYS] System Management Features.md
Normal file
@@ -0,0 +1,326 @@
|
||||
<macro class="toc op-uc-placeholder op-uc-toc">
|
||||
</macro>
|
||||
|
||||
#
|
||||
System Management Features
|
||||
|
||||
## Sensor Hub (Sub-Hub) Scope
|
||||
|
||||
## 1 Feature Overview
|
||||
|
||||
The **System Management Features** provide deterministic control over the Sensor Hub’s operational lifecycle, runtime state visibility, controlled shutdown behavior, and engineering interaction capabilities.
|
||||
|
||||
This feature group is responsible for:
|
||||
|
||||
* Managing system operational states and transitions
|
||||
|
||||
* Ensuring safe teardown during updates or failures
|
||||
|
||||
* Providing local human–machine interaction via OLED display and buttons
|
||||
|
||||
* Supporting engineering/debug sessions for diagnostics and maintenance
|
||||
|
||||
|
||||
These features act as the **supervisory layer** governing all other functional domains (DAQ, DQC, COM, DIAG, DATA, OTA, SEC).
|
||||
|
||||
## 2 Scope and Assumptions
|
||||
|
||||
**In Scope**
|
||||
|
||||
* ESP32-S3 Sensor Hub
|
||||
|
||||
* OLED-based local UI (I2C)
|
||||
|
||||
* Physical input buttons
|
||||
|
||||
* Controlled state transitions and teardown
|
||||
|
||||
* Debug and engineering access
|
||||
|
||||
|
||||
**Out of Scope**
|
||||
|
||||
* Main Hub UI
|
||||
|
||||
* Cloud dashboards
|
||||
|
||||
* User authentication / role management
|
||||
|
||||
|
||||
## 3 Sub-Feature Breakdown
|
||||
|
||||
### 3.1 F-SYS-01: System State Management
|
||||
|
||||
#### Description
|
||||
|
||||
System State Management defines and controls the operational states of the Sensor Hub and governs all valid transitions between them.
|
||||
|
||||
The system operates as a **finite state machine (FSM)** with deterministic behavior.
|
||||
|
||||
#### Typical System States
|
||||
|
||||
* **INIT** – Hardware and software initialization
|
||||
|
||||
* **RUNNING** – Normal sensor acquisition and communication
|
||||
|
||||
* **WARNING** – Non-fatal fault detected, degraded operation
|
||||
|
||||
* **FAULT** – Fatal error, core functionality disabled
|
||||
|
||||
* **OTA\_UPDATE** – Firmware update in progress
|
||||
|
||||
* **MC\_UPDATE** – Machine constants update in progress
|
||||
|
||||
* **TEARDOWN** – Controlled shutdown sequence
|
||||
|
||||
* **IDLE / SERVICE** – Engineering or diagnostic interaction
|
||||
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Enforce valid state transitions
|
||||
|
||||
* Notify dependent components of state changes
|
||||
|
||||
* Prevent unsafe operations during restricted states
|
||||
|
||||
|
||||
### 3.2 F-SYS-02: Controlled Teardown Mechanism
|
||||
|
||||
#### Description
|
||||
|
||||
The Controlled Teardown Mechanism ensures that the Sensor Hub transitions safely from an active state into reset, update, or shutdown without data loss or corruption.
|
||||
|
||||
Teardown is triggered by:
|
||||
|
||||
* Firmware update
|
||||
|
||||
* Machine constant update
|
||||
|
||||
* Fatal system fault
|
||||
|
||||
* Manual engineering command
|
||||
|
||||
|
||||
#### Teardown Sequence (Mandatory)
|
||||
|
||||
1. Stop sensor acquisition tasks
|
||||
|
||||
2. Flush pending data via DP component
|
||||
|
||||
3. Persist calibration, diagnostics, and runtime state
|
||||
|
||||
4. Close communication sessions
|
||||
|
||||
5. Release hardware resources
|
||||
|
||||
6. Enter target state (reset, OTA, idle)
|
||||
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Guarantee data consistency
|
||||
|
||||
* Ensure deterministic shutdown behavior
|
||||
|
||||
* Prevent flash or SD corruption
|
||||
|
||||
|
||||
### 3.3 F-SYS-03: Status Indication (OLED-Based HMI)
|
||||
|
||||
#### Description
|
||||
|
||||
The Sensor Hub provides local system visibility using an **OLED display connected via I2C**, replacing LED indicators.
|
||||
|
||||
The display, together with **three physical buttons (Up / Down / Select)**, forms a minimal local Human–Machine Interface (HMI).
|
||||
|
||||
#### Default Information Displayed (Main Screen)
|
||||
|
||||
1. **Connectivity status**
|
||||
|
||||
* Connected / Disconnected
|
||||
|
||||
* Signal strength (RSSI) if available
|
||||
|
||||
2. **System status**
|
||||
|
||||
* Current system state (RUNNING, WARNING, FAULT, OTA, etc.)
|
||||
|
||||
3. **Connected sensors**
|
||||
|
||||
* Count and/or summary status
|
||||
|
||||
4. **Time and date**
|
||||
|
||||
* Synchronized system time
|
||||
|
||||
|
||||
#### Menu Navigation Behavior
|
||||
|
||||
* **Select button**
|
||||
|
||||
* From main screen → opens menu
|
||||
|
||||
* From submenu → returns to main screen
|
||||
|
||||
* **Up / Down buttons**
|
||||
|
||||
* Navigate menu entries
|
||||
|
||||
* Scroll within pages if applicable
|
||||
|
||||
|
||||
#### Menu Structure
|
||||
|
||||
**Main Menu**
|
||||
|
||||
* **Diagnostics**
|
||||
|
||||
* Lists active and stored diagnostic codes
|
||||
|
||||
* Displays occurrence count per diagnostic
|
||||
|
||||
* **Sensors**
|
||||
|
||||
* Lists all detected sensors
|
||||
|
||||
* Displays sensor type and configuration status
|
||||
|
||||
* **Health**
|
||||
|
||||
* Displays SD card usage
|
||||
|
||||
* Displays overall system health indicators
|
||||
|
||||
|
||||
#### Responsibilities
|
||||
|
||||
* Provide real-time system visibility
|
||||
|
||||
* Support local inspection without external tools
|
||||
|
||||
* Reflect system state and diagnostics accurately
|
||||
|
||||
|
||||
### 3.4 F-SYS-04: Debug & 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.
|
||||
|
||||
### GPIO & Hardware Discipline [NEW]
|
||||
|
||||
* **SR-SYS-014**: The system shall enforce GPIO discipline by avoiding strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O.
|
||||
* **SR-SYS-015**: The system shall ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V).
|
||||
* **SR-SYS-016**: The system shall use ADC1 for all analog sensors when Wi-Fi is active (ADC2 is not available with Wi-Fi).
|
||||
* **SR-SYS-017**: The system shall maintain a canonical GPIO map document as a single source of truth.
|
||||
|
||||
## 6 Traceability Matrix
|
||||
|
||||
| Feature ID | System Requirements |
|
||||
|------------|---------------------|
|
||||
| F-SYS-01 | SR-SYS-001, SR-SYS-002, SR-SYS-003 |
|
||||
| F-SYS-02 | SR-SYS-004, SR-SYS-005, SR-SYS-006 |
|
||||
| F-SYS-03 | SR-SYS-007, SR-SYS-008, SR-SYS-009, SR-SYS-010 |
|
||||
| F-SYS-04 | SR-SYS-011, SR-SYS-012, SR-SYS-013 |
|
||||
| F-SYS-05 | SR-SYS-014, SR-SYS-015, SR-SYS-016, SR-SYS-017 |
|
||||
|
||||
## 7 Dependencies
|
||||
|
||||
* Diagnostics & Health Monitoring Features
|
||||
|
||||
* Persistence & DP Component
|
||||
|
||||
* Communication Features
|
||||
|
||||
* Security & Safety Features
|
||||
|
||||
* OTA Features
|
||||
|
||||
|
||||
##
|
||||
252
system_design/specifications/Failure_Handling_Model.md
Normal file
252
system_design/specifications/Failure_Handling_Model.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Failure Handling Model Specification
|
||||
|
||||
**Document Type:** Normative System Specification
|
||||
**Scope:** Sensor Hub (Sub-Hub) Fault Detection, Classification, and Recovery
|
||||
**Traceability:** SR-DIAG-001 through SR-DIAG-011, SR-SYS-002, SR-SYS-004
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the fault taxonomy, escalation rules, recovery behaviors, and integration with the system state machine. All components SHALL adhere to this failure handling model.
|
||||
|
||||
## 2. Fault Taxonomy
|
||||
|
||||
### 2.1 Severity Levels
|
||||
|
||||
| Severity | Code | Description | State Impact | Recovery Behavior |
|
||||
|----------|------|-------------|--------------|-------------------|
|
||||
| **INFO** | `DIAG_SEV_INFO` | Informational event, no action required | None | Log only |
|
||||
| **WARNING** | `DIAG_SEV_WARNING` | Non-critical fault, degraded operation | `RUNNING` → `WARNING` | Continue with reduced functionality |
|
||||
| **ERROR** | `DIAG_SEV_ERROR` | Critical fault, feature disabled | Feature-specific | Feature isolation, retry logic |
|
||||
| **FATAL** | `DIAG_SEV_FATAL` | System-critical fault, core functionality disabled | `RUNNING` → `FAULT` | Controlled teardown, recovery attempt |
|
||||
|
||||
### 2.2 Fault Categories
|
||||
|
||||
| Category | Description | Examples | Typical Severity |
|
||||
|----------|-------------|----------|------------------|
|
||||
| **SENSOR** | Sensor hardware or communication failure | Disconnection, out-of-range, non-responsive | WARNING (single), ERROR (multiple), FATAL (all) |
|
||||
| **COMMUNICATION** | Network or protocol failure | Link loss, timeout, authentication failure | WARNING (temporary), ERROR (persistent), FATAL (critical) |
|
||||
| **STORAGE** | Persistence or storage medium failure | SD card failure, NVM corruption, write failure | WARNING (degraded), ERROR (persistent), FATAL (critical) |
|
||||
| **SECURITY** | Security violation or authentication failure | Secure boot failure, key corruption, unauthorized access | FATAL (always) |
|
||||
| **SYSTEM** | System resource or configuration failure | Memory exhaustion, task failure, configuration error | ERROR (recoverable), FATAL (unrecoverable) |
|
||||
| **OTA** | Firmware update failure | Validation failure, transfer error, flash error | ERROR (retry), FATAL (rollback) |
|
||||
| **CALIBRATION** | Calibration or machine constants failure | Invalid MC, calibration error, sensor mismatch | WARNING (single), ERROR (critical) |
|
||||
|
||||
## 3. Diagnostic Code Structure
|
||||
|
||||
### 3.1 Diagnostic Code Format
|
||||
|
||||
```
|
||||
DIAG-<CATEGORY>-<COMPONENT>-<NUMBER>
|
||||
```
|
||||
|
||||
- **CATEGORY:** Two-letter code (SN, CM, ST, SC, SY, OT, CL)
|
||||
- **COMPONENT:** Component identifier (e.g., TEMP, HUM, CO2, NET, SD, OTA)
|
||||
- **NUMBER:** Unique fault number (0001-9999)
|
||||
|
||||
### 3.2 Diagnostic Code Registry
|
||||
|
||||
| Code | Severity | Category | Component | Description |
|
||||
|------|----------|----------|-----------|-------------|
|
||||
| `DIAG-SN-TEMP-0001` | WARNING | SENSOR | Temperature | Temperature sensor disconnected |
|
||||
| `DIAG-SN-TEMP-0002` | ERROR | SENSOR | Temperature | Temperature sensor out of range |
|
||||
| `DIAG-SN-TEMP-0003` | FATAL | SENSOR | Temperature | All temperature sensors failed |
|
||||
| `DIAG-CM-NET-0001` | WARNING | COMMUNICATION | Network | Main Hub link temporarily lost |
|
||||
| `DIAG-CM-NET-0002` | ERROR | COMMUNICATION | Network | Main Hub link persistently lost |
|
||||
| `DIAG-ST-SD-0001` | WARNING | STORAGE | SD Card | SD card write failure (retry successful) |
|
||||
| `DIAG-ST-SD-0002` | ERROR | STORAGE | SD Card | SD card persistent write failure |
|
||||
| `DIAG-ST-SD-0003` | FATAL | STORAGE | SD Card | SD card corruption detected |
|
||||
| `DIAG-SC-BOOT-0001` | FATAL | SECURITY | Secure Boot | Secure boot verification failed |
|
||||
| `DIAG-SY-MEM-0001` | ERROR | SYSTEM | Memory | Memory allocation failure |
|
||||
| `DIAG-OT-FW-0001` | ERROR | OTA | Firmware | Firmware integrity validation failed |
|
||||
| `DIAG-CL-MC-0001` | WARNING | CALIBRATION | Machine Constants | Invalid sensor slot configuration |
|
||||
|
||||
## 4. Fault Detection Rules
|
||||
|
||||
### 4.1 Sensor Fault Detection
|
||||
|
||||
| Condition | Detection Method | Severity Assignment |
|
||||
|-----------|------------------|-------------------|
|
||||
| Sensor disconnected | Hardware presence signal | WARNING (if other sensors available) |
|
||||
| Sensor non-responsive | Communication timeout (3 retries) | ERROR (if critical sensor) |
|
||||
| Sensor out of range | Value validation against limits | WARNING (if single occurrence), ERROR (if persistent) |
|
||||
| All sensors failed | Count of failed sensors = total | FATAL |
|
||||
|
||||
### 4.2 Communication Fault Detection
|
||||
|
||||
| Condition | Detection Method | Severity Assignment |
|
||||
|-----------|------------------|-------------------|
|
||||
| Link temporarily lost | Heartbeat timeout (< 30s) | WARNING |
|
||||
| Link persistently lost | Heartbeat timeout (> 5 minutes) | ERROR |
|
||||
| Authentication failure | Security layer rejection | FATAL |
|
||||
| Protocol error | Message parsing failure (3 consecutive) | ERROR |
|
||||
|
||||
### 4.3 Storage Fault Detection
|
||||
|
||||
| Condition | Detection Method | Severity Assignment |
|
||||
|-----------|------------------|-------------------|
|
||||
| Write failure (retry successful) | Write operation with retry | WARNING |
|
||||
| Write failure (persistent) | Write operation failure (3 retries) | ERROR |
|
||||
| SD card corruption | File system check failure | FATAL |
|
||||
| Storage full | Available space < threshold | WARNING |
|
||||
|
||||
### 4.4 Security Fault Detection
|
||||
|
||||
| Condition | Detection Method | Severity Assignment |
|
||||
|-----------|------------------|-------------------|
|
||||
| Secure boot failure | Boot verification failure | FATAL (always) |
|
||||
| Key corruption | Cryptographic key validation failure | FATAL |
|
||||
| Unauthorized access | Authentication failure (3 attempts) | FATAL |
|
||||
| Message tampering | Integrity check failure | ERROR (if persistent → FATAL) |
|
||||
|
||||
## 5. Escalation Rules
|
||||
|
||||
### 5.1 Severity Escalation
|
||||
|
||||
| Current Severity | Escalation Trigger | New Severity | State Transition |
|
||||
|------------------|-------------------|--------------|-----------------|
|
||||
| INFO | N/A | N/A | None |
|
||||
| WARNING | Same fault persists > 5 minutes | ERROR | `WARNING` → `WARNING` (feature degraded) |
|
||||
| WARNING | Multiple warnings (≥3) | ERROR | `WARNING` → `WARNING` (feature degraded) |
|
||||
| WARNING | Critical feature affected | FATAL | `WARNING` → `FAULT` |
|
||||
| ERROR | Same fault persists > 10 minutes | FATAL | `RUNNING` → `FAULT` |
|
||||
| ERROR | Cascading failures (≥2 features) | FATAL | `RUNNING` → `FAULT` |
|
||||
| FATAL | N/A | N/A | `RUNNING` → `FAULT` |
|
||||
|
||||
### 5.2 Cascading Failure Detection
|
||||
|
||||
A cascading failure is detected when:
|
||||
- Multiple independent features fail simultaneously
|
||||
- Failure in one feature causes failure in another
|
||||
- System resource exhaustion (memory, CPU, storage)
|
||||
|
||||
**Response:** Immediate escalation to FATAL, transition to `FAULT` state.
|
||||
|
||||
## 6. Recovery Behaviors
|
||||
|
||||
### 6.1 Recovery Strategies by Severity
|
||||
|
||||
| Severity | Recovery Strategy | Retry Logic | State Impact |
|
||||
|----------|------------------|-------------|--------------|
|
||||
| **INFO** | None | N/A | None |
|
||||
| **WARNING** | Automatic retry, degraded operation | 3 retries with exponential backoff | Continue in `WARNING` state |
|
||||
| **ERROR** | Feature isolation, automatic retry | 3 retries, then manual intervention | Feature disabled, system continues |
|
||||
| **FATAL** | Controlled teardown, recovery attempt | Single recovery attempt, then manual | `FAULT` → `TEARDOWN` → `INIT` |
|
||||
|
||||
### 6.2 Recovery Time Limits
|
||||
|
||||
| Fault Type | Maximum Recovery Time | Recovery Action |
|
||||
|------------|----------------------|----------------|
|
||||
| Sensor (WARNING) | 5 minutes | Automatic retry, sensor exclusion |
|
||||
| Communication (WARNING) | 30 seconds | Automatic reconnection |
|
||||
| Storage (WARNING) | 10 seconds | Retry write operation |
|
||||
| Sensor (ERROR) | Manual intervention | Sensor marked as failed |
|
||||
| Communication (ERROR) | Manual intervention | Communication feature disabled |
|
||||
| Storage (ERROR) | Manual intervention | Persistence disabled, system continues |
|
||||
| FATAL (any) | 60 seconds | Controlled teardown and recovery attempt |
|
||||
|
||||
### 6.3 Latching Behavior
|
||||
|
||||
| Severity | Latching Rule | Clear Condition |
|
||||
|----------|--------------|----------------|
|
||||
| **INFO** | Not latched | Overwritten by new event |
|
||||
| **WARNING** | Latched until cleared | Fault condition cleared + manual clear OR automatic clear after 1 hour |
|
||||
| **ERROR** | Latched until cleared | Manual clear via diagnostic session OR system reset |
|
||||
| **FATAL** | Latched until cleared | Manual clear via diagnostic session OR system reset |
|
||||
|
||||
## 7. Fault Reporting
|
||||
|
||||
### 7.1 Reporting Channels
|
||||
|
||||
| Severity | Local HMI | Diagnostic Log | Main Hub | Diagnostic Session |
|
||||
|----------|-----------|----------------|----------|-------------------|
|
||||
| **INFO** | Optional | Yes | No | Yes |
|
||||
| **WARNING** | Yes (status indicator) | Yes | Yes (periodic) | Yes |
|
||||
| **ERROR** | Yes (status indicator) | Yes | Yes (immediate) | Yes |
|
||||
| **FATAL** | Yes (status indicator) | Yes | Yes (immediate) | Yes |
|
||||
|
||||
### 7.2 Diagnostic Event Structure
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint32_t diagnostic_code; // Unique diagnostic code
|
||||
diag_severity_t severity; // INFO, WARNING, ERROR, FATAL
|
||||
uint64_t timestamp; // System timestamp (microseconds)
|
||||
const char* source_component; // Component identifier
|
||||
uint32_t occurrence_count; // Number of occurrences
|
||||
bool is_latched; // Latching status
|
||||
fault_category_t category; // SENSOR, COMMUNICATION, etc.
|
||||
} diagnostic_event_t;
|
||||
```
|
||||
|
||||
## 8. Integration with State Machine
|
||||
|
||||
### 8.1 Fault-to-State Mapping
|
||||
|
||||
| Fault Severity | Current State | Target State | Transition Trigger |
|
||||
|----------------|---------------|--------------|-------------------|
|
||||
| INFO | Any | Same | None (no state change) |
|
||||
| WARNING | `RUNNING` | `WARNING` | First WARNING fault |
|
||||
| WARNING | `WARNING` | `WARNING` | Additional WARNING (latched) |
|
||||
| ERROR | `RUNNING` | `RUNNING` | Feature isolation, continue |
|
||||
| ERROR | `WARNING` | `WARNING` | Feature isolation, continue |
|
||||
| FATAL | `RUNNING` | `FAULT` | First FATAL fault |
|
||||
| FATAL | `WARNING` | `FAULT` | Escalation to FATAL |
|
||||
| FATAL | `FAULT` | `FAULT` | Additional FATAL (latched) |
|
||||
|
||||
### 8.2 State-Dependent Fault Handling
|
||||
|
||||
| State | Fault Handling Behavior |
|
||||
|-------|------------------------|
|
||||
| `INIT` | Boot-time faults → `BOOT_FAILURE` if security-related |
|
||||
| `RUNNING` | Full fault detection and handling |
|
||||
| `WARNING` | Fault escalation monitoring, recovery attempts |
|
||||
| `FAULT` | Fault logging only, recovery attempt preparation |
|
||||
| `OTA_PREP` | OTA-related faults only, others deferred |
|
||||
| `OTA_UPDATE` | OTA progress faults only |
|
||||
| `TEARDOWN` | Fault logging only, no new fault detection |
|
||||
| `SERVICE` | Fault inspection only, no new fault detection |
|
||||
|
||||
## 9. Error Handler Responsibilities
|
||||
|
||||
The Error Handler component SHALL:
|
||||
1. Receive fault reports from all components
|
||||
2. Classify faults according to taxonomy
|
||||
3. Determine severity and escalation
|
||||
4. Trigger state transitions when required
|
||||
5. Manage fault latching and clearing
|
||||
6. Coordinate recovery attempts
|
||||
7. Report faults to diagnostics and Main Hub
|
||||
|
||||
## 10. Traceability
|
||||
|
||||
- **SR-DIAG-001:** Implemented via diagnostic code framework
|
||||
- **SR-DIAG-002:** Implemented via unique diagnostic code assignment
|
||||
- **SR-DIAG-003:** Implemented via severity classification
|
||||
- **SR-DIAG-004:** Implemented via timestamp and source association
|
||||
- **SR-SYS-002:** Implemented via fault-to-state mapping
|
||||
- **SR-SYS-004:** Implemented via FATAL fault → TEARDOWN transition
|
||||
|
||||
## 11. Mermaid Fault Escalation Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
FaultDetected[Fault Detected] --> ClassifySeverity{Classify Severity}
|
||||
ClassifySeverity -->|INFO| LogOnly[Log Only]
|
||||
ClassifySeverity -->|WARNING| CheckState1{Current State?}
|
||||
ClassifySeverity -->|ERROR| IsolateFeature[Isolate Feature]
|
||||
ClassifySeverity -->|FATAL| TriggerFaultState[Trigger FAULT State]
|
||||
|
||||
CheckState1 -->|RUNNING| TransitionWarning[Transition to WARNING]
|
||||
CheckState1 -->|WARNING| LatchWarning[Latch Warning]
|
||||
|
||||
IsolateFeature --> RetryLogic{Retry Logic}
|
||||
RetryLogic -->|Success| ClearError[Clear Error]
|
||||
RetryLogic -->|Failure| EscalateToFatal{Escalate?}
|
||||
EscalateToFatal -->|Yes| TriggerFaultState
|
||||
EscalateToFatal -->|No| ManualIntervention[Manual Intervention]
|
||||
|
||||
TriggerFaultState --> TeardownSequence[Initiate Teardown]
|
||||
TeardownSequence --> RecoveryAttempt{Recovery Attempt}
|
||||
RecoveryAttempt -->|Success| ResetToInit[Reset to INIT]
|
||||
RecoveryAttempt -->|Failure| ManualIntervention
|
||||
```
|
||||
304
system_design/specifications/System Review Checklist.md
Normal file
304
system_design/specifications/System Review Checklist.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# System Review Checklist
|
||||
|
||||
**Project:** Sensor Hub – Poultry Farm Automation
|
||||
**Scope:** Sensor Hub (Sub-Hub Only)
|
||||
**Purpose:** Verify system readiness before FRD/SAD generation and AI-assisted implementation
|
||||
|
||||
## 1\. Requirements Completeness Review
|
||||
|
||||
### 1.1 Feature Coverage
|
||||
|
||||
✔ All major functional domains defined:
|
||||
|
||||
* ☐ Data Acquisition (DAQ)
|
||||
|
||||
* ☐ Data Quality & Calibration (DQC)
|
||||
|
||||
* ☐ Communication (COM)
|
||||
|
||||
* ☐ Diagnostics & Health (DIAG)
|
||||
|
||||
* ☐ Persistence & Data Management (DATA)
|
||||
|
||||
* ☐ OTA Update (OTA)
|
||||
|
||||
* ☐ Security & Safety (SEC)
|
||||
|
||||
* ☐ System Management & HMI (SYS)
|
||||
|
||||
|
||||
**Acceptance Criteria:**
|
||||
No functional behavior is undocumented or implicit.
|
||||
|
||||
### 1.2 Requirement Quality
|
||||
|
||||
For **each system requirement**, verify:
|
||||
|
||||
* ☐ Uses “SHALL”
|
||||
|
||||
* ☐ Is testable
|
||||
|
||||
* ☐ Is unambiguous
|
||||
|
||||
* ☐ Has a unique ID
|
||||
|
||||
* ☐ Is traceable to a feature
|
||||
|
||||
|
||||
**Red Flags:**
|
||||
|
||||
* Vague timing (“fast”, “real-time”)
|
||||
|
||||
* Mixed requirements (“shall… and …”)
|
||||
|
||||
* Implementation leakage (“using mutex”)
|
||||
|
||||
|
||||
## 2\. Architectural Soundness Review
|
||||
|
||||
### 2.1 Layering & Separation of Concerns
|
||||
|
||||
* ☐ Hardware access isolated
|
||||
|
||||
* ☐ No feature bypasses System Manager
|
||||
|
||||
* ☐ Persistence accessed only via DP
|
||||
|
||||
* ☐ HMI does not modify safety-critical configuration
|
||||
|
||||
|
||||
**Fail Condition:**
|
||||
Any feature directly accesses hardware or storage without abstraction.
|
||||
|
||||
### 2.2 State Machine Validity
|
||||
|
||||
* ☐ All system states defined
|
||||
|
||||
* ☐ Valid transitions documented
|
||||
|
||||
* ☐ Illegal transitions blocked
|
||||
|
||||
* ☐ Feature behavior defined per state
|
||||
|
||||
|
||||
**States to Verify:**
|
||||
|
||||
* INIT
|
||||
|
||||
* IDLE
|
||||
|
||||
* RUNNING
|
||||
|
||||
* DEGRADED
|
||||
|
||||
* OTA\_UPDATE
|
||||
|
||||
* TEARDOWN
|
||||
|
||||
* ERROR
|
||||
|
||||
|
||||
## 3\. Cross-Feature Constraint Compliance
|
||||
|
||||
### 3.1 Constraint Awareness
|
||||
|
||||
* ☐ Each feature respects cross-feature constraints
|
||||
|
||||
* ☐ No constraint contradicts a requirement
|
||||
|
||||
* ☐ Constraints are globally enforceable
|
||||
|
||||
|
||||
### 3.2 Conflict Resolution
|
||||
|
||||
Check for conflicts such as:
|
||||
|
||||
* ☐ OTA vs DAQ timing
|
||||
|
||||
* ☐ Persistence vs Power Loss
|
||||
|
||||
* ☐ Diagnostics vs Real-Time Tasks
|
||||
|
||||
* ☐ Debug vs Secure Boot
|
||||
|
||||
|
||||
**Acceptance:**
|
||||
Conflicts resolved via priority rules or system state restrictions.
|
||||
|
||||
## 4\. Timing & Performance Review
|
||||
|
||||
### 4.1 Real-Time Constraints
|
||||
|
||||
* ☐ High-frequency sampling bounded
|
||||
|
||||
* ☐ Worst-case execution time considered
|
||||
|
||||
* ☐ Non-blocking design enforced
|
||||
|
||||
|
||||
### 4.2 Resource Usage
|
||||
|
||||
* ☐ CPU usage bounded
|
||||
|
||||
* ☐ RAM usage predictable
|
||||
|
||||
* ☐ Stack sizes justified
|
||||
|
||||
* ☐ Heap usage minimized in runtime
|
||||
|
||||
|
||||
## 5\. Reliability & Fault Handling Review
|
||||
|
||||
### 5.1 Fault Detection
|
||||
|
||||
* ☐ Sensor failure detection defined
|
||||
|
||||
* ☐ Communication failure detection defined
|
||||
|
||||
* ☐ Storage failure detection defined
|
||||
|
||||
|
||||
### 5.2 Fault Response
|
||||
|
||||
* ☐ Graceful degradation defined
|
||||
|
||||
* ☐ Diagnostics logged
|
||||
|
||||
* ☐ System state updated appropriately
|
||||
|
||||
|
||||
## 6\. Security Review
|
||||
|
||||
### 6.1 Boot & Firmware
|
||||
|
||||
* ☐ Secure boot enforced
|
||||
|
||||
* ☐ Firmware integrity verified
|
||||
|
||||
* ☐ Rollback prevention defined
|
||||
|
||||
|
||||
### 6.2 Communication
|
||||
|
||||
* ☐ Encryption mandatory
|
||||
|
||||
* ☐ Authentication required
|
||||
|
||||
* ☐ Key management strategy defined
|
||||
|
||||
|
||||
### 6.3 Debug Access
|
||||
|
||||
* ☐ Debug sessions authenticated
|
||||
|
||||
* ☐ Debug disabled in production unless authorized
|
||||
|
||||
* ☐ Debug cannot bypass security or safety
|
||||
|
||||
|
||||
## 7\. Data Management Review
|
||||
|
||||
### 7.1 Data Ownership
|
||||
|
||||
* ☐ Single source of truth enforced
|
||||
|
||||
* ☐ Clear ownership per data type
|
||||
|
||||
* ☐ No duplicated persistent data
|
||||
|
||||
|
||||
### 7.2 Persistence Safety
|
||||
|
||||
* ☐ Safe writes during state transitions
|
||||
|
||||
* ☐ Power-loss tolerance defined
|
||||
|
||||
* ☐ Data recovery defined
|
||||
|
||||
|
||||
## 8\. HMI & Usability Review (OLED + Buttons)
|
||||
|
||||
### 8.1 Display Content
|
||||
|
||||
* ☐ Connectivity status
|
||||
|
||||
* ☐ System status
|
||||
|
||||
* ☐ Connected sensors
|
||||
|
||||
* ☐ Time & date
|
||||
|
||||
|
||||
### 8.2 Navigation Logic
|
||||
|
||||
* ☐ Menu hierarchy defined
|
||||
|
||||
* ☐ Button behavior consistent
|
||||
|
||||
* ☐ No destructive action via UI
|
||||
|
||||
|
||||
## 9\. Standards & Compliance Readiness
|
||||
|
||||
### 9.1 IEC 61499 Mapping Readiness
|
||||
|
||||
* ☐ Functional blocks identifiable
|
||||
|
||||
* ☐ Event/data separation respected
|
||||
|
||||
* ☐ Distributed execution possible
|
||||
|
||||
|
||||
### 9.2 ISA-95 Alignment Readiness
|
||||
|
||||
* ☐ Sensor Hub maps to Level 1/2
|
||||
|
||||
* ☐ Clear boundary to Level 3/4
|
||||
|
||||
* ☐ No business logic leakage
|
||||
|
||||
|
||||
## 10\. AI Readiness Review
|
||||
|
||||
### 10.1 Prompt Compatibility
|
||||
|
||||
* ☐ Features modular
|
||||
|
||||
* ☐ Requirements structured
|
||||
|
||||
* ☐ Architecture explicit
|
||||
|
||||
|
||||
### 10.2 Tool Handoff Readiness
|
||||
|
||||
* ☐ Claude can generate FRD/SAD
|
||||
|
||||
* ☐ Mermaid diagrams derivable
|
||||
|
||||
* ☐ DeepSeek can critique logic
|
||||
|
||||
* ☐ Cursor rules enforce constraints
|
||||
|
||||
|
||||
## Final Gate Decision
|
||||
|
||||
### GO / NO-GO Criteria
|
||||
|
||||
**GO** if:
|
||||
|
||||
* All sections ≥ 90% checked
|
||||
|
||||
* No critical architectural violation
|
||||
|
||||
* Security constraints enforced
|
||||
|
||||
|
||||
**NO-GO** if:
|
||||
|
||||
* Missing system states
|
||||
|
||||
* Undefined failure behavior
|
||||
|
||||
* Security gaps
|
||||
|
||||
* Persistence inconsistency
|
||||
@@ -0,0 +1,314 @@
|
||||
# System State Machine Specification
|
||||
|
||||
**Document Type:** Normative System Specification
|
||||
**Scope:** Sensor Hub (Sub-Hub) Operational States
|
||||
**Traceability:** SR-SYS-001, SR-SYS-002, SR-SYS-003
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the complete finite state machine (FSM) governing the Sensor Hub's operational lifecycle. All system components SHALL respect state-based operation restrictions as defined herein.
|
||||
|
||||
## 2. State Definitions
|
||||
|
||||
### 2.1 State Enumeration
|
||||
|
||||
| State ID | State Name | Description | Entry Condition |
|
||||
|----------|------------|-------------|-----------------|
|
||||
| `INIT` | Initialization | Hardware and software initialization phase | Power-on, reset, or post-teardown |
|
||||
| `BOOT_FAILURE` | Boot Failure | Secure boot verification failed | Secure boot check failure during INIT |
|
||||
| `RUNNING` | Normal Operation | Active sensor acquisition and communication | Successful initialization |
|
||||
| `WARNING` | Degraded Operation | Non-fatal fault detected, degraded functionality | Non-critical fault detected during RUNNING |
|
||||
| `FAULT` | Fatal Error | Critical fault, core functionality disabled | Fatal error or cascading failures |
|
||||
| `OTA_PREP` | OTA Preparation | Preparing for firmware update | OTA request accepted, validation pending |
|
||||
| `OTA_UPDATE` | OTA Update Active | Firmware update in progress | Firmware transfer and flashing |
|
||||
| `MC_UPDATE` | Machine Constants Update | Machine constants update in progress | MC update request accepted |
|
||||
| `TEARDOWN` | Controlled Shutdown | Safe shutdown sequence execution | Update, fault recovery, or manual command |
|
||||
| `SERVICE` | Service Mode | Engineering/diagnostic interaction | Debug session active |
|
||||
| `SD_DEGRADED` | SD Card Degraded | SD card failure detected, fallback mode | SD card access failure |
|
||||
|
||||
### 2.2 State Characteristics
|
||||
|
||||
#### INIT
|
||||
- **Duration:** Bounded (max 5 seconds)
|
||||
- **Allowed Operations:** Hardware initialization, secure boot verification, MC loading
|
||||
- **Forbidden Operations:** Sensor acquisition, communication, persistence writes
|
||||
- **Exit Conditions:** Success → RUNNING, Secure boot failure → BOOT_FAILURE
|
||||
|
||||
#### BOOT_FAILURE
|
||||
- **Duration:** Indefinite (requires manual intervention)
|
||||
- **Allowed Operations:** Diagnostic reporting, secure boot retry (limited)
|
||||
- **Forbidden Operations:** All application features
|
||||
- **Exit Conditions:** Manual reset, secure boot success → INIT
|
||||
|
||||
#### RUNNING
|
||||
- **Duration:** Indefinite (normal operation)
|
||||
- **Allowed Operations:** All features (DAQ, DQC, COM, DIAG, DATA, HMI)
|
||||
- **Forbidden Operations:** OTA, MC update (must transition via TEARDOWN)
|
||||
- **Exit Conditions:** Fault → WARNING/FAULT, OTA request → OTA_PREP, MC update → MC_UPDATE, Debug session → SERVICE
|
||||
|
||||
#### WARNING
|
||||
- **Duration:** Until fault cleared or escalated
|
||||
- **Allowed Operations:** Degraded DAQ, COM, DIAG (limited), DATA (read-only)
|
||||
- **Forbidden Operations:** OTA, MC update
|
||||
- **Exit Conditions:** Fault cleared → RUNNING, Fault escalated → FAULT
|
||||
|
||||
#### FAULT
|
||||
- **Duration:** Until recovery attempt or manual intervention
|
||||
- **Allowed Operations:** Diagnostic reporting, error logging, controlled teardown
|
||||
- **Forbidden Operations:** Sensor acquisition, communication (except diagnostics)
|
||||
- **Exit Conditions:** Recovery attempt → TEARDOWN, Manual reset → INIT
|
||||
|
||||
#### OTA_PREP
|
||||
- **Duration:** Bounded (max 2 seconds)
|
||||
- **Allowed Operations:** OTA readiness validation, teardown initiation
|
||||
- **Forbidden Operations:** Sensor acquisition, new communication sessions
|
||||
- **Exit Conditions:** Ready → TEARDOWN, Rejected → RUNNING
|
||||
|
||||
#### OTA_UPDATE
|
||||
- **Duration:** Bounded (max 10 minutes)
|
||||
- **Allowed Operations:** Firmware reception, validation, flashing
|
||||
- **Forbidden Operations:** Sensor acquisition, normal communication, persistence (except OTA data)
|
||||
- **Exit Conditions:** Success → RUNNING (after reboot), Failure → FAULT
|
||||
|
||||
#### MC_UPDATE
|
||||
- **Duration:** Bounded (max 30 seconds)
|
||||
- **Allowed Operations:** MC reception, validation, teardown
|
||||
- **Forbidden Operations:** Sensor acquisition, normal communication
|
||||
- **Exit Conditions:** Success → TEARDOWN, Failure → RUNNING
|
||||
|
||||
#### TEARDOWN
|
||||
- **Duration:** Bounded (max 500ms)
|
||||
- **Allowed Operations:** Data flush, resource release, state persistence
|
||||
- **Forbidden Operations:** New sensor acquisition, new communication sessions
|
||||
- **Exit Conditions:** Complete → INIT (reset), OTA → OTA_UPDATE, MC → MC_UPDATE
|
||||
|
||||
#### SERVICE
|
||||
- **Duration:** Until session closed
|
||||
- **Allowed Operations:** Diagnostic access, read-only inspection, controlled commands
|
||||
- **Forbidden Operations:** Sensor acquisition (may be paused), OTA, MC update
|
||||
- **Exit Conditions:** Session closed → RUNNING
|
||||
|
||||
#### SD_DEGRADED
|
||||
- **Duration:** Until SD recovery or manual intervention
|
||||
- **Allowed Operations:** Sensor acquisition (no persistence), communication, diagnostics
|
||||
- **Forbidden Operations:** Persistence writes (except critical diagnostics)
|
||||
- **Exit Conditions:** SD recovery → RUNNING, Manual intervention → SERVICE
|
||||
|
||||
## 3. State Transition Table
|
||||
|
||||
| From State | To State | Trigger | Guard Condition | Action | Authorized Caller |
|
||||
|------------|----------|---------|-----------------|--------|------------------|
|
||||
| `[*]` | `INIT` | Power-on, Reset | None | Initialize hardware, secure boot check | System |
|
||||
| `INIT` | `RUNNING` | Init success | Secure boot OK, MC loaded, sensors detected | Start DAQ, COM, DIAG tasks | System Manager |
|
||||
| `INIT` | `BOOT_FAILURE` | Secure boot fail | Secure boot verification failed | Log security fault, disable application | Secure Boot |
|
||||
| `BOOT_FAILURE` | `INIT` | Manual reset | None | Reset system | User/Engineer |
|
||||
| `RUNNING` | `WARNING` | Non-fatal fault | Diagnostic severity = WARNING | Degrade functionality, notify | Error Handler |
|
||||
| `RUNNING` | `FAULT` | Fatal fault | Diagnostic severity = FATAL | Stop critical features | Error Handler |
|
||||
| `RUNNING` | `OTA_PREP` | OTA request | OTA request received, system ready | Validate readiness | OTA Manager |
|
||||
| `RUNNING` | `MC_UPDATE` | MC update request | MC update received, authenticated | Validate MC | MC Manager |
|
||||
| `RUNNING` | `SERVICE` | Debug session | Debug session authenticated | Pause non-critical tasks | Debug Manager |
|
||||
| `RUNNING` | `SD_DEGRADED` | SD failure | SD card access failure detected | Disable persistence writes | Persistence |
|
||||
| `WARNING` | `RUNNING` | Fault cleared | Diagnostic cleared, system healthy | Restore full functionality | Error Handler |
|
||||
| `WARNING` | `FAULT` | Fault escalated | Multiple warnings or critical fault | Stop degraded features | Error Handler |
|
||||
| `FAULT` | `TEARDOWN` | Recovery attempt | Recovery command received | Initiate controlled shutdown | System Manager |
|
||||
| `OTA_PREP` | `TEARDOWN` | OTA ready | Readiness validated | Begin teardown | OTA Manager |
|
||||
| `OTA_PREP` | `RUNNING` | OTA rejected | Readiness check failed | Resume normal operation | OTA Manager |
|
||||
| `TEARDOWN` | `OTA_UPDATE` | Teardown complete (OTA) | OTA pending, data flushed | Enter OTA state | System Manager |
|
||||
| `TEARDOWN` | `MC_UPDATE` | Teardown complete (MC) | MC update pending, data flushed | Enter MC update | System Manager |
|
||||
| `TEARDOWN` | `INIT` | Teardown complete (reset) | Reset requested, data flushed | Reset system | System Manager |
|
||||
| `OTA_UPDATE` | `RUNNING` | OTA success | Firmware flashed, validated | Reboot into new firmware | OTA Manager |
|
||||
| `OTA_UPDATE` | `FAULT` | OTA failure | Firmware validation failed | Log error, enter fault | OTA Manager |
|
||||
| `MC_UPDATE` | `TEARDOWN` | MC update complete | MC validated, applied | Reinitialize system | MC Manager |
|
||||
| `SERVICE` | `RUNNING` | Session closed | Debug session terminated | Resume normal operation | Debug Manager |
|
||||
| `SD_DEGRADED` | `RUNNING` | SD recovered | SD card access restored | Re-enable persistence | Persistence |
|
||||
| `SD_DEGRADED` | `SERVICE` | Manual intervention | User intervention required | Enter service mode | User/Engineer |
|
||||
|
||||
## 4. Per-State Feature Execution Rules
|
||||
|
||||
### 4.1 DAQ (Data Acquisition) Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | None | Sensor initialization only |
|
||||
| `RUNNING` | Full acquisition cycle | None |
|
||||
| `WARNING` | Degraded acquisition (reduced frequency) | Failed sensors excluded |
|
||||
| `FAULT` | None | Acquisition stopped |
|
||||
| `OTA_PREP` | None | Acquisition stopped |
|
||||
| `OTA_UPDATE` | None | Acquisition stopped |
|
||||
| `MC_UPDATE` | None | Acquisition stopped |
|
||||
| `TEARDOWN` | None | Acquisition stopped |
|
||||
| `SERVICE` | Paused (optional read-only) | No new samples |
|
||||
| `SD_DEGRADED` | Full acquisition | Data not persisted |
|
||||
| `BOOT_FAILURE` | None | Not applicable |
|
||||
|
||||
### 4.2 DQC (Data Quality & Calibration) Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | Sensor detection, MC loading | No calibration |
|
||||
| `RUNNING` | Full quality checks, calibration | None |
|
||||
| `WARNING` | Degraded quality checks | Reduced validation |
|
||||
| `FAULT` | Error reporting only | No quality checks |
|
||||
| `OTA_PREP` | None | Quality checks stopped |
|
||||
| `OTA_UPDATE` | None | Quality checks stopped |
|
||||
| `MC_UPDATE` | MC validation only | No sensor calibration |
|
||||
| `TEARDOWN` | None | Quality checks stopped |
|
||||
| `SERVICE` | Read-only inspection | No calibration |
|
||||
| `SD_DEGRADED` | Full quality checks | Results not persisted |
|
||||
| `BOOT_FAILURE` | None | Not applicable |
|
||||
|
||||
### 4.3 COM (Communication) Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | None | No communication |
|
||||
| `RUNNING` | Full bidirectional communication | None |
|
||||
| `WARNING` | Limited communication (diagnostics only) | Reduced bandwidth |
|
||||
| `FAULT` | Diagnostic reporting only | No data transmission |
|
||||
| `OTA_PREP` | OTA negotiation only | No other communication |
|
||||
| `OTA_UPDATE` | OTA data transfer only | No other communication |
|
||||
| `MC_UPDATE` | MC transfer only | No other communication |
|
||||
| `TEARDOWN` | Session closure only | No new sessions |
|
||||
| `SERVICE` | Debug session communication | No Main Hub communication |
|
||||
| `SD_DEGRADED` | Full communication | Data not persisted |
|
||||
| `BOOT_FAILURE` | Diagnostic reporting only | Limited communication |
|
||||
|
||||
### 4.4 DIAG (Diagnostics) Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | Boot diagnostics | Limited logging |
|
||||
| `RUNNING` | Full diagnostics | None |
|
||||
| `WARNING` | Full diagnostics | None |
|
||||
| `FAULT` | Full diagnostics | None |
|
||||
| `OTA_PREP` | OTA diagnostics | Limited scope |
|
||||
| `OTA_UPDATE` | OTA progress diagnostics | Limited scope |
|
||||
| `MC_UPDATE` | MC update diagnostics | Limited scope |
|
||||
| `TEARDOWN` | Teardown diagnostics | Limited scope |
|
||||
| `SERVICE` | Full diagnostics (read access) | No new diagnostics |
|
||||
| `SD_DEGRADED` | Full diagnostics | Persistence limited |
|
||||
| `BOOT_FAILURE` | Security diagnostics | Limited scope |
|
||||
|
||||
### 4.5 DATA (Persistence) Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | MC loading only | No writes |
|
||||
| `RUNNING` | Full persistence | None |
|
||||
| `WARNING` | Read-only, critical writes | Limited writes |
|
||||
| `FAULT` | Critical diagnostics only | No sensor data writes |
|
||||
| `OTA_PREP` | Read-only | No writes |
|
||||
| `OTA_UPDATE` | OTA data only | No sensor data writes |
|
||||
| `MC_UPDATE` | MC writes only | No sensor data writes |
|
||||
| `TEARDOWN` | Critical data flush only | Authorized writes only |
|
||||
| `SERVICE` | Read-only | No writes |
|
||||
| `SD_DEGRADED` | Read-only (if possible) | No writes |
|
||||
| `BOOT_FAILURE` | None | Not applicable |
|
||||
|
||||
### 4.6 OTA Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | None | OTA not active |
|
||||
| `RUNNING` | OTA negotiation only | No transfer |
|
||||
| `WARNING` | None | OTA blocked |
|
||||
| `FAULT` | None | OTA blocked |
|
||||
| `OTA_PREP` | Readiness validation | No transfer |
|
||||
| `OTA_UPDATE` | Full OTA operations | None |
|
||||
| `MC_UPDATE` | None | OTA blocked |
|
||||
| `TEARDOWN` | None | OTA blocked |
|
||||
| `SERVICE` | None | OTA blocked |
|
||||
| `SD_DEGRADED` | None | OTA blocked |
|
||||
| `BOOT_FAILURE` | None | OTA blocked |
|
||||
|
||||
### 4.7 SEC (Security) Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | Secure boot verification | Must complete before app start |
|
||||
| `RUNNING` | Full security (encryption, authentication) | None |
|
||||
| `WARNING` | Full security | None |
|
||||
| `FAULT` | Security diagnostics | Limited operations |
|
||||
| `OTA_PREP` | OTA authentication | None |
|
||||
| `OTA_UPDATE` | Firmware verification | None |
|
||||
| `MC_UPDATE` | MC authentication | None |
|
||||
| `TEARDOWN` | Key protection | None |
|
||||
| `SERVICE` | Debug authentication | None |
|
||||
| `SD_DEGRADED` | Full security | None |
|
||||
| `BOOT_FAILURE` | Security fault handling | Limited operations |
|
||||
|
||||
### 4.8 SYS (System Management) Feature
|
||||
|
||||
| State | Allowed Operations | Restrictions |
|
||||
|-------|-------------------|--------------|
|
||||
| `INIT` | State management, initialization | Limited operations |
|
||||
| `RUNNING` | Full system management | None |
|
||||
| `WARNING` | Degraded management | Limited operations |
|
||||
| `FAULT` | Fault recovery management | Limited operations |
|
||||
| `OTA_PREP` | OTA state management | Limited operations |
|
||||
| `OTA_UPDATE` | OTA state management | Limited operations |
|
||||
| `MC_UPDATE` | MC state management | Limited operations |
|
||||
| `TEARDOWN` | Teardown execution | Limited operations |
|
||||
| `SERVICE` | Service mode management | Limited operations |
|
||||
| `SD_DEGRADED` | Degraded management | Limited operations |
|
||||
| `BOOT_FAILURE` | Boot failure management | Limited operations |
|
||||
|
||||
## 5. State Transition Timing Requirements
|
||||
|
||||
| Transition | Maximum Duration | Justification |
|
||||
|------------|------------------|---------------|
|
||||
| `[*]` → `INIT` | 100ms | Power-on initialization |
|
||||
| `INIT` → `RUNNING` | 5s | Hardware init, secure boot, MC load |
|
||||
| `INIT` → `BOOT_FAILURE` | 2s | Secure boot verification |
|
||||
| `RUNNING` → `WARNING` | 50ms | Fault detection and state change |
|
||||
| `RUNNING` → `FAULT` | 50ms | Critical fault detection |
|
||||
| `RUNNING` → `OTA_PREP` | 100ms | OTA request processing |
|
||||
| `OTA_PREP` → `TEARDOWN` | 2s | Readiness validation |
|
||||
| `TEARDOWN` → `OTA_UPDATE` | 500ms | Data flush and resource release |
|
||||
| `TEARDOWN` → `INIT` | 500ms | Data flush and reset |
|
||||
| `OTA_UPDATE` → `RUNNING` | 10 minutes | Firmware transfer and flashing |
|
||||
| `RUNNING` → `SERVICE` | 100ms | Debug session establishment |
|
||||
| `SERVICE` → `RUNNING` | 50ms | Debug session closure |
|
||||
|
||||
## 6. State Notification Mechanism
|
||||
|
||||
All state transitions SHALL notify registered components via the Event System:
|
||||
- **Event Type:** `SYSTEM_STATE_CHANGED`
|
||||
- **Payload:** Previous state, new state, transition reason
|
||||
- **Subscribers:** All feature managers (DAQ, DQC, COM, DIAG, DATA, OTA, SEC, SYS)
|
||||
|
||||
## 7. Traceability
|
||||
|
||||
- **SR-SYS-001:** Implemented via complete FSM definition
|
||||
- **SR-SYS-002:** Implemented via per-state feature execution rules
|
||||
- **SR-SYS-003:** Implemented via state notification mechanism
|
||||
|
||||
## 8. Mermaid State Diagram
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> INIT
|
||||
INIT --> RUNNING: initSuccess
|
||||
INIT --> BOOT_FAILURE: secureBootFail
|
||||
BOOT_FAILURE --> INIT: manualReset
|
||||
RUNNING --> WARNING: nonFatalFault
|
||||
RUNNING --> FAULT: fatalFault
|
||||
RUNNING --> OTA_PREP: otaRequest
|
||||
RUNNING --> MC_UPDATE: mcUpdateRequest
|
||||
RUNNING --> SERVICE: debugSession
|
||||
RUNNING --> SD_DEGRADED: sdFailure
|
||||
WARNING --> RUNNING: faultCleared
|
||||
WARNING --> FAULT: faultEscalated
|
||||
FAULT --> TEARDOWN: recoveryAttempt
|
||||
OTA_PREP --> TEARDOWN: otaReady
|
||||
OTA_PREP --> RUNNING: otaRejected
|
||||
TEARDOWN --> OTA_UPDATE: otaPending
|
||||
TEARDOWN --> MC_UPDATE: mcPending
|
||||
TEARDOWN --> INIT: resetRequested
|
||||
OTA_UPDATE --> RUNNING: otaSuccess
|
||||
OTA_UPDATE --> FAULT: otaFailure
|
||||
MC_UPDATE --> TEARDOWN: mcComplete
|
||||
SERVICE --> RUNNING: sessionClosed
|
||||
SD_DEGRADED --> RUNNING: sdRecovered
|
||||
SD_DEGRADED --> SERVICE: manualIntervention
|
||||
```
|
||||
115
system_design/system_requirementsand_and_traceability.csv
Normal file
115
system_design/system_requirementsand_and_traceability.csv
Normal file
@@ -0,0 +1,115 @@
|
||||
ID,Type,Status,Title,Description,Parent_ID,Relations
|
||||
45,Requirements,Specified,"The system shall include a central server that aggregates and analyzes data from all main hubs across different farms, using machine learning algorithms to optimize control strategies for each farm based on collected data.","The system shall include a central server that aggregates and analyzes data from all main hubs across different farms, using machine learning algorithms to optimize control strategies for each farm based on collected data.",,
|
||||
46,Requirements,Specified,"The sub-hub shall be capable of performing minor calibration functions, including sensor recalibration, before sending data to the main hub.","The sub-hub shall be capable of performing minor calibration functions, including sensor recalibration, before sending data to the main hub.",,
|
||||
47,Requirements,Specified,"The main hub shall include control algorithms for managing the environment of the poultry house, including temperature, humidity, and air quality, by controlling the actuators like ventilation fans, heaters, lighting systems, and feeding systems.","The main hub shall include control algorithms for managing the environment of the poultry house, including temperature, humidity, and air quality, by controlling the actuators like ventilation fans, heaters, lighting systems, and feeding systems.",,
|
||||
48,Requirements,Specified,"The central server shall use the aggregated data from all farms to generate optimized control strategies based on machine learning, which are then sent back to the respective main hubs.","The central server shall use the aggregated data from all farms to generate optimized control strategies based on machine learning, which are then sent back to the respective main hubs.",,
|
||||
49,Requirements,Specified,"The main hub shall be connected to a local control board, which directly controls the actuators, such as fans, heaters, lights, and feeders.","The main hub shall be connected to a local control board, which directly controls the actuators, such as fans, heaters, lights, and feeders.",,
|
||||
50,Requirements,Specified,The sub-hubs shall be capable of real-time data collection and will update the main hub with sensor readings at specified intervals or when sensor values change beyond predefined thresholds.,The sub-hubs shall be capable of real-time data collection and will update the main hub with sensor readings at specified intervals or when sensor values change beyond predefined thresholds.,,
|
||||
51,Requirements,Specified,"The system shall be capable of remote monitoring and control, allowing farm managers to access real-time data and control system settings via a mobile application or web interface.","The system shall be capable of remote monitoring and control, allowing farm managers to access real-time data and control system settings via a mobile application or web interface.",,
|
||||
52,Requirements,Specified,"The system shall be able to generate alarms for critical situations such as temperature deviations, high ammonia levels, equipment malfunctions, or other emergency conditions.","The system shall be able to generate alarms for critical situations such as temperature deviations, high ammonia levels, equipment malfunctions, or other emergency conditions.",,
|
||||
53,Requirements,Specified,"The system shall support data logging and historical analysis, providing insights into past farm conditions, sensor performance, and actuator behavior.","The system shall support data logging and historical analysis, providing insights into past farm conditions, sensor performance, and actuator behavior.",,
|
||||
54,Requirements,Specified,The system shall implement security measures such as data encryption and user authentication for remote access to prevent unauthorized access to farm data and control systems.,The system shall implement security measures such as data encryption and user authentication for remote access to prevent unauthorized access to farm data and control systems.,,
|
||||
55,Requirements,Specified,"The sub-hubs shall include diagnostic tools to ensure the correct functionality of sensors, communication, and data transmission.","The sub-hubs shall include diagnostic tools to ensure the correct functionality of sensors, communication, and data transmission.",,
|
||||
56,Requirements,Specified,"The system shall support scalability, allowing new sub-hubs and main hubs to be added seamlessly to expand the system to additional poultry rooms or farms.","The system shall support scalability, allowing new sub-hubs and main hubs to be added seamlessly to expand the system to additional poultry rooms or farms.",,
|
||||
57,Requirements,Specified,"The system shall provide automated decision-making logic for controlling environmental parameters, which may be based on fuzzy logic or proportional control algorithms.","The system shall provide automated decision-making logic for controlling environmental parameters, which may be based on fuzzy logic or proportional control algorithms.",,
|
||||
58,Requirements,Specified,"The central server shall be capable of over-the-air (OTA) updates for all system firmware, ensuring that the latest software updates and features can be deployed to all hubs.","The central server shall be capable of over-the-air (OTA) updates for all system firmware, ensuring that the latest software updates and features can be deployed to all hubs.",,
|
||||
59,Requirements,Specified,"The system shall include energy management capabilities, optimizing the operation of actuators such as fans, heaters, and lighting to reduce energy consumption.","The system shall include energy management capabilities, optimizing the operation of actuators such as fans, heaters, and lighting to reduce energy consumption.",,
|
||||
60,Requirements,Specified,"The system shall be compliant with industry standards, including animal welfare regulations and environmental requirements, ensuring the health and safety of the poultry.","The system shall be compliant with industry standards, including animal welfare regulations and environmental requirements, ensuring the health and safety of the poultry.",,
|
||||
61,Requirements,Specified,"The system shall support multi-zone control, allowing different sections of the poultry house to have independent environmental control based on the local conditions measured by sensors in those zones.","The system shall support multi-zone control, allowing different sections of the poultry house to have independent environmental control based on the local conditions measured by sensors in those zones.",,
|
||||
62,Requirements,Specified,"The system shall provide integration with other farm management software, allowing data from environmental control to be merged with broader farm management systems.","The system shall provide integration with other farm management software, allowing data from environmental control to be merged with broader farm management systems.",,
|
||||
63,Requirements,Specified,"The system shall include fail-safe mechanisms to ensure continuous operation in case of failure in communication or hardware, including backup power and data storage.","The system shall include fail-safe mechanisms to ensure continuous operation in case of failure in communication or hardware, including backup power and data storage.",,
|
||||
64,Requirements,Specified,"The system shall be designed for ease of use, with a user-friendly interface for farm managers to configure, monitor, and control the system.","The system shall be designed for ease of use, with a user-friendly interface for farm managers to configure, monitor, and control the system.",,
|
||||
65,Requirements,Specified,"The system shall enable remote diagnostics for troubleshooting and support, reducing the need for on-site visits.","The system shall enable remote diagnostics for troubleshooting and support, reducing the need for on-site visits.",,
|
||||
394,Requirements,In specification,[SR-DAQ-001] Support Multi-Sensor Environmental Data Acquisition,"The system shall support simultaneous acquisition of environmental data from multiple sensor types, including temperature, humidity, CO2, NH3, VOC, particulate matter, and ambient light.\n\nThis requirements traces to feature [F-DAQ-01].",,includes(#388)
|
||||
395,Requirements,In specification,[SR-DAQ-002] Dedicated Sensor Slot Mapping,The system shall assign each supported sensor type to a predefined and unique hardware slot to prevent incorrect sensor insertion or configuration.\n\nThis requirements traces to feature [F-DAQ-01].,,includes(#388)
|
||||
396,Requirements,In specification,[SR-DAQ-003] Sensor Presence Detection,The system shall detect the physical presence of each sensor via a dedicated hardware detection signal prior to sensor initialization.\n\nThis requirements traces to feature [F-DAQ-01].,,includes(#388)
|
||||
397,Requirements,In specification,[SR-DAQ-004] Conditional Sensor Initialization,The system shall initialize and activate only those sensors that are detected as present and enabled during system startup or reinitialization.\n\nThis requirements traces to feature [F-DAQ-01].,,includes(#389)
|
||||
398,Requirements,In specification,[SR-DAQ-005] High-Frequency Sensor Sampling,"The system shall sample each enabled sensor multiple times within a single acquisition cycle, with a default of ten (10) samples per sensor per cycle.\n\nThis requirements traces to feature [F-DAQ-02].",,includes(#389)
|
||||
399,Requirements,In specification,[SR-DAQ-006] Local Sensor Data Filtering,The system shall apply a local filtering mechanism to raw sensor samples to produce a single filtered sensor value per acquisition cycle.\n\nThe filtering mechanism shall execute on the Sensor Hub.\n\nThis requirements traces to feature [F-DAQ-02].,,includes(#389)
|
||||
400,Requirements,In specification,[SR-DAQ-007] Deterministic Sampling Window,The system shall complete each sensor’s sampling and filtering process within a bounded and deterministic time window to ensure real-time behavior.\n\nThis requirements traces to feature [F-DAQ-02].,,includes(#390)
|
||||
401,Requirements,In specification,[SR-DAQ-008] Timestamp Generation for Sensor Data,The system shall generate a timestamp for each filtered sensor value upon completion of the acquisition and filtering process.\n\nThis requirements traces to feature [F-DAQ-03].,,includes(#390)
|
||||
402,Requirements,In specification,[SR-DAQ-009] Timestamped Sensor Data Record Structure,"The system shall generate a timestamped sensor data record containing at minimum the sensor identifier, sensor type, filtered value, unit of measurement, timestamp, and data validity status.\n\nThis requirements traces to feature [F-DAQ-03].",,includes(#390)
|
||||
403,Requirements,In specification,[SR-DAQ-010] Availability of Latest Sensor Data,The system shall maintain the most recent timestamped sensor data record in memory and make it available for persistence and on-demand communication requests.\n\nThis requirements traces to feature [F-DAQ-03].,,includes(#390)
|
||||
409,Requirements,In specification,[SR-DQC-001] Detect Sensor Presence,The system shall detect the physical presence of each sensor using a dedicated hardware-based detection mechanism. This requirement traces to feature [F-DQC-01].,,includes(#405)
|
||||
410,Requirements,In specification,[SR-DQC-002] Perform Sensor Detection During Initialization,The system shall perform sensor presence detection during system startup and after any reinitialization or reconfiguration event. This requirement traces to feature [F-DQC-01].,,includes(#405)
|
||||
411,Requirements,In specification,[SR-DQC-003] Conditional Sensor Initialization,The system shall initialize and activate only sensors that are detected as present. This requirement traces to feature [F-DQC-01].,,includes(#405)
|
||||
412,Requirements,In specification,[SR-DQC-004] Assign Fixed Sensor Slot Types,The system shall assign each physical sensor slot to a predefined sensor type. This requirement traces to feature [F-DQC-02].,,includes(#406)
|
||||
413,Requirements,In specification,[SR-DQC-005] Verify Sensor Type Compatibility,The system shall verify that a detected sensor matches the expected sensor type for its assigned slot. This requirement traces to feature [F-DQC-02].,,includes(#406)
|
||||
414,Requirements,In specification,[SR-DQC-006] Reject Invalid Sensor Configurations,The system shall reject and report any sensor-slot mismatch as a diagnostic event. This requirement traces to feature [F-DQC-02].,,includes(#406)
|
||||
415,Requirements,In specification,[SR-DQC-007] Monitor Sensor Health,The system shall continuously monitor sensor responsiveness and signal validity during normal operation. This requirement traces to feature [F-DQC-03].,,includes(#407)
|
||||
416,Requirements,In specification,[SR-DQC-008] Detect Sensor Failure Conditions,"The system shall detect sensor failures including disconnection, non-responsiveness, and out-of-range measurement values. This requirement traces to feature [F-DQC-03].",,includes(#407)
|
||||
417,Requirements,In specification,[SR-DQC-009] Isolate Failed Sensors,The system shall mark detected faulty sensors as defective and exclude them from data acquisition and reporting. This requirement traces to feature [F-DQC-03].,,includes(#407)
|
||||
418,Requirements,In specification,[SR-DQC-010] Report Sensor Failures,The system shall report detected sensor failures to the Main Hub with timestamps and failure classification. This requirement traces to feature [F-DQC-03].,,includes(#407)
|
||||
419,Requirements,In specification,[SR-DQC-011] Maintain Machine Constants Dataset,"The system shall maintain a Machine Constants dataset defining sensor configuration, calibration parameters, and communication identifiers. This requirement traces to feature [F-DQC-04].",,includes(#408)
|
||||
420,Requirements,In specification,[SR-DQC-012] Persist Machine Constants,The system shall store the Machine Constants dataset in non-volatile storage. This requirement traces to feature [F-DQC-04].,,includes(#408)
|
||||
421,Requirements,In specification,[SR-DQC-013] Load Machine Constants at Startup,The system shall load and apply the Machine Constants dataset during system initialization. This requirement traces to feature [F-DQC-04].,,includes(#408)
|
||||
422,Requirements,In specification,[SR-DQC-014] Support Remote Machine Constants Update,The system shall support remote updates of the Machine Constants dataset initiated by the Main Hub. This requirement traces to feature [F-DQC-04].,,includes(#408)
|
||||
423,Requirements,In specification,[SR-DQC-015] Controlled Reinitialization After Update,The system shall apply updated Machine Constants only after executing a controlled teardown and reinitialization procedure. This requirement traces to feature [F-DQC-04].,,includes(#408)
|
||||
429,Requirements,In specification,[SR-COM-001] Bidirectional Main Hub Communication,The system shall support bidirectional communication between the Sensor Hub and the Main Hub. This requirement traces to feature [F-COM-01].,,includes(#426)
|
||||
430,Requirements,In specification,[SR-COM-002] Transmit Data to Main Hub,"The system shall transmit sensor data, diagnostics information, and system status to the Main Hub. This requirement traces to feature [F-COM-01].",,includes(#426)
|
||||
431,Requirements,In specification,[SR-COM-003] Receive Commands from Main Hub,"The system shall receive commands, configuration updates, and firmware update requests from the Main Hub. This requirement traces to feature [F-COM-01].",,includes(#426)
|
||||
432,Requirements,In specification,[SR-COM-004] Monitor Communication Link Status,The system shall monitor the status of the communication link with the Main Hub and report link availability and failure conditions. This requirement traces to feature [F-COM-01].,,includes(#426)
|
||||
433,Requirements,In specification,[SR-COM-005] Support On-Demand Data Requests,The system shall support on-demand requests from the Main Hub for sensor data. This requirement traces to feature [F-COM-02].,,includes(#427)
|
||||
434,Requirements,In specification,[SR-COM-006] Respond with Latest Sensor Data,The system shall respond to on-demand data requests with the most recent timestamped sensor data. This requirement traces to feature [F-COM-02].,,includes(#427)
|
||||
435,Requirements,In specification,[SR-COM-007] Include Data Validity in Responses,The system shall include sensor status and data validity information in on-demand data responses. This requirement traces to feature [F-COM-02].,,includes(#427)
|
||||
436,Requirements,In specification,[SR-COM-008] Support Peer Sensor Hub Communication,The system shall support limited peer-to-peer communication between Sensor Hubs. This requirement traces to feature [F-COM-03].,,includes(#428)
|
||||
437,Requirements,In specification,[SR-COM-009] Allow Peer Coordination Functions,The system shall allow peer communication for basic coordination functions such as connectivity checks or time synchronization. This requirement traces to feature [F-COM-03].,,includes(#428)
|
||||
438,Requirements,In specification,[SR-COM-010] Isolate Peer Communication from Control Logic,The system shall ensure that peer Sensor Hub communication does not interfere with Main Hub communication or control operations. This requirement traces to feature [F-COM-03].,,includes(#428)
|
||||
443,Requirements,New,[SR-DIAG-001] Implement Diagnostic Code Framework,"The system shall implement a diagnostic code framework for reporting system health conditions, warnings, errors, and fatal faults. This requirement traces to feature [F-DIAG-01].",,includes(#440)
|
||||
444,Requirements,New,[SR-DIAG-002] Assign Unique Diagnostic Codes,The system shall assign a unique diagnostic code to each detected fault or abnormal condition. This requirement traces to feature [F-DIAG-01].,,includes(#440)
|
||||
445,Requirements,New,[SR-DIAG-003] Classify Diagnostic Severity,"The system shall classify diagnostic codes by severity level including informational, warning, error, and fatal. This requirement traces to feature [F-DIAG-01].",,includes(#440)
|
||||
446,Requirements,New,[SR-DIAG-004] Timestamp and Source Diagnostics,The system shall associate each diagnostic event with a timestamp and the originating system component. This requirement traces to feature [F-DIAG-01].,,includes(#440)
|
||||
447,Requirements,New,[SR-DIAG-005] Persist Diagnostic Events,The system shall persist diagnostic events in non-volatile storage. This requirement traces to feature [F-DIAG-02].,,includes(#441)
|
||||
448,Requirements,New,[SR-DIAG-006] Retain Diagnostics Across Resets,The system shall retain diagnostic data across system resets and power cycles. This requirement traces to feature [F-DIAG-02].,,includes(#441)
|
||||
449,Requirements,New,[SR-DIAG-007] Bounded Diagnostic Storage,The system shall implement a bounded diagnostic storage mechanism with a defined overwrite or rollover policy. This requirement traces to feature [F-DIAG-02].,,includes(#441)
|
||||
450,Requirements,New,[SR-DIAG-008] Provide Diagnostic Session Interface,The system shall provide a diagnostic session interface for accessing diagnostic and system health data. This requirement traces to feature [F-DIAG-03].,,includes(#442)
|
||||
451,Requirements,New,[SR-DIAG-009] Retrieve Diagnostic Records,The system shall allow authorized diagnostic sessions to retrieve stored diagnostic events. This requirement traces to feature [F-DIAG-03].,,includes(#442)
|
||||
452,Requirements,New,[SR-DIAG-010] Clear Diagnostic Records,The system shall allow authorized diagnostic sessions to clear stored diagnostic records. This requirement traces to feature [F-DIAG-03].,,includes(#442)
|
||||
453,Requirements,New,[SR-DIAG-011] Non-Intrusive Diagnostic Sessions,The system shall ensure that diagnostic sessions do not interfere with normal sensor acquisition or communication operations. This requirement traces to feature [F-DIAG-03].,,includes(#442)
|
||||
465,Requirements,New,[SR-DATA-001] Persistent Timestamped Sensor Data,The system shall persist timestamped sensor data in non-volatile storage.,,includes(#462)
|
||||
466,Requirements,New,[SR-DATA-002] Sensor Data Metadata Storage,"The system shall store sensor data together with sensor identifiers, timestamps, and validity status.",,includes(#462)
|
||||
467,Requirements,New,[SR-DATA-003] Configurable Data Retention Policy,The system shall support configurable data retention and overwrite policies for persisted sensor data.,,includes(#462)
|
||||
468,Requirements,New,[SR-DATA-004] Data Persistence Component Interface,The system shall provide a Data Persistence (DP) component as the sole interface for persistent data access.,,includes(#463)
|
||||
469,Requirements,New,[SR-DATA-005] Storage Access Isolation,The system shall prevent application and feature modules from directly accessing storage hardware.,,includes(#463)
|
||||
470,Requirements,New,[SR-DATA-006] Structured Data Serialization,The DP component shall support serialization and deserialization of structured system data.,,includes(#463)
|
||||
471,Requirements,New,[SR-DATA-007] Data Flush Before Teardown,The system shall flush all critical runtime data to non-volatile storage before entering a controlled teardown or reset state.,,includes(#464)
|
||||
472,Requirements,New,[SR-DATA-008] Data Integrity During Updates,The system shall protect data integrity during firmware updates and machine constant updates.,,includes(#464)
|
||||
473,Requirements,New,[SR-DATA-009] Persistence Verification,The system shall verify successful data persistence before completing a system state transition.,,includes(#464)
|
||||
479,Requirements,New,[SR-OTA-001] OTA Negotiation Support,The system shall support OTA update negotiation initiated by the Main Hub.,,includes(#475)
|
||||
480,Requirements,New,[SR-OTA-002] OTA Readiness Validation,The system shall verify internal readiness conditions before accepting an OTA update request.,,includes(#475)
|
||||
481,Requirements,New,[SR-OTA-003] OTA Acknowledgement,The system shall explicitly acknowledge or reject OTA update requests.,,includes(#475)
|
||||
482,Requirements,New,[SR-OTA-004] Firmware Reception,The system shall receive firmware images over the established communication interface.,,includes(#476)
|
||||
483,Requirements,New,[SR-OTA-005] Firmware Temporary Storage,The system shall store received firmware images in non-volatile storage prior to validation.,,includes(#476)
|
||||
484,Requirements,New,[SR-OTA-006] Active Firmware Protection,The system shall prevent overwriting or execution of the active firmware during firmware reception.,,includes(#476)
|
||||
485,Requirements,New,[SR-OTA-007] Firmware Integrity Verification,The system shall validate the integrity of received firmware images before activation.,,includes(#477)
|
||||
486,Requirements,New,[SR-OTA-008] Firmware Rejection Handling,The system shall reject firmware images that fail integrity validation.,,includes(#477)
|
||||
487,Requirements,New,[SR-OTA-009] OTA Status Reporting,The system shall report firmware validation and OTA status to the Main Hub.,,includes(#477)
|
||||
488,Requirements,New,[SR-OTA-010] OTA Teardown Execution,The system shall execute a controlled teardown procedure prior to firmware activation.,,includes(#478)
|
||||
489,Requirements,New,[SR-OTA-011] Data Persistence Before Flashing,The system shall persist critical runtime data and calibration data before flashing new firmware.,,includes(#478)
|
||||
490,Requirements,New,[SR-OTA-012] Controlled Firmware Activation,The system shall activate new firmware only after successful integrity validation.,,includes(#478)
|
||||
491,Requirements,New,[SR-OTA-013] OTA Reboot Execution,The system shall reboot into the new firmware after successful activation.,,includes(#478)
|
||||
496,Requirements,New,[SR-SEC-001] Firmware Authenticity Verification,The system shall verify the authenticity of the firmware image before execution during every boot cycle.,,includes(#493)
|
||||
497,Requirements,New,[SR-SEC-002] Unauthorized Firmware Blocking,The system shall prevent execution of firmware images that fail cryptographic verification.,,includes(#493)
|
||||
498,Requirements,New,[SR-SEC-003] Secure Boot Failure Handling,The system shall enter a defined security fault state when secure boot verification fails.,,includes(#493)
|
||||
499,Requirements,New,[SR-SEC-004] Root-of-Trust Protection,The system shall protect the root-of-trust against unauthorized modification.,,includes(#493)
|
||||
500,Requirements,New,[SR-SEC-005] Flash Data Access Protection,The system shall protect sensitive data stored in internal flash memory from unauthorized access.,,includes(#494)
|
||||
501,Requirements,New,[SR-SEC-006] Encrypted External Storage,The system shall support encryption of sensitive data stored in external storage devices.,,includes(#494)
|
||||
502,Requirements,New,[SR-SEC-007] Cryptographic Key Isolation,The system shall restrict access to cryptographic keys to authorized system components only.,,includes(#494)
|
||||
503,Requirements,New,[SR-SEC-008] Stored Data Integrity Assurance,"The system shall ensure integrity of stored configuration, calibration, and machine constant data.",,includes(#494)
|
||||
504,Requirements,New,[SR-SEC-009] Encrypted Main Hub Communication,The system shall encrypt all communication exchanged with the Main Hub.,,includes(#495)
|
||||
505,Requirements,New,[SR-SEC-010] Message Integrity and Authenticity,The system shall ensure integrity and authenticity of all transmitted and received messages.,,includes(#495)
|
||||
506,Requirements,New,[SR-SEC-011] Secure OTA Data Transfer,The system shall use encrypted and authenticated communication channels for OTA firmware updates.,,includes(#495)
|
||||
507,Requirements,New,[SR-SEC-012] Security Violation Reporting,The system shall detect and report communication and security violations to the Main Hub.,,includes(#495)
|
||||
513,Requirements,New,[SR-SYS-001] Finite State Machine Control,The system shall implement a defined finite state machine to manage operational states and transitions.,,includes(#509)
|
||||
514,Requirements,New,[SR-SYS-002] State-Based Operation Restriction,The system shall restrict functional operations based on the current system state.,,includes(#509)
|
||||
515,Requirements,New,[SR-SYS-003] State Transition Notification,The system shall notify system components when a system state transition occurs.,,includes(#509)
|
||||
516,Requirements,New,[SR-SYS-004] Controlled Teardown Execution,"The system shall execute a controlled teardown sequence before firmware updates, machine constant updates, or system resets.",,includes(#510)
|
||||
517,Requirements,New,[SR-SYS-005] Critical Data Persistence Before Teardown,The system shall persist all critical runtime data before completing a teardown sequence.,,includes(#510)
|
||||
518,Requirements,New,[SR-SYS-006] Data Integrity Protection During Shutdown,"The system shall prevent data corruption during teardown, reset, or power-down operations.",,includes(#510)
|
||||
519,Requirements,New,[SR-SYS-007] OLED Display Interface,The system shall provide a local OLED display using the I2C communication protocol.,,includes(#511)
|
||||
520,Requirements,New,[SR-SYS-008] System Information Display,"The system shall display connectivity status, system state, connected sensor summary, and time/date on the OLED display.",,includes(#511)
|
||||
521,Requirements,New,[SR-SYS-009] Button-Based Menu Navigation,"The system shall provide menu navigation using Up, Down, and Select buttons.",,includes(#511)
|
||||
522,Requirements,New,[SR-SYS-010] Local Diagnostic and Health Menus,"The system shall provide diagnostic, sensor, and health information through the local OLED menu interface.",,includes(#511)
|
||||
523,Requirements,New,[SR-SYS-011] Diagnostic Session Support,The system shall support diagnostic sessions for retrieving system status and diagnostic data.,,includes(#512)
|
||||
524,Requirements,New,[SR-SYS-012] Debug Session Support,The system shall support debug sessions allowing controlled engineering commands.,,includes(#512)
|
||||
525,Requirements,New,[SR-SYS-013] Authorized Debug Access Control,The system shall restrict debug session actions to authorized engineering access only.,,includes(#512)
|
||||
|
Reference in New Issue
Block a user