My PiTFT used to work, now it doesn't!

Did you do an apt-get upgradeor rpi-update? This command will blow away our PiTFT kernel which means that you will no longer have PiTFT support, you will have to redo the easy-install steps to reinstall the kernel.

If you had already made a working PiTFT setup, you may be able to reinstall the Adafruit kernel like so:

sudo apt-get install raspberrypi-kernel=1.20161027-1

If it tells you that the latest version is already installed, try this instead:

sudo apt-get install --reinstall raspberrypi-kernel=1.20161027-1 can check here and substitute the most recent version you see in the =1.20161027-1 part.

I'm booting my Pi with the PiTFT and the HDMI output 'locks up' during boot!

It looks like the Pi is 'halting' or 'locking' up during boot but what is really happening is the console is switching from the HDMI output to the PiTFT output.

Check your PiTFT connections, particularly make sure you seated the PiTFT on the Pi properly, nothing is in the way, and the TFT flex connector is seated properly.

My PiTFT works for a bit and then I get a black screen with a short line of white pixels in one corner

Sounds like you tried to configure your Pi to 'boot straight to X', that is, start up the graphics interface on boot. This doesn't work by default because the Pi operating system is not expecting a PiTFT so it boots to the HDMI output. See below for how to set up your Pi to boot to X on the PiTFT

To 'fix' this, you can either connect an HDMI monitor, then in a terminal window run sudo raspi-config and configure the Pi to boot to the command line not X! If you do not have an HDMI monitor, you can also try a console cable

How can I force the Pi to bring up X on the HDMI/TV monitor?

There's two ways to do it. In older Pi installs, use the fb0 framebuffer when you want to display stuff on the HDMI/TV display, for example:
will use the HDMI/TV framebuffer for X windows instead of the PiTFT

On Jessie Pi installs, run
sudo nano /usr/share/X11/xorg.conf.d/99-fbdev.conf
to edit the configuration file and make sure it contains:

Section "Device"
  Identifier "display"
  Driver "fbdev"
  Option "fbdev" "/dev/fb0"

change the Option "fbdev" "/dev/fb0" line to Option "fbdev" "/dev/fb1" if you want the xdisplay on the PiTFT

I'm tring to run startx and I get FATAL: Module g2d_23 not found.

don't forget you have to remove the turbo file!
sudo mv /usr/share/X11/xorg.conf.d/99-fbturbo.conf ~

How come OMX-Player and Minecraft and other programs don't appear on the PiTFT display?

Some programs are graphics-optimized, particularly the video playback tools and some other programs like Minecraft. They write 'directly' to the HDMI output, and cannot write to the PiTFT so there is no way to directly make them work. However, you can have the output go to HDMI and then mirror the HDMI onto the PiTFT with fbcp. See this tutorial for more details

Why doesn't the tactile button on GPIO #21 work?

On some older PiTFTs we had one of the buttons labeled #21 - that's the original RasPi name for that pin. If you're using a V2 (chance is, you are!) that is now called #27.
All the PiTFT's we ship now have the button labeled #21 and #27

I want better performance and faster updates!

You can change the SPI frequency (overclock the display) by editing /boot/config.txt and changing the dtoverlay options line to:


Or whatever you like for speed, rotation, and frames-per-second. BUT, here's the thing, the Pi only supports a fixed number of SPI frequencies. So tweaking the number a little won't do anything. The kernel will round the number to the closest value. You will always get frequencies that are 250MHz divided by an even number. Here's the only SPI frequencies this kernel supports

  • 15,625,000 (a.k.a 16000000 = 16 MHz)
  • 17,857,142 (a.k.a. 18000000 = 18 MHz)
  • 20,833,333 (a.k.a 21000000 = 21 MHz)
  • 25,000,000 (= 25 MHz)
  • 31,250,000 (a.k.a 32000000 = 32MHz)
  • 41,666,666 (a.k.a 42000000 = 42MHz)
  • 62,500,000 (a.k.a 62000000 = 62MHz)

So if you put in 48000000 for the speed, you won't actually get 48MHz, you'll actually only get about 42MHz because it gets rounded down. We tested this display nicely with 32MHz and we suggest that. But you can put in 42MHz or even try 62MHz and it will update faster

You can tweak fps (frames per second) from 20 to 60 and frequency up to 62MHz for tradeoffs in performance and speed. Reboot after each edit to make sure the settings are loaded properly. There's a trade off that if you ask for higher FPS you're going to load the kernel more because it's trying to keep the display updated.

How can I take screenshots of the little screen?

How do I automatically boot to X windows on the PiTFT?

Once you have a PiTFT installation setup you can add a custom X windows configuration to use the PiTFT by default.  Then you can use the normal raspi-config boot to console/desktop options to control if the Pi boots to a console or desktop.  See the detailed instructions on this page of the guide for more information.

My screen isn't working/works erratically/looks funny

Check to make syre that the flat flex cable is fully seated in the connetor and the 'ears' are pushed in to secure it. See the picture for what it should look like:

On my first run of startx I get a window saying "GDBus Policy Kit1 Error: Failed Cannot determine user of subject"

This happens on the Raspberry Pi the first time you run startx, no matter what display. You can just re-start X and it wont appear again.

Can I get a right-click from the touch-screen?

I'm having difficulties with the STMPE resistive touch screen controller

My PiTFT's rotation/calibration isn't working in X11

X11 (the graphical system) has changed how it gets touchscreen input, so if you rotate the display and the calibration isn't being picked up:

Check /usr/share/X11/xorg.conf.d for a file called 10-evdev.conf 

If you don't see that file

  1. You need to sudo apt-get install xserver-xorg-input-evdev, and then...
  2. If you do have a 40-libinput.conf in that same directory, you must remove it even if/once evdev is installed, since it will override the 10-evdev.conf otherwise.

Thanks to cerebrate in the forums for the hint!

Last updated on 2018-02-15 at 05.17.47 PM Published on 2014-09-17 at 06.14.28 PM