esp32-hub75-matrixpanel-dma

When calculating the performance of your LED matrix application, note that filling the DMA buffer involves heavy bit-level memory operations rather than simple byte/word stores. This makes the process computationally intensive for both the ESP32 core and the compiler.

Performance varies significantly based on the method used to update the screen. For example, using specialized 'Fast' methods (like fast-V-line or fast-H-line) is substantially more efficient than using standard drawPixel methods. When benchmarking your own setup, consider the following patterns used in testing:

• clearScreen(): Full blanking of the buffer.
• fillScreenRGB888(): Filling with monochrome or gray colors.
• drawPixel(): Individual pixel updates.
• fillRect(): Drawing rectangles over the matrix.
• Line drawing: Using standard vs. fast line methods.

The AnimatedGIFPanel_SD example uses the 'Animated GIF' library by Larry Bank and the Espressif SD/File system library for Arduino.

Note on Pin Configuration: Because the SD Card requires specific pins, some default HUB75 pins must be remapped to accommodate the SD Card hardware. Refer to the wiring diagram in the repository for the specific pinout used in this example.

Using External RAM on the ESP32-S3 introduces specific behaviors regarding cache and memory access:

• Cache Dependency: External RAM shares the same cache region as external flash. Accessing large chunks of data (>32 KB) may exceed cache capacity, causing performance to fall back to the slower external RAM access speed. This can also 'push out' cached flash, potentially slowing down code execution.
• Flash Cache Disabling: If the flash cache is disabled (e.g., during a flash write operation), External RAM becomes inaccessible. Any attempt to read or write to it during this time will trigger an illegal cache access exception.
• Task Stacks: By default, xTaskCreate() and similar functions allocate task stacks and TCBs in internal memory, not external RAM, to avoid issues when the flash cache is disabled.

This library utilizes the ESP32's 'LCD Mode' DMA for high-speed data output.

Supported Hardware:

• Original ESP32 (ESP-WROOM-32 / ESP32-D0WDQ6)
• ESP32-S2
• ESP32-S3

Unsupported Hardware:

• RISC-V ESP32s (e.g., ESP32-C3) because they lack 'LCD mode' support.
• ESP32-S3 boards with poor PCB design (e.g., Adafruit MatrixPortal S3) may experience WiFi interference due to high-frequency DMA output.

Memory Considerations:

• The DMA buffer consumes internal SRAM. For the original ESP32, you are limited to the available free internal SRAM (typically ~200KB).
• For the ESP32-S3, you can use OCTAL SPI-RAM (PSRAM) (e.g., N8R8 variant) to drive the DMA buffer, but this limits the maximum output frequency to ~13MHz, which may cause flicker when chaining multiple panels. Do not use QUAD SPI (Q-SPI) PSRAM as it is too slow.

To create a larger display by connecting multiple LED Matrix Panels, use the VirtualMatrixPanel class. Examples demonstrating this include:

• ChainedPanels: Basic implementation of chaining panels.
• ChainedPanelsAuroraDemo: Demonstrates a large-scale plasma animation across chained panels.
• ChainedPanelsScreenBuffer: Combines VirtualMatrixPanel with a FastLED off-screen pixel buffer for advanced rendering techniques.

You can chain multiple HUB75 panels together to create larger displays:

1. Horizontal Chaining: Connect panels in series using the HUB75 ribbon cable to create a single long virtual matrix (e.g., two 64x32 panels to make a 128x32 display). You must configure the class constructor to treat them as "one long virtual matrix chain". See the Pattern Plasma example for configuration details.
2. Grid Chaining (2x2, etc.): To create a grid (e.g., four 64x32 panels in a 2x2 arrangement to make a 128x64 display), use the VirtualMatrixPanel or AuroraDemo examples for the necessary configuration logic.

Warning: Resolutions exceeding 128x64 are prone to crashes due to ESP32 SRAM memory constraints.

A robust power supply is critical. For chained LED panels, it is highly recommended to solder a 1000-2000uF capacitor across the GND and VCC pins of each LED panel. This prevents 'flashy' graphics caused by current/power draw peaks and troughs when many LEDs turn on or off simultaneously.

Note on Voltage: Some panels may not work well with the 3.3V signal provided by the ESP32 GPIO pins.

The VirtualMatrixPanel_T class is an abstraction used to perform pixel re-mapping. It allows you to decouple the logical display coordinates from the physical wiring of the LED panels. This is useful for two primary scenarios:

1. Creating larger displays from chained panels: When panels are connected in a non-standard physical order (like a grid or a serpentine/zig-zag pattern), VirtualMatrixPanel_T maps a single large virtual display area to the multiple physical panels.
2. Supporting non-standard scan types: It provides support for panels with non-standard pixel mapping, such as 1/4 scan outdoor panels, which are not natively supported by the core library.

By using this class, you can draw to a single large virtual display, and the library handles the complex math of routing those pixels to the correct physical location and scan sequence.

The Aurora Demo is a complex example that demonstrates how to combine multiple libraries to create a large-scale visual display. It uses three core components:

1. ESP32-HUB75-MatrixPanel-DMA: Used to drive physical LED panels. It utilizes the VirtualMatrix class to chain multiple physical panels together into a single, larger virtual display grid.
2. GFX_Lite: A simplified graphics library used to draw effects on the virtual display. It is a fork of AdaFruitGFX and FastLED designed for ease of use.
3. VirtualMatrix: An abstraction within the DMA library that allows graphical effects to treat a collection of chained panels as one continuous coordinate system.