Build an MQTT based RGB LED panel! // Project

This quick project shows you how to build an MQTT controlled RGB LED matrix panel in under 30 minutes, but I reckon it should take you a lot less.

Or check out the video on YouTube.

I’ve been asked several times about why am I promoting Docker for embedded systems.

Well, this project is an answer to that question – building an MQTT controlled RGB LED matrix panel from scratch in under 30 minutes and probably a whole lot less. I’ll also be soon running a video series called DockerFu, which will be similar to my LinuxFu series – getting you from knowing nothing, to knowing everything about Docker.

Back in MickMakeMail #27 you would have seen me un-box two RGB LED matrix panels. The goal was to be able very quickly setup the panels to display arbitrary messages using MQTT. This would allow me to tie it in to services such as IFTTT, but it wasn’t enough to just write some code. I wanted to be able to make it very easy for anyone to run the software without having all that messy installation process.

This is where Docker comes in.

Parts required

To make this project, you’ll need to have:

Of course you’ll also need a Pi Zero W and an SD card. You can use any Pi for this but I wanted it to be as compact as possible.

You’ll also need a pretty hefty 5v power supply. I used a 10A switch-mode power supply, which had plenty of juice.

Download Raspbian

Once you have all your bits, download the latest Raspbian image from the Raspberry Pi website.

Soldering the Pi hat

While that is happening, you’ll need to make a choice between having a slow panel with audio, or a fast panel without audio. The slower panels can be a little flickery sometimes.

So, if you’re happy without any audio, then you can make this small change on the matrix hat, which is connecting up GPIO 4 to GPIO 18.

Burning the SD

By now your download should have finished. Fire up the SD burner of your choice and burn that to an SD card.

While that’s happening … you can solder up a header to the Pi Zero W. Of course this header is already provided on most Pis.

Connecting up the panel

Next you’ll need to connect up the matrix hat to the provided cable and then to the panel. Next connect the power cable to the paneland then the other end to the screw terminals of the Pi hat.Make sure you have the correct orientation, with the red and black cables in this position.

SD card changes

Now that your SD card has finished burning, you’ll need to make some changes so that it’ll connect to your WiFi Access Point.

First edit the config.txt file and add this line at the end. Also make sure that you disable audio.


Next edit the wpa supplicant file and add your WiFi Access Point details.

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
 ssid="Your SSID"
 psk="Your password"

Then create a blank file called ‘ssh’.

Then eject and chuck it into your Pi Zero and wait for it to boot.

Enable root logins

Now the next step is optional, which is to allow root logins. It’s just something that I do on all Pis.

Edit the /etc/ssh/sshd_config file and change the PermitRootLogin line to yes and then save.Change the root password to something that will annoy you in future and restart SSH.

/etc/init.d/ssh restart

Then you can login to your Pi directly as root.

Installing Docker

Next on to installing Docker. This is very trivial and all it requires is running this commandwhich will take around 4 minutes to complete.

If you use the pi user account often then don’t forget to give access to Docker for that user account.

usermod -aG docker pi

Then reboot. You don’t really need to reboot, but I often do so just to make sure there’s no issues when booting.

Now on to the good bit. I’ve created a Docker image that you can download that has my snazzy MQTT panel driver as well as all the C and Python libraries supporting it. So you can use my app, or write your own.The source code is also up on GitHub along with handy shell scripts for creating, starting and stopping this container.

You can pull this container by running this command.

docker pull mickmake/project-mqttpanel:latest

Once it’s finished downloading and extracting, you’ll need to create a container from the image by running this command.

docker create --name project-mqttpanel --restart unless-stopped -p 1883:1883 --device /dev/mem:/dev/mem --privileged --user root mickmake/project-mqttpanel:latest

and typing this command will show that it has indeed been created.

docker ps -as

Then you can start it by typing this command.

docker start project-mqttpanel

This will start up the container and execute my pre-loaded app. The default display will be an animated GIF of a creepy alien guy in the background along with the date and time. This is completely configurable via MQTT publish commands.


If you have any MQTT clients installed on your PC, you’ll be able to send MQTT messages to the panel. For example you can change the background image to an animated heart beat.

mosquitto_pub -d -h -t /display/background/load -m HeartBeat.gif

Or a pair of animated handsReally any GIF or JPG file will display as the background. These are stored within the Docker container and you can change them to anything you want.

You can also send MQTT messages on the Pi itself. To make it easier for yourself create a script. This will run the Mosquitto client within a Docker container.Or you can use the scripts from the GitHub page.

Then you can issue the same commands. For example; Display ‘congrats’ in blue text with clapping hands as the background.

mosquitto_pub -d -h PI_HOST -t /display/text/format -m 'Congrats'
mosquitto_pub -d -h PI_HOST -t /display/text/color -m '#00FF00'
mosquitto_pub -d -h PI_HOST -t /display/background/load -m Hand3.gif

Or display “warning” text in red, hide the date and time and set the background image to some dancing skeletons…

mosquitto_pub -d -h PI_HOST -t /display/text/format -m 'Warning'
mosquitto_pub -d -h PI_HOST -t /display/text/color -m '#FF0000'
mosquitto_pub -d -h PI_HOST -t /display/background/load -m DancingSkeletons.gif
mosquitto_pub -d -h PI_HOST -t /display/date/show -m 0
mosquitto_pub -d -h PI_HOST -t /display/time/show -m 0

Heat and speed

The Pi Zero can keep up with the display without issue, although for larger animated GIFs, you may want to use a Pi2 or Pi3.

As you can see, my MQTTpanel executable and Mosquitto server consume almost 70% of the CPU.

If you find things a bit laggy, you can always stop and disable the LightDM service, as desktop logins won’t ever be needed.

systemctl stop lightdm.service
systemctl disable lightdm.service

Also, the Pi will get quite hot. The peak temperature is around 50C with an ambient 30C room temperature. When you build an enclosure for this, make sure that there is adequate ventilation.

Speaking of enclosures… You can do away with the long cable if you buy a female to female header and mount the Pi hat directly to the panel. This is something that I’ll definitely be doing.

Pretty easy stuff.


So, hopefully you’ll see how Docker simplifies software installation which is just as important on embedded systems as it is on large data-centers. One of the issues that plagues the SBC Maker scene is software configuration and dependencies.

Docker solves that and gets you up and running quickly.

Hope you enjoyed this quick video. If you’d like to see more of them, then consider supporting me on Patreon or directly. My current Patrons, along with sponsorships, have been a great help to me.

I’ve always tried to produce high quality videos packed full of content that are easily digestible, but I’d really like to be able to take it to the next level. So, with your help, I’ll be able to reach that goal.

And if it’s not possible to support me that way, you can always subscribe to this channel or like this video.

If you like this YouTube channel please subscribe by clicking the in-video button, or the little red "Subscribe" button in your browser or app. You can also get updates by subscribing to me on Facebook, Twitter, Google+, Pinterest, and also Tumblr.

Forum comments to this post...

  1. Dear Mick,

    Your RGB LED panel project is really impressive.
    I hope I could try to make this MQTT controlled RGB LED MATRIX panel. But before that, I would like to ask you something.

    There are some ways to use RGB LED panel.

    A. Adafruit RGB Matrix HAT + RTC for Raspberry Pi
    B. Raspberry PI zero + zero Pi HAT
    C. Adafruit RGB LED matrix, teensy 2.0++, bluesmirf gold, 5v8a UBEC, 5000mah lipo battery (

    How do you think which one is the best way to use what if I would like to make something to communicate with music, images, data, etc?

    I knew that it is very complicated.
    So I will give some examples.

    Option1. I would like to send some images, text with smart phone application in a room about 1,000 square feet.
    Option2. I would like to send images, text with my computer to RGB LED PANEL based on your MQTT project.

    Please, give me your advice.
    Thank you in advance!
    Hopefully, help me to build this great project.

    Best regards,

  2. Dear kind Mick,

    I am so appreciated to your fast answer.

    Actually, I would like to make some RGB LED display projects.

    Project 1. Song list RGB LED display

    Our worship team sing 4 songs every Sunday and sometimes we do 5 songs.
    I would like to communicate with Song list RGB LED display

    Project2. Short Cartoon Display like PEANUTS

    Sometimes, whenever I feel nervous, I would like to watch short cartoon with LED display. Specifically , I love Charles Schulz’s and his philosophical dog Snoopy. Recently, I bought some books!

    From the beginning, I will make your project one by one and then I will try to do and research my works.

    Thank you for your magnificent project sharing always.

    P.S/ And I like your humour :))
    Have a wonderful day.

    Best regards,

  3. Hi Clara,
    In that case I would use a Pi Zero. I’m gathering that you have someone up the back who manages the lyrics for the congregation? They could also control the LED panel and update the song title.

  4. Dear Mick,

    It has been a long journey to me. But today, I have seen a light of my life. Because, I could see red light in my LED RGB PANEL! Though it was kept on lighting only for 10 seconds and then it disappeared.

    I chose Raspberry pie 3 instead of zero.

    Now I am checking what is the problem.

    Most of all, I think that I have finished my first Raspberry coding successfully until now. I installed programs from Rasbian to vim by myself and followed up your whole manual one by one. Sometimes, I made some mistakes back and forth. But finally, I did it. And also, I did my best to solder to make it perfect.

    I soldered 40 GPIO pins, cable socket and connected GPIO 4 to 18 ,too.

    Hopefully, I could see the light tonight in my LED RGB PANEL.

    With warmest regards,
    Clara Kim

  5. Finally , it is getting started to work!
    Thank you, Mick!

    Now I will try to do more right now.

    With warmest regards,

  6. Mick,

    I came across this project while trying to hack together exactly the same thing in Python. I use Home Assistant and wanted a way to use MQTT to to display messages around the house.

    After playing with this for about 30 seconds I abandoned my plans to make my own because this is a fantastic project. Thank you very much for making it. The gifs are an added bonus that I hadn’t thought of!

    I wanted to ask if you’re accepting bugs. I’m not a C person so I don’t want to start hacking around in your code!

    The bug is that this sequence

    mosquitto_pub -h -t /display/date/format -m '%a %d %b'
    mosquitto_pub -h -t /display/text/format -m '10°C'

    for some reason causes the 10°C to appear where the date is AND in the text location. If I then publish another date/format it goes to what I’d expect to see.

    Bug 2 - probably more of a request - could you make the container time zone aware? I had to start the container with

    -v /etc/timezone:/etc/timezone -v /etc/localtime:/etc/localtime:ro

    before it would display the time-zone adjusted time rather than UTC time.

    Once again - thanks for making this. You’ve saved me at least a few weekends of doing my own coding and experimenting!


  7. Hello, I’m very interested in this project and I have ordered all the needed parts to do it. In case of using an Adafruit bonnet, I’ve seen that for 64x64 matrix panels you need to connect in the lower side of the bonnet a couple of points (8 or 16) with a solder blob, but I have not seen this on your instructions. Could you please confirm if this is needed or not?

    Thanks a lot and best regards / Fernando

Continue the discussion at

14 more replies