hzeller/rpi-rgb-led-matrix: Driving Hub75 LED Panels from a Raspberry Pi

What rpi-rgb-led-matrix actually solves, and for whom

Hub75 LED panels are cheap and plentiful, but they are not displays in the sense a framebuffer understands. They have no controller, no EDID, no memory. A panel expects a host to shift pixel data in continuously, drive row address lines, and pulse the output-enable line at the right moment. The README describes the library as doing what is needed to control commonly available 128x64, 64x64, 32x32 or 16x32 panels with the Raspberry Pi, and that is the whole job: turn GPIO bit-banging into a framebuffer you can draw into.

The audience is narrow and specific. You are building a sign, a clock, a scoreboard, an art piece, or a status wall, you have physical panels in hand, and you have a Raspberry Pi with a 40-pin header. The README recommends a lightweight, non-GUI distribution such as DietPi, with Raspbian Lite as a good second choice, which tells you the intended deployment is a dedicated board, not a desktop. If you are writing an application and want a display API, the RGBMatrix class in include/led-matrix.h is the interface; if you just want to see something light up, the demo binary and the utils/ directory are the faster path.

How the GPIO driver turns pixels into panel signals

The library compiles to a static archive, lib/librgbmatrix.a, built by the top-level Makefile through the lib subdirectory. Applications link against it and either construct an RGBMatrix instance directly or use the demo binary. Configuration lives in an Options struct declared in include/led-matrix.h, and every command-line flag maps onto a field there, so anything you can set with --led-cols you can also set in code.

The mechanism is multiplexing. A panel does not show all its rows at once; it shows a few rows, then switches address lines and shows the next few, fast enough that persistence of vision blends them. The README spells out the address-line variants: ABC for 8x2=16 lines, ABCD for 16x2=32 lines, and ABCDE for 32x2=64 lines, plus panels that use shift registers for line addressing, called ABC panels, up to 64 lines. That is why a 64x32 panel needs --led-cols=64 --led-rows=32 and nothing more, while an unusual panel needs a pixel mapper.

Refresh rate is the constraint that shapes everything. The README states that on a Raspberry Pi 2 or 3 you can easily chain 12 panels per chain, so 36 panels total across three chains, and that stretching to 32 panels per chain, roughly 96 total, should still reach around 100Hz with full 24-bit color. It labels that figure theoretical and never tested, and warns that timing problems with the panels will likely creep up. Treat the larger number as an upper bound to probe, not a specification. Color depth is the other lever: the README notes that with fewer colors, or with outdoor panels, you can control even more, faster.

Installing rpi-rgb-led-matrix and running the demo

The repository has no install script and no published release tarball, so the path is clone, build, run. The top-level Makefile builds the static library and then descends into examples-api-use, which is where the demo binary lives.

git clone https://github.com/hzeller/rpi-rgb-led-matrix.git
cd rpi-rgb-led-matrix
make

After make finishes you have lib/librgbmatrix.a and the example binaries. Run the demo with flags that match your panel. The README gives 64x32 panels as the example for --led-cols and --led-rows.

cd examples-api-use
sudo ./demo --led-rows=32 --led-cols=64 --led-chain=1 --led-parallel=1 -D 0

If nothing appears, the README's advice is to try every value of --led-multiplexing from 0 to 17, because panels with uncommon pixel layouts, especially the brighter ones, need the right mapper. On a Raspberry Pi 5 there is an extra decision. The README documents two modes: --led-rp1-pio=0 uses the RP1 RIO backend, which it describes as the default, with higher CPU usage but much faster performance, and --led-rp1-pio=1 uses the RP1 PIO backend with very minimal CPU usage. It also warns that --led-slowdown-gpio can have the opposite effect in RIO mode, so going from 2 to 3 may increase performance slightly with --led-rp1-pio=0.

If you want Python rather than C++, the repository root contains pyproject.toml, which uses scikit-build-core and cython as build requirements and declares the project name rgbmatrix with requires-python >=3.11. The Makefile notes that Python is now handled by scikit-build-core and cmake, not by the top-level Makefile, so the Python binding is built through the packaging path rather than make.

PWM panels, and the cases where this is the wrong library

The clearest limitation is stated in the README without hedging: this library does not support PWM panels, which it calls actually better but needing a completely different driver. The same restriction is repeated for the newer PWM, E-PWM and S-PWM panels, where the README says support would really be appreciated and links to two tracking issues. A fork, kingdo9/rpi-rgb-led-matrix_pwm_experiment, is named as having some experimentation and success with FM6373, FM6363 and SM16380SH panels. If your panel is PWM, this library is the wrong tool and the fork is the honest starting point, with the caveat that the README describes it as an experiment.

The second failure mode is pixel layout. The README warns that a fair number of panels have uncommon pixel layouts and may require special pixel mappers, some called zigzag or zagzig, and points to a discourse thread about P10 panels. There is no confirmed list of working panels in the repository; the README instead suggests referring to the DMD_STM32 wiki driver table and assuming supported panels there should work, or could work with minimal effort to write a mapper. That is a research task, not a configuration step.

The third is the 26-pin constraint. Older Raspberry Pi 1 boards with a 26-pin header drive one chain only. Three chains need a 40-pin model, and six chains need a Compute Module with 44 GPIOs. If your design assumes three parallel chains, check the header before buying panels.

Finally, the README asks users not to file bugs for personal help and to use the discourse group instead. That is a support-model constraint worth knowing before you plan around issue-tracker responses.

Compared with the Python and Pico routes people search for

The related searches around this project mix in two other approaches, and the difference is architectural rather than cosmetic. The first is the Python route. This repository does ship a Python binding, packaged as rgbmatrix through scikit-build-core, but the core timing code is still the same C++ GPIO driver underneath. A pure-Python driver on a Raspberry Pi would be fighting the interpreter for the microsecond-level timing the panels need, which is why the binding wraps the C++ library rather than reimplementing it. If you want Python, use the binding; the mechanism does not change.

The second is the Raspberry Pi Pico. A Pico is a microcontroller with programmable I/O, and it has no operating system scheduling between it and the GPIO, so the timing problem is structurally different. This library targets the Raspberry Pi family from version 1 through 5 plus Compute Modules, and the README's Pi 5 section shows how far it has to go to get deterministic output on a Linux board: an RP1 RIO backend and an RP1 PIO backend, each with its own CPU trade-off. That is the cost of running on a general-purpose computer. A Pico-based project avoids that cost but gives up the Linux userspace, the filesystem, and the ability to run the same program you develop on a desktop. Choose based on whether your project needs a computer attached.

A third comparison the searches surface is the RGB Matrix Bonnet, an adapter board. The repository has an adapter/ directory and a wiring.md file, so the library does contemplate adapter hardware, but the README does not document specific third-party bonnets. Check wiring.md against your board rather than assuming a bonnet matches the default pin mapping.

Licence, maintenance and what upgrading costs you

The library is licensed GPL-2.0, and the README states the practical consequence plainly: if you use it in a product somewhere, you need to make the source and all your modifications available to the receiver of that product so they have the freedom to adapt and improve. It also notes that you are allowed to use the code under GPL-3.0, which permits linking with Apache 2.0 and LGPL-3.0 code. The pyproject.toml declares license GPL-2.0-or-later, consistent with that dual option. If you are shipping a closed product, this is the fact that decides the project for you, and it is worth a conversation with someone qualified rather than a guess.

Maintenance is visible in the repository state. The last push was on 2026-09-07, and the repository is not archived. There are no retrieved releases, so there is no versioned artifact to pin against and no changelog to read before upgrading. Upgrading means pulling master and rebuilding, which means your compiled binaries and your Python wheel both move at once. The pyproject.toml version string, 0.0.1+20260125, is a date-stamped development version rather than a semantic release, which is consistent with that.

The practical upgrade cost is the flag surface. Because panel behaviour depends on --led-multiplexing, --led-slowdown-gpio, --led-rows, --led-cols, --led-chain and --led-parallel, and because the Pi 5 backend flags change performance characteristics, a rebuild can shift timing on hardware you already tuned. Keep your working flag set in version control alongside the commit you built from. That is the cheapest insurance available here.

Editorial conclusion

Adopt it if you have Hub75 panels with direct addressing (ABC, ABCD or ABCDE lines) and a Raspberry Pi 1 through 5, and you are willing to tune --led-multiplexing and --led-slowdown-gpio by experiment. Do not adopt it for PWM, E-PWM or S-PWM panels, which the README states are not supported, and do not expect a packaged release: the pyproject.toml still carries version 0.0.1+20260125. Before committing, verify your panel's pixel layout against the DMD_STM32 driver table the README points to, and confirm whether your board is a 26-pin, 40-pin or Compute Module, because that decides whether you get one, three or six chains.

Frequently asked questions

Official sources

1. hzeller/rpi-rgb-led-matrix on GitHub
2. Issues
3. License: GPL-2.0
4. README