# 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