If the GIF player doesn’t quite do what you want (different matrix size, etc.), the source code can be tweaked and recompiled.

This assumes you already have the Arduino development environment installed for the Matrix Portal M4 or MatrixPortal S3. If you’ve not done this before, these steps are described in the MatrixPortal M4 introductory guide or the MatrixPortal S3 guide.

Additionally, this requires that the Adafruit_Protomatter and AnimatedGIF Arduino libraries be installed. This process is also explained in the guide linked above, or in the Adafruit_Protomatter guide (opens in new window).

Once installed in the Arduino IDE, you can find the animated GIF player among the Protomatter library examples…

File→Examples→Adafruit Protomatter→animated_gif

You can also find the project source code on Github, but will still need the Protomatter library installed.

Changing the GIF folder and playback time

Near the top of the code, starting around line 26, you’ll see these two lines:

char GIFpath[] = "/gifs";     // Absolute path to GIFs on CIRCUITPY drive
uint16_t GIFminimumTime = 10; // Min. repeat time (seconds) until next GIF

char GIFpath[] = "/gifs";     // Absolute path to GIFs on CIRCUITPY drive
uint16_t GIFminimumTime = 10; // Min. repeat time (seconds) until next GIF

The first of these is the folder name containing the GIF images to play. By default this is gifs, but you can change that here if you like.

Second line tells how long to repeat each GIF. This is a minimum time, in seconds. With the default value of 10 here, a short 1-second GIF would be repeated 10 times before advancing to the next image…while a long 10+ second GIF will play only once. GIF playback is not truncated to this time, they will always play back in their entirety at least once.

Using different matrix sizes

The next couple of lines define the matrix dimensions…

#define WIDTH  64 // Matrix width in pixels
#define HEIGHT 32 // Matrix height in pixels
// Maximim matrix height is 32px on most boards, 64 on MatrixPortal if the
// 'E' jumper is set.

#define WIDTH  64 // Matrix width in pixels
#define HEIGHT 32 // Matrix height in pixels
// Maximim matrix height is 32px on most boards, 64 on MatrixPortal if the
// 'E' jumper is set.

NOTE: 64x64 matrices require soldering between two pads on the MatrixPortal board. This is explained in the MatrixPortal guide (see “Address E Line Jumper” at the bottom). Other matrix sizes (64x32 and 32x16) are plug-and-play with just the code change.

Make sure you have the correct board type selected:

Tools→Board→Adafruit Matrix Portal M4

or!

Tools→Board→Adafruit MatrixPortal ESP32-S3

Compile and upload to the board, and it should work at the new size or new folder & time settings.

HELPFUL TIP: remember how you double-tap reset to install a .UF2 file onto the MatrixPortal board? This works both ways! Once you’ve got the code configured and running how you like, double-tap the reset button and copy the file CURRENT.UF2 off the board to your computer. Now it’s easy to reinstall your custom version any time. This file can be renamed something descriptive if you like, just keep the .UF2 at the end.