hub75_demo.mp4
Demo video: Colours are much brighter and more brilliant in reality
This project is based on:
To understand how RGB matrix panels work, refer to the article Everything You Didn't Want to Know About RGB Matrix Panels. For details on Binary Coded Modulation (BCM), see LED Dimming Using Binary Code Modulation.
The modifications to the Pimoroni HUB75 driver result in the following improvements:
- Offloading Work: Moves processing from the CPU to DMA and PIO co-processors.
- Performance Boost: Implements self-paced, interlinked DMA and PIO processes.
- Eliminates Synchronization Delays: No need for
hub75_wait_tx_stall, removing blocking synchronization. - Optimized Interrupt Handling: Reduces code complexity in the interrupt handler.
These enhancements lead to significant performance improvements. In tests up to a 250 MHz system clock, no ghost images were observed.
As part of a private project, I sought to gain deeper knowledge of the Raspberry Pi Pico microcontroller. I highly recommend Raspberry Pi Pico Lectures 2022 by Hunter Adams—they provide excellent insights!
If you are specifically interested in PIO (Programmable Input/Output), start with Lecture 14: Introducing PIO and Lecture 15: PIO Overview and Examples.
Inspired by Adams' discussion on DMA and PIO co-processors, I optimized the HUB75 driver as a self-assigned challenge.
😊 Raspberry Pi Pico Lectures 2025 by Hunter Adams is available now!
The Pico HUB75 example demonstrates connecting an HUB75 LED matrix panel using PIO. This educational example prioritizes clarity and ease of understanding.
- The color palette is generated by modulating the Output Enable (OE) signal.
- Binary Coded Modulation (BCM) is applied row-by-row, modulating all color bits before advancing to the next row.
- Synchronization depends on
hub75_wait_tx_stall. - No DMA is used, leading to lower performance.
The Pimoroni HUB75 driver improves performance by:
- Switching from row-wise to plane-wise modulation handling.
- Using DMA to transfer pixel data to the PIO state machine.
- Still relying on
hub75_wait_tx_stallfor synchronization.
Picture 1: Pimoroni's Hub75 Driver DMA Section
Both the Raspberry Pi and Pimoroni implementations use hub75_wait_tx_stall, which ensures:
- The state machine stalls on an empty TX FIFO.
- The system waits until the OEn pulse has finished.
However, this blocking method prevents an efficient DMA-based approach.
static inline void hub75_wait_tx_stall(PIO pio, uint sm) {
uint32_t txstall_mask = 1u << (PIO_FDEBUG_TXSTALL_LSB + sm);
pio->fdebug = txstall_mask;
while (!(pio->fdebug & txstall_mask)) {
tight_loop_contents();
}
}Instead of waiting for TX FIFO stalling, we can:
- Modify the PIO program to emit a signal once the OEn pulse completes.
- Set up a DMA channel to listen for this signal.
- Establish an interrupt handler to trigger once the signal is received.
This approach allows fully chained DMA execution without CPU intervention.
Picture 2: Modified hub75_row Program
The following diagram illustrates the interactions between DMA channels and PIO state machines:
[ Pixel Data DMA ] -> [ hub75_data_rgb888 PIO ]
|
|--> [ Dummy Pixel Data DMA ] -> [ hub75_data_rgb888 PIO ]
|
|--> [ OEn Data DMA ] -> [ hub75_row PIO ]
|
|--> [ OEn Finished DMA ] (Triggers interrupt)
-
Pixel Data Transfer
- Pixel data is streamed via DMA to the hub75_rdata_gb888 PIO state machine.
- This handles shifting pixel data into the LED matrix.
-
Dummy Pixel Handling
- A secondary dummy pixel DMA channel adds additional pixel data.
- This ensures correct clocking of the final piece of genuine data.
-
OEn Pulse Generation
- The OEn data DMA channel sends 32-bit words - 5 bit address information (row select) and 27 bit puls width - to the hub75_row PIO state machine.
- This output enable signal switches on those LEDs in the current row with bit set in the current bitplane for the specified number of cycles.
-
Interrupt-Driven Synchronization
- A final OEn finished DMA channel listens for the end of the pulse.
- An interrupt handler (
oen_finished_handler) resets DMA for the next cycle.
Picture 3: Chained DMA Channels and assigned PIOs
With a bit-depth of 10, the HUB75 driver achieves the following refresh rates for a 64 x 64 matrix depending on the system clock:
| System Clock | Refresh Rate |
|---|---|
| 100 MHz | 179 Hz |
| 150 MHz | 268 Hz |
| 200 MHz | 358 Hz |
| 250 MHz | 448 Hz |
These results demonstrate stable operation and high-performance display rendering across a wide range of system clocks.
✅ Fully automated data transfer using chained DMA channels.
✅ Eliminates CPU-intensive busy-waiting (hub75_wait_tx_stall).
✅ Ensures precise timing without unnecessary stalling.
By offloading tasks to DMA and PIO, the revised HUB75 driver achieves higher performance, simpler interrupt handling, and better synchronization. This approach significantly reduces CPU overhead while eliminating artifacts like ghosting at high clock speeds.
If you're interested in optimizing RGB matrix panel drivers, this implementation serves as a valuable reference for efficient DMA-based rendering.
You can easily use this project with VSCode, especially with the Raspberry Pi Pico plugin installed. Follow these steps:
-
Open VSCode and start a new window.
-
Clone the repository:
-
Press
Ctrl+Shift+Pand selectGit: Clone. -
Paste the URL:
https://github.com/JuPfu/hub75 -
Choose a local directory to clone the repository into.
-
-
Project Import Prompt:
-
Consent to open the project.
-
When prompted, "Do you want to import this project as Raspberry Pi Pico project?", click Yes or wait a few seconds until the dialog prompt disappears by itself.
-
-
Configure Pico SDK Settings:
-
A settings page will open automatically.
-
Use the default settings unless you have a specific setup.
-
Click Import to finalize project setup.
-
Switch the board-type to your Pico model.
-
-
Wait for Setup Completion:
- VSCode will download required tools, the Pico SDK, and any plugins.
-
Connect the Hardware:
- Make sure the HUB75 LED matrix is properly connected to the Raspberry Pi Pico.
- Attach the Rasberry Pi Pico USB cable to your computer
-
Build and Upload:
-
Compiling the project can be done without a Pico attached to the computer.
-
Click the Run button in the bottom taskbar.
-
VSCode will compile and upload the firmware to your Pico board.
-
💡 If everything is set up correctly, your matrix should come to life with the updated HUB75 DMA driver.
-
Add another chained DMA channel to further reduce calls to the oen_finished_handler, trading memory for reduced CPU load.
-
Investigate removing the hub75_data_rgb888_set_shift method, potentially achieving a completely DMA- and PIO-based solution with no CPU involvement.
For any questions or discussions, feel free to contribute or open an issue!