# GPIO Wrapper Module

## Overview

The GPIO wrapper module provides a C++ object-oriented interface for ESP-IDF GPIO functionality. This module encapsulates the ESP-IDF GPIO driver functions and provides a clean, easy-to-use API for GPIO operations.

## Features

- **Pin Configuration**: Configure GPIO pins as input, output, or open-drain
- **Digital I/O**: Read and write digital values to GPIO pins
- **Pull Resistors**: Configure internal pull-up and pull-down resistors
- **Interrupt Handling**: Attach interrupt handlers to GPIO pins
- **Pin Validation**: Automatic validation of GPIO pin numbers
- **Error Handling**: Comprehensive error checking and logging

## Architecture

### Class Diagram

```
┌─────────────────────────────────────┐
│              Gpio                   │
├─────────────────────────────────────┤
│ - m_isrInstalled_: bool             │
├─────────────────────────────────────┤
│ + Gpio()                            │
│ + ~Gpio()                           │
│ + configure(pin, mode): bool        │
│ + setLevel(pin, level): bool        │
│ + getLevel(pin): int32_t            │
│ + toggleLevel(pin): bool            │
│ + installIsr(flags): bool           │
│ + uninstallIsr(): bool              │
│ + attachInterrupt(...): bool        │
│ + detachInterrupt(pin): bool        │
│ + enableInterrupt(pin): bool        │
│ + disableInterrupt(pin): bool       │
│ + isValidPin(pin): bool [static]    │
│ - convertMode(mode): gpio_mode_t    │
│ - convertIntType(type): gpio_int_t  │
└─────────────────────────────────────┘
```

### Enumerations

#### GpioMode
- `INPUT`: Standard input mode
- `OUTPUT`: Standard output mode  
- `INPUT_PULLUP`: Input with internal pull-up resistor
- `INPUT_PULLDOWN`: Input with internal pull-down resistor
- `OUTPUT_OD`: Open-drain output mode

#### GpioIntType
- `DISABLE`: Disable interrupt
- `RISING_EDGE`: Trigger on rising edge
- `FALLING_EDGE`: Trigger on falling edge
- `ANY_EDGE`: Trigger on any edge
- `LOW_LEVEL`: Trigger on low level
- `HIGH_LEVEL`: Trigger on high level

## Usage Examples

### Basic GPIO Operations

```cpp
#include "gpio.hpp"

// Create GPIO instance
Gpio gpio;

// Configure pin 2 as output
gpio.configure(2, GpioMode::OUTPUT);

// Set pin high
gpio.setLevel(2, 1);

// Configure pin 4 as input with pull-up
gpio.configure(4, GpioMode::INPUT_PULLUP);

// Read pin level
int level = gpio.getLevel(4);
```

### Interrupt Handling

```cpp
// Interrupt callback function
void IRAM_ATTR gpioInterruptHandler(uint32_t pin, void* arg) {
    // Handle interrupt
    printf("Interrupt on pin %lu\n", pin);
}

// Setup interrupt
gpio.configure(5, GpioMode::INPUT);
gpio.attachInterrupt(5, GpioIntType::FALLING_EDGE, gpioInterruptHandler, nullptr);
```

## API Reference

### Constructor/Destructor

- **Gpio()**: Initialize GPIO wrapper instance
- **~Gpio()**: Clean up resources and uninstall ISR if needed

### Configuration Methods

- **configure(pin, mode)**: Configure GPIO pin mode and pull resistors
- **isValidPin(pin)**: Check if GPIO pin number is valid

### Digital I/O Methods

- **setLevel(pin, level)**: Set output pin level (0 or 1)
- **getLevel(pin)**: Read pin level, returns 0, 1, or -1 on error
- **toggleLevel(pin)**: Toggle output pin level

### Interrupt Methods

- **installIsr(flags)**: Install GPIO interrupt service
- **uninstallIsr()**: Uninstall GPIO interrupt service
- **attachInterrupt(pin, type, callback, arg)**: Attach interrupt handler
- **detachInterrupt(pin)**: Detach interrupt handler
- **enableInterrupt(pin)**: Enable interrupt for pin
- **disableInterrupt(pin)**: Disable interrupt for pin

## Error Handling

The module provides comprehensive error handling:
- Invalid pin numbers are checked and logged
- ESP-IDF errors are caught and logged with descriptive messages
- Return values indicate success/failure for all operations
- ESP_LOG is used for debugging and error reporting

## Dependencies

- ESP-IDF GPIO driver (`driver/gpio.h`)
- ESP-IDF error handling (`esp_err.h`)
- ESP-IDF logging (`esp_log.h`)

## Thread Safety

The GPIO wrapper is not inherently thread-safe. If used in multi-threaded applications, external synchronization mechanisms should be employed.

## Memory Usage

The GPIO wrapper has minimal memory footprint:
- Single boolean flag for ISR installation status
- No dynamic memory allocation
- Stack-based configuration structures

## Performance Considerations

- Direct ESP-IDF function calls for optimal performance
- Minimal overhead over raw ESP-IDF calls
- Interrupt handlers should be kept short and use IRAM_ATTR