The installer creates a directory called rpi-rgb-led-matrix, and inside this is a subdirectory examples-api-use with a few programs we can use to experiment with the matrix and confirm everything’s working.
These are compiled C based stand alone examples that do not rely on Python. There's no need to worry about the "python bindings" or the "virtual environment" to run these.
To run these examples, first change to the directory:
cd ~/rpi-rgb-led-matrix/examples-api-use/
We'll use the demo program to test the setup. Here is an example for a 32x32 LED matrix. Note the program must be run with sudo.
sudo ./demo --led-rows=32 --led-cols=32 --led-gpio-mapping=adafruit-hat -D 0
Change the following parameters as needed for your setup:
-
--led-row=set this to the number of LEDs in each matrix row -
--led-cols=set this to the number of LEDs in each matrix column -
--led-gpio-mapping=set this toadafruit-hatoradafruit-hat-pwmfor single matrix bonnet/HAT. For triple matrix bonnet useregular -
--led-parallel=set this to3if you are using the triple matrix bonnet or other active3 compatible hardware. Otherwise it can be omitted.
Running the demo program:
should result in a rotating square on the matrix:
The -D parameter picks the specific demo to run. There are several to choose from, some with additional parameters:
Demos, choosen with -D 0 - some rotating square 1 - forward scrolling an image (-m <scroll-ms>) 2 - backward scrolling an image (-m <scroll-ms>) 3 - test image: a square 4 - Pulsing color 5 - Grayscale Block 6 - Abelian sandpile model (-m <time-step-ms>) 7 - Conway's game of life (-m <time-step-ms>) 8 - Langton's ant (-m <time-step-ms>) 9 - Volume bars (-m <time-step-ms>) 10 - Evolution of color (-m <time-step-ms>) 11 - Brightness pulse generator
Tuning the Demo
Depending on your matrix type and Raspberry Pi model, some additional options may need fine-tuning:
--led-slowdown-gpio=(0…n) Sometimes needed to throttle back the speed when using a fast Pi. Default is 1.
For Raspberry Pi 3 use a slowdown of 1 to start (use higher values if image still flickers). For Raspberry Pi 4, use a slowdown of 4. Older Pi models might work with 0, try it.
--led-rgb-sequence=(RGB order) Some LED matrices may have their red, green and blue LEDs wired up in a different order…for example, if you need to swap the green and blue channels, use --led-rgb-sequence=RBG. Default is RGB.
--led-pwm-bits=(1…11) For long matrix chains you’ll probably need to use fewer PWM bits, sacrificing some color fidelity to improve refresh speed. Default is 11.
If your Pi is overclocked, or if you’re using a Raspberry Pi 2 or Pi 4, you may need to dial back the matrix control speed slightly. This can be done with the --led-slowdown-gpio=2 setting. Pi 4 may require larger values, depending on the matrix…experiment! Conversely, early Raspberry Pis (Model A, B and similar) might get an improved image by speeding up the matrix code with a value of 0 here.
Page last edited July 15, 2025
Text editor powered by tinymce.
