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

Requires ESP-IDF 4.4.8+ (ESP32-C6/P4 require 5.1+). Tested with 4.4.8, 5.5.2, and 6.0-rc1.

• ✅ 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)
• ✅ Display rotation - 0°, 90°, 180°, 270° rotation support (runtime configurable)
• ✅ CIE 1931 gamma correction - Native bit-depth LUTs (4-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)

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!

Add to platformio.ini:

lib_deps = esphome/esp-hub75@^0.1.0

Browse on the PlatformIO Registry.

See Component Documentation for manual installation options.

#include "hub75.h" void app_main() { // Configure your panel Hub75Config config{}; config.panel_width = 64; config.panel_height = 64; config.shift_driver = Hub75ShiftDriver::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) driver.fill(0, 0, 32, 32, 0, 0, 255); // Blue 32x32 rectangle at (0,0) }

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

• 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

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

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

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 2025.12+ includes a built-in hub75 display component that uses this library.

See the ESPHome HUB75 documentation for configuration.

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.

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

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.

• ESPHome - Built-in hub75 display component (2025.12+)
• Tronbyt - A community supported firmware for the Tidbyt hardware (1.5.0+)

This driver combines best practices from:

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

MIT License - See LICENSE file for details.

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