Overview

This guide will show you how to add a microSD card to a Teensy 3 to play back animated GIFs on a RGB LED Matrix Panel.  The Teensy 3 runs an Arduino sketch that decodes the animated GIF and refreshes the display at a high frame rate with good color depth.  The SmartMatrix Shield makes it easy to connect everything together, with only minimal soldering required if you use a Teensy 3.5 or 3.6.

We will explain how to connect the parts together, how to compile the Arduino sketch that decodes the GIF animations, and go over options for creating your own GIFs.

Bare 32x32 6mm panel on the left, mounted in an 8"x8" shadow box frame with frosted acrylic diffuser on the right.

Major Components

RGB LED Matrix Panel

A multiplexed RGB LED Matrix Panel is an affordable way to add over a thousand bright pixels to your project. Compared to a Neopixel/DotStar matrix, these panels use smaller LEDs which are bright, but not blinding, and have a higher pixel density. Unlike a Neopixel/DotStar matrix, the panel requires a microcontroller to refresh the LEDs continuously to display an image. It takes about 40% of the CPU time and most of the memory of an Arduino Uno just to refresh a panel, and that's with a low refresh rate and a limited 12-bit color palette. To get a better image quality, we will use a more powerful microcontroller.

Teensy 3

Despite their small size, the Teensy 3 series dev boards pack a lot of horsepower as they use ARM Cortex M4 CPUs with plenty of RAM. The Teensy 3.2 runs at 72MHz and has 64kB RAM, while the Teensy 3.6 runs at 180 MHz, and has 256kB RAM. Even better, the processors in the Teensy 3 boards come with a DMA engine that can move data from memory to pins to allow refreshing the display in the background, so the main program can run without as many interruptions. The Teensy 3.2 has more than enough power and memory to drive a 32x32 display with a high refresh rate and full color palette while decoding GIFs, and the Teensy 3.6 can handle up to a 64x64 display. The Teensy 3 is programmable using a modified Arduino IDE, and uses many of the same libraries as normal Arduino boards, so it should be familiar to program for anyone that has written an Arduino sketch before.

Note that the Teensy 3.2 doesn't have an SD card reader built in. You can add one external to the SmartMatrix Shield, following the pinout listed here, but using a Teensy 3.5/3.6 is the recommended route, and what this guide will cover.

SmartMatrix Shield and Library

The SmartMatrix Shield is the best way to connect the Teensy 3 to the RGB LED Matrix Panel. The shield takes care of routing the 13 signals needed to refresh the display, adds convenient connectors for power, and brings the unused signals out to a convenient expansion header. The SmartMatrix Library includes code that refreshes the display in the background, and provides functions that make it easy to draw to the display and scroll text on top of the drawing.

Parts List for Guide

  • RGB LED Matrix Panel
    • Photos and video in this tutorial use Adafruit's 32x32 6mm pitch panel
    • Also supported are 16x32, 32x32, 64x32, and 64x64 panels in various pixel pitches available from Adafruit
    • You can chain several panels together to create a larger display, but that is out of the scope of this guide. Check out the SmartMatrix Library README file for more details. Keep the number of pixels for a Teensy 3.2 to 1024 or less, and Teensy 3.6 to 4096 or less
  • Teensy 3.2, Teensy 3.5, or Teensy 3.6 with headers soldered
  • SmartLED Shield V4
  • 5V 4A Switching Power Supply
  • MicroSD Reader to load files onto card

Assembling Teensy 3.2

If you're using the Teensy 3.5 or 3.6, you can skip this section

Parts and tools needed for assembling SD adapter for Teensy 3.2:

  • MicroSD Memory Card and SD to MicroSD Adapter
  • 6-conductor 3" Female/Female Jumper Wires
  • 15-pin right-angle male header
  • For assembly
  • Soldering Iron
  • Solder
  • Diagonal Cutters
  • Wire Strippers
  • Small Flathead Screwdriver
  • X-Acto or similar Knife
  • Recommended: Multimeter

Assembly (Teensy 3.5, 3.6)

Follow the instructions here to assemble your SmartLED Shield V4 with a Teensy 3.5 or 3.6:

SmartLED Shield V4 - Assembly

Follow the instructions here to assemble your SmartLED Shield V4 with a Teensy 3.5 or 3.6:

SmartLED Shield V4 - Assembly

Assembly (Teensy 3.2 only)

 SmartMatrix Shield

We'll start with an assembled SmartMatrix Shield.  For the pictures in this guide we used a SmartMatrix Shield with female connector to plug the Shield directly into the panel, the terminal block power option, and we added the diode and cut the Teensy VUSB trace to power the Teensy from the external power supply.  You can use the other assembly options listed in the SmartMatrix Shield assembly instructions if you prefer.

To make for a lower profile install, you might want to swap out the straight male pins for the expansion header with right angle pins if you have them, like we did in this guide.

Refer to the linked instructions to assemble your shield:

Note that the below instructions were written for SmartMatrix Shield V1, and that is the board used in the photos.  The pins names below will similar on all shields, but the pin positions on the board may be different depending on your shield.

SD reader

Because the Teensy 3.1 runs at 3.3V, it can be connected directly to a microSD card without any level translation or voltage converters required. You probably have some spare microSD to SD adapters that came with microSD cards. You could also use a microSD or SD breakout board if you prefer, just match the pinout of the board you purchase to the diagram.

You'll need a microSD to SD adapter card, 7-pin straight header pins, and a 3" six-conductor female-female jumper cable. You can use a longer cable if you need to for your build, but you may have to slow down the SPI signals if you have trouble reading the card through long wires.

Don't solder directly to an actual SD card! If you don't have a microSD card + adapter, pick up an SD card breakout of some sort!

Solder header to card

Melt a bit of solder to the first gold contact, skipping the recessed contact which isn't needed for this build.

Add the 7-pin header, and melt the solder to make a good bond between the gold contact and the pin.

Continue soldering at the other end of the card and repeat for the remaining pins.  There are two pads close together at this end.  Make sure you don't short the two together while soldering.

When you're done it should look like this. Inspect to make sure the solder is connecting each pin and contact.

Connect microSD adapter to SmartMatrix Shield

Connect the six-conductor cable to the pins, skipping one pin as shown in the photo.

To avoid tangles it's best to connect the microSD adapter to the SmartMatrix Shield expansion header with the adapter contacts facing up and starting from the 3V3/GND signals.  Then work your way left connecting the remaining wires along the expansion header.

When using right-angle pins for the expansion header, the labels get covered up.  Use this diagram to identify the pins.

Mounting

When you're done wiring, you can give the cable a slight twist and mount the microSD adapter to the plastic in the center of the display with some double stick tape.

Arduino Sketch

Installing Software Tools

Arduino IDE

You'll need Arduino version 1.6.5 or later installed.

Download Here

Teensyduino

To compile a sketch for the Teensy 3, you need an add-on for the Arduino IDE called Teensyduino. Download the latest version of Teensyduino for compatibility with the SmartMatrix Library.

Download Here

SmartMatrix Library

The latest version of the SmartMatrix is available on the project's GitHub Releases page. Download the latest SmartMatrix Library release and install it, using this guide as a reference if needed.

Download Here

Compiling

The AnimatedGIFs sketch is an example included with the SmartMatrix Library. It can be found under File, Examples, SmartMatrix, AnimatedGIFs

Note that if you used the Arduino Library Manager to install the SmartMatrix Library (instead of following the above instructions), the AnimatedGIFs example won't be included, as that sketch is included as a Git Submodule which is not supported by Arduino Library Manager. You will need to download the AnimatedGIFs example separately here

Under Tools, choose the settings you need for this Sketch:

  • Board: Teensy 3.2, 3.5, 3.6 depending on what you chose

  • CPU Speed: Choose the highest speed available without overclocking; decoding the GIFs is CPU intensive!  (Overclocked speeds may work too if you want to try them)

Edit the example sketch with the specifics of your SmartMatrix Shield, and LED matrix

Find the line with #include .  If you have a SmartLED Shield V4, make sure this line is uncommented (remove any // slashes before the #include).  If you are using a different shield, make sure the comments are there.

Find the section with this code:

#define SD_CS 15

//#define SD_CS BUILTIN_SDCARD

  • If you're using a Teensy 3.5/3.6, you want to uncomment the line with `BUILTIN_SDCARD`, and comment out the other line
  • If you're using a Teensy 3.2, or wired up your SD card externally, make sure `SD_CS ` is set to the pin you used for chip select - most likely pin 15.

Set kMatrixWidth, kMatrixHeight to the width and height of your display.

Set kPanelType according to the type of panel you are using. 

  • 16x32: kPanelType = SMARTMATRIX_HUB75_16ROW_MOD8SCAN
  • 32x32 or 64x32: kPanelType = SMARTMATRIX_HUB75_32ROW_MOD16SCAN
  • 64x64: kPanelType = SMARTMATRIX_HUB75_64ROW_MOD32SCAN

The Sketch is ready to compile and upload.  Connect the Teensy 3 via USB to your computer, plug in power to the SmartMatrix Shield, and press Upload.  When the Arduino IDE is done compiling, it calls a second program called Teensy Loader to do the uploading. You may need to press the button on your Teensy 3 to start the upload.

The sketch will run but display an error message as there is no SD card installed at this point. You can remove power from the SmartMatrix Shield while you load GIFs onto the microSD card.

Preparing GIFs

Most 32x32-64x64 pixel GIF should play using this sketch. If you find one that doesn't play, let us know by opening an Issue on GitHub with your GIF attached so we can troubleshoot.

We haven't actively looked for the longest GIF that will play using this sketch, but we did try a 15 MB 32x32 GIF that is long enough to break OSX's preview application, but plays on the Teensy 3.2 without problems.

So, where can you find GIFs to run on your display?

The library comes with a few samples, navigate to your Arduino sketch folder, then "libraries\SmartMatrix\Examples\AnimatedGIFs\gifs".

We have a collection of GIFs that we converted and other SmartMatrix users have shared here at the SmartMatrix Community.

Google image search can be filtered down to look for an exact size and type of image. This search query is looking for "GIF" with size 32x32 and type "Animated":

Google Image Search - 32x32 pixel Animated

There are online tools to take existing video or animated GIFs and resize and crop them down to the size you need.  Some of the sample animations were made using the crop and resize tools provided by ezgif.com.  Use "gifsicle" not "imagemagik" for the best results, and crop the animation to a large square (or rectangle matching your display's aspect ratio) before resizing down to 32x32 or the size you need.

There are many sources for GIF content online.  Here are a couple to get you started:

There are both free and commercial software and online tools to convert video to GIF.  A lot of the tools drop the frame rate when converting.  For best results use a tool that keeps a frame rate that matches your source video, usually 30 fps.

  • The "Video" demo was made using GIFBrewery on the Mac.

You can make your own GIFs using GIMP, Photoshop, or other image editing tools.

You can export a Processing sketch to a GIF using the gif-animation library.

This is the Processing Sketch that produced the "Pattern" demo in the video:

Github Gist - RingsGif.pde

We have another tutorial on Adafruit Learning System on how to create GIFs

If you make a cool animation you want to share online, please post it to the SmartMatrix Community forum, where community members have been building up a collection.

Loading GIFs onto MicroSD card

The card must be formatted in FAT16 or FAT32.  If you just bought the card, it should be ready to go.  The GIFs must use 8.3 format file names, with the name eight characters or shorter, and the extension ".gif".  

More details can be found in the Arduino SD Library notes.

After your card is formatted, create a new folder called "gifs" in the root of the card and copy your gifs there.

Playing GIFs

Here are some examples of GIFs playing on the display.  These GIFs are all included with the library.

It's hard to see subtle variations in color using just a bare display.  The display on the right has the light diffused using a specialty frosted acrylic made for lighting applications.  There are other options for diffusing the LEDs, and a piece of white copy paper in front of the LEDs can work in a pinch.

Troubleshooting

Nothing is displayed

  • Make sure the sketch uploads successfully to the Teensy 3
  • Check the soldering on the SmartMatrix Shield

 

"No SD card" message

  • Make sure the microSD card is inserted in the reader, and is formatted properly
  • Check your soldering on the Teensy headers, (plus expansion connector and SD card adapter if you used a Teensy 3.2)
    • Check the wires, make sure none are loose or connected to the wrong pins
  • Try another microSD card

 

"No gifs directory" message

  • Make sure there is a directory called "gifs" in the root of the microSD card
  • Make sure the card is formatted properly

 

"Empty gifs directory" message

  • Make sure all files are named in 8.3 format, and are placed in the /gifs/directory on the microSD card

 

Other GIFs are playing, but my custom gif isn't playing

  • Check the name, make sure it is in 8.3 format
  • Try removing all other .gif files from the /gifs/ directory, leaving just the GIF you want to test
  • Make sure the size is exactly 32x32 pixels (or the size you set for your display)
  • Make sure the file plays on a computer. You can open the GIF with a web browser if you don't have any other programs to play it back.
  • If your file plays on the computer but not on the display, please let us know by opening an Issue on GitHub with your GIF attached so we can troubleshoot.

Next Steps

AnimatedGIFs is meant to be a basic GIF player.  The sketch is short, and should be easy to understand and modify to make your own custom display.  Here are some ideas of what to do next:

  • Try scrolling text on top of a GIF to make a marquee display or clock with animated background.
    • Run the SmartMatrix FeatureDemo Example Sketch to see what the display is capable of, and get code to copy into your Sketch.
  • Connect up more stuff.
    • There are still pins left over on the expansion header after connecting up the SD card. There are pins free to connect up peripherals via I2C, UART, ADC or GPIO.
  • Make and Share GIFs
    • If you make a cool animation you want to share online, please post it to the SmartMatrix Community forum, where community members have been building up a collection

 

Acknowledgements

Craig Lindley - Original author of the AnimatedGIFs sketch, and is the first person to write a GIF decoder running on a Teensy, which months later still impresses me.

Micah Elizabeth Scott - Author of the awesome Fadecandy project, which has beautiful example patterns written for Processing. The "Pattern" demo for this guide came from a Fadecandy example.

Discord Games - The Pixel Art used in the demo is used with permission from Discord Games, Inc., makers of Chasm

Blender Foundation - The animated video used in the demo is (c) copyright 2008, Blender Foundation

 

Guide written by Louis Beaudoin (Pixelmatix.com)  CC-BY-SA

This guide was first published on Oct 16, 2014. It was last updated on Oct 16, 2014.