update

System Design/system_design/features/[HW] Hardware Abstraction Features.md

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