software and system v1
This commit is contained in:
241
1 software design/features/SF-HW_Hardware_Abstraction.md
Normal file
241
1 software design/features/SF-HW_Hardware_Abstraction.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Software Feature: Hardware Abstraction (SF-HW)
|
||||
## ASF Sensor Hub (Sub-Hub) Embedded System
|
||||
|
||||
**Feature ID:** SF-HW
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Platform:** ESP32-S3, ESP-IDF v5.4
|
||||
**Standard:** ISO/IEC/IEEE 29148:2018
|
||||
|
||||
---
|
||||
|
||||
## 1. Feature Overview
|
||||
|
||||
The Hardware Abstraction feature provides platform-independent hardware access through Sensor Abstraction Layer (SAL) and hardware interface abstraction. This feature ensures application logic is isolated from hardware specifics.
|
||||
|
||||
**Primary Purpose:** Enable hardware independence and maintainability through abstraction layers.
|
||||
|
||||
---
|
||||
|
||||
## 2. Feature Scope
|
||||
|
||||
### 2.1 In-Scope
|
||||
|
||||
- Sensor Abstraction Layer (SAL) implementation
|
||||
- Hardware interface abstraction (I2C, SPI, UART, ADC, GPIO)
|
||||
- GPIO discipline enforcement
|
||||
- Hardware resource conflict detection
|
||||
- Sensor state management
|
||||
|
||||
### 2.2 Out-of-Scope
|
||||
|
||||
- Hardware driver implementation details (ESP-IDF)
|
||||
- Hardware-specific optimizations (deferred to implementation)
|
||||
|
||||
---
|
||||
|
||||
## 3. Sub-Features
|
||||
|
||||
### 3.1 SF-HW-01: Sensor Abstraction Layer (SAL)
|
||||
|
||||
**Description:** Provide uniform sensor interface for all sensor types.
|
||||
|
||||
**Software Requirements:**
|
||||
- SWR-HW-001: Provide Sensor Abstraction Layer for all sensor access
|
||||
- SWR-HW-002: Prevent application layer from directly accessing sensor hardware
|
||||
- SWR-HW-003: Track sensor state (INIT, WARMUP, STABLE, DEGRADED, FAILED)
|
||||
- SWR-HW-004: Provide sensor validation and health check functions
|
||||
|
||||
**Implementing Components:**
|
||||
- Sensor Drivers (SAL implementation)
|
||||
- Sensor Manager (SAL interface usage)
|
||||
- Hardware Abstraction Layer (coordination)
|
||||
|
||||
### 3.2 SF-HW-02: Hardware Interface Abstraction
|
||||
|
||||
**Description:** Abstract all hardware interfaces through OSAL layer.
|
||||
|
||||
**Software Requirements:**
|
||||
- SWR-HW-005: Abstract all hardware interfaces through driver layers
|
||||
- SWR-HW-006: Enforce GPIO discipline (no strapping pins, proper pull-ups, ADC1/ADC2 separation)
|
||||
- SWR-HW-007: Maintain canonical GPIO map document
|
||||
- SWR-HW-008: Detect and report hardware resource conflicts
|
||||
|
||||
**Implementing Components:**
|
||||
- OSAL Wrappers (I2C, SPI, UART, ADC, GPIO)
|
||||
- Hardware Abstraction Layer (coordination)
|
||||
- GPIO Wrapper (discipline enforcement)
|
||||
|
||||
---
|
||||
|
||||
## 4. Software Requirements
|
||||
|
||||
### 4.1 Sensor Abstraction Layer Requirements
|
||||
|
||||
**SWR-HW-001:** The software SHALL provide a Sensor Abstraction Layer (SAL) for all sensor access, with uniform interface for all sensor types.
|
||||
|
||||
**Traceability:** SR-HW-001
|
||||
**Component:** Sensor Drivers, Sensor Manager
|
||||
**Verification:** Inspection, Test
|
||||
|
||||
**SWR-HW-002:** The software SHALL prevent application layer from directly accessing sensor hardware, enforcing access only through SAL interface.
|
||||
|
||||
**Traceability:** SR-HW-002
|
||||
**Component:** Sensor Drivers, Hardware Abstraction Layer
|
||||
**Verification:** Inspection
|
||||
|
||||
**SWR-HW-003:** The software SHALL track sensor state including INIT, WARMUP, STABLE, DEGRADED, and FAILED states.
|
||||
|
||||
**Traceability:** SR-HW-003
|
||||
**Component:** Sensor Drivers, Sensor Manager
|
||||
**Verification:** Test
|
||||
|
||||
**SWR-HW-004:** The software SHALL provide sensor validation and health check functions through SAL interface.
|
||||
|
||||
**Traceability:** SR-HW-004
|
||||
**Component:** Sensor Drivers
|
||||
**Verification:** Test
|
||||
|
||||
### 4.2 Hardware Interface Abstraction Requirements
|
||||
|
||||
**SWR-HW-005:** The software SHALL abstract all hardware interfaces (I2C, SPI, UART, ADC, GPIO) through OSAL driver layers.
|
||||
|
||||
**Traceability:** SR-HW-005
|
||||
**Component:** OSAL Wrappers
|
||||
**Verification:** Inspection
|
||||
|
||||
**SWR-HW-006:** The software SHALL enforce GPIO discipline including avoiding strapping pins (GPIO 0, 3, 45, 46), ensuring proper pull-up resistors, and separating ADC1/ADC2 usage.
|
||||
|
||||
**Traceability:** SR-HW-006
|
||||
**Component:** GPIO Wrapper
|
||||
**Verification:** Inspection, Test
|
||||
|
||||
**SWR-HW-007:** The software SHALL maintain a canonical GPIO map document as single source of truth for GPIO pin assignments.
|
||||
|
||||
**Traceability:** SR-HW-007
|
||||
**Component:** Hardware Abstraction Layer
|
||||
**Verification:** Documentation Review
|
||||
|
||||
**SWR-HW-008:** The software SHALL detect and report hardware resource conflicts including GPIO pin conflicts, I2C bus conflicts, and ADC channel conflicts.
|
||||
|
||||
**Traceability:** SR-HW-008
|
||||
**Component:** Hardware Abstraction Layer, GPIO Wrapper
|
||||
**Verification:** Test
|
||||
|
||||
---
|
||||
|
||||
## 5. Component Responsibilities
|
||||
|
||||
### 5.1 Sensor Drivers
|
||||
|
||||
- Implement SAL interface
|
||||
- Handle sensor-specific protocols
|
||||
- Manage sensor state
|
||||
- Report sensor health
|
||||
|
||||
### 5.2 OSAL Wrappers
|
||||
|
||||
- Abstract ESP-IDF services
|
||||
- Provide platform-independent interfaces
|
||||
- Enforce hardware discipline
|
||||
- Detect resource conflicts
|
||||
|
||||
### 5.3 Hardware Abstraction Layer
|
||||
|
||||
- Coordinate hardware access
|
||||
- Validate GPIO usage
|
||||
- Manage resource allocation
|
||||
- Report conflicts
|
||||
|
||||
### 5.4 Sensor Manager
|
||||
|
||||
- Use SAL interface (not direct hardware access)
|
||||
- Coordinate sensor operations
|
||||
- Manage sensor lifecycle
|
||||
|
||||
---
|
||||
|
||||
## 6. GPIO Discipline
|
||||
|
||||
### 6.1 Strapping Pin Protection
|
||||
|
||||
- **GPIO 0:** Boot mode selection (PROTECTED)
|
||||
- **GPIO 3:** JTAG (PROTECTED)
|
||||
- **GPIO 45:** Strapping pin (PROTECTED)
|
||||
- **GPIO 46:** Strapping pin (PROTECTED)
|
||||
|
||||
### 6.2 ADC Constraints
|
||||
|
||||
- **ADC1:** Available when Wi-Fi active
|
||||
- **ADC2:** NOT available when Wi-Fi active
|
||||
- All analog sensors must use ADC1
|
||||
|
||||
### 6.3 I2C Pull-up Requirements
|
||||
|
||||
- Physical pull-up resistors: 2.2kΩ - 4.7kΩ (3.3V)
|
||||
- Software pull-ups: Not recommended for production
|
||||
- All shared I2C buses must have pull-ups
|
||||
|
||||
---
|
||||
|
||||
## 7. Traceability
|
||||
|
||||
### 7.1 System Requirements
|
||||
|
||||
- **SR-HW-001** through **SR-HW-008:** All hardware abstraction requirements
|
||||
|
||||
### 7.2 System Features
|
||||
|
||||
- **F-HW-01:** Sensor Abstraction Layer
|
||||
- **F-HW-02:** Hardware Interface Abstraction
|
||||
|
||||
### 7.3 Gap Resolution
|
||||
|
||||
- **GAP-SR-SWR-005** through **GAP-SR-SWR-007:** Missing HW software requirements (RESOLVED)
|
||||
- **GAP-COV-002:** Missing HW software coverage (RESOLVED)
|
||||
|
||||
---
|
||||
|
||||
## 8. Dependencies
|
||||
|
||||
### 8.1 Feature Dependencies
|
||||
|
||||
- **SF-DAQ:** Sensor data acquisition uses SAL
|
||||
- **SF-DQC:** Sensor quality checks use SAL
|
||||
- **SF-SYS:** GPIO discipline enforcement
|
||||
|
||||
### 8.2 Component Dependencies
|
||||
|
||||
- OSAL Wrappers
|
||||
- Sensor Drivers
|
||||
- Hardware Abstraction Layer
|
||||
- Sensor Manager
|
||||
|
||||
---
|
||||
|
||||
## 9. Testing Strategy
|
||||
|
||||
### 9.1 Unit Testing
|
||||
|
||||
- SAL interface implementation
|
||||
- GPIO discipline enforcement
|
||||
- Resource conflict detection
|
||||
|
||||
### 9.2 Integration Testing
|
||||
|
||||
- Sensor driver integration
|
||||
- OSAL wrapper integration
|
||||
- Hardware access validation
|
||||
|
||||
### 9.3 Hardware Testing
|
||||
|
||||
- GPIO pin usage validation
|
||||
- I2C bus operation
|
||||
- ADC channel operation
|
||||
- Resource conflict scenarios
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
**Approval Required:** Software Architect
|
||||
246
1 software design/features/SF-PWR_Power_Fault_Handling.md
Normal file
246
1 software design/features/SF-PWR_Power_Fault_Handling.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# Software Feature: Power & Fault Handling (SF-PWR)
|
||||
## ASF Sensor Hub (Sub-Hub) Embedded System
|
||||
|
||||
**Feature ID:** SF-PWR
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Platform:** ESP32-S3, ESP-IDF v5.4
|
||||
**Standard:** ISO/IEC/IEEE 29148:2018
|
||||
|
||||
---
|
||||
|
||||
## 1. Feature Overview
|
||||
|
||||
The Power & Fault Handling feature provides brownout detection, power-loss recovery, and graceful shutdown mechanisms. This feature ensures system reliability under power fluctuations and enables clean recovery after power restoration.
|
||||
|
||||
**Primary Purpose:** Protect critical data during power interruptions and enable graceful system recovery.
|
||||
|
||||
---
|
||||
|
||||
## 2. Feature Scope
|
||||
|
||||
### 2.1 In-Scope
|
||||
|
||||
- Brownout detection and handling
|
||||
- Critical data flush on power loss
|
||||
- Graceful shutdown sequence
|
||||
- Power restoration detection
|
||||
- Clean recovery after power restoration
|
||||
- Power-loss event reporting
|
||||
|
||||
### 2.2 Out-of-Scope
|
||||
|
||||
- Battery-powered operation
|
||||
- Power management for low-power modes
|
||||
- Power consumption optimization
|
||||
|
||||
---
|
||||
|
||||
## 3. Sub-Features
|
||||
|
||||
### 3.1 SF-PWR-01: Brownout Detection and Handling
|
||||
|
||||
**Description:** Monitor input voltage and take immediate action if voltage drops below safe threshold.
|
||||
|
||||
**Software Requirements:**
|
||||
- SWR-PWR-001: Monitor input voltage and detect brownout conditions
|
||||
- SWR-PWR-002: Immediately flush critical data buffers on brownout
|
||||
- SWR-PWR-003: Enter graceful shutdown mode during brownout
|
||||
- SWR-PWR-004: Perform clean reboot after power stabilization
|
||||
|
||||
**Implementing Components:**
|
||||
- Error Handler (brownout detection)
|
||||
- Data Persistence (critical data flush)
|
||||
- System State Manager (shutdown coordination)
|
||||
|
||||
### 3.2 SF-PWR-02: Power-Loss Recovery
|
||||
|
||||
**Description:** Recover gracefully from power interruptions and restore system state.
|
||||
|
||||
**Software Requirements:**
|
||||
- SWR-PWR-005: Recover gracefully from power interruptions
|
||||
- SWR-PWR-006: Verify data integrity after power restoration
|
||||
- SWR-PWR-007: Restore system state from persistent storage
|
||||
- SWR-PWR-008: Report power-loss and recovery events
|
||||
|
||||
**Implementing Components:**
|
||||
- System State Manager (recovery coordination)
|
||||
- Data Persistence (state restoration)
|
||||
- Diagnostics Manager (event reporting)
|
||||
|
||||
---
|
||||
|
||||
## 4. Software Requirements
|
||||
|
||||
### 4.1 Brownout Detection Requirements
|
||||
|
||||
**SWR-PWR-001:** The software SHALL monitor input voltage and detect brownout conditions below 3.0V using hardware brownout detector (BOD).
|
||||
|
||||
**Traceability:** SR-PWR-001
|
||||
**Component:** Error Handler
|
||||
**Verification:** Hardware Test
|
||||
|
||||
**SWR-PWR-002:** The software SHALL immediately flush all critical data buffers to non-volatile storage upon brownout detection.
|
||||
|
||||
**Traceability:** SR-PWR-002
|
||||
**Component:** Data Persistence
|
||||
**Verification:** Hardware Test
|
||||
|
||||
**SWR-PWR-003:** The software SHALL enter graceful shutdown mode during brownout conditions, completing all pending operations within supercapacitor runtime (1-2 seconds).
|
||||
|
||||
**Traceability:** SR-PWR-003
|
||||
**Component:** System State Manager
|
||||
**Verification:** Hardware Test
|
||||
|
||||
**SWR-PWR-004:** The software SHALL perform clean reboot after power stabilization, waiting for power stabilization (100ms) before rebooting.
|
||||
|
||||
**Traceability:** SR-PWR-004
|
||||
**Component:** System State Manager
|
||||
**Verification:** Hardware Test
|
||||
|
||||
### 4.2 Power-Loss Recovery Requirements
|
||||
|
||||
**SWR-PWR-005:** The software SHALL recover gracefully from power interruptions (< 1 second) without data corruption.
|
||||
|
||||
**Traceability:** SR-PWR-005
|
||||
**Component:** System State Manager
|
||||
**Verification:** Hardware Test
|
||||
|
||||
**SWR-PWR-006:** The software SHALL verify data integrity after power restoration by checking checksums and file system consistency.
|
||||
|
||||
**Traceability:** SR-PWR-006
|
||||
**Component:** Data Persistence
|
||||
**Verification:** Hardware Test
|
||||
|
||||
**SWR-PWR-007:** The software SHALL restore system state from persistent storage after power restoration, including sensor configuration and calibration data.
|
||||
|
||||
**Traceability:** SR-PWR-007
|
||||
**Component:** Data Persistence, System State Manager
|
||||
**Verification:** Hardware Test
|
||||
|
||||
**SWR-PWR-008:** The software SHALL report power-loss and recovery events via diagnostics with timestamps and recovery status.
|
||||
|
||||
**Traceability:** SR-PWR-008
|
||||
**Component:** Diagnostics Manager
|
||||
**Verification:** Test
|
||||
|
||||
---
|
||||
|
||||
## 5. Component Responsibilities
|
||||
|
||||
### 5.1 Error Handler
|
||||
|
||||
- Brownout detection via hardware BOD interrupt
|
||||
- Trigger critical data flush
|
||||
- Coordinate graceful shutdown
|
||||
|
||||
### 5.2 Data Persistence
|
||||
|
||||
- Flush critical data buffers
|
||||
- Verify data integrity
|
||||
- Restore system state
|
||||
|
||||
### 5.3 System State Manager
|
||||
|
||||
- Coordinate shutdown sequence
|
||||
- Manage recovery process
|
||||
- State restoration
|
||||
|
||||
### 5.4 Diagnostics Manager
|
||||
|
||||
- Report power-loss events
|
||||
- Report recovery events
|
||||
- Log power-related diagnostics
|
||||
|
||||
---
|
||||
|
||||
## 6. State Machine Integration
|
||||
|
||||
### 6.1 Brownout Handling
|
||||
|
||||
```
|
||||
[RUNNING]
|
||||
↓ Brownout detected
|
||||
[TEARDOWN] (fast path)
|
||||
↓ Critical data flushed
|
||||
[INIT] (after power restoration)
|
||||
↓ State restoration
|
||||
[RUNNING]
|
||||
```
|
||||
|
||||
### 6.2 Power-Loss Recovery
|
||||
|
||||
```
|
||||
[Power Loss]
|
||||
↓ Data flush
|
||||
[Power Off]
|
||||
↓ Power restoration
|
||||
[INIT]
|
||||
↓ Data integrity check
|
||||
↓ State restoration
|
||||
[RUNNING]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Traceability
|
||||
|
||||
### 7.1 System Requirements
|
||||
|
||||
- **SR-PWR-001** through **SR-PWR-008:** All power and fault handling requirements
|
||||
|
||||
### 7.2 System Features
|
||||
|
||||
- **F-PWR-01:** Brownout Detection and Handling
|
||||
- **F-PWR-02:** Power-Loss Recovery
|
||||
|
||||
### 7.3 Gap Resolution
|
||||
|
||||
- **GAP-SR-SWR-001** through **GAP-SR-SWR-004:** Missing PWR software requirements (RESOLVED)
|
||||
- **GAP-COV-001:** Missing PWR software coverage (RESOLVED)
|
||||
|
||||
---
|
||||
|
||||
## 8. Dependencies
|
||||
|
||||
### 8.1 Feature Dependencies
|
||||
|
||||
- **SF-DATA:** Data persistence for critical data flush
|
||||
- **SF-SYS:** System state management for shutdown/recovery
|
||||
- **SF-DIAG:** Diagnostic reporting for power events
|
||||
|
||||
### 8.2 Component Dependencies
|
||||
|
||||
- Error Handler
|
||||
- Data Persistence
|
||||
- System State Manager
|
||||
- Diagnostics Manager
|
||||
- Storage Drivers
|
||||
|
||||
---
|
||||
|
||||
## 9. Testing Strategy
|
||||
|
||||
### 9.1 Unit Testing
|
||||
|
||||
- Brownout detection logic
|
||||
- Data flush operations
|
||||
- Recovery sequence
|
||||
|
||||
### 9.2 Integration Testing
|
||||
|
||||
- End-to-end brownout handling
|
||||
- Power-loss recovery
|
||||
- Data integrity verification
|
||||
|
||||
### 9.3 Hardware Testing
|
||||
|
||||
- Actual brownout conditions
|
||||
- Power interruption simulation
|
||||
- Supercapacitor behavior validation
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
**Approval Required:** Software Architect
|
||||
Reference in New Issue
Block a user