Is this not the cutest little display for the Raspberry Pi? It features a 2.8″ display with 320×240 16-bit color pixels and a resistive touch overlay. The plate uses the high speed SPI interface on the Pi and can use the mini display as a console, X window port, displaying images or video etc. Best of all it plugs right in on top!

Original PiTFT

The original version PID 1601 is designed to fit nicely onto the Pi Model A or B but also works perfectly fine with the Pi Zero, Pi 2, Pi 3 or Pi 1 Model A+ or B+ as long as you don’t mind the PCB overhangs the USB ports by 5mm

PiTFT Plus

The newer PiTFTs are updated to fit perfectly onto the Pi Zero, Pi 3, Pi 2 or Model A+, B+! (Any Pi with a 2×20 connector) Not for use with an old Pi 1 with 2×13 connector

This design uses the hardware SPI pins (SCK, MOSI, MISO, CE0, CE1) as well as GPIO #25 and #24. All other GPIO are unused. Since we had a tiny bit of space, there’s 4 spots for optional slim tactile switches wired to four GPIOs, that you can use if you want to make a basic user interface. For example, you can use one as a power on/off button.

We bring out GPIO #23, #22, #21, and #18 to the four switch locations!

Setting up the Touchscreen

Now that the screen is working nicely, we’ll take care of the touchscreen. There’s just a bit of calibration to do, but it isn’t hard at all.

Before we start, we’ll make a udev rule for the touchscreen. That’s because the eventX name of the device will change a lot and its annoying to figure out what its called depending on whether you have a keyboard or other mouse installed.

Run

sudo nano /etc/udev/rules.d/95-stmpe.rules

to create a new udev file and copy & paste the following line in:

Remove and re-install the touchscreen with

sudo rmmod stmpe_ts; sudo modprobe stmpe_ts

Then type ls -l /dev/input/touchscreen
It should point to eventX where X is some number, that number will be different on different setups since other keyboards/mice/USB devices will take up an event slot

There are some tools we can use to calibrate & debug the touchscreen. Install the “event test” and “touchscreen library” packages with

sudo apt-get install evtest tslib libts-bin

Running evtest

Now you can use some tools such as

sudo evtest /dev/input/touchscreen

which will let you see touchscreen events in real time, press on the touchscreen to see the reports.

AutoMagic Calibration Script

If you rotate the display you need to recalibrate the touchscreen to work with the new screen orientation. You can manually run the calibration processes in the next section, or you can re-run the installer script and select a new rotation:

Manual Calibration

If the “automagic” calibration technique isn’t working for you, or you have some other setup where you need to carefully calibrate you can do it ‘manually’

You will want to calibrate the screen once but shouldn’t have to do it more than that. We’ll begin by calibrating on the command line by running

sudo TSLIB_FBDEVICE=/dev/fb1 TSLIB_TSDEVICE=/dev/input/touchscreen ts_calibrate

follow the directions on the screen, touching each point. Using a stylus is suggested so you get a precise touch. Don’t use something metal, plastic only!

Next you can run

sudo TSLIB_FBDEVICE=/dev/fb1 TSLIB_TSDEVICE=/dev/input/touchscreen ts_test

which will let you draw-test the touch screen. Go back and re-calibrate if you feel the screen isn’t precise enough!

X Calibration

You can also calibrate the X input system but you have to use a different program called xtcal (xinput_calibrator no longer works)

You can do this if the calibration on the screen isn’t to your liking or any time you change the rotate=XX module settings for the screen. Since the screen and touch driver are completely separated, the touchscreen doesn’t auto-rotate

Download and compile it with the following:

You must be running PIXEL (the GUI) while calibrating.

Before you start the calibrator you will need to ‘reset’ the old calibration data so run

DISPLAY=:0.0 xinput set-prop "stmpe-ts" 'Coordinate Transformation Matrix' 1 0 0 0 1 0 0 0 1

Now you’ll have to run the calibrator while also running X. You can do this by opening up the terminal program and running the the xtcal command (which is challenging to do on such a small screen) OR you can do what we do which is create an SSH/Terminal shell and then run the calibrator from the same shell, which requires the following command:

DISPLAY=:0.0 xtcal/xtcal -geometry 640x480

Note that the geometry may vary!

If you are using a 2.4″/2.8″/3.2″ 320×240 display with landscape orientation, use 640×480. If you’re in portrait, use 480×640.

If you are using a 3.5″ display with landscape, use 720×480, portrait is 480×720

Follow the directions on screen

Run sudo nano /usr/share/X11/xorg.conf.d/20-calibration.conf and copy the 9 numbers into the TransformationMatrix option so it looks like:

or whatever you got, into there.

You will want to reboot your Pi to verify you’re done

Your touchscreen is now super calibrated, hurrah!

One fun thing you can do with the display is have it as your main console instead of the HDMI/TV output. Even though it is small, with a good font you can get 20 x 40 of text. For more details, check out https://github.com/notro/fbtft/wiki/Boot-console

First up, we’ll update the boot configuration file to use the TFT framebuffer /dev/fb1 instead of the HDMI/TV framebuffer /dev/fb0

sudo nano /boot/cmdline.txt

you can also edit it by putting the SD card into a computer and opening the same file.

At the end of the line, find the text that says rootwait and right after that, enter in:
fbcon=map:10 fbcon=font:VGA8x8 then save the file.

On the next boot, it will bring up the console.

Note that the kernel has to load up the display driver module before it can display anything on it so you won’t get the rainbow screen, a NooBs prompt, or a big chunk of the kernel details since the module is loaded fairly late in the boot process.

Turn off Console Blanking

You may notice the console goes black after 30 minutes, this is a sort of ‘power saving’ or ‘screensaver’ feature.

Raspbian Jessie

Add the following line to /etc/rc.local

sudo sh -c "TERM=linux setterm -blank 0 >/dev/tty0"

on the line before the final exit 0

Raspbian Wheezy

You can disable this by editing /etc/kbd/config and looking for

BLANK_TIME=30

and setting the blank time to 0 (which turns it off)

BLANK_TIME=0

Sometimes the PiTFT device tree and related kernel package don’t work across different OS releases, so we’ve experimented with an alternate approach that doesn’t rely on a custom kernel — it instead works in “user space.” So far it’s worked well regardless of the OS version being used!

There are tradeoffs. The code is still in a rough state with many features yet to be implemented, and also the performance is slightly less than the kernel approach. It’s typically adequate though, even for game emulation (RetroPie, etc.), so give it a try if you’ve had trouble with the “classic” approach.

This currently requires a bit of Linux-y knowledge, editing files and such…

Download, Test and Install

PiTFT displays use SPI to communicate, so make sure that’s enabled using the raspi-config utility:

Menu options move around from time to time…at the time of this writing, SPI is under “Interfacing Options.”

Then retrieve the software using wget…

And then a quick test…

The PiTFT should mirror the contents of the Raspberry Pi’s HDMI output at this point. Text and everything will be microscopic, but we’re just checking that the program runs. If not, confirm that the file /dev/spidev0.0 exists — this should happen when SPI is enabled. Double-check raspi-config and it never hurts to reboot.

Does it run? Good. Press control+c to kill the program, and we’ll set it up to run automatically on boot.

First, copy the tftcp executable to /usr/local/bin:

Then edit the file /etc/rc.local as root (you can substitute your editor of preference for nano):

Just above the final “exit 0” line, insert the following line:

The screen looks best if the HDMI resolution exactly matches the PiTFT resolution, so the final step is to configure the system for 320×240 video:

Append the following lines to the bottom of the file:

OPTIONAL: you can also use “640 480” in place of “320 240” above. This is exactly twice the PiTFT native resolution, and the tftcp utility will perform a smooth 2:1 filtering of the image. Any larger though and the image isn’t as sharp (and text becomes tiny, like when we first tested it).

Now reboot and the PiTFT should activate toward the end of the boot process.

Resistive Touchscreen Support

This is even more experimental than the tftcp utility…it only works with the resistive screen, and there’s no calibration support yet, but if you’d like to try it out…

First there’s some prerequisite software to install:

“cd” to the same directory where the software was downloaded earlier, and try it out…

Whether you’re in X11 or in text console mode (e.g. Raspbian Lite), the cursor should move in response to touch, which is emulating a mouse.

If that seems OK, press control+c to stop it and we’ll use the same steps to make it auto-run on boot:

Insert this line just above the “exit 0” at the end of the file:

reboot and both PiTFT and touch should be active now.

How To Play Videos

You can play many types of videos on the screen, using mplayer you don’t even need to run X and you can script the movies to play using Python. We’ll show you how to just play one video for now.
To demo, we’ll use an mp4 of Big Buck Bunny for 320 pixel wide screens. Below we show you how to create/resize videos, but to make it easy, just download our version with:

wget http://adafruit-download.s3.amazonaws.com/bigbuckbunny320p.mp4

If you don’t have mplayer yet, run

sudo apt-get update

sudo apt-get install mplayer

to install it. It may take a few minutes to complete

OK now you just have to run:

sudo SDL_VIDEODRIVER=fbcon SDL_FBDEV=/dev/fb1 mplayer -vo sdl -framedrop bigbuckbunny320p.mp4

If your video is not sized for 320 wide, you may need to add a -zoom after -framedrop so that it will resize – note that this is quite taxing for the Pi, so it may result in a choppy or mis-synced video!

Converting/Resizing Videos

It’s possible to play full length videos on the TFT plate, but since the screen is small and the Pi cant use hardware accelleration to play the videos its best to scale them down to 320×240 pixels. This will be easier for the Pi to play and also save you tons of storage space. For this demo, we’ll be using the famous Big Buck Bunny video, which is creative commons and also very funny!

You can download it from the link above, we’ll be using the 720p AVI version.

Python Backlight Control with Blinka

You can also use python to control the backlight using Python. With Blinka, you can use it to turn the backlight off or on or even use PWM to control the level of the backlight. Since Python is such a flexible language, you can add some effects such as fading the backlight in or fading it out. First make sure you have Blinka installed. For the Raspberry Pi, you can follow our CircuitPython on Linux and Raspberry Pi guide. To turn the backlight on, you can use this simple demo script:

To turn it off, you can use this script:

To use PWM and demonstrate the fading in and fading out effect, you can try running this script:

Since the PiTFT screen is fairly small, you may need to write custom UI programs. Pygame is the easiest way by far to do this.

Jeremy Blythe has an excellent tutorial here on getting started.

However, before you follow that link you’ll want to set up pygame for the best compatibility:

Install pip & pygame

Install Pip: sudo apt-get install python-pip

#!/bin/bash

# enable wheezy package sources
echo "deb http://legacy.raspbian.org/raspbian wheezy main
" > /etc/apt/sources.list.d/wheezy.list

# set stable as default package source (currently buster)
echo "APT::Default-release \"stable\";
" > /etc/apt/apt.conf.d/10defaultRelease

# set the priority for libsdl from wheezy higher then the buster package
echo "Package: libsdl1.2debian
Pin: release n=buster
Pin-Priority: -10
Package: libsdl1.2debian
Pin: release n=wheezy
Pin-Priority: 900
" > /etc/apt/preferences.d/libsdl

# install
apt-get update
apt-get -y --allow-downgrades install libsdl1.2debian/wheezy

run

sudo sh ./installsdl.sh

Using the Capacitive touch screen in PyGame

The 2.8″ Capacitive touch screen driver may not work by default in pygame, but this handy script shows how you can capture the device messages in python to create a UI

• https://github.com/nift4/pigame
  For examples:
  https://github.com/nift4/Raspberry-Pi-Testing

Extras!

Making it easier to click icons in X

If you want to double-click on icons to launch something in X you may find it annoying to get it to work right. In LXDE you can simply set it up so that you only need to single click instead of double.
From LXDE launch the file manager (sorry these pix are grayscale, still figuring out how to screenshot the framebuffer!)

Right-click on a touchscreen

Obviously if you have a touchscreen, it cannot tell what finger you are pressing with. This means that all ‘clicks’ are left clicks. But if you want a right-click, you can do it.

Just add the following lines into your InputClass of /etc/X11/xorg.conf.d/99-calibration.conf after the calibration section

Option "EmulateThirdButton" "1"
Option "EmulateThirdButtonTimeout" "750"
Option "EmulateThirdButtonMoveThreshold" "30"


So for example your file will look like:

Section "InputClass"
Identifier      "calibration"
MatchProduct    "stmpe-ts"
Option  "Calibration"   "3800 120 200 3900"
Option  "SwapAxes"      "1"
Option "EmulateThirdButton" "1"
Option "EmulateThirdButtonTimeout" "750"
Option "EmulateThirdButtonMoveThreshold" "30"
EndSection

This makes a right mouse click emulated when holding down the stylus for 750 ms.

(Thx adamaddin!)

Gesture Input

With the PiTFT touchscreen and xstroke you can enter text in applications by drawing simple character gestures on the screen! Check out the video below for a short demonstration and overview of gesture input with xstroke:

Temporarily unable to load embedded content:
https://www.youtube.com/watch?v=k8NW-1QFjBU

Installation

Unfortunately xstroke hasn’t been actively maintained for a few years so there isn’t a binary package you can directly install. However compiling the tool is straightforward and easy with the steps below. Credit for these installation steps goes to mwilliams03 at ozzmaker.com.

First install a few dependencies by opening a command window on the Pi and executing:

 Download File

 Copy Code

sudo apt-get -y install build-essential libxft-dev libxpm-dev libxtst-dev

Now download, compile, and install xstroke by executing:

 Download File

 Copy Code

cd ~
wget http://mirror.egtvedt.no/avr32linux.org/twiki/pub/Main/XStroke/xstroke-0.6.tar.gz
tar xfv xstroke-0.6.tar.gz
cd xstroke-0.6
./configure
sed -i '/^X_LIBS = / s/$/ -lXrender -lX11 -lXext -ldl/' Makefile
make
sudo make install

If the commands above execute successfully xstroke should be installed. If you see an error message, carefully check the dependencies above were installed and try again.

Once xstroke is installed you will want to add a couple menu shortcuts to start and stop xstroke. Execute the following commands to install these shortcuts:

 Download File

 Copy Code

wget https://github.com/adafruit/PiTFT_Extras/raw/master/xstroke.desktop
wget https://github.com/adafruit/PiTFT_Extras/raw/master/xstrokekill.desktop
sudo cp xstroke*.desktop /usr/share/applications/

Usage

To use xstroke I highly recommend using a plastic stylus instead of your finger. Also calibrate the touchscreen for X-Windows so you have the best control over the cursor possible.

Don’t use a ballpoint pen or sharp metal stylus as it could scratch or damage the touchscreen!

Start X-Windows on the PiTFT and open the LXDE menu by clicking the icon in the lower left corner. Scroll up to the Accessories menu at the top and notice the new XStroke and XStroke Kill commands.

Click the XStroke menu option to start xstroke. You should see a small pencil icon appear on the bottom right side of the screen. The pencil icon means xstroke is running, however by default it’s not yet looking for gesture input.

Open an application that takes text input, such as LXTerminal. To enable gesture input click the xstroke pencil icon. You should see the pencil turn green and the text ‘abc’ written over top of the icon. You might need to click the icon a few times to get the click to register in the right spot.

When xstroke is looking for gesture input you can drag the mouse cursor in a gesture anywhere on the screen to send specific key strokes. Here’s a picture of the possible gestures you can send:

(credit to Carl Worth for the image above)

To draw a gesture from the above image, press anywhere on the screen, start from the circle in the gesture, and follow the gesture pattern towards the arrow. As you draw a gesture you should see a blue line displayed that shows what you’ve drawn. Lift up the stylus when you get to the end of the gesture at the arrow. If xstroke recognizes the gesture it will send the appropriate key press to the active window. Try drawing a few characters from the image above to get the hang of writing gestures.

A few very useful gestures are backspace (which deletes a character), return/enter, and space. To draw a backspace gesture just draw a line going from the right side of the screen to the left side. The gesture for return/enter is a diagonal line from the top right to bottom left. Finally a space is a straight line from the left to the right.

Note that when xstroke is looking for gestures you might not be able to click or control the cursor as you normally would expect. To stop xstroke’s gesture recognition carefully press the xstroke pencil icon again until the ‘abc’ text disappears. I’ve found this process can be a little finicky as the icon is very small and any movement will be interpreted as a gesture. Use a light touch and try a few times to click the icon.

If you get stuck completely and can’t disable xstroke by clicking the icon, connect to the Raspberry Pi in a terminal/SSH connection and run ‘killall xstroke’ (without quotes) to force xstroke to quit. The normal way to stop xstroke is to navigate to the Accessories -> XStroke Kill command, but you might not be able to do that if xstroke is listening for gesture input.

Have fun using xstroke to control your Pi by writing gestures on the PiTFT screen!

Downloads

• The latest kernel fork that adds all the TFT, touchscreen, and other addons is here on github
• Datasheet for the ‘raw’ 2.8″ TFT display
• Original 2.8″ PiTFT EagleCAD PCB Files on GitHub
• PiTFT Plus 2.8″ EagleCAD PCB Files on GitHub
• PiTFT Plus 3.2″ EagleCAD PCB Files on GitHub
• Fritzing Files in the Adafruit Fritzing Library

2.8″ PiTFT Plus Schematic & Layout

For the Pi B+ & Pi 2 version (2×20 header)