# afiskon/stm32-i2s-examples architecture

> Architecture diagram of the GitHub repository afiskon/stm32-i2s-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afiskon/stm32-i2s-examples
- Repository: https://github.com/afiskon/stm32-i2s-examples

## Overview

##### Project type and purpose
- This is a collection of bare-metal STM32F4 firmware examples demonstrating I2S audio usage.
- Two sample applications:
- sdcard-wav-example: reads a WAV file from an SD card (using FATFS), drives an ST7735 display, and outputs audio over I2S.
- sine-wave-example: generates a test sine wave in software and outputs it over I2S.
- Purpose: illustrate HAL-based peripheral initialization, DMA streams, file-system integration, and audio output on an STM32F411RE.

##### File structure
- Top-level: LICENSE, README, two example folders.
- Each example folder has:
- Inc/ : public headers (main.h, HAL config, interrupt prototypes).
- Src/ : application code (main.c, HAL MSP, interrupt handlers, system init).
- startup_stm32f411xe.s, STM32F411RETx_FLASH.ld: MCU startup and linker script.
- Makefile + cubefix.sh: build automation and CubeMX integration hack.
- main.ioc + mx.scratch: STM32CubeMX configuration.
- sdcard-wav-example/fatfs: FATFS file-system sources.
- sdcard-wav-example/sdcard: SD card low-level driver.
- sdcard-wav-example/st7735: TFT LCD display driver and fonts.

##### Key reminders
- Be very detailed: show each layer, each peripheral interface, and every data path.
- Do not over-simplify: separate the SD card driver, the file-system middleware, the audio pipeline, and the display pipeline into distinct components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Devices
    subgraph "External Devices"
        direction TB
        microSD["microSD Card"]:::external
        AudioOut["Audio Output (Codec/Headphones)"]:::external
        LCD["ST7735 LCD"]:::external
    end

    %% MCU Hardware
    subgraph "STM32F411RE MCU" 
        direction TB
        Core["Cortex-M4 Core"]:::hardware
        DMA["DMA Controller"]:::hardware
        I2S["I2S Peripheral"]:::hardware
        SDIF["SD Interface"]:::hardware
        SPI["SPI Peripheral (for LCD)"]:::hardware
        TIMER["SysTick/Timers"]:::hardware
    end

    %% Software Layers
    subgraph "Software Layers"
        direction TB
        subgraph "Startup & System"
            CMSIS_WAV["CMSIS Startup & System (WAV)"]:::middleware
            CMSIS_SINE["CMSIS Startup & System (Sine)"]:::middleware
        end
        subgraph "HAL Drivers"
            HAL_WAV["STM32Cube HAL (WAV)"]:::driver
            HAL_SINE["STM32Cube HAL (Sine)"]:::driver
        end
        subgraph "Middleware & Drivers"
            FATFS["FATFS Middleware"]:::middleware
            SD_DRV["SD Card Driver"]:::driver
            ST7735_DRV["ST7735 Display Driver"]:::driver
        end
        subgraph "Application & IRQ"
            APP_WAV["Application main.c (WAV)"]:::app
            APP_SINE["Application main.c (Sine)"]:::app
            IRQ_WAV["Interrupt Handlers (WAV)"]:::app
            IRQ_SINE["Interrupt Handlers (Sine)"]:::app
        end
        subgraph "Build Configuration"
            LINK_WAV["Linker & Build (WAV)"]:::middleware
            LINK_SINE["Linker & Build (Sine)"]:::middleware
            IOC_WAV["Project Config IOC (WAV)"]:::middleware
            IOC_SINE["Project Config IOC (Sine)"]:::middleware
            GPIO_TMP["GPIO & System Templates (Sine)"]:::middleware
        end
    end

    %% Data and Control Flows
    microSD -->|SPI/SDIO| SDIF
    SDIF -->|block I/O| SD_DRV
    SD_DRV -->|diskio| FATFS
    FATFS -->|read WAV| APP_WAV
    APP_WAV -->|buffer data| DMA
    APP_SINE -->|generate samples| DMA
    DMA -->|transfer| I2S
    I2S -->|audio stream| AudioOut

    Core -->|calls| CMSIS_WAV
    Core -->|calls| CMSIS_SINE
    CMSIS_WAV --> HAL_WAV
    CMSIS_SINE --> HAL_SINE
    HAL_WAV --> SD_DRV
    HAL_WAV --> ST7735_DRV
    HAL_SINE --> DMA
    HAL_SINE --> I2S

    APP_WAV --> HAL_WAV
    APP_SINE --> HAL_SINE
    IRQ_WAV --> DMA
    IRQ_WAV --> I2S
    IRQ_SINE --> DMA
    IRQ_SINE --> I2S

    ST7735_DRV -->|SPI| SPI
    SPI --> LCD

    LINK_WAV --> CORE_INIT[/"Linker Script & Makefile"/]:::middleware
    LINK_SINE --> CORE_INIT
    IOC_WAV --> CMSIS_WAV
    IOC_SINE --> CMSIS_SINE
    GPIO_TMP --> CMSIS_SINE

    %% Click Events
    click HAL_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/Inc/stm32f4xx_hal_conf.h"
    click HAL_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/Src/stm32f4xx_hal_msp.c"
    click HAL_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Inc/stm32f4xx_hal_conf.h"
    click HAL_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Src/stm32f4xx_hal_msp.c"

    click CMSIS_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/Src/system_stm32f4xx.c"
    click CMSIS_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/startup_stm32f411xe.s"
    click CMSIS_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Src/system_stm32f4xx.c"
    click CMSIS_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/startup_stm32f411xe.s"

    click APP_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/Src/main.c"
    click APP_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Src/main.c"

    click IRQ_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/Src/stm32f4xx_it.c"
    click IRQ_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/Inc/stm32f4xx_it.h"
    click IRQ_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Src/stm32f4xx_it.c"
    click IRQ_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Inc/stm32f4xx_it.h"

    click LINK_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/STM32F411RETx_FLASH.ld"
    click LINK_WAV "https://github.com/afiskon/stm32-i2s-examples/tree/master/sdcard-wav-example/Makefile"
    click LINK_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/cubefix.sh"
    click LINK_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/STM32F411RETx_FLASH.ld"
    click LINK_SINE "https://github.com/afiskon/stm32-i2s-examples/tree/master/sine-wave-example/Makefile"
    click LINK_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/cubefix.sh"

    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/ff.c"
    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/ff.h"
    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/ffsystem.c"
    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/ffunicode.c"
    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/diskio.c"
    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/diskio.h"
    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/integer.h"
    click FATFS "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/fatfs/ffconf.h"

    click SD_DRV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/sdcard/sdcard.c"
    click SD_DRV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/sdcard/sdcard.h"

    click ST7735_DRV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/st7735/st7735.c"
    click ST7735_DRV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/st7735/st7735.h"
    click ST7735_DRV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/st7735/fonts.c"
    click ST7735_DRV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/st7735/fonts.h"
    click ST7735_DRV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/st7735/testimg.h"

    click IOC_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/main.ioc"
    click IOC_WAV "https://github.com/afiskon/stm32-i2s-examples/blob/master/sdcard-wav-example/mx.scratch"
    click IOC_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/main.ioc"
    click IOC_SINE "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/mx.scratch"

    click GPIO_TMP "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Src/gpio.tmp"
    click GPIO_TMP "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Src/system.tmp"
    click GPIO_TMP "https://github.com/afiskon/stm32-i2s-examples/blob/master/sine-wave-example/Src/license.tmp"

    %% Styling
    classDef hardware fill:#ddd,stroke:#333,stroke-width:1px
    classDef middleware fill:#bbf,stroke:#333,stroke-width:1px
    classDef driver fill:#aaf,stroke:#333,stroke-width:1px
    classDef app fill:#afa,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
```
