23 December 2019 / Last updated: 27 Jan 2021

Control your Christmas tree: A Raspberry Pi powered RGB LED matrix v2

Execution time: 1hr - 2hr
Difficulty: Medium
Cost: High
Build and animate your own web and remote-controllable lighting from commonly available RGB LED strings and a Raspberry Pi. We’re going to go through the process of building a fully-configurable 10x25 LED matrix with a graphical configurator to run animations and patterns.


Last year, I wrote a blog post showing how to build an RGB LED matrix. Since then, we’ve developed the project to add web control, a selection of presets, lighting timer and more. Furthermore, it has come to my attention that my original post is “a little on the long side”, with my colleagues using words such as “intense”, “full on” and “ludicrous” to describe it.
In light of this cutting, and quite frankly upsetting feedback, I decided to cut my article down and decorate it with some new ornaments features. I may be biased, but I think LED matrices are cool and so didn’t want everyone to miss out on the coolness because the content was hidden within an absurd wall of text.
TL;DR: lots of LEDs, Raspberry Pi, web browser control, cool animations, limitless possibilities for nerding out, no more rambling. Let’s go!

Hardware required

  • 250 5-volt WS2811 LEDs in the form of 5x 50 LED strings - I got mine from AliExpress of course, but Amazon and others carry them too.
  • A Raspberry Pi 3B/3B+ (others will likely work too, but probably not the Zero for this one)
  • SD Card - 8GB is plenty, but go for the Sandisk Extreme Pro
  • A 5V power supply - get the Mean Well LRS-100-5
  • An Adafruit Fadecandy board
  • LED string connectors - you can just solder the wires but the connectors are nice for modularity
  • Optionally, if you want to print your own case, a 3D printer or 3D printing service to print the case - recommended!

Soldering irons at the ready

For this project you are going to need to do a little bit of soldering, nothing crazy, but it means you do need access to soldering equipment.

Software required

  • A download of the fadecandy-led-controller project from GitHub
  • Software to flash your SD card (balenaEtcher)
  • A free balenaCloud account to setup and manage the Pi
  • Download and install the balena CLI tools - to be installed on your computer, allowing you to install the project code on the Pi

Assemble the hardware

The majority of the work here is connecting your LED strips to the Fadecandy board. This is done by connecting things according to the circuit diagram below.
If you bought the fancy connectors like I did, you’ll solder the connectors to the Fadecandy board and then plug the LED strings in when you’re ready. It’s important to keep note of the LED strings and connect them in order.
The PSU can be connected directly to the power pins on the GPIO header using male-female dupont cables, saving the need for another USB cable to be crammed into the case.

Set up the software

Once you’ve finished assembling the hardware, it’s time to flash the SD card and get your Raspberry Pi loaded with the project code. The process of setting up the various software components has been vastly simplified by the use of balenaCloud. This means you don’t have to manually install or configure packages, you just have to set up an application, add a device and flash your SD card, and push the code from your computer using the balena CLI tools. I’m not going to go into great detail about this process here but we have a lot of great documentation surrounding deploying a fleet of devices.

Set up the balenaCloud application

If you don’t have one already, sign up for a balenaCloud account. After this, add a new application, ensuring you select the correct device type for the device you’re using. Next, add a new device to your application, configure your networking and download the balenaOS image.

Flash your SD card and power on the device

Use Etcher to flash your SD card with the downloaded OS image.
Insert the SD card into your Raspberry Pi and boot up the device. Within a few minutes it should appear in the balenaCloud dashboard.

Push the app code

The next step in the process is to push the code to balenaCloud, after which it will automatically distribute it to all of the devices in your application; just the Raspberry Pi you added earlier at this point! We’ll need to download the code from GitHub, then push the project using the balena CLI tools. I’ve summarised the process of doing this below, but if you need more detailed information we have a detailed deployment guide available in our docs.
First of all, download the app from the GitHub repo, to make a copy on your computer.
Then, after installing the balena CLI tool on your computer, from the project directory, execute balena push <appName> where <appName> is the name of the application you created within the balenaCloud dashboard earlier. For example: balena push fadecandyXmas.
If all went well you’ll see the balena unicorn mascot and the code you’ve just pushed will automatically be distributed to the devices in your application.

Light up that tree!

The LED strings need to be laid out on the tree in a specific configuration so that the software knows roughly where they are. In my case I started each string at the top of the tree, ran it down to the bottom, and then back to the top. This gives me a 10x25 LED matrix assuming 5 strings of 50 LEDs.

Power on!

Once you’ve assembled the hardware, pushed the code and dressed the tree, that’s it! You can now power on and you should be greeted with the default ‘rainbow rain’ preset, smoothly and beautifully scrolling down your tree.

The rainbowrain preset (default)

Try some alternative presets

I’ve built a few presets and saved them so you have a couple of options to get ideas. You can try these by configuring device service variables within the balenaCloud dashboard; set the PATTERN_PRESET variable for the glediator service as below.
Other options in addition to animatedgifexample are partyballs, redvsblue, sparklywaves, twinkly, and rainbowrain (default).

Set up a schedule

What good is a light controller if you can’t schedule a simple on and off time?! Set the device service variables below for the glediator service within the balenaCloud dashboard to enable automated switching of the lighting. The TIMER_OFF and TIMER_ON variables use cron format. ENABLE_TIMER simply needs to be set to 1 to enable the feature.

Open the control software

Now it’s time for the fun stuff! We can finally start to configure the output that’s going to run on the matrix. Glediator is an awesome bit of free software built to produce animations for LED matrices.
A new update to this project allows remote control via a web browser (using either the local IP address, or the balenaCloud public URL of your device). When visiting either URL in a browser you should be greeted with the noVNC interface. Hit the connect button and you’ll be connected to the software.
As an alternative to the web browser interface, you can still connect directly to the Raspberry Pi using VNC on the local IP address, which sometimes gives better performance than using the web interface.
After you’re connected via noVNC, or directly to the local IP address via a viewer such as RealVNC Viewer, you’ll see an interface like the below.

Create your own!

The Glediator software can look daunting at first, but the best thing is that you can’t break anything! If something goes wrong, simply restart the container or device and as long as you haven’t saved the project everything will go back to normal.
A particularly interesting feature is that you can display animated gifs on your tree! I created an animatedgifexample PATTERN_PRESET (see ‘Try some alternative presets’ above), but you can add your own gifs to the project and try those too.
I thought we were having steamed clams?
Animated GIF example

Build a case

If you’ve got 3D printer, or access to one, we’ve created a printable case for this hardware set up. It’s available on Thingiverse.

Printing the case

Fitting the power supply

All hardware fitted

Lid on, and installed under the tree


I hope you found this quick how-to useful! I’m still really happy with this project; the options it gives you for lighting effects quickly and easily within the Glediator GUI is truly awesome - full props to the people at Solderlab.de for making this software available. If you decide to build the project we’d love to hear from you!
You can always find us on the forums at https://forums.balena.io, on Twitter @balena_io, on Instagram @balena_io or on Facebook.

Extend the project

Can you think of any ways to improve this project? Want to contribute? We would love to get feature requests, issues and PRs on the Github repo. Some ideas we were throwing around are: to make a queuing system for the web control, add sound/music interaction, add configurable matrix settings to cover different sizes, but all are welcome!
by Chris Crocker-WhiteHardware Hacker turned Product guy turned co-CEO