Raspberry Pi


Working with RGB LED matrices requires to install a base driver software. We are using the incredibly versatile rpi-rgb-led-matrix. Here are our development notes on installation.

led matrix


Installation is perfectly covered on the main page of rpi-rgb-led-matrix. We have distilled our approach below. The guide installs rpi-rgb-led-matrix for use with Python 3 and our library for handling RGB matrices (coming soon)

Installing a new image

It's a good idea to start from a new image, when creating your RGB Panel thing. You can choose any recent distro of Raspbian. We will use Raspbian Lite, but if you wish to develop on your Pi directly, choose a heavier version. Our guide for setting up a headless Raspberry Pi can be a good start.

  • install git (required on Raspbian Lite - in other images git is already included)
sudo apt install git
  • Update All - see our guide Updating Raspberry Pi to learn more
  • [Optional] You can install Samba, if you wish to access your Pi through a Windows network
  • [Optional] If you have installed a full version of Raspbian, you might want to install xrdp for remote access through RDP to your development environment
  • [Optional] Install Mosquitto if you wish to use our libraries for controlling the matrices (don't forget to include the paho Python libraries)


As mentioned, this guide covers a Python 3 installation. For 2.7, go to the original guide - rpi-rgb-led-matrix

# setup pre-requisites for rpi-rgb-led-matrix
sudo apt-get update

sudo apt install libgraphicsmagick++-dev libwebp-dev
sudo apt install libwebp-dev
# python2.7-dev required for the make process
sudo apt install python2.7-dev -y
sudo apt install python3-dev python3-pillow -y

# download the project
git clone https://github.com/hzeller/rpi-rgb-led-matrix

# build the project using the standard hardware profile (change based on your hardware)
cd rpi-rgb-led-matrix
sudo HARDWARE_DESC=regular make install-python

cd utils/
sudo make led-image-viewer

cd ../examples-api-use

# compile for Python 3 (https://github.com/hzeller/rpi-rgb-led-matrix/tree/master/bindings/python)
cd ../bindings/python/
sudo make build-python PYTHON=$(which python3)
sudo make install-python PYTHON=$(which python3)

Don't forget to disable the sound card!

Run Demos

To run the basic demo and test your installation (change the gpio mapping parameter based on your hardware). Please also notice the 'slowdown' parameter: on our Pi with a standard matrix hat, the Pi was too fast :)

cd ~/rpi-rgb-led-matrix/examples-api-use
 sudo ./demo -D -m 0 --led-no-hardware-pulse --led-gpio-mapping=regular --led-slowdown-gpio=2

Navigate to the project python folder to run Python demos

cd rpi-rgb-led-matrix/bindings/python/samples
sudo ./runtext.py
# run other demos available in this directory


Here is a bunch of links and descriptions for hardware: matrices and hats


You might need some of the tools below to manage your development

  • IrfanView - a lightweight image viewer. In our case, it supports PPM files. Both viewing and saving (save-as)
  • Gimp - used to generate PPM files. If you take art creation seriously, this is the tool to use. For simple conversions, IrfanView should be enough

Tools - Animated GIFs

Animated GIF images are a special category for our makerspace. We run those a lot. While it is true that the resolution of smaller RGB Matrices is simply not enough, there is still huge value using them. And with a bit of tweaking, the results are very, very good.

This section lists tools and sites which we use. If anything else, they are great for inspiration.

  • ezGIF - a great online tool to edit and manipulate your animated GIFs
  • Shadertoy - making GLSL shaders, and a great inspiration gallery
    • The Book of Shaders - great reading to understand shaders
    • Shadertoy Exporter - tool to export and convert Shadertoys to animated GIFs or movies
    • Shadertoy Render - a Python tool similar to Shadertoy Exporter. Inspiration for converting your own animations via Python
  • GeeXLab - another tool to create and render animations. This tool can connect directly to RGB Matrices; see example use here

Interesting Applications

The library has some traction across the maker-verse. This section describes interesting applications, which expect rpi-rgb-led-matrix to be present as the display part, and which use it to create visual effects.

  • Art-Net - Art-Net is the core protocol behind most of the solutions listed here. Not an application per-se, but instead a protocol wrapping rpi-rgb-led-matrix, as a network entry point.
  • Jinx! - a free solution, allowing us to control RGB Matrices with this library and Art-Net, across the network. No source code available.


  • Glediator - A Java based application, used to control RGB Matrices via Art-Net.


  • GeeXLab - yet another great tool for 3D programming, creating demos etc. This one has RGB Matrix support as well