ASF_01_sys_sw_arch/0 system_design/features/[HW] Hardware Abstraction Features.md

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)