- Project

MATRIX - Animation Editor


Here I’ve developed an easy to use application, for programming animation effects into LED panels, built from 16x16 arrays of WS2812B programmable RGB LEDs. The images you design with this app are stored on a microSD card, from which they are loaded and manipulated using an ESP32 microcontroller. Large panels up 48 x 128 LEDs can be designed using this app.


Project Overview
This project was created in support of a local school wanting to build several display panels for a light show, the 2021 Lumiere festival held in Durham city centre. I built a 48x16 panel as a proof of principle, and to develop the Windows app, so that is what the information on this page is all about. There are applications on the internet that can generate colourful patterns, but none that I could find, that would make the creation of LED images easy and then help you animate them. So it is essentially a graphical drawing tool, combined with a script editor for controlling your animations. Once the files are saved to the microSD card you don’t need a PC to run them.

Click on the image to the right to see examples of what can easily be created on a 48x16 LED panel using the MATRIX app..

The design was created using a 3-D modeller and printer, to ensure that the assembly goes together with ease. The ESP32 microcontroller is house in a small box, along with the 64x128 OLED display, a rotary encoder and a removable microSD card. This box mounts directly onto the back of the first LED matrix supporting frames, and they in turn connect together to make a larger display. The flexible 16x16 LED panels are glued to the supporting frames, which act as stiffeners.

The panels are grouped together using M3 screws and interlocking bars, and short legs can be fitted in the corners, so that they can be rotated outwards to hold the display panel in a vertical plane. But if you wish the LED panels could just as easily be mounted on a single sheet a plywood, with holes to allow the wires to come through.

The Matrix app was developed in ‘Processing’ an environment very similar to the Arduino IDE, and you can download the Java executable file from a link below; which runs on a PC without the need to be installed. The left-hand graphics editor supports multiple panel formats, and provides a range of drawing tools like freestyle pen, line, box and circle, as well as more sophisticated options like flood fill, cloning, moving, mirroring and flipping areas, as well as a text drawing mode.

The right-hand side is the animation script editor, which is like a simple programming language, with commands like ‘Bright’ to set the LED brightness, and ‘Speed’ to set the animation frame rate Just like conventional animation, the script supports multiple planes, used to build up the output image, and special functions like scrolling text and sprites. The editor is a ‘click’ to select and modify tool, with the only need for typing being to enter text for comments and display purposes. There is a simple help system too, which details the controls currently under the mouse pointer..

The circuit diagram for the control box is shown here on the left, with the ESP32 connected to the microSD card and display, as well as a rotary encoder, to provide a simple menu system on the display. As the ESP32 board runs at 3.3 volts, and the WS2812B LEDs run at 5 volts, there is an issue of incompatibility which has to be resolved with a level shifter circuit. This is solved by using a single WS2812B LED in the controller, powered from the 5 volt rail, but through a diode. This intermediate voltage supply ensures that the ESP32 can drive this LED, and it in turn can drive the first LED in the LED matrix. Problem solved reliably!

In construction I use wire wrap technology, to make the process easier and more reliable, and you can test your solution before needing to solder it. There is however an initial outlay in buying the wrapping tool and spools of wire.


Design Files
The following files can be downloaded to help you complete this project. Each has a hyper-link and an associated description. Depending on how your web browser is configured the links will either open the files directly into the browser or offer them as downloads.

Circuit Diagram - a detailed pdf of what is seen in the views above. Use it as a step by step guide to wiring up your project.
Parts list - the things you will need, and indicative budget prices.
3-D Models - a zip file containing all of the STL files, which you can use with a slicer application for 3-D printing.
3-D Parts - a pdf file which identifies the 3-D parts, and to prepare them for assembly
Software - the all important code, .ino files for Matrix controller, plus a  ‘Processing’ application. See comments below on coding
Quick Guide - introduces the Matrix Editor and outlines its many features
Command Reference - a pdf file containing essential descriptions of each command used in the script editor.

This project relies on the use of nine libraries, <Arduino.h>, <HardwareSerial.h>,, <Wire.h>, "SSD1306Wire.h", <FastLED.h>, “FS.h”,”SD.h”,”SPI.h”, and <stdlib.h>, which need to be included in the IDE set-up, in order for the .ino code to compile correctly. If you haven’t used an ESP32 before with the Arduino IDE, then you will need to install the board libraries too. There are several articles on the web that explain this process. I would recommend this one by Random Nerd Tutorials.

Design Notes:

The following notes will help you understand how the files in this project work or can be used in principle. Each note has a bold heading for quick reference and they are listed in alphabetical order.

ino File - the software .zip file contains two folders: Matrix_Editor_R3, and Panel_48x128, which in turn contains several files. These are all to be extracted and retained within the same folders, of those named. The first folder is the Matrix editor application, which is compiled into Java and will run from any hard drive, included a USB memory stick. The second folder contains the ESP32 .ino files. If you are wondering why there are several .ino files, it is because I use the tabbed interface within the Arduino IDE, and for each tab there is a corresponding .ino file.
3-D Models - The pdf files provided should give you sufficient information to identify the .stl parts and indicates the quantity of each to be printed. As the ESP32 can come in different board sizes I have included two cases to accommodate whichever part you have purchased. There is a 30 mm M3 nylon screw which passes through the case to hold it onto the back of the first LED panel, but you may choose to simply mount the LED 16x16 matrices onto a piece of plywood, if that suits you better.
Coding - The ESP32 code is full of comments to aid your understanding of it. If you are using a panel of greater than 48x16 LEDs then you will need to change the configuration at the start of the code on the first tab. Depending on the power supply you are using you may wish to change the current limit too.

Serial Port
- is used in this design connect the ESP32 controller to the Matrix application, running on your PC. The baud rate used is 500,000 bps, as a lot of data may need to be transferred to the controller in the form of graphics images. Clicking on the serial COM port field in the application causes it to connect to the controller. A right-click will cause it to disconnect, which is useful if you are using the Arduino IDE serial port or programming in parallel.
STL Model Files - use these with your favourite slicer application. In the 3D Parts pdf document I have indicated the size of pilot holes needed for the screws..

Need more?
If you feel that I haven’t included enough information to allow you to tackle a project of this type then send me an email explaining what you need. Or if you just want to give me some general feedback on this site, or to suggest projects what I might include which would be interesting to you, I’d be pleased to hear from you.

Page updated: 30/11/2021