# 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)