Getting started: OzzMaker 16×16 RGB LED Matrix Panel with a Raspberry Pi

This guide gets you from a fresh Raspberry Pi to your first lit pixel using hzeller’s rpi-rgb-led-matrix library — the same library used in our examples and demos.

 

What you’ll need

Step 1 — Disable the onboard sound

The library uses the same hardware sub-system as the Pi’s onboard sound, so they can’t both run at once. Disable the sound module:

pi@raspberrypi ~ $ sudo nano /etc/modprobe.d/blacklist-rgb-matrix.conf

Paste in the line below:

blacklist snd_bcm2835

Update boot image and then reboot

pi@raspberrypi ~ $ sudo update-initramfs -u
pi@raspberrypi ~ $ sudo reboot

Install prerequisites:

pi@raspberrypi ~ $ sudo apt-get update && sudo apt-get install python3-dev cython3 -y

Download hzeller’s RGB LED matrix library and uncompress:

pi@raspberrypi ~ $ curl -L https://github.com/hzeller/rpi-rgb-led-matrix/archive/7a503494378a67f3baa4ac680cecbae2703cc58f.zip -o rpi-rgb-led-matrix.zip
pi@raspberrypi ~ $ unzip rpi-rgb-led-matrix.zip
pi@raspberrypi ~ $ rm rpi-rgb-led-matrix.zip
pi@raspberrypi ~ $ mv rpi-rgb-led-matrix-7a503494378a67f3baa4ac680cecbae2703cc58f rpi-rgb-led-matrix

Build and install the libraries:

pi@raspberrypi ~ $ cd rpi-rgb-led-matrix
pi@raspberrypi ~ $ make build-python
pi@raspberrypi ~ $ sudo make install-python

Now we can test two of the C++ examples;

pi@raspberrypi ~ $ cd ~/rpi-rgb-led-matrix/examples-api-use
pi@raspberrypi ~ $ sudo ./demo --led-rows=16 --led-cols=16 --led-chain=1 -D 1 runtext16.ppm
pi@raspberrypi ~ $ sudo ./demo –led-rows=16 –led-cols=16 –led-chain=1 -D 0

You can update led-chain above if you are using more than 1 panel in your chain.

You can also test the Python examples:

pi@raspberrypi ~ $ cd ~/rpi-rgb-led-matrix/bindings/python/samples
pi@raspberrypi ~ $ sudo python pulsing-brightness.py

Now you can try your first python script to light three LEDs, one red, one green and the last blue.

pi@raspberrypi ~ $ nano hello.py

Enter in the below script


from rgbmatrix import RGBMatrix, RGBMatrixOptionsoptions = RGBMatrixOptions()
options.rows = 16
options.cols = 16
options.chain_length = 1
options.parallel = 1
options.hardware_mapping = "regular"
matrix = RGBMatrix(options=options)# Light a single pixel red, green, blue
matrix.SetPixel(0, 0, 255, 0, 0)
matrix.SetPixel(1, 0, 0, 255, 0)
matrix.SetPixel(2, 0, 0, 0, 255)input("Press Enter to exit...")

Then run it:

pi@raspberrypi ~ $ sudo python hello.py

The library always needs root because it talks directly to the GPIO at high speed.

 

Common gotchas

  • Nothing displays: Check the FFC cable orientation and that you’re plugged into the panel’s IN port (look for the arrow).
  • Flickering or glitches on a Pi 4: try --led-slowdown-gpio=2 (or 3, or 4). The Pi 4’s GPIO is faster than the panel can keep up with by default.
  • Want to see the refresh rate? Add --led-show-refresh.

Chaining multiple panels

The OzzMaker panels are designed to be chained. Each panel has an IN and an OUT side (look for the arrow) — signal flows from the Pi into the first panel’s IN, out of its OUT, and into the next panel’s IN, and so on.

One chain only. The OzzMaker RGB LED Matrix Connector supports a single chain. The library can drive up to three parallel chains on a 40-pin Pi, but that requires wiring the extra chains to additional GPIO pins, which this connector doesn’t break out. Everything below assumes a single chain (–led-parallel=1, which is the default).

Wiring the chain
Plug the OzzMaker connector onto the Pi’s 40-pin GPIO header.
Connect the FFC cable from the connector to the IN side of the first panel.
Connect a second FFC cable from the first panel’s OUT to the second panel’s IN, and repeat for each additional panel.

Telling the library how many panels

The number of chained panels is set with --led-chain. For four panels in a row you would use;

pi@raspberrypi ~ $ sudo ./demo --led-rows=16 --led-cols=16 --led-chain=4 -D 0

 

By default the library treats the chain as one long horizontal strip — for four 16×16 panels that’s a 64×16 display.

Arranging panels into a square or grid

If you’ve soldered the panels into a square or rectangular block rather than a single long strip, the chain is still electrically one line of panels, but you want the library to map the pixels into a 2D arrangement. That’s what the pixel mapper is for. For example, four panels soldered into a 2×2 block (a 32×32 display):

pi@raspberrypi ~ $ sudo ./demo --led-rows=16 --led-cols=16 --led-chain=4 --led-pixel-mapper="U-mapper" -D 0

The U-mapper arranges a single chain that snakes up and back down in a U shape — the most common physical layout for a soldered grid. You may need to add ;Rotate:180 or adjust how you physically order the chain until the image appears the right way up:

--led-pixel-mapper="U-mapper;Rotate:180"

Getting the mapper right is mostly trial and error the first time — run a demo with recognisable text or an image and rotate/re-map until it reads correctly.

In Python

The same options apply when using the Python bindings:

options.rows = 16
options.cols = 16
options.chain_length = 4          # number of panels in the chain
options.parallel = 1              # the OzzMaker connector supports 1 chain
options.pixel_mapper_config = "U-mapper"   # only if arranged as a grid

Going further

The library supports text rendering, image and GIF playback, video, and pixel mappers for building large soldered grids from a single chain. Have a look at examples-api-use/ and bindings/python/samples/ in the cloned repo — there are dozens of working examples to start from.

If you build something with these panels, share it on the OzzMaker forums — we’d love to see what you make.

Blip, blop, bloop…