This project implements a custom controller for a 16x16 addressable LED matrix using an ESP32 to display high-framerate animations.

https://v.redd.it/2gezibfc8v6g1/CMAF_1080.mp4

This work was inspired by Pipplee - a project that displays animated GIFs on WLED installations.

While Pipplee is excellent for managing an animation catalog, its reliance on WLED's preset system introduces two major limitations that this custom solution addresses:

Pipplee loads animations by repeatedly uploading and editing WLED presets. According to the WLED documentation, frequent, random writes to the LittleFS preset file are highly resource-intensive.

...random writes to the preset file are very resource intensive. This means that while updating your presets, you might notice your light freezing and becoming unresponsive for up to a few seconds.

Because Pipplee uploads a new preset every time an animation is switched, the system frequently becomes unresponsive, leading to a frustrating user experience.

Pipplee generates a separate WLED preset for every frame of an animation and uses a playlist to cycle through them.

The playlist feature in WLED imposes a minimal preset duration of 0.2 seconds, locking the maximum framerate at 5 FPS. This project bypasses the WLED playlist limitation to achieve a significantly smoother animation display.

The system is controlled using two rotary encoders, each with an integrated push button:

The circuit utilizes two rotary encoders and an external power supply for the LED matrix.

📌 Note: I used encoders which do not need power pins - only GND and INPUT_PULLUP type inputs.

The full interactive circuit diagram is available at: cirkitdesigner url

• You can use external power supply connected to LED matrix power inputs
• Make sure to use buck converter between matrix + terminal and ESP32 VIN if your LED matrix is 12V!
• When using WS2812b matrices, signal level converter such as SN74 is often recommended, but I don't have one and adding 330 Ohm resistor seems to work fine.

I remixed this model to create frame with encoders

The project includes a Python-based animation converter that transforms WLED presets (generated by Pipplee) into a C header file containing a PROGMEM array. This stores the animation data directly in the ESP32's flash memory for fast access.

Animations I like are included in the repository. If you want more animations - respect the original developer who created hundreds of animations and an app to create animations from gif and purchase $3/year Pipplee license.

The conversion process is as follows:

1. Load the desired animation into WLED.
2. Save the preset (Config -> Security & Updates -> Backup & Restore -> Backup presets).
3. Rename the resulting JSON file and place it in the project's animations_src directory.
4. Animations will be converted to header files in include/animations folder (which is cleaned by conversion script) on every build

If you want to try running conversion manually:

1. Run the converter: python3 scripts/convert.py.

Animations data is stored usin RGB565 format which uses 16bits for every pixel. A 16x16 matrix frame requires $16 \times 16 \times 2 \text{ bytes} = 512 \text{ bytes}$ of storage.

The standard ESP32 4MB flash partition table reserves approximately 1.5MB for the application (app0) and 1.5MB for a second application (app1).

Currently APP without animations uses ~1.16 MB of flash. This leaves ~300 KB for animations (~600 frames or about 30 animations). Full length of every animation is in the end of this file. Inluded 63 animation use ~960 KB which translates to total 2.1 MB

That's why custom partition table is used whith 3 MB app0 parition.