Who hasn't wanted their own animated GIFs to play in a private desk museum? The future is now! Build this desktop Raspberry Pi picture frame to display animated GIFs in a slideshow on a color 2.8" TFT, in Chromium kiosk mode.

Start with a Pi Model B or Pi Model B+ and an Adafruit 2.8" PiTFT. With a liberal use of a dremel (or diagonal cutters) and a touch of overclocking, you too can achieve your dreams of collecting GIFs and entertaining yourself to no end. Find inspiration. Use Sugru.

There is a very minimal amount of code involved with this project. It would be difficult to actually do less adjustment to a Raspberry Pi, and not see as dramatic of results.

I believe in you.

For this project, you will need:

Lady Ada has masterfully covered the assembly of the PiTFT Display before, so click the link below to go to see how. Both capacitive, and resistive displays are assembled in the same way. Capacitive also has the option of adding PWM backlighting control through a solder bridge, but this GIF tutorial will not implement that.

Chances are you already have the PiTFT 2.8" resistive pre-assembled but in case you have a older one or a capacitive one or whatever, it's good to know!

Note: You DO need to add the tactile switches, so make sure to follow that step.

Note: You DO NOT need to add the cobbler portion, so you can just skip that step.

Adafruit has some great easy install images for both the resistive and capacitive touch displays. For this project, I find it's useful to see a little of what's going on under the hood, so I've opted to use the downloaded files from terminal.

Get Raspbian

To install Raspbian, first format your SD card using the SD Card Formatter.

Make sure not to accidentally format any other USB Drivers or cards you might have installed.

Next, download the most recent distro of NOOBS. You want to download the "Offline and network install" version.

 Once downloaded, uncompress the file. Then drag the contents of that file directly onto your recently formatted SD card.

Before powering up your B+, attach your HDMI monitor, keyboard, mouse, and ethernet cable.

Plug in your microSD card into the B+, and power it up. Follow the onscreen prompts to install Raspbian.

Important Commands

LXDE (or, X) is the GUI for Raspbian. Otherwise, you're in Terminal.

Unless you tell the RasPi to boot into X on start up, you will boot into Terminal. However, anything you can do in X, you can manipulate quickly in Terminal. SO MUCH POWER. Settle yourself. POWER. Relax.

Assuming you've never worked with either, there are some important Terminal things to remember.

The default username is: pi

The default password is: raspberry

While you type the password, you won't see any keystrokes.

To start up X, type:

To reboot the Pi, type:

sudo reboot

The RasPi does not have a built-in power switch, so to kill the power, you have to unplug the USB connection. Before doing that, you need to issue a shutdown command:

sudo halt -p

The Pi will then enter shutdown procedures, and tell you when it's time to power it off, with the phrase:

Power down

To edit a file on the pi, you type:

sudo nano /thisIsTheDirectory/thisIsTheTextFile/

After you've installed the PiTFT screen, only one display will be available to use by the framebuffer at any given time (the driver of the display for the RasPi.)

To switch between them, type:


Until you are ready to test the GIFs, I recommend sticking with the HDMI. The larger screen real estate is needed to finish all of your Terminal commands.

To open the original configuration screen for the Raspberry Pi, type:

sudo raspi-config

Update Everything

Now that you're sitting in Terminal, or sitting on the desktop of X, you'll want to get going on the road of installation. First, we want to update and upgrade all the built-in software just installed from NOOBS. You will need that ethernet connection to be active.

If in X, open the application on the Desktop labeled, LXTerminal. You are now running Terminal inside X.

To update all of the software, type:

sudo apt-get update

Follow the on-screen prompts. Revel in your new importance.

Once that concludes, it's time to upgrade the packages, so type:

sudo apt-get upgrade

Follow the on-screen prompts. This one may take a while.

Install Chromium

The GIFs for this project will play inside out of Chromium, in X.

A great thing about Linux (Raspbian) is the ability to install programs directly from Terminal.

Just type:

sudo apt-get install chromium

And follow the on-screen prompts.

Change the Video Memory Allocation

The default video memory allocation for the B+ is only 64 MB. We want to assign more, for the GIFs.


sudo nano /boot/config.txt

You're looking for a line that should say either, 




Or it's possible the line isn't there whatsoever.

In any case, the line should either be modified, or added to say,


Then hit Control + O, follow the prompt to save by hitting Enter, and then Control + X to exit nano.

Turn Off Screen Blanking:

There is a persistent power-saving feature on the Raspberry Pi that is duplicated in many places. To disable it, you'll need to turn it off in different ways.


sudo nano /etc/kbd/config





Then Control + O, follow the prompt to save by hitting Enter, Control +X, and you've finished the first adjustment.


sudo nano /etc/X11/xinit/xinitrc

After the first line, type in these three lines:

xset s off
xset -dpms
xset s noblank

Then Control + O, Enter, and Control + X.


sudo nano /etc/lightdm/lightdm.conf

Under the SeatDefaults section, you want to modify it to be:

xserver-command=X -s 0 -dpms

Then Control + O, Enter, and Control + X.

Fourth: Noticing a pattern yet?

sudo nano /etc/xdg/lxsession/LXDE/autostart

We'll be back here, but for now let's just get rid of the screen saver and double up the xset commands.

Find the line:

@xscreensaver -no-splash

and comment it out, by adding a #

# @xscreensaver -no-splash

Next add three additional lines directly below the now commented line:

@xset s off
@xset -dpms
@xset s noblank

Then Control + O, Enter, and Control + X.

Overclock the Raspberry Pi:

Overclocking the B+ doesn't void the warranty. To bump it up from 700 Mhz to 800 Mhz, type:

sudo raspi-config

You'll recognize this screen from the first time you booted up Raspbian. Use the navigation arrows to scroll down, hit the right arrow once you've highlighted Overclocking, and then hit enter.

On the next screen, select 800 Mhz, hit the right arrow, and hit enter. More juice!

The GIFs (of your choosing) will be playing inside an auto-start kiosk of Chromium. This project doesn't rely on Internet connectivity, and instead launches all of the clips locally. This gives you the ability to curate, without relying on streams, and also more flexibility in using the device.

Some WiFi networks aren't always obliging for an unmonitored Linux machine to idly hang out 24/7.

Get the GIF folder from Github

The GIF folder has three types of files in it:

  1. GIFs
  2. A .js reference file
  3. the HTML file that will handle the slideshow

I found it easiest to work on this folder on my PC, and then transfer it once done to the RasPi with a USB stick. It needs to eventually sit in the Desktop folder for the autolaunch code to work in the RasPi.


The GIFs can be any size you want, as the code in the HTML will do some resizing to fit the display. I don't recommend file sizes larger than 2 MB, unless the file is very efficiently compiled.

Framerates will have a magnified effect here. Not all GIFs are created equally. You'll have to just try them out to see what works.

The HTML file is manually encoded to launch the files by name, so each file will need to be named sequentially to match the HTML.

1.gif, 2.gif, 3.gif, 4.gif...101.gif

There isn't an array launching them, so you don't need to worry about digit counts.

.JS File

This is the easiest step. Just download it here, and put it into the folder. It's a reference file for the HTML, so it doesn't need to ping a website.

HTML of Wonder

The whole project hinges on this file. It was artfully crafted by Ryan Sumner for this project, and I'm posting it here with his permission.

The file itself has been set to include 3 .gif files, set to an approximation of 280 px wide to accomodate most .gif files, and on a timer of 9.5 seconds before transition. In my experimentation, that covered almost all .GIF files I wanted to include.

Make your edits as you so desire, following the established layout, and resave as a .html file.

Once you've got the file how you want it, save it to the folder containing the GIFs and the .JS file.

Test the file project by right clicking on the HTML file, and opening it with your browser of choice. You should see your GIFs, in small size.

Pi Migration

Move your entire "GIF" Folder to a USB stick, and boot up your Raspberry Pi. If you aren't automatically booting to X, in terminal, type:

Insert the USB stick into your Raspberry Pi, and drag the GIF folder to your desktop.

Click into the folder, and similarly right click on the .HTML file to open it within Chromium. If this test works, it's time to install the display.

Now that the steps requiring a large monitor are done, we can install the PiTFT without having to fuss with switching back and forth between monitors.

With the Raspberry Pi powered down, plug in the PiTFT display into the Raspberry Pi using the GPIO pins. The B+ has more pins that the PiTFT, so you want to make sure they're aligned properly with 1 on the GPIO lining up with 1 on the PiTFT. It doesn't require much force, just a little pressure.

Power up the RasPi. Once in Terminal, we need to get the software for the PiTFT - visit the matching PiTFT page to add support:

This process requires some time. At the end, you'll be asked whether or not you want to see the console on the PiTFT. I personally like this, because it is interesting to see the boot cycle before the picture frame comes alive.

Setting Chromium to Auto-Launch

Now that the RasPi is ready to display on the PiTFT, Chromium needs to be set to auto-launch. To do this, type:

sudo nano /etc/xdg/lxsession/LXDE/autostart

Underneath the code you recently inserted to turn off screen blanking, add the line:

@chromium --kiosk file:/home/pi/Desktop/GIF/gif_player.html

Now everytime you reboot, the RasPi will attempt to launch Chromium at the start, and the gif_player.html file.

Control + O, Enter, and Control + X will take you back into Terminal.

More work to be done!

To exit Kiosk Mode in Chromium, just hit Control + F4. You do not need to exit Kiosk mode to shut down. You can just issue the shut down command with the bottom left tactile button on Pin 23.

 Boot to PiTFT

 It's time to tell the RasPi what display to use on start up when booting directly to X.

sudo nano /usr/share/X11/xorg.conf.d/99-pitft.conf

This will get you into the configuration file. If the text below already appears, don't worry about changing anything. This is just a way of double checking.

Section "Device"
 Identifier "Adafruit PiTFT"
 Driver "fbdev"
 Option "fbdev" "/dev/fb1"

Then hit Control + O, Enter, and then Control + X.

Lastly, we need to tell the RasPi to now boot to the Desktop instead of Terminal.

sudo raspi-config

This will open the RasPi Configuration page. Select Enable Boot to Desktop/Scratch, and then select Finish, and Reboot.

Your RasPi should now boot directly to the PiTFT, with slideshow running! (this can take around 30 seconds.) BUT HOORAY! If you selected to have text appear on the PiTFT, after a period of time text will cease appearing on the HDMI output, and begin appearing on the PiTFT.

Now it's time to make it look pretty by ruining a case, and then making the ruined case look pretty.

Cut at Your Own Risk

Mike Doell is an incredible designer. The PiTFT enclosure for the RasPi B is absolutely brilliant, and absolutely will not fit the B+.

This step is not required if you are using a Model B Raspberry Pi!

However, with liberal use of an appropriate cutting tool and patience, it will.

This plastic is very high quality, and does not want to be damaged in the way I describe below. Take your time, and do not use scissors or a knife/razor blade. You'll barely make a dent, and likely hurt yourself - and I am not responsible for you if you do.

There are two areas requiring cuts. The first is the top, to make room for the offset board, USB/HDMI ports, and headphone jack, and the second is the side, to make room for the microSD slot. The two posts also require filing down.

I recommend using a thin permanent marker to draw an outline for the cuts. If the lines are straight here, the finishing step will be much easier. Go slowly! I cannot repeat this enough. This plastic is very durable.

Using a flush cutter is actually easier than a Dremel. The speed of the Dremel tends to cause melting on the edges of the cuts, which then require sanding and trimming to clean.

I found it easier by slowly cutting away with the flush cutter, moving along the line. The plastic should not be warping from any twisting. Slow and steady wins.

Special consideration is required for the space around the USB jack and HDMI jack. The sideways-H shape outlined in the photo, separating the two cut-outs, is to keep the structural integrity of the case as high as possible. By leaving a small bridge, the case doesn't fall in on itself.

Once cut, attach the PiTFT to the facade of the case using the included screws and button covers. You'll need to remove the PiTFT from the GPIO pins of the B+ to accomplish this, and then reaffix the B+ to the now installed display.

Check your alignment. Plug in the USB and HDMI cables to ensure clearance, and then leave a little extra room for the Sugru finishing step.

Once everything is lined up, clean up the edges so they're smooth.

Using a Dremel or the flush cutters, file the posts down until they no longer interfere.

Sugru It

Sugru is wonderful. In this case, it will be used to cover some of the cutlines made during the modification. Once finished, it looks more much intentional, rather than accidental. If you're looking for a DIY-look, skip this step.

Before putting the Sugru on, remove the facade attached to the PiTFT and set it aside.

I use latex gloves when handling Sugru, because they recommend it. Also, the coloring can really get on your hands. It's sticky.

I managed to cover every portion of the cuts with only a single packet of the black, and had about 1/3 left over.

Tear off small portions, roll it into a ball until it's activated, and then into a small tube. I recommend trying to keep everything smooth from the beginning, so that it doesn't leave tiny splotches or jagged lines.

I used a cheap set of $2.00 clay molding tools to massage the Sugru into place, but plastic utencils would work as well.

I found the best method was to put a little bit on all the spots to make sure I kept it as thin as possible, and then work my way back around to keep it consistent. You want to finish this entire application within about a halfhour, so the Sugru stays pliable. Don't get up to take a break until you're finished.

Once it's all smooth and even, and any inadvertent coloring smudges have been rubbed off the plastic, leave the entire thing to sit for 24 hours to cure.

Affix the Switch

Because of the amount of material removed, and the different balance from the B+ in the B case, I needed a way to make the case more stable when standing up.

The JBTek switch I used was the perfect length, and permanently attaching it to the case kept the cable from having an tension on the USB port. Plus signs all around.

To do this, just apply a little bit of plastic-sticking glue of your choice. I used Krazy glue, and it worked like a dream.

Apply two small lines, staying closer to the middle so it doesn't creep to the edges and glue your project to the table.

Then, while the case is upright (being careful not to glue your project to the table), place and hold the switch against the base of the case for 45 seconds, to a minute. The glue will have a primary bond, and will be stable enough to allow it to dry.

Make sure your orientation is correct on the switch, so that you don't accidentally glue it with the micro-USB end pointing away from the USB port on the RasPi.

After 12 hours, it's done!

You've finished! Your RasPi is now ready to turn on, and boot!

Remember, it takes about 30 seconds to go from power up, to GIF-tastacy.

Alt + Left Click = Lifesaver

If you've never used a small screen with Linux, you may not know that you can click and drag a window around to navigate, even when you can't see the rest of the window on screen.

Some menus won't scale to the small size of the PiTFT, so in order to accommodate this  (for example: wanting to copy over the contents of the USB stick to update the GIF folder on the Desktop) just use Alt + Left Click, while clicking on the body of the window, to drag it around so you can resposition it to click through the prompts.

Otherwise, you won't know what you're agreeing to when it asks if you want to overwrite, or skip.

Thank You

A huge thanks to Ryan Sumner for providing the HTML that makes this slideshow happen. He went above and beyond a basic question, and provided an exact solution.

Also, a big thanks to Thorin Klosowski of Lifehacker for having the brilliant idea of using Kiosk mode in Chromium for animated GIF displays. Lifehacker article

This guide was first published on Jan 13, 2015. It was last updated on Mar 08, 2024.