# mrcodetastic/esp32-hub75-matrixpanel-dma architecture

> Architecture diagram of the GitHub repository mrcodetastic/esp32-hub75-matrixpanel-dma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrcodetastic/esp32-hub75-matrixpanel-dma
- Repository: https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma

## Overview

ESP32-HUB75-MatrixPanel-DMA is an embedded graphics library for driving HUB75 RGB LED panels through ESP32 hardware DMA. A user sketch invokes the MatrixPanel API, optionally through virtual-panel coordinate mapping or a GFX API; pixels are encoded into a DMA framebuffer with brightness and color correction, linked into descriptors, and continuously streamed by the platform-specific I2S or S3 GDMA backend to the panel. The graph reflects sampled runtime code and README capabilities; some unsampled integration details remain intentionally unwired.

Main entry points: [`src/ESP32-HUB75-MatrixPanel-I2S-DMA.h`](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h) (Matrix Panel API), [`src/platforms/esp32s3/gdma_lcd_parallel16.cpp`](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32s3/gdma_lcd_parallel16.cpp) (S3 GDMA Bus), [`src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp`](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp) (DMA Descriptors), [`src/platforms/esp32/esp32_i2s_parallel_dma.cpp`](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32/esp32_i2s_parallel_dma.cpp) (I2S Parallel Bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interface"]
  node_gfx["GFX API"]
  node_matrix_api["Matrix Panel API"]
  node_virtual_panel["Virtual Mapping"]
end

subgraph group_render["Rendering Core"]
  node_framebuffer[("DMA Framebuffer")]
  node_pixel_encoder["Pixel Encoder"]
  node_cie["CIE Correction<br/>[cie_luts.h]"]
  node_brightness["Brightness Control"]
  node_panel_drivers["Panel Drivers"]
end

subgraph group_transport["DMA Transport"]
  node_platform_detect["Platform Selection"]
  node_dma_descriptors["DMA Descriptors"]
  node_legacy_bus["I2S Parallel Bus"]
  node_s3_bus["S3 GDMA Bus"]
end

subgraph group_hardware["Panel Hardware"]
  node_pin_config["Pin Configuration"]
end

node_sketch(("User Sketch"))
node_esp32["ESP32 Hardware"]
node_hub75["HUB75 Panel"]
node_psram[("S3 PSRAM")]

node_sketch -->|"draws pixels"| node_matrix_api
node_sketch -->|"draws virtually"| node_virtual_panel
node_gfx -.->|"calls API"| node_matrix_api
node_virtual_panel -->|"maps coordinates"| node_matrix_api
node_matrix_api -->|"encodes pixels"| node_pixel_encoder
node_pixel_encoder -->|"uses LUTs"| node_cie
node_pixel_encoder -->|"writes pixels"| node_framebuffer
node_matrix_api -->|"sets brightness"| node_brightness
node_brightness -->|"updates OE"| node_framebuffer
node_matrix_api -->|"initializes drivers"| node_panel_drivers
node_framebuffer -->|"supplies buffers"| node_dma_descriptors
node_matrix_api -->|"creates links"| node_dma_descriptors
node_platform_detect -.->|"selects backend"| node_legacy_bus
node_platform_detect -.->|"selects backend"| node_s3_bus
node_dma_descriptors -->|"streams descriptors"| node_legacy_bus
node_dma_descriptors -->|"streams descriptors"| node_s3_bus
node_pin_config -->|"configures pins"| node_legacy_bus
node_pin_config -->|"configures pins"| node_s3_bus
node_legacy_bus -->|"outputs DMA"| node_esp32
node_s3_bus -->|"outputs GDMA"| node_esp32
node_s3_bus -.->|"optionally reads"| node_psram
node_esp32 -->|"drives panel"| node_hub75

click node_matrix_api "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h"
click node_virtual_panel "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-VirtualMatrixPanel_T.hpp"
click node_framebuffer "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h"
click node_pixel_encoder "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp"
click node_cie "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/cie_luts.h"
click node_brightness "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp"
click node_panel_drivers "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-leddrivers.cpp"
click node_platform_detect "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/platform_detect.hpp"
click node_dma_descriptors "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp"
click node_legacy_bus "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32/esp32_i2s_parallel_dma.cpp"
click node_s3_bus "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32s3/gdma_lcd_parallel16.cpp"
click node_pin_config "https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32/esp32-default-pins.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gfx,node_matrix_api,node_virtual_panel,node_sketch toneBlue
class node_framebuffer,node_pixel_encoder,node_cie,node_brightness,node_panel_drivers,node_psram toneAmber
class node_platform_detect,node_dma_descriptors,node_legacy_bus,node_s3_bus toneMint
class node_pin_config toneRose
class node_esp32,node_hub75 toneIndigo
```

## Components

### User Interface

- **GFX API**
- [Matrix Panel API](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h): `src/ESP32-HUB75-MatrixPanel-I2S-DMA.h`
- [Virtual Mapping](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-VirtualMatrixPanel_T.hpp): `src/ESP32-HUB75-VirtualMatrixPanel_T.hpp`

### Rendering Core

- [DMA Framebuffer](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h): `src/ESP32-HUB75-MatrixPanel-I2S-DMA.h`
- [Pixel Encoder](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp): `src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp`
- [CIE Correction](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/cie_luts.h): `src/cie_luts.h`
- [Brightness Control](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp): `src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp`
- [Panel Drivers](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-leddrivers.cpp): `src/ESP32-HUB75-MatrixPanel-leddrivers.cpp`

### DMA Transport

- [Platform Selection](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/platform_detect.hpp): `src/platforms/platform_detect.hpp`
- [DMA Descriptors](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp): `src/ESP32-HUB75-MatrixPanel-I2S-DMA.cpp`
- [I2S Parallel Bus](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32/esp32_i2s_parallel_dma.cpp): `src/platforms/esp32/esp32_i2s_parallel_dma.cpp`
- [S3 GDMA Bus](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32s3/gdma_lcd_parallel16.cpp): `src/platforms/esp32s3/gdma_lcd_parallel16.cpp`

### Panel Hardware

- [Pin Configuration](https://github.com/mrcodetastic/esp32-hub75-matrixpanel-dma/blob/master/src/platforms/esp32/esp32-default-pins.hpp): `src/platforms/esp32/esp32-default-pins.hpp`

### Other components

- **User Sketch**
- **ESP32 Hardware**
- **HUB75 Panel**
- **S3 PSRAM**

## Connections

- User Sketch → Matrix Panel API: draws pixels
- User Sketch → Virtual Mapping: draws virtually
- GFX API → Matrix Panel API: calls API
- Virtual Mapping → Matrix Panel API: maps coordinates
- Matrix Panel API → Pixel Encoder: encodes pixels
- Pixel Encoder → CIE Correction: uses LUTs
- Pixel Encoder → DMA Framebuffer: writes pixels
- Matrix Panel API → Brightness Control: sets brightness
- Brightness Control → DMA Framebuffer: updates OE
- Matrix Panel API → Panel Drivers: initializes drivers
- DMA Framebuffer → DMA Descriptors: supplies buffers
- Matrix Panel API → DMA Descriptors: creates links
- Platform Selection → I2S Parallel Bus: selects backend
- Platform Selection → S3 GDMA Bus: selects backend
- DMA Descriptors → I2S Parallel Bus: streams descriptors
- DMA Descriptors → S3 GDMA Bus: streams descriptors
- Pin Configuration → I2S Parallel Bus: configures pins
- Pin Configuration → S3 GDMA Bus: configures pins
- I2S Parallel Bus → ESP32 Hardware: outputs DMA
- S3 GDMA Bus → ESP32 Hardware: outputs GDMA
- S3 GDMA Bus → S3 PSRAM: optionally reads
- ESP32 Hardware → HUB75 Panel: drives panel
