Testing all the component before assembly is vital. Most likely all the parts will work on the first try, and you’ll have spent 30 minutes seemingly for nothing. But at worst…you skip testing, build the whole cube, encounter trouble and then you cry as it all has to come apart. Testing is the cheapest insurance in the world! It’s also an opportunity to familiarize yourself with the software and parts. Wax on, wax off.

Seat the RGB Matrix Bonnet onto the Raspberry Pi’s GPIO header, making sure all the pins are aligned, that it’s not off-by-one. Connect a ribbon cable (included with each LED matrix) from the Bonnet to the INPUT connector on one matrix…

The input connector isn’t always clearly labeled, and the manufacturers change up the silkscreen from time to time. Usually there will be two sets of arrows: one set points toward the top of the matrix, the other indicates the flow of data, from the INPUT to OUTPUT connector. Another way is to look for the key or notch on the header shroud. On the input connector, this will face toward the edge of the board, not toward the center.

We’re intentionally being coy about power connections here. That’s another detail that manufacturers change from time to time, and we don’t want to show specific pin positions that could ruin a matrix if taken literally. The connector socket will usually have labels for GND and VCC or +5V, and the power cable included with each matrix has color-coded wires.

Also, there are myriad ways to get power to both the Pi and Matrix. The matrix power cable could go to the screw terminals on the Bonnet with everything powered through the 5V DC jack, or you might want to power the matrix and Pi separately, as shown in the diagram above.

For the love of everything, be certain you are using a 5V power supply! A lot of 12V supplies have the exact same connector…this will destroy the matrix!

Now flip the matrix over, doubling back on the ribbon connector, so you can watch the LEDs during testing:

With the Pi booted, log into the system via ssh again.

The installer created a directory called rpi-rgb-led-matrix, and inside this is a subdirectory examples-api-use with a few programs that can be used to experiment with the matrix and confirm everything’s working.

cd ~/rpi-rgb-led-matrix/examples-api-use

Here’s the command to test one matrix:

sudo ./demo -D 0 --led-rows=64 --led-cols=64 --led-slowdown-gpio=4

If everything goes well, you should see a smoothly rotating colorful square. No gaps, no flicker. Press Control+C to stop.

I’m getting no image at all!
  • Confirm both the voltage and polarity of the power supply. 5 Volts!
  • Confirm ribbon cable is connected to the INPUT socket on the LED matrix, not the output.
  • Confirm Bonnet is correctly aligned on the Pi’s GPIO header, not off by one.
  • Confirm the GPIO4-to-GPIO18 wire is installed on the Bonnet, on the correct pins.

If none of these fix it, swap out the ribbon cable for another (you should have six, one for each matrix). If still nothing, swap out the matrix for another.

I’m getting an image, but it’s split in half, with black bars

There’s a solder bridge on the back of the Matrix Bonnet that must be closed. Connect “E” to “8.” You’ll need to remove the Bonnet to access this…shut down the Pi first.

If everything works and you see the rotating square: stop the program (Control+C), disconnect power from just the matrix (keep the Pi running), and repeat this test for each of the five other matrices and their included ribbon cables. It’s important to swap both. While it’s exceedingly rare…one in thousands…very occasionally a ribbon cable is poorly crimped, and testing each one avoids heartbreak later.

If all six matrices and ribbon cables pass the test, then you can be more confident as the build progresses and gets more complicated that any problems are more likely a poor connection somewhere than an inherent defect in any part.

So! Let’s forge ahead and test all six matrices working at once:

Again, we’re being intentionally vague about power. You’ll probably tie all the matrix +5V and ground lines together using the power distribution bus bars, but we’ll leave that decision up to you.

Except for the last matrix, each OUTPUT connector now links to the INPUT of the next matrix, forming a chain. Six matrices, six ribbon cables.

Notice we’ve labeled the matrices #5 through #0 here, with #5 closest to the Pi. This starts to make more sense when the chain is flipped around and viewed from the front…

It’s because these matrices work as shift registers…the first data sent down the wire makes the long trip to the end of the chain. The first bits…the first, leftmost pixels…go to matrix #0. We’ll call them 0 through 5 (rather than 1–6) because that designation is easier if you want to write your own software for this later.

Here’s a command to test a chain of six matrices (this may appear “wrapped” here, but should be entered as one continuous long line):

sudo ./scrolling-text-example --led-rows=64 --led-cols=64 --led-slowdown-gpio=4 --led-chain=6 -f ../fonts/texgyre-27.bdf Hello World!

“Hello World!” should scroll right-to-left down the matrices. Control+C to quit.

Message scrolls partway down the chain, but leftmost matrices remain unlit

Either one or more panels isn’t receiving power, or one or more ribbon cables are faulty. Try swapping the positions of two ribbon cables and see if the problem moves with it. If so, you can try fixing the crimp (a bench vise works, applying uniform pressure across the whole row)…if still not working, request a replacement in the forums.

Now that the Pi, essential software, and all six matrices and cables are known good and working…don’t dismantle anything yet, but…

  • Pat yourself on the back for your patience and maturity to perform this full diagnostic step.
  • Celebrate, take a short break, maybe have a treat.
  • Next we’ll install some software of our own, then move ahead with folding this up into a cube!

This guide was first published on May 04, 2022. It was last updated on Mar 08, 2024.

This page (First Light) was last updated on Mar 08, 2024.

Text editor powered by tinymce.