How to Use an LED Matrix Panel with Your Raspberry Pi

We've listed the Raspberry Pi Zero WH as the preferred Pi for this project because it's small enough to fit behind the display, includes WiFi, and comes with GPIO headers pre-soldered.

If you happen to be using a Pi Zero W (without headers), you'll need to go ahead and solder on your headers.

Need a soldering iron? Check out our guide to the best soldering irons.

Next, you'll need to install Raspberry Pi OS. To do so, please check out our detailed guide on how to install Raspberry Pi OS on your Raspberry Pi. After installing the OS, I recommend that you enable SSH and configure Wi-Fi as well, but this is only required if you're using a fully headless setup.

Connect the bonnet to the Raspberry Pi. To do this, you'll need to line up the GPIO pins on the Pi with the female adapter on the bonnet.

Don't rush this step. If you push too hard or try to do it too quickly, you could damage the GPIO pins.

With the pins lined up, press firmly and evenly across the GPIO pins. Squeeze the boards together between your thumb and index fingers. If you do it correctly, you should see the GPIO pins entering the female adapter evenly all the way across.

Optional:

You could add standoffs between the Pi and the bonnet on the non-GPIO side if you want to add support. This isn't necessary as long as you're careful when you're connecting the rest of the hardware.

The RGB matrix bonnet will provide power to both the panel and the Raspberry Pi. The Raspberry Pi will receive power through the GPIO pins, but we'll need to connect the panel to the bonnet to provide power to the panel.

Depending on the exact panel you purchase, you will likely need to cut and strip the red and black wires.

Then on the bonnet:

• Unscrew the small screws at the top of the terminals.
• Slide the exposed copper from the cables into the terminals
• Then tighten the screws to secure them.

At this point, you're ready to connect all of the hardware.

• Connect the ribbon cable from the panel to the RGB matrix bonnet.
• Install your SD card in the Raspberry Pi.
• Connect your power supply to the bonnet.

Things used here

See all

Check Price

Adafruit RGB Matrix Bonnet

on Adafruit

Now, you're ready to write some code!

From here, you'll need to either connect your Pi to a keyboard and monitor or if you're comfortable with the command line, you can work via ssh. If you're using the Raspberry Pi OS Desktop, you'll need to log in and open Terminal.

There are a few ways to configure this library. I'm going to configure the library for use with Python 3. You can also install the bindings for Python 2, C++, or C#, or just use it as a command-line tool.

To get going, you'll need to install some dependencies:

sudo apt-get update  && sudo apt-get install -y git python3-dev python3-pillow

Then you're going to install the rpi-rgb-led-matrix library. Let's start by cloning the repository:

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

Now, cd into the repo folder and install:

cd rpi-rgb-led-matrix
make build-python PYTHON=$(which python3)
sudo make install-python PYTHON=$(which python3)

Each of these commands should run without a hitch.

With our hardware set up and the software installed, let's run a simple test.

The library ships with some sample code to get us started. You're going to use a Python script called runtext.py that scrolls text across the screen on repeat.

Navigate to the samples directory:

cd bindings/python/samples

Now run the following command:

sudo python3 runtext.py --led-cols=64 --led-gpio-mapping=adafruit-hat --text="Hello, world!"

Note: Some of the sample scripts are a little bit feeble. You must be in the samples directory for the fonts to load properly.

Let's break down this command.

1. This is important. We're calling this script with python3 because that's how we built the library. It will not work using python or ./.
2. Then, because the default display size is 32x32 and my panel is 64x32, I'm passing in --led-cols=64 to override the number of columns.
3. And, because we're using the adafruit bonnet, we need to specify the hardware with --led-gpio-mapping=adafruit-hat. Finally, for this particular sample script, we can pass in the text we want to scroll with --text.

Give this a shot to make sure everything is set up correctly.

For this example, you'll work from another directory. Feel free to create a working directory of your choice, but I'm going work right out of the home directory:

cd 

First, you need to download a sample image:

wget https://howchoo.com/media/nz/i3/md/howchoo-low-res-h.png

Then you'll use the following script. Create a new file called test-image.py and add the following:

#!/usr/bin/env python3

import time
import sys

from rgbmatrix import RGBMatrix, RGBMatrixOptions
from PIL import Image

if len(sys.argv) < 2:
    sys.exit("Require an image argument")
else:
    image_file = sys.argv[1]

image = Image.open(image_file)

# Configuration for the matrix
options = RGBMatrixOptions()
options.rows = 32
options.cols = 64
options.chain_length = 1
options.parallel = 1
options.hardware_mapping = 'adafruit-hat' 

matrix = RGBMatrix(options=options)

# Create a thumbnail that first our screen
image.thumbnail((matrix.width, matrix.height), Image.ANTIALIAS)

matrix.SetImage(image.convert('RGB'))

try:
    print("Press CTRL-C to stop.")
    while True:
        time.sleep(100)
except KeyboardInterrupt:
    sys.exit(0)

Now make the script executable:

chmod +x test-image.py

And run the script passing in your image as an argument:

sudo ./test-image.py howchoo-low-res-h.png

For best results, you'll want to use an image that's the same aspect ratio as your panel or else build some cropping functionality into the script.

If you browse the repository there are plenty of examples to choose from. You can also check out some projects that use this panel, like our Raspberry Pi Scoreboard (see video below) and our cryptocurrency ticker.

If you have trouble with this guide or would like to see more examples, let me know in the comments below. I might be able to help :)