ESP32 HUB75 DMA Driver

High-performance DMA-based driver for HUB75 RGB LED matrix panels, supporting ESP32, ESP32-S2, ESP32-S3, ESP32-C6, and ESP32-P4.

Features

• ✅ Static circular DMA refresh - No interrupts, no CPU intervention after begin()
• ✅ Multi-platform support - ESP32-S3 (GDMA), ESP32/S2 (I2S), ESP32-P4 (PARLIO)
• ✅ BCM timing - Descriptor duplication (GDMA/I2S) or buffer padding (PARLIO)
• ✅ Scan pattern support - 1/4, 1/8, 1/16, 1/32 scan panels with coordinate remapping
• ✅ Shift driver initialization - FM6126A/ICN2038S, FM6124, MBI5124, DP3246
• ✅ Multi-panel layouts - Serpentine and zigzag chaining for M×N grids
  • Serpentine: Alternate rows upside down (saves cable length)
  • Zigzag: All panels upright (longer cables)
  • Row-major traversal (matches ESP32-HUB75-MatrixPanel-DMA reference)
• ✅ CIE 1931 gamma correction - Native bit-depth LUTs (6-12 bit)
• ✅ Dual-mode brightness - Basis (1-255) + intensity (0.0-1.0) control
• ✅ Multiple pixel formats - RGB888, RGB888_32, RGB565 input
• ✅ Direct buffer writes - No separate framebuffer copy, IRAM optimized
• ✅ Double buffering - Tear-free animation with flipBuffer()
• ✅ Ghosting prevention - LSB bit plane previous row address technique
• ✅ PSRAM support - ESP32-P4 PARLIO uses PSRAM for large buffers (frees internal SRAM)
• ⏳ Temporal dithering - Planned

Installation

ESP-IDF Component Manager

Add to your project's idf_component.yml:

dependencies:
  hub75:
    version: "^0.1.0"

Browse on the ESP Component Registry.

Or install from git:

dependencies:
  hub75:
    git: https://github.com/esphome-libs/esp-hub75
    path: components/hub75  # Important: point to the component subdirectory!

PlatformIO

Add to platformio.ini:

lib_deps =
    esphome/esp-hub75@^0.1.0

Browse on the PlatformIO Registry.

Manual Installation

See Component Documentation for manual installation options.

Quick Start

#include "hub75.h"

void app_main() {
    // Configure your panel
    Hub75Config config{};
    config.panel_width = 64;
    config.panel_height = 64;
    config.scan_pattern = Hub75ScanPattern::SCAN_1_32;
    config.shift_driver = ShiftDriver::FM6126A;  // Try this if GENERIC doesn't work

    // Set GPIO pins (example for ESP32-S3)
    config.pins.r1 = 42; config.pins.g1 = 41; config.pins.b1 = 40;
    config.pins.r2 = 38; config.pins.g2 = 39; config.pins.b2 = 37;
    config.pins.a = 45; config.pins.b = 36; config.pins.c = 48;
    config.pins.d = 35; config.pins.e = 21;
    config.pins.lat = 47; config.pins.oe = 14; config.pins.clk = 2;

    // Initialize and draw
    Hub75Driver driver(config);
    driver.begin();
    driver.set_pixel(10, 10, 255, 0, 0);  // Red pixel at (10,10)
}

See examples/01_basic/simple_colors for complete working example and examples/common/ for board-specific pin configurations.

Getting Started Paths

• First time with HUB75 panels? → See Quick Start above, then try examples/01_basic/
• Setting up multiple panels? → See Multi-Panel Guide
• Display not working? → See Troubleshooting Guide
• Want to understand the internals? → See Architecture Overview
• Need complete API reference? → See Component Documentation

Building & Testing Standalone

This repository includes a standalone test application and examples that can be built and run directly.

Build and Run Test Application

cd esp-hub75
idf.py set-target esp32s3  # or esp32, esp32s2, esp32c6, esp32p4
idf.py build
idf.py flash monitor

Build and Run Examples

cd examples/01_basic/simple_colors
idf.py set-target esp32s3
idf.py build
idf.py flash monitor

Available Examples:

• 01_basic/ - Simple color tests, gradients, brightness control
• 02_multi_panel/ - Multi-panel layout demonstrations
• 03_lvgl/ - LVGL graphics library integration
• common/ - Shared pin configuration examples

Each example includes specific instructions and pin configuration guidance.

ESPHome Integration

An ESPHome component is available that wraps this driver for easy integration with ESPHome projects. Supports all driver features including multi-panel layouts, shift driver initialization, and platform auto-detection.

See hub75-esphome for installation and configuration.

Project Structure

This repository is structured as an ESP-IDF component with a standalone test application:

esp-hub75/                    # Repository root
├── main/                     # Standalone test application
├── components/
│   └── hub75/                # ← THE COMPONENT (point here when including!)
│       ├── include/          # Public API headers
│       └── src/
│           ├── core/         # Core driver coordinator
│           ├── color/        # CIE 1931 gamma LUTs & pixel format conversion
│           ├── panels/       # Scan pattern & multi-panel layout remapping
│           └── platforms/    # Platform-specific DMA implementations
│               ├── i2s/      # ESP32/ESP32-S2
│               ├── gdma/     # ESP32-S3
│               └── parlio/   # ESP32-P4/C6
└── examples/
    ├── common/               # Pin configuration examples
    ├── 01_basic/             # Simple color tests
    ├── 02_multi_panel/       # Multi-panel layouts
    └── 03_lvgl/              # LVGL integration

Important: When including this component in your project, point to components/hub75/ subdirectory, not the repository root.

Documentation

API Reference & Quick Start

Complete API documentation is available in components/hub75/README.md:

• Installation options (Component Manager, manual copy)
• API methods (initialization, drawing, brightness control, double buffering)
• Configuration options (hardware specs, scan patterns, multi-panel layouts)
• Brief troubleshooting guide

Technical Deep-Dives

For architecture, platform specifics, and advanced topics, see docs/:

• Architecture Overview - How BCM timing and static DMA chains work
• Platform Details - Platform comparison, memory calculations, and optimization strategies
• Troubleshooting Guide - Complete debugging reference
• Multi-Panel Guide - Layout patterns, wiring diagrams, coordinate remapping
• Color & Gamma - CIE 1931 correction and bit depth guide

Pin configuration examples: See examples/common/ for board-specific GPIO layouts.

References

This driver combines best practices from:

• mrcodetastic/ESP32-HUB75-MatrixPanel-DMA - Native CIE LUTs, GDMA, multi-platform
• JuPfu/hub75 - Temporal dithering, dual-mode brightness
• liebman/esp-hub75 - Rust patterns, IRAM optimization
• Espressif PARLIO Example - ESP32-C6/P4 PARLIO

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or pull request for bugs, features, or improvements.