# esp-rs/esp-idf-hal architecture

> Architecture diagram of the GitHub repository esp-rs/esp-idf-hal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/esp-rs/esp-idf-hal
- Repository: https://github.com/esp-rs/esp-idf-hal

## Overview

##### Component Details

a) Hardware Layer (Bottom):
- Hardware components based on the drivers (GPIO, ADC, I2C, SPI, etc.)

b) ESP-IDF SDK Layer:
- Connection to esp-idf-sys bindings

c) HAL Interface Layer (Core):
- Create modules matching the src/ directory structure:
- Peripheral Management (peripheral.rs, peripherals.rs)
- Communication Protocols (i2c.rs, spi.rs, uart.rs)
- Timer and System (timer.rs, sys.rs)
- GPIO and Interrupts (gpio.rs, interrupt.rs)
- Special Features (adc.rs, ledc.rs, rmt.rs)

d) Application Layer:
- Example applications from the examples/ directory
- Demonstrate both blocking and async implementations

##### Interactions and Data Flow

- Trait implementations (embedded-hal traits)
- Hardware access paths
- Async vs blocking operations
- Safety boundaries between unsafe and safe code

##### Notes Section

Callouts for:
- Hardware restrictions (from README's Hardware Notes section)
- Build requirements
- Supported MCU variants
- Key dependencies

- The clear separation between safe Rust code and unsafe ESP-IDF bindings
- The hardware abstraction layer architecture
- Support for multiple ESP32 variants
- Both blocking and async interfaces
- Integration with embedded-hal traits

- Future driver additions
- New MCU support
- Additional async implementations
- New example applications

This structure will provide a clear visualization of how the HAL provides safe Rust abstractions over the ESP-IDF SDK while maintaining performance and flexibility for embedded systems development.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef hardware fill:#a0d8ef
    classDef sdk fill:#ffcb9a
    classDef hal fill:#98fb98
    classDef app fill:#ffa07a
    classDef async fill:#dda0dd
    classDef unsafe fill:#ff6b6b

    %% Legend
    subgraph Legend
        L1[Hardware Components]:::hardware
        L2[ESP-IDF SDK]:::sdk
        L3[Safe HAL Interface]:::hal
        L4[Applications]:::app
        L5[Async Components]:::async
        L6[Unsafe Boundaries]:::unsafe
    end

    %% Hardware Layer
    subgraph Hardware
        ESP32[ESP32 MCU Family]:::hardware
        GPIO[GPIO Pins]:::hardware
        ADC[ADC Module]:::hardware
        I2C[I2C Interface]:::hardware
        SPI[SPI Interface]:::hardware
        UART[UART Port]:::hardware
        TIMER[Timer Hardware]:::hardware
    end

    %% ESP-IDF SDK Layer
    subgraph SDK
        ESP_IDF[ESP-IDF Native SDK]:::sdk
        ESP_SYS[esp-idf-sys Bindings]:::sdk
    end

    %% HAL Interface Layer
    subgraph HAL
        %% Peripheral Management
        PERIPH_MGT[Peripheral Management]:::hal
        click PERIPH_MGT "https://github.com/esp-rs/esp-idf-hal/blob/master/src/peripheral.rs"
        PERIPHERALS[Peripherals]:::hal
        click PERIPHERALS "https://github.com/esp-rs/esp-idf-hal/blob/master/src/peripherals.rs"
        PRELUDE[Prelude]:::hal
        click PRELUDE "https://github.com/esp-rs/esp-idf-hal/blob/master/src/prelude.rs"

        %% Communication Protocols
        COMM_PROTO[Communication Protocols]:::hal
        I2C_HAL[I2C HAL]:::hal
        click I2C_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/i2c.rs"
        SPI_HAL[SPI HAL]:::hal
        click SPI_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/spi.rs"
        UART_HAL[UART HAL]:::hal
        click UART_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/uart.rs"
        I2S_HAL[I2S HAL]:::hal
        click I2S_HAL "https://github.com/esp-rs/esp-idf-hal/tree/master/src/i2s/"

        %% Timer and System
        SYS_TIMER[Timer & System]:::hal
        TIMER_HAL[Timer]:::hal
        click TIMER_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/timer.rs"
        SYS_HAL[System]:::hal
        click SYS_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/sys.rs"
        TASK_HAL[Task]:::hal
        click TASK_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/task.rs"
        DELAY_HAL[Delay]:::hal
        click DELAY_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/delay.rs"

        %% GPIO and Interrupts
        GPIO_INT[GPIO & Interrupts]:::hal
        GPIO_HAL[GPIO]:::hal
        click GPIO_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/gpio.rs"
        INT_HAL[Interrupts]:::hal
        click INT_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/interrupt.rs"
        IO_HAL[IO]:::hal
        click IO_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/io.rs"

        %% Special Features
        SPECIAL[Special Features]:::hal
        ADC_HAL[ADC]:::hal
        click ADC_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/adc.rs"
        LEDC_HAL[LEDC]:::hal
        click LEDC_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/ledc.rs"
        RMT_HAL[RMT]:::hal
        click RMT_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/rmt.rs"
        PCNT_HAL[PCNT]:::hal
        click PCNT_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/pcnt.rs"
        TEMP_HAL[Temperature Sensor]:::hal
        click TEMP_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/temp_sensor.rs"

        %% Hardware Specific
        HW_SPEC[Hardware Specific]:::hal
        HALL_HAL[Hall Sensor]:::hal
        click HALL_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/hall.rs"
        MAC_HAL[MAC]:::hal
        click MAC_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/mac.rs"
        CPU_HAL[CPU]:::hal
        click CPU_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/cpu.rs"
        RESET_HAL[Reset]:::hal
        click RESET_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/reset.rs"
        ROM_HAL[ROM]:::hal
        click ROM_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/rom.rs"

        %% Storage
        STORAGE[Storage]:::hal
        SD_HAL[SD Card]:::hal
        click SD_HAL "https://github.com/esp-rs/esp-idf-hal/tree/master/src/sd/"
        ULP_HAL[ULP]:::hal
        click ULP_HAL "https://github.com/esp-rs/esp-idf-hal/blob/master/src/ulp.rs"
    end

    %% Application Layer
    subgraph Applications
        BLINKY[Blinky Example]:::app
        click BLINKY "https://github.com/esp-rs/esp-idf-hal/blob/master/examples/blinky.rs"
        BLINKY_ASYNC[Async Blinky]:::app
        click BLINKY_ASYNC "https://github.com/esp-rs/esp-idf-hal/blob/master/examples/blinky_async.rs"
        I2C_EXAMPLE[I2C Master/Slave]:::app
        click I2C_EXAMPLE "https://github.com/esp-rs/esp-idf-hal/blob/master/examples/i2c_master_slave.rs"
        SPI_EXAMPLE[SPI Loopback]:::app
        click SPI_EXAMPLE "https://github.com/esp-rs/esp-idf-hal/blob/master/examples/spi_loopback.rs"
        UART_EXAMPLE[UART Loopback]:::app
        click UART_EXAMPLE "https://github.com/esp-rs/esp-idf-hal/blob/master/examples/uart_loopback.rs"
        TIMER_ASYNC[Async Timer]:::app
        click TIMER_ASYNC "https://github.com/esp-rs/esp-idf-hal/blob/master/examples/timer_async.rs"
    end

    %% Relationships
    ESP32 --> GPIO & ADC & I2C & SPI & UART & TIMER
    ESP_IDF --> ESP_SYS
    ESP_SYS --> PERIPH_MGT
    PERIPH_MGT --> PERIPHERALS
    PERIPHERALS --> GPIO_INT & COMM_PROTO & SYS_TIMER & SPECIAL & HW_SPEC & STORAGE
    Applications --> HAL
```
