Driving Hub75 LED panels from Raspberry Pi GPIO with rpi-rgb-led-matrix

The Pi becomes the LED controller, so no HAT stands between you and the panel

The RGBMatrix class in include/led-matrix.h talks to the panel address, row select and RGB data lines directly.

The scope is broad in panel size and narrow in panel type. The library targets 128x64, 64x64, 32x32 and 16x32 panels, which are the sizes you can buy from SparkFun, Adafruit, eBay, Aliexpress or, if you are in China, direct from a manufacturer through Taobao or Alibaba. It reaches them through the shared Hub75 connector, but panels using that connector differ in how multiplexing happens, and those differences are exposed as command line flags rather than hidden behind auto detection. You tell the software the geometry and the addressing scheme; the software does not work it out from the hardware.

Chain capacity follows the header. A 26 pin board drives one chain. A 40 pin board, which covers the Pi 2, 3, 4, 5 and the B+ models, drives up to three chains in parallel, each chain 12 panels or longer. The Compute Module with its 44 GPIOs manages up to six. The README describes a stretch case of roughly 96 panels across a 32 panel chain reaching around 100Hz at full 24 bit colour, and it is careful to call that theoretical and never tested.

Row multiplexing is the whole game, and --led-multiplexing=<0..17> is where panels go wrong

A Hub75 panel does not hold a full image in memory. It lights one pair of rows at a time and sweeps the rest very fast, which is why these displays look dim to a camera and why scan count is the spec that matters. This library sets that sweep through the multiplexing parameter, and it accepts values zero through seventeen. The geometry flags are easy, because you can count the columns and rows off the panel. Everything else is guesswork unless the manufacturer publishes it.

The README says to try all multiplexing values when a panel does not come with a description, and it says going through these options for experiments would typically not do harm. At the same time it points readers at a community wiki of LED drivers and says to assume that all supported panels there should work with this library, or could work with minimal work to create a pixel mapper. So the project's own guidance is that most panels will work and the tuning is empirical. Budget time for that, not just for wiring.

Some panels fall outside the easy case. The README singles out the brighter panels as the ones with uncommon pixel layouts, and points at layouts called zigzag or zagzig that need a custom pixel mapper. Shift register line addressing, the so-called ABC panels up to 64 lines, is supported, as are direct addressed panels using three to five address lines: ABC for 8x2, ABCD for 16x2, ABCDE for 32x2. One deliberate exclusion runs the other way. The library does not support PWM panels, which the README concedes are actually better but need a completely different driver.

Two Pi 5 backends trade CPU time for refresh rate

Pi 5 support arrived through two separate backends, and the difference between them is CPU load rather than feature set. The flag --led-rp1-pio=0 selects the RP1 RIO backend and is the default. It burns more CPU and refreshes faster. The flag --led-rp1-pio=1 selects the RP1 PIO backend, which the README describes as using very minimal CPU usage. If you are running a matrix alongside other work on a Pi 5, that is the switch to know about before you start blaming your own code for dropped frames.

There is a second-order effect in the same section that a skim misses. The README notes that --led-slowdown-gpio can have the opposite effect in RIO mode, so moving that slowdown from 2 to 3 may increase performance slightly with --led-rp1-pio=0. The knob that normally slows things down makes one mode faster. Do not assume the flag's name tells you its direction on every backend.

Support spans the hardware line well: Version 1 boards with the 26 pin header, B+ models, the Pi Zero, Pi 2 through 5, and the Compute Modules. The README also notes that on the faster boards the panels sometimes cannot keep up with the drive speed, and sends you to its own troubleshooting section for that case. That is the fundamental constraint of the whole approach. The Pi is the timing source, so the panel, not the CPU, sets the ceiling.

utils/ and examples-api-use/ split the tool from the library

Two entry points sit at the top level and they answer different questions. The utils/ directory holds ready-made command line tools built on the library, and the examples-api-use/ directory is where you write your own against the API. A C++ project that only ships a library would leave you to do the second job yourself; this one ships a working tool for the first.

The geometry flags are the ones you will set first, and the README gives the 64x32 case directly:

--led-cols=64 --led-rows=32

Everything else about a display, from scan count to inversion, is set through the same mechanism, either as flags or programmatically through the Options struct in include/led-matrix.h. That dual surface matters when you are weighing the project: the flags make the utils usable without writing code, and the Options struct makes the same behaviour reachable from your own binary.

The build is a plain C++ one. The top level Makefile compiles the library in the lib subdirectory and then builds examples-api-use, producing a static library named lib/librgbmatrix.a. Python is not built by that Makefile at all; the file comments say Python is handled by scikit-build-core and cmake. There are also other language bindings under bindings/, with a build-csharp target. If your project needs a language other than C++, check that binding before you plan around the utils.

The packaged Python path goes through pyproject.toml, not the Makefile

A packaged distribution exists and it is set up differently from the C++ build. pyproject.toml names the project rgbmatrix, at version 0.0.1+20260125, describes it as a packaged version of Christoph Friedrich's rpi-rgb-led-matrix library, requires Python 3.11 or newer, and uses scikit-build-core with cython as the build backend. The version number carries a date stamp of 20260125 rather than a semantic tag, which tells you it tracks snapshots.

This separation has a practical consequence for anyone scripting against the matrix. If you build the Python module from this repository, you go through CMake and scikit-build-core. If you build the C++ library, you go through the Makefile. Mixing the two mental models leads to hunting for a top-level setup.py that does not exist in the repository.

Wiring is documented separately in wiring.md at the top level, which keeps the pin assignments out of the README proper. The Pi 5 discussion lives in issue 1603, while 466 is the master PWM tracking issue and 1866 carries the continued PWM discussion. Help requests are directed to a Discourse board rather than to the issue tracker, and the README asks that anyone opening a bug for personal help say in the bug that they read that page first.

PWM panels have no support path in this library, only an experiment elsewhere

The clearest failure mode is the panel you cannot drive at all. Newer PWM, E-PWM and S-PWM panels are not supported, and the README says so plainly rather than burying it. It frames PWM support as something that would really be appreciated and points at two tracking issues, 466 and 1866. For a fork it names a separate repository, rpi-rgb-led-matrix_pwm_experiment, credited with some panel support across FM6373, FM6363 and SM16380SH parts.

That is the whole honest position. If your panels are PWM type, this library is the wrong tool and the fork or your own driver is the route. The README also flags that DMD_STM32 has started adding experimental support for some PWM panels, labelled as special, which are not supported here because the library handles only non PWM panels until someone contributes otherwise. The library is not archived, so treat the PWM gap as an open request rather than a settled decision and recheck the issues before you rule the project out.

Shipping hardware means reading the licence, and the README is explicit that putting the library in a product requires giving the receiver the source and your modifications.

DietPi over a full desktop, because the OS is competing with the timing budget

The README recommends a lightweight, non-GUI distribution, naming DietPi first, with Raspbian Lite as an easier second choice. That recommendation is not incidental. This library drives timing critical output from userspace GPIO, and a desktop system with compositing and background services competes for the same cycles that determine whether your refresh is smooth or visibly torn.

The same section recommends the Pi 2 and 3 over the older models and the Pi Zero for being faster.

Panels purchased from overseas often arrive with no driver documentation. For that case the README points at a community list of LED drivers and tells you to use it as the starting set of panels the library should handle, then confirm each one with --led-multiplexing. That is the honest path. The library gives you the tools, the panel vendor gives you nothing, and the loop between them is yours to close.

Editorial conclusion

Adopt rpi-rgb-led-matrix if your panels use direct or shift register addressing and you want the Raspberry Pi to be the only board in the chain, and build the C++ library from source with the Makefile. Do not adopt it for PWM, E-PWM or S-PWM panels, where the README points to an experimental fork instead, and be suspicious of any bright panel described as needing a zigzag pixel mapper. Before anything else, confirm the addressing style of the exact panel you bought, then run it through every value of --led-multiplexing from 0 to 17, because that single flag decides whether the image is scrambled or correct.

Frequently asked questions

Official sources

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