{"id":36949137,"url":"https://github.com/esphome-libs/esp-hub75","last_synced_at":"2026-03-18T02:29:16.524Z","repository":{"id":320156362,"uuid":"1081012558","full_name":"esphome-libs/esp-hub75","owner":"esphome-libs","description":"HUB75 display library for ESP-IDF/PlatformIO","archived":false,"fork":false,"pushed_at":"2026-03-11T01:50:06.000Z","size":348,"stargazers_count":24,"open_issues_count":4,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-11T07:38:08.213Z","etag":null,"topics":["esp-idf-component","esp32","hub75","platformio-library"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esphome-libs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":"https://www.openhomefoundation.org"}},"created_at":"2025-10-22T07:27:24.000Z","updated_at":"2026-03-11T01:50:08.000Z","dependencies_parsed_at":"2026-01-03T19:04:24.200Z","dependency_job_id":null,"html_url":"https://github.com/esphome-libs/esp-hub75","commit_stats":null,"previous_names":["stuartparmenter/hub75-esp32","stuartparmenter/esp-hub75","esphome-libs/esp-hub75"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/esphome-libs/esp-hub75","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome-libs%2Fesp-hub75","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome-libs%2Fesp-hub75/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome-libs%2Fesp-hub75/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome-libs%2Fesp-hub75/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esphome-libs","download_url":"https://codeload.github.com/esphome-libs/esp-hub75/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome-libs%2Fesp-hub75/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30642995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-18T01:41:58.583Z","status":"online","status_checked_at":"2026-03-18T02:00:07.824Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp-idf-component","esp32","hub75","platformio-library"],"created_at":"2026-01-13T11:55:44.497Z","updated_at":"2026-03-18T02:29:16.515Z","avatar_url":"https://github.com/esphome-libs.png","language":"C++","funding_links":["https://www.openhomefoundation.org"],"categories":[],"sub_categories":[],"readme":"# ESP32 HUB75 DMA Driver\n\n[![ESP Component Registry](https://components.espressif.com/components/esphome/esp-hub75/badge.svg)](https://components.espressif.com/components/esphome/esp-hub75)\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/esphome/library/esp-hub75.svg)](https://registry.platformio.org/libraries/esphome/esp-hub75)\n\nHigh-performance DMA-based driver for HUB75 RGB LED matrix panels, supporting ESP32, ESP32-S2, ESP32-S3, ESP32-C6, and ESP32-P4.\n\n**Requires ESP-IDF 4.4.8+** (ESP32-C6/P4 require 5.1+). Tested with 4.4.8, 5.5.2, and 6.0-rc1.\n\n## Features\n\n- ✅ **Static circular DMA refresh** - No interrupts, no CPU intervention after `begin()`\n- ✅ **Multi-platform support** - ESP32-S3 (GDMA), ESP32/S2 (I2S), ESP32-P4 (PARLIO)\n- ✅ **BCM timing** - Descriptor duplication (GDMA/I2S) or buffer padding (PARLIO)\n- ✅ **Scan pattern support** - 1/4, 1/8, 1/16, 1/32 scan panels with coordinate remapping\n- ✅ **Shift driver initialization** - FM6126A/ICN2038S, FM6124, MBI5124, DP3246\n- ✅ **Multi-panel layouts** - Serpentine and zigzag chaining for M×N grids\n  - Serpentine: Alternate rows upside down (saves cable length)\n  - Zigzag: All panels upright (longer cables)\n  - Row-major traversal (matches ESP32-HUB75-MatrixPanel-DMA reference)\n- ✅ **Display rotation** - 0°, 90°, 180°, 270° rotation support (runtime configurable)\n- ✅ **CIE 1931 gamma correction** - Native bit-depth LUTs (4-12 bit)\n- ✅ **Dual-mode brightness** - Basis (1-255) + intensity (0.0-1.0) control\n- ✅ **Multiple pixel formats** - RGB888, RGB888_32, RGB565 input\n- ✅ **Direct buffer writes** - No separate framebuffer copy, IRAM optimized\n- ✅ **Double buffering** - Tear-free animation with `flipBuffer()`\n- ✅ **Ghosting prevention** - LSB bit plane previous row address technique\n- ✅ **PSRAM support** - ESP32-P4 PARLIO uses PSRAM for large buffers (frees internal SRAM)\n\n## Installation\n\n### ESP-IDF Component Manager\n\nAdd to your project's `idf_component.yml`:\n\n```yaml\ndependencies:\n  hub75:\n    version: \"^0.1.0\"\n```\n\nBrowse on the [ESP Component Registry](https://components.espressif.com/components/esphome/esp-hub75).\n\nOr install from git:\n\n```yaml\ndependencies:\n  hub75:\n    git: https://github.com/esphome-libs/esp-hub75\n    path: components/hub75  # Important: point to the component subdirectory!\n```\n\n### PlatformIO\n\nAdd to `platformio.ini`:\n\n```ini\nlib_deps =\n    esphome/esp-hub75@^0.1.0\n```\n\nBrowse on the [PlatformIO Registry](https://registry.platformio.org/libraries/esphome/esp-hub75).\n\n### Manual Installation\n\nSee [Component Documentation](components/hub75/README.md) for manual installation options.\n\n## Quick Start\n\n```cpp\n#include \"hub75.h\"\n\nvoid app_main() {\n    // Configure your panel\n    Hub75Config config{};\n    config.panel_width = 64;\n    config.panel_height = 64;\n    config.shift_driver = Hub75ShiftDriver::FM6126A;  // Try this if GENERIC doesn't work\n\n    // Set GPIO pins (example for ESP32-S3)\n    config.pins.r1 = 42; config.pins.g1 = 41; config.pins.b1 = 40;\n    config.pins.r2 = 38; config.pins.g2 = 39; config.pins.b2 = 37;\n    config.pins.a = 45; config.pins.b = 36; config.pins.c = 48;\n    config.pins.d = 35; config.pins.e = 21;\n    config.pins.lat = 47; config.pins.oe = 14; config.pins.clk = 2;\n\n    // Initialize and draw\n    Hub75Driver driver(config);\n    driver.begin();\n    driver.set_pixel(10, 10, 255, 0, 0);  // Red pixel at (10,10)\n    driver.fill(0, 0, 32, 32, 0, 0, 255); // Blue 32x32 rectangle at (0,0)\n}\n```\n\nSee [examples/01_basic/simple_colors](examples/01_basic/simple_colors) for complete working example and [examples/common/](examples/common/) for board-specific pin configurations.\n\n## Getting Started Paths\n\n- **First time with HUB75 panels?** → See [Quick Start](#quick-start) above, then try [examples/01_basic/](examples/)\n- **Setting up multiple panels?** → See [Multi-Panel Guide](docs/MULTI_PANEL.md)\n- **Display not working?** → See [Troubleshooting Guide](docs/TROUBLESHOOTING.md)\n- **Want to understand the internals?** → See [Architecture Overview](docs/ARCHITECTURE.md)\n- **Need complete API reference?** → See [Component Documentation](components/hub75/README.md)\n\n## Building \u0026 Testing Standalone\n\nThis repository includes a standalone test application and examples that can be built and run directly.\n\n### Build and Run Test Application\n\n```bash\ncd esp-hub75\nidf.py set-target esp32s3  # or esp32, esp32s2, esp32c6, esp32p4\nidf.py build\nidf.py flash monitor\n```\n\n### Build and Run Examples\n\n```bash\ncd examples/01_basic/simple_colors\nidf.py set-target esp32s3\nidf.py build\nidf.py flash monitor\n```\n\n**Available Examples:**\n- `01_basic/` - Simple color tests, gradients, brightness control\n- `02_multi_panel/` - Multi-panel layout demonstrations\n- `03_lvgl/` - LVGL graphics library integration\n- `common/` - Shared pin configuration examples\n\nEach example includes specific instructions and pin configuration guidance.\n\n## ESPHome Integration\n\nESPHome 2025.12+ includes a built-in `hub75` display component that uses this library.\n\nSee the [ESPHome HUB75 documentation](https://esphome.io/components/display/hub75.html) for configuration.\n\n## Project Structure\n\nThis repository is structured as an **ESP-IDF component** with a standalone test application:\n\n```\nesp-hub75/                    # Repository root\n├── main/                     # Standalone test application\n├── components/\n│   └── hub75/                # ← THE COMPONENT (point here when including!)\n│       ├── include/          # Public API headers\n│       └── src/\n│           ├── core/         # Core driver coordinator\n│           ├── color/        # CIE 1931 gamma LUTs \u0026 pixel format conversion\n│           ├── panels/       # Scan pattern \u0026 multi-panel layout remapping\n│           └── platforms/    # Platform-specific DMA implementations\n│               ├── i2s/      # ESP32/ESP32-S2\n│               ├── gdma/     # ESP32-S3\n│               └── parlio/   # ESP32-P4/C6\n└── examples/\n    ├── common/               # Pin configuration examples\n    ├── 01_basic/             # Simple color tests\n    ├── 02_multi_panel/       # Multi-panel layouts\n    └── 03_lvgl/              # LVGL integration\n```\n\n**Important**: When including this component in your project, point to `components/hub75/` subdirectory, not the repository root.\n\n## Documentation\n\n### API Reference \u0026 Quick Start\n\nComplete API documentation is available in [components/hub75/README.md](components/hub75/README.md):\n- Installation options (Component Manager, manual copy)\n- API methods (initialization, drawing, brightness control, double buffering)\n- Configuration options (hardware specs, scan patterns, multi-panel layouts)\n- Brief troubleshooting guide\n\n### Technical Deep-Dives\n\nFor architecture, platform specifics, and advanced topics, see [docs/](docs/):\n- **[Architecture Overview](docs/ARCHITECTURE.md)** - How BCM timing and static DMA chains work\n- **[Platform Details](docs/PLATFORMS.md)** - Platform comparison, memory calculations, and optimization strategies\n- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Complete debugging reference\n- **[Multi-Panel Guide](docs/MULTI_PANEL.md)** - Layout patterns, wiring diagrams, coordinate remapping\n- **[Color \u0026 Gamma](docs/COLOR_GAMMA.md)** - CIE 1931 correction and bit depth guide\n\n**Pin configuration examples:** See [examples/common/](examples/common/) for board-specific GPIO layouts.\n\n## Used By\n\n- **[ESPHome](https://esphome.io/)** - Built-in [`hub75` display component](https://esphome.io/components/display/hub75.html) (2025.12+)\n- **[Tronbyt](https://github.com/tronbyt/firmware-esp32)** - A community supported firmware for the Tidbyt hardware (1.5.0+)\n\n## References\n\nThis driver combines best practices from:\n\n- [mrcodetastic/ESP32-HUB75-MatrixPanel-DMA](https://github.com/mrcodetastic/ESP32-HUB75-MatrixPanel-DMA) - Native CIE LUTs, GDMA, multi-platform\n- [JuPfu/hub75](https://github.com/JuPfu/hub75) - Dual-mode brightness inspiration\n- [liebman/esp-hub75](https://github.com/liebman/esp-hub75) - Rust patterns, IRAM optimization\n- [Espressif PARLIO Example](https://github.com/espressif/esp-idf/tree/v5.4.1/examples/peripherals/parlio) - ESP32-C6/P4 PARLIO\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or pull request for bugs, features, or improvements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesphome-libs%2Fesp-hub75","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesphome-libs%2Fesp-hub75","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesphome-libs%2Fesp-hub75/lists"}