First make sure you've loaded the latest Raspbian Lite operating system on your Raspberry Pi.  You can find the OS image download here, instructions for burning to an SD card image here, and a convenient guide here that explains how to load an operating system.

Make sure your Raspberry Pi is connected to the internet, either with a wired connection to its ethernet port, or by setting up wireless access to a WiFi network.  Check out the guide on network setup for more details on using wireless and WiFi networks with the Pi.

Once your Raspberry Pi is powered up and connected to a network you can follow the steps below to install the video looper software.

If you're familiar with connecting to the Raspberry Pi over SSH you can use an SSH terminal application to connect and skip down to the install commands section below.  If you aren't familiar with SSH you can use the Adafruit Pi Finder tool to find your Raspberry Pi and open a terminal to run the installation.  I'll show installation steps using the Pi Finder tool below.

Note with the latest versions of Raspbian (Jessie full & lite since ~February 2017) they disable SSH by default! Read below to see how to enable SSH so you can access the Pi with tools like Pi Finder.

Install Matrix Driver

OK now you are ready to install the drive for the LED matrix. We have a script that downloads the code and any prerequisite software. It works with the current Raspbian “Stretch” operating system (either the Lite or Desktop version). Walk through the options it presents and select the ones that pertain to your setup. If you get stuck, we have a more details in the Bonnet Matrix guide.

curl >
sudo bash

The script will confirm your selections and offer one more chance to cancel without changes.

There’s a lot of software to update, download and install, so it may take up to 15 minutes or so to complete. Afterward, you’ll be asked whether you want to reboot the system.

Install Git and Clone

Once you have enabled SSH and connected to the Pi via a separate computer over WiFi, you can install the proper tools to install the software. First, let's get the git command so we can clone the library repo. Then, we'll install the library and copy code from the repo to the home directory of the Pi.

sudo apt-get install -y git
git clone

Enable I2C via raspi-config

In order to read the accelerometer, I2C must be enabled via the raspi-config interface. Follow the guide below for a step by step guide. If your familiar with this, use sudo raspi-config and enable I2C through the “Interfacing Options.”

Make PixelDust

In order to compile the Adafruit PixelDust library to the Pi, we'll need to execute a make command.

cd Adafruit_PixelDust/raspberry_pi

Running the Code

OK now it's time to run the demo! Execute the command below and use the two buttons to change demos and reset the simulation. You'll need to be in the right directory to run the python script.

cd Adafruit_PixelDust/raspberry_pi/
sudo python

Press Control+C to stop the program and get back to the command line.

Adjusting Brightness

By default the LED brightness is set to 100%…this might be a bit much both on the eyes and the battery. We can tone it down by editing the Python script…


Look for this line near the top of the code (around line 15):

FLAGS        = ["--led-rgb-sequence=rbg", "--led-brightness=100"]

That “100” is the brightness, expressed as a percentage from 1 to 100. Quite often running around 1/3 brightness (33) looks perfectly good. For photography and video you may want even less, perhaps 10 percent. Save changes to the file, exit and try running again with “sudo python”

Automatic Startup

We can configure the system to start the demo automatically after booting, so you don’t need a keyboard and screen to get it started every time…

sudo nano /etc/rc.local

Just BEFORE the final “exit 0” line, insert the following two lines:

cd /home/pi/Adafruit_PixelDust/raspberry_pi
python &

(If you’ve installed the code in a different location, adjust the “cd” command to match.)

Save changes to the file, exit and reboot.

It may take 30 second to a minute before the software starts. This is normal…booting a Linux system is a lot of work and our code is the last thing to run.

Safely Shutdown setup

Turning the switch off before properly shutting down the Pi can cause the SD card to corrupt so we suggest safely shutting down the Pi before turning off the PowerBoost. We have a dedicate guide for enabling Read-Only mode which will allow you to quickly turn off the Pi without risking corrupting the SD card. Check it out here: 

Customization Options

The Python script (Adafruit_PixelDust/raspberry_pi/ uses two buttons (currently on GPIO 19 and 25) to cycle between demos or reset the current one. Near the top of that file you'll see settings for the GPIO pin numbers and LED brightness. You can edit and save the script using nano so you won't not have to type changes every single time.

This guide was first published on Feb 28, 2018. It was last updated on Mar 08, 2024.

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

Text editor powered by tinymce.