How to Set Up an AdaFruit PiTFT for the Raspberry Pi

How to set up an Adafruit PiTFT for the Raspberry PiMy PiTFT...finally working!

About 2 months ago I received my Adafruit PiTFT through the post, possibly the most excited I’ve ever been to see my postman. I also ordered the 4 tactile buttons to go with it, adding to my geeky buzz.

Foolishly I thought it would be a quick “Plug n’ Play” unit, expecting to get my console showing on the little 2.8″ screen in seconds. Not quite. I should have read the install guide before ordering!

You see, the PiTFT isn’t the easiest thing to get running. In fact, have a quick search on-line and you’ll see a mass of forum messages going back and forth trying to get certain parts working. Some can’t get their desktop to show up, some can’t get the buttons working, others struggle with the backlight control – and so on and so on. It’s a bit of a fiddly one to say the least!

After a few attempts and a lot of Googling, I’ve got mine working perfectly (update – “almost perfectly”) – so I’m here to show you exactly what I did, step by step, so that you don’t have to go through the same headache as me.

Start with a Fresh Raspbian Image

If you’ve been having trouble getting things working perfectly on your PiTFT, this is probably the most important part. I’m convinced that it’s best to start with a fresh image, but your experiences may differ.

One of my first attempts to get the PiTFT working, was on an existing Raspbian install – one I had run many projects on. I’m not sure why, but I couldn’t get the screen working on this – maybe I had done something to the settings somewhere. I had tried updating it first, but it still didn’t work.

Next, I tried the custom PiTFT image on the AdaFruit site. This would surely work, I told myself. Whilst it did get the screen running, I had problems with the backlight GPIO #252 being recognised. I couldn’t seem to fix this.

Eventually, I started with a clean image of Raspbian from the Raspberry Pi site. This, plus my other steps, worked for me – so if you can, do this first.

I’m not sure if it makes any difference, but with my fresh Raspbian image I took the following actions in the raspi-config screen:

  • Expanded filesystem
  • Enabled Camera
  • Enabled SSH
  • Enabled SPI

Despite it always being recommended, I didn’t update the raspi-config tool or the Pi itself.

Set Up the Pi-TFT

Here’s what I did to set the PiTFT up on my fresh Raspbian image. What you’re doing here is installing a new ‘kernel’ (nothing to do with grain). You need internet access to download the files you need, so sort out an Ethernet or WiFi connection first.

Download Kernel Files

Head to a Terminal session either on screen or using something like SSH, and enter the usual ‘cd’ command to make sure you’re in the main directory.

Then run these one by one, to download the Kernel files:






Install Kernel Files

Now that you’ve downloaded the files you need, run this command to install the kernel:

sudo dpkg -i -B *.deb

This might take a minute or two, be patient with it.

Turn Off Accelerated X Framebuffer

You’re following this guide, which means by now you should be using the latest image of Raspbian.

With recent versions of Raspbian you need to turn off the accelerated X framebuffer when using the PiTFT. To do this we move that file to your home directory, which means it has been removed but can still be put back later if needed. We use ‘mv’ to move files here – use the command below:

sudo mv /usr/share/X11/xorg.conf.d/99-fbturbo.conf ~

Now we need to reboot, so run the usual reboot command:

sudo reboot

You won’t see anything on screen yet, don’t panic.

Install the Screen Driver

Run the following commands to install the screen driver:

sudo modprobe spi-bcm2708
sudo modprobe fbtft_device name=adafruitts rotate=90
export FRAMEBUFFER=/dev/fb1

That last command will start ‘X’ on your PiTFT – now I didn’t know this before, but ‘X’ means the GUI…the desktop view for Raspbian. You learn something every day huh?

We’re not finished yet, so calm down, and press ‘Ctrl – C’ on your keyboard to go back to the Terminal view. If you’ve SSH’d in, you don’t have to do this as you will still have terminal view.

Setting the Modules to Auto-load

Open up the modules list with the following command:

sudo nano /etc/modules

Add these lines underneath the line already in there:


Once you’ve added them, hit ‘Ctrl + x’ to save (press ‘Y’ at the prompt to save the file with the same name).

Add Configuration Info to Modprobe

Open up the configuration file with this command:

sudo nano /etc/modprobe.d/adafruit.conf

Now just add this line:

options fbtft_device name=adafruitts rotate=90 frequency=32000000

Again, hit ‘Ctrl + x’ to save (press ‘Y’ at the prompt to save the file with the same name).

Starting the GUI (‘X’)

Most people will want to start the Raspberry Pi Desktop view regularly, but unfortunately the PiTFT requires a separate command before ‘startx’ (‘FRAMEBUFFER=/dev/fb1 startx’)

Luckily there’s a way around this. Open up your profile file:

sudo nano ~/.profile

…and add this line above the other non-# lines:

export FRAMEBUFFER=/dev/fb1

You can now just use ‘startx’ to start the desktop.

Attention to Detail

Don’t be fooled – you may think you’re done, but there’s a few things to tweak yet. For example, if you leave that PiTFT on for 30 minutes, the screen will go blank and you’ll be wondering what went wrong. Also, you don’t know which GPIO to use for those switches – and did I mention font size on the screen?

Let’s sort these things out now.

Screen Time-out

As I mentioned above, the default setting is for the screen to turn off after 30 minutes, and I couldn’t find a way to bring it back over SSH – very annoying. Use the following command to open the settings file:

sudo nano /etc/kbd/config

Then set ‘BLANK_TIME’ to ‘0’ to stop the screen from timing out.

I also set POWERDOWN_TIME to ‘0’ as it seemed like a good idea as the description made it seem like it shut down ‘something’ after 60 minutes (30+30). You may not need to do this, but I did. (UPDATE – try #’ing that POWERDOWN line out if you still experience time-outs)

Starting Terminal on Boot

If you want to go straight to the terminal (my preference), follow these steps…

First, tell the Pi to use the TFT Framebuffer instead of the HDMI one. Open up the cmdline file:

sudo nano /boot/cmdline.txt

There will already be a long line of text in this file – we’re going to change it. Near the end of the text you’ll find ‘rootwait’ – directly after this enter the following text:

fbcon=map:10 fbcon=font:VGA8x8

Exit and save the usual way, and you’re done.

Font Size

The last step will get Terminal running on boot, but one of the many guides I used suggested changing the text size by doing the following…

Run the following command to get into console setup – it’s a pretty blue screen:

sudo dpkg-reconfigure console-setup
  • On the first screen select the appropriate encoding (UK should be UTF-8)
  • At the next screen select ‘choose optimal character set’
  • Next select ‘Terminus’ as the font
  • Then select ‘6×12 framebuffer only’

Have a play if you don’t like that font, there are a load to choose from.

GPIO Buttons

The PiTFT comes with some built in options for button control (backlight and shut down), but I never really understood why as it’s easy to start your own Python script on boot to control whatever you want – much more fun!

From left to right (buttons on the PiTFT), the GPIO numbering (GPIO.BCM) is as follows:

23 | 22 | 27 | 18

The GPIO pins feeding these buttons are set high by default, so to trigger them you have to tell your script to look for ‘FALSE’…let me show you my script – copy it, tweak it, freak it – go for it! I’d love to hear what you’ve done with your PiTFT buttons.

 import RPi.GPIO as GPIO  
 import time    
 import os  
 #Set GPIO mode  
 #Setup GPIO  
 GPIO.setup(23, GPIO.IN, pull_up_down=GPIO.PUD_UP)  
 GPIO.setup(22, GPIO.IN, pull_up_down=GPIO.PUD_UP)  
 GPIO.setup(27, GPIO.IN, pull_up_down=GPIO.PUD_UP)  
 GPIO.setup(18, GPIO.IN, pull_up_down=GPIO.PUD_UP)  
 #Set up backlight GPIO  
 os.system("sudo sh -c 'echo 252 > /sys/class/gpio/export'")  
 #Give the system a quick break  
 #Set the intitial counter value to zero  
 counter = 0  
 #var for the 'while' statement to keep it running  
 var = 1  
 #Main program  
 while var == 1:  
  if (GPIO.input(23) == False): #Backlight control
   if (counter == 0):  
    os.system("sudo sh -c 'echo 'out' > /sys/class/gpio/gpio252/direction'")  
    counter = 1  
    print("counter now 1")  
   elif (counter == 1) or (counter == 3):  
    os.system("sudo sh -c 'echo '1' > /sys/class/gpio/gpio252/value'")  
    counter = 2  
    print("counter now 2")  
   elif (counter == 2):  
    os.system("sudo sh -c 'echo '0' > /sys/class/gpio/gpio252/value'")  
    counter = 3  
    print("counter now 3")  
  if (GPIO.input(22) == False):  
   print("22 Working")  
  if (GPIO.input(27) == False):  
   print("27 working")  
  if (GPIO.input(18) == False): #Shutdown button  
   os.system("sudo halt")  


I used a few different guides to finally get my PiTFT working. I’m not confident that one single guide has the correct way of doing things, but here they are anyway – they contain extra information such as calibrating your touchscreen and more:

Adafruit Guide – Guide –

As always, if you need any help just comment below.

Until next time…

31 Comments on "How to Set Up an AdaFruit PiTFT for the Raspberry Pi"

  1. Ive followed your instructions up to the first reboot then I find myself very stuck. The HDMI port does not display unless I plug it in after I power up my Pi B+. Furthermore the USB ports no longer seem to work, thus I cannot use the keyboard to log in. Any thoughts?

    • Hi. I read a while back that Adafruit released an updated image to ensure that it worked with the B+ Raspberry Pi. Although the original image wasn’t that great, it might be worth downloading their latest image and giving that a try?

  2. For some reason I am unable to add this line :
    export FRAMEBUFFER=/dev/fb1
    lxterminal says ~/.profile does not exist.

    I'm a complete noob and cannot seem to fix this in lxterminal. Where should I be looking for this file? I found a .profile in home/pi but changes do not seem to do what is expected.

    Any advice?

    • I haven’t come across this before, and haven’t played with profiles before, so your best bet is to try the Raspberry Pi forums. There will definitely be people there that know about this.

  3. I'll have to try that. Either way, thank you so much for the tutorial you did provide. Thanks to you, I can at least use the piTFT, and that's a lot better than the alternative.

  4. About my previous comments and experience. First of all I am using a PiTFT image for a device that is similar but not the same as the one I purchased. The image can be found here: **LINK DEAD**

    There appear to be issues with localization in this particular build of Wheezy. Raspi-config does not change the keyboard settings as implied. You must edit the keyboard preference manually.

    Some of the steps included in this tutorial are no longer necessary. The accelerated framebuffer file has been removed, so all instructions pointing to it will not work. Likewise, /etc/modules already exists as you have instructed us to change them.

    Again, I do not know which image (or revision) is being referred to in the article, but it seems likely that a few things have been changed since this was written.

    • Thanks for sharing your experience Daniel. It has been a while since I wrote this, and I know they changed some stuff when the B+ came out.

      I’ll have to run through this again myself to see what happens 🙂

  5. Very useful post thanks. I used the Adafruit image for my Pitft which worked OK but then, what to do with it? I can display the GUI desktop on it but only a small section. I cannot 'move' this small window around the display to see the remainder of the desktop. Have you any experience of this and how to overcome it?

    • Hi Barry

      I too found the screen a little ‘awkward’. I haven’t played with it for a while, but when I do, it’s mostly for ‘novelty’ use of the Terminal.

      An ideal use is with ‘tkinter’ to make a GUI interface for a project – be it an internet radio, temperature monitor, data display or something else.

      Tkinter is good for this, and it’s something I want to cover soon.

  6. Richard I just tried your method for installing the Pitft but when tried to download the kernel I get a 403 Error 'Forbidden'. I admit I was trying to over write the original Pitft image I installed but that shouldn't cause this problem, should it?

    • My advice is to try a fresh image rather than trying to do it manually with the kernels – I always struggled when trying to make the screen work the ‘manual’ way.

      It’s a shame really as some people won’t want to lose their image settings etc.

      Now I’m no expert as the name of this blog suggests (!), so there may be a better way of doing it, however people I have spoken to have always said the same thing.

  7. Hi, I'm having a similar issue. When I get to the first shutdown, nothing shows up out of the HDMI port at all, no matter what. I am also using the updated images. Any ideas?

  8. Luciana Ohira | 13/07/2015 at 17:41 | Reply

    Hey! We are having the same problem as Justin and Quetin, after the first reboot our USB ports aren´t working anymore… So, we can´t use a mouse neither a keyboard! We are algo using updates images!
    We will reinstall Raspbian! Ideas?

    • That’s really odd because I just re-installed my PiTFT on a Model B the other day, using the image from Adafruit (it has been updated and works very well now).

      Rather than trying it manually as I have suggested, try their new image. If that doesn’t work, try their forums as it’s working fine for me.

      If you’re using a B+ or Pi 2…maybe something has changed?

  9. I got as far as the desktop, but it is larger than the screen size so when I open programs they are off the screen. Is this the normal view or is there a way to adjust the desktop to fit the screen size?

    • A lot of people have this issue, and I’m not convinced there is a way around it. The resolution isn’t great, and I don’t think there’s any way of changing Raspbian to adjust.

      The desktop view is a bit of a novelty – I prefer to use mine with the command line, or for a project using a GUI like PyGame.

  10. Bruce Nulty | 21/07/2015 at 01:52 | Reply

    Thanks for your touch screen set up notes. I finally got my PiTFT working yesterday on my Internet Radio Pi. My on/off button 23 works using the Adafruit programming and I want another button to “go to the next file”. e.g. I have a VLC playlist on my Desktop. One touch on it boots VLC and the first station plays. VLC has a menu item Playback with Next and Previous entries which move to the next (or previous) item on the playlist but I do not know how to program these using button 22 (say). I would appreciate any help you can give me.

    • Hi Bruce. Do you mean the other buttons on the PiTFT? They should just simply be GPIO on/off (high/low) commands – they’re all wired up ready to go, just check which GPIO they are via Adafruit’s site.

      If you mean how to code the button, I always seem to use os.system(“terminal command here”) – which lets you run any terminal command in a script – such as “mpc play”, which I used in my internet radio project.

      So something that kind of says “if GPIO X is high, os.system….etc…”.

      Make sense?

  11. Rasp Pi 2 with 2.8″ resis screen.
    trying to download the bootloader 112613 but keep on getting “forbidden” message, any help please

    • Hi Chris. Like with most of the questions I get, I would recommend trying the Raspberry Pi forums. I’m not sure exactly what you’re trying there, but I haven’t tried any of the Adafruit screens with the new Pi 2 – so the forums are your best bet.

      Sorry i can’t be much more help – I can only really give you advice on things i have tried.

  12. Justin Townsend | 08/01/2016 at 11:10 | Reply

    Any idea how to fine tune the X/Y sensitivity on the screen? I got my PCB working following your tutorial (many thanks!) but seems the x/y is possibly flipped and needs to be tuned as well….I am sure there is a way to mod this, but not sure how to do so.

  13. Marina H. | 25/01/2016 at 17:23 | Reply

    Hello! I’m wondering, have you experienced any issues in terms of shutdown/poweroff with the PiTFT? I am attempting to run variations of the “sudo shutdown -h now” command and it seems to restart after shutdown every time. Would you know what could be causing this issue?

    • Hi Marina. I don’t use that ‘-h now’command myself so it’s difficult to comment, does the standard ‘sudo halt’ work for you?

    • It could be caused by a program hanging, or the system just halting instead of powering off.
      Instead of the -h flag, try using -P instead.
      Alternatively try sudo poweroff instead.
      That is the command that is called by sudo shutdown -P now.
      sudo poweroff will close down the system properly then power off without restarting.
      sudo poweroff always works like a charm for me. 🙂

  14. I have a working Pitft using the Adafruit image. But I’d like my Pi to boot to the command line rather than X. Can you advise which files need editing. Many thanks

  15. I used the 3 step easy install from the instruction file for this exact 2.8″ touchscreen and the last step tells you to reboot the Pi, and I did that and it has not completely rebooted since. All it says is “Mounting/boot and File System Check on /dev/mmcblkop5..” etc….it’s been like that for days. I can’t do anything on my pi anymore, it’s like it’s stuck on reboot. I keep unplugging it to restart it then I end up stuck in boot again.

    • Try using the provided images instead – they now have Jessie (full) and Jessie Lite versions. I tried the full version yesterday and it worked fine.

  16. Hi, I’m a noob at this stuff but I’m able to do everything up until installing the kernel files. After I enter the dpkg command it goes through all the files but comes up with an error for each one saying they depend on the next file which is “not configured” so nothing gets installed. Any help? Man I am trying to get this touch screen up so many different ways and there is always some issue.

  17. How do you turn off accelerated x frame buffer in retropie as am not using Raspbian?

  18. How do you install new images with an SD card while having the OS hooked up? There’s one SD card slot, I have the OS image in there but don’t I need a whole other SD card to install different images? Basically how do I install an image for a screen or something while running the OS on an SD card?

Leave a comment

Your email address will not be published.


This website uses cookies. Please visit our privacy policy page for more information. Privacy policy

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.