Do you love Raspberry Pis, animated GIFs, and the Internet of Things? If so, this project is for you. We will show you how to easily turn your Raspberry Pi into a animated GIF display device that you can update from anywhere!

This guide requires your Raspberry Pi to be connected to Adafruit IO over the internet. If you are looking for a standalone GIF display, check out this great animated GIF picture frame guide!

Let's get started by setting up our new GIF feed on Adafruit IO!

Retreiving your Adafruit IO Key

You will need your Adafruit IO key to connect your Raspberry Pi to Adafruit IO. To get your key, log in to Adafruit IO and click the AIO KEY button on the right hand side of the window.

A window will pop up with your Adafruit IO. Keep a copy of this in a safe place. We'll need it later.

Creating a New Dashboard & Feed

For this project, we will be creating a new dashboard and feed. First will need to navigate to the dashboards section of Adafruit IO.

Once you have navigated to the dashboard section, click the New Dashboard button on the top right of the window. Give your dashboard a name. In this example, we will be using Pi GIF as the dashboard name.

You will be redirected to your new dashboard after creating it. You will now need to add a text block to your dashboard. To do that, click the New Block button on the top right of the window.

A menu with block options will pop up, and you will need to select the Create New Text (HELLO WORLD!) option at the bottom right of the list of buttons.

You will then be presented with the configuration options for the text block. First you will need to create a new feed. Enter PiGIF the Create New Feed text box at the bottom of the second column and click CREATE NEW FEED.

After creating the new feed, click on the name of that feed in the Select Data section of the second column.

Enter the URL of your favorite Animated GIF in the third column under Block Text, and click CREATE BLOCK.

You can then click the EDIT button on the left hand side of the dashboard and resize the text block so you can see the entire URL. Click DONE EDITING when you are finished.

Next we will go through the software you will need to install on your Raspberry Pi.

Now that you have the Adafruit IO key and feed that you will be using, the next step will be to install the required software on your Raspberry Pi from the command line. If you need help getting started with the basics of using the command line, check out Brennen's great series of guides.

If you are using a PiTFT as a display, you can refer to the appropriate PiTFT install guide to get your PiTFT up and running.

Adding the Repository

The first step will be to add the Raspbian package repository to your Raspberry Pi if you haven't added it yet. You can do that by running the following command on your Pi.

curl -sLS | sudo bash

The repo will be added, and you will see output similar to the scrolling text seen below.

Installing the adafruit-io-gif Package

You are now ready to install the adafruit-io-gif package. Run the following command to install the package.

sudo apt-get install adafruit-io-gif

You will be asked for your Adafruit IO key and feed name. Enter those values exactly as they appear on Adafruit IO. You will be able to change the values later if necessary, but it's easier to setup if you carefully enter them correctly the first time.

After the install has completed, run sudo reboot to restart your Pi. This is necessary to make sure the changes to GPU memory take effect.

sudo reboot

Now that you have the required software installed, you can start the server so it will listen to your Adafruit IO feed for new GIF URLs. Run the following command to start the server.

aio_gif start

If everything works as expected, your display will be filled with the animated GIF you set during the Adafruit IO setup.


If your GIF didn't display, but a GIF of ladyada did, we know that there must be a configuration problem with the AIO setup. Make sure you have the correct values in /etc/adafruit-io-gif/server.conf. To view and edit the values, run the following command.

sudo nano /etc/adafruit-io-gif/server.conf

Confirm that the feed and key values match up exactly as you see them on Adafruit IO. The HTTP_PORT and DISPLAY values are for the local setup. Close and save the file when you are finished editing. If the AIO key and feed values are correct, then you should try to enter a new GIF URL in the text block on Adafruit IO. The server only accepts URLs that end in gif, png or jpg.

If you didn't see an image at all when starting the server, then you might need to edit the DISPLAY variable in /etc/adafruit-io-gif/server.conf to point to the address of the X display you wish to use. If you have another service using port 8080, then you might also have to change the HTTP_PORT to another value like 8888.

Now that your display is up and running, you can push new GIF URLs to your Pi from any web connected browser using the text block on Adafruit IO. Click on the text to change it, type or paste in the new URL, and press Return or Enter to send the new value.

Your Raspberry Pi should now display the new image. If not, you may have entered the URL improperly. Keep in mind the server will only accept URLs that end in a .gif, .png, or .jpg extension.

Client Libraries

You can also push new URLs from any of the available Adafruit IO client libraries. Refer to the library documentation for more information about pushing values to a feed.

This guide was first published on Mar 14, 2015. It was last updated on Mar 14, 2015.