Adafruit 2.
Guide Contents Guide Contents Overview Assembly Easy Install Install Raspbian on an SD Card Installer script 2 4 7 15 15 15 PiTFT Selection Rotation 16 17 Configuring what shows where 18 PiTFT as Text Console (best for Raspbian 'Lite') PiTFT as HDMI Mirror (Best for Raspbian Full/PIXEL) PiTFT as Raw Framebuffer Device 18 19 19 Unsupported Full Images 19 PiTFT 2.2" Images PiTFT 2.4"/2.8"/3.2" Resistive Images PiTFT 2.8" Capacitive PiTFT 3.
Converting/Resizing Videos Displaying Images Using FBCP Backlight Control PWM Backlight Control with GPIO 18 On / Off Using STMPE GPIO For older versions of PiTFT Kernel Extras! Making it easier to click icons in X Right-click on a touchscreen Gesture Input Installation Usage 49 49 PiTFT PyGame Tips Install pip & pygame Ensure you are running SDL 1.
Overview Is this not the cutest little display for the Raspberry Pi? It features a 2.4" display with 320x240 16-bit color pixels and a resistive touch overlay. The HAT 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! It's designed to fit nicely onto the Pi Model A+, B+ or Pi 2. © Adafruit Industries https://learn.adafruit.
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 5 spots for optional slim tactile switches wired to five 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 have a right-angle 26-pin connector off to the side.
Each order ships with an assembled HAT with 2.4" TFT display with resistive touchscreen and a 2x20 female socket header. Some light soldering is required to attach the header but it is easy work for anyone with a soldering iron & solder. Alternatively, you can use a stacking type header instead if you'd like to plug a 2x20 GPIO cable on top (http://adafru.
Assembly Before you start check that you have the parts you need: an assembled PiTFT 2.4" HAT with the 2.4" screen and 2 x 20 female header. Note that it is normal for the screen to be 'loose' - this is so its easier for you to solder the connector on! Check also on the back that the TFT is attached and that the flex connector is seated into the onboard FPC socket.
Plug the extra tall female header into the GPIO port on the Pi as shown. Make sure its seated nice and flat Place the PiTFT HAT on top so all the pins stick through the connector on the side. Gently flip the TFT so its off to the side and wont be in your way while you solder © Adafruit Industries https://learn.adafruit.
Heat up your soldering iron, and grab some solder. Start by tack-soldering one of the corners. Then you can reheat that solder point and adjust the circuit board to make it sit flat. © Adafruit Industries https://learn.adafruit.
Do the same for the other end, to stabilize the header mechanically © Adafruit Industries https://learn.adafruit.
Once you have those two pins done you can continue to solder each of the pins. Do one row first © Adafruit Industries https://learn.adafruit.
Then do the other row! © Adafruit Industries https://learn.adafruit.
Before attaching the display, check that all the pins are soldered nicely and there's no bridging, cold solder, shorts, or unsoldered pins. Now we can attach the screen. Remove the two thin tape cover strips. You may find that some extra double-sided tape will keep the screen in place better than the two little tape strips! Put a piece or two on the back. © Adafruit Industries https://learn.adafruit.
Line up the TFT screen so it matches the white outline and press it down to stick it to the circuit board Turn the board over and press gently on the back to get the TFT stuck-on well! © Adafruit Industries https://learn.adafruit.
Easy Install The PiTFT requires some device tree support and a couple other things to make it a nice stand-alone display. If you just want to get going, check out the following for easy-install instructions! The same installer is used for all PiTFTs, you will pick and configure the setup during installation! Install Raspbian on an SD Card You'll need to start with Raspbian or Raspbian Lite. The last known for-sure tested-and-working version is March 13, 2018 (https://downloads.raspberrypi.
cd ~ wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/adafruit-pitft.sh chmod +x adafruit-pitft.sh sudo ./adafruit-pitft.sh PiTFT Selection Once you run it you will be presented with menus for configuration. For the 2.4", 2.8" and 3.2" PiTFT with resistive touchscreen overlay select #1 © Adafruit Industries https://learn.adafruit.
For the 2.2" PiTFT select #2 For the 2.8" Capacitive PiTFT select #3 For the 3.5" PiTFT select #4 Rotation Next you will be asked for the rotation you want, don't worry if you're not 100% sure which you want, you can always change this later by re-running the script © Adafruit Industries https://learn.adafruit.
It will take a few minutes to install the software and download all the things... Configuring what shows where You have a few different ways to set up the PiTFT, we ask 2 questions to figure out what you want PiTFT as Text Console (best for Raspbian 'Lite') This is the simplest to set-up type of use. Its great if you have a simple text based or pygame/SDL based interface.
Then simply reboot. Once rebooted you will not see anything on HDMI, but the console will appear on the PiTFT. That's it! PiTFT as HDMI Mirror (Best for Raspbian Full/PIXEL) This option is the easiest to understand: whatever appears on the HDMI display will be 'mirrored' to the PiTFT. Note that HDMI is much higher resolution so it's not like it turns the PiTFT into a 1080p display. This is great for when you want to run OpenGL-optimized software, PIXEL desktop software, or really anything.
months. These are no longer supported, and won't even boot on Pi 3B+, so we recommend the script above. There's the larger 'classic Jessie' image that will boot into X by default, and requires a 8G image, it has a lot more software installed. There's also the smaller 'Jessie Lite' that will boot into the command line, and can be burned onto a 2G card! Click below to download and install into a new SD card. Unzip and follow the classic SD card burning tutorials (https://adafru.it/aMW) PiTFT 2.
Resistive Touchscreen Manual Install & Calibrate If you've grabbed our Easy Install image, or used the installer script, this step is not required, it's already done! This is just for advanced users who are curious on how to configure and customize the touchscreen This procedure is identical for the 2.4", 2.8", 3.2" and 3.5" Resistive PiTFTs. Not for use with the Capacitive PiTFT! Setting up the Touchscreen Now that the screen is working nicely, we'll take care of the touchscreen.
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 © Adafruit Industries https://learn.
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. © Adafruit Industries https://learn.adafruit.
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: Try using this default calibration script to easily calibrate your touchscreen display. Note that the calibration values might not be exactly right for your display, but they should be close enough for most needs.
You should see five crosshair targets. If you see less than that, the touchscreen probably generated multiple signals for a single touch, and you should try calibrating again. 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.
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 autorotate Download and compile it with the following: sudo apt-get install libxaw7-dev libxxf86vm-dev libxaw7-dev libxft-dev git clone https://github.com/KurtJacobson/xtcal cd xtcal make You must be running PIXEL (the GUI) while calibrating.
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: Section "InputClass" Identifier "STMPE Touchscreen Calibration" MatchProduct "stmpe" MatchDevicePath "/dev/input/event*" Driver "libinput" Option "TransformationMatrix" "-0.000087 1.094214 -0.028826 -1.091711 -0.004364 1.057821 0 0 1" EndSection or whatever you got, into there.
Console Configuration If you've used our installer script, this step is not required, it's already done! This is just for advanced users who are curious on how to configure and customize the console 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 (https://adafru.
© Adafruit Industries https://learn.adafruit.
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 © Adafruit Industries https://learn.adafruit.
and setting the blank time to 0 (which turns it off) BLANK_TIME=0 © Adafruit Industries https://learn.adafruit.
HELP! (FAQ) My PiTFT used to work, now it doesn't! If you messed with /boot/config.txt or /etc/rc.local you may have removed or disabled some of the elements required for the PiTFT to work. Try re-running the Easy Installer script! 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 console output.
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.
How do I automatically boot to X windows on the PiTFT? Make sure your Pi boots to the graphical PIXEL desktop on the HDMI output monitor, then using the Easy Installer, select Mirror HDMI 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: © Adafruit Industries https://learn.adafruit.
On my first run of startx I get a window saying "GDBus Error.org.Freedesktop 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? Yes! Please see this post: https://forums.adafruit.com/viewtopic.
© Adafruit Industries https://learn.adafruit.
Playing Videos 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 (https://adafru.
OK now you just have to run: sudo SDL_VIDEODRIVER=fbcon SDL_FBDEV=/dev/fb1 mplayer -vo sdl -framedrop bigbuckbunny320p.
You can download it from the link above, we'll be using the 720p AVI version. To do the conversion itself, we suggest HandBrake (https://adafru.it/cXT) which works great and is open source so it runs on all operating systems! Download and install from the link. Then run the installed application and open up the AVI file from before. The app will pre-fill a bunch of information about it. Under Destination click Browse... to select a new MP4 file to save.
Click START to begin the conversion, it will take a minute or two. That's it! You now have a smaller file. Don't forget to play it on your computer to make sure it plays right before copying it to your Pi © Adafruit Industries https://learn.adafruit.
Displaying Images You can display every day images such as GIFs, JPGs, BMPs, etc on the screen. To do this we'll install fbi which is the frame buffer image viewer (not to be confused with the FBI agency!) sudo apt-get install fbi will install it Grab our lovely wallpapers with wget http://adafruit-download.s3.amazonaws.com/adapiluv320x240.jpg wget http://adafruit-download.s3.amazonaws.com/adapiluv480x320.png (https://adafru.it/cXU) For 320x240 PiTFTs (2.2", 2.4", 2.8" or 3.
© Adafruit Industries https://learn.adafruit.
Using FBCP The Ideal: Adafruit’s PiTFT displays are razor sharp. Whereas small composite screens on the Raspberry Pi usually require some video scaling (resulting in blurriness), PiTFT uses the GPIO header, digitally controlled pixel-by-pixel for a rock steady image. Though not a lot of pixels, it works great for retro gaming (and the display neatly stacks above the board, no side protuberances for video cables).
Backlight Control The backlight of the 2.8" PiTFT has 4 LEDs in series and it draws ~75mA at all times, controlled by a transistor. The PiTFT 3.5" display has 6 LEDs in a row, and we use a boost converter to get the 5V from the Pi up to the ~20V needed to light up all the LEDs. There might be times you'd like to save some power and turn off the backlight. The screen and touchplate will still work, you just can't see anything.
On / Off Using STMPE GPIO Another option is to just turn it on and off using the extra GPIO created by the touchscreen driver Thanks to the raspberry Pi overlay system, this GPIO is already set up for you in a file called /sys/class/backlight/soc:backlight/brightness To turn the backlight off run sudo sh -c 'echo "0" > /sys/class/backlight/soc\:backlight/brightness' To turn it back on, run sudo sh -c 'echo "1" > /sys/class/backlight/soc\:backlight/brightness' For older versions of PiTFT Kernel On older ve
© Adafruit Industries https://learn.adafruit.
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.
Just add the following lines into your InputClass of /etc/X11/xorg.conf.d/99-calibration.
Gesture Input With the PiTFT touchscreen and xstroke (https://adafru.it/dD0) 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: 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.
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.
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! © Adafruit Industries https://learn.adafruit.
PiTFT PyGame Tips 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. (https://adafru.it/saw) 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 Install Pygame: sudo apt-get install python-pygame (this will take a while) Ensure you are running SDL 1.2 SDL 2.
and paste in the following text: #!/bin/bash # enable wheezy package sources echo "deb http://archive.raspbian.org/raspbian wheezy main " > /etc/apt/sources.list.d/wheezy.list # set stable as default package source (currently stretch) echo "APT::Default-release \"stable\"; " > /etc/apt/apt.conf.d/10defaultRelease # set the priority for libsdl from wheezy higher then the stretch package echo "Package: libsdl1.2debian Pin: release n=stretch Pin-Priority: -10 Package: libsdl1.
it will force install SDL 1.2 OK now you can continue with pygame 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/PrzemoF/pitft_touchscreen (https://adafru.it/C2d) here's another option https://github.com/nift4/pigame (https://adafru.it/CYw) For examples: https://github.com/nift4/Raspberry-Pi-Testing (https://adafru.
Downloads Files Github repository for the PiTFT Helper installer (https://adafru.it/eIn) Github repository for auto-calibrator (https://adafru.it/f3T) Our branch of the 3.18 Pi Kernel with support for all the PiTFT stuff! (https://adafru.it/aPa) Fritzing object in the Adafruit Fritzing Library (https://adafru.it/aP3) EagleCAD PCB files (https://adafru.it/rF3) Fabrication Layout Dimensions in mm, same layout as the official Raspbery Pi HAT spec (https://adafru.
© Adafruit Industries https://learn.adafruit.
Detailed Installation If you've grabbed our Easy Install image, or use the script, this step is not required, it's already done! This is just for advanced users who are curious on how to configure and customize the kernel install In the next few steps we'll cover the detailed installation procedure. Chances are, you should grab the Easy Install image or script. If you have some interest in the details of how we install the PiTFT setup, read on! In order to add support for the 2.4" or 2.
Download & Install Kernel The only way we're distributing the PiTFT kernel packages right now is thru apt.adafruit.com so you'll still need to run: curl -SLs https://apt.adafruit.com/add-pin | sudo bash To add apt.adafruit.com to your list of software sources Then install the kernel with sudo apt-get install raspberrypi-bootloader This will take a up to 20 minutes so go make a sandwich or coffee.
OK since you're not going to run the helper, lets add the device tree overlay manually. Edit /boot/config.txt with sudo nano /boot/config.txt and add the following lines at the end: [pi1] device_tree=bcm2708-rpi-b-plus.dtb [pi2] device_tree=bcm2709-rpi-2-b.dtb [all] dtparam=spi=on dtparam=i2c1=on dtparam=i2c_arm=on dtoverlay=pitft28r,rotate=90,speed=32000000,fps=20 © Adafruit Industries https://learn.adafruit.
The rotate= variable tells the driver to rotate the screen 0 90 180 or 270 degrees. 0 is portrait, with the bottom near theUSB jacks 90 is landscape, with the bottom of the screen near the headphone jack 180 is portrait, with the top near the USB jacks 270 is landscape, with the top of the screen near the headphone jack. You can change this file with nano and reboot to make the change stick. The speed= variable tells the driver how to fast to drive the display.
You should see the Pi desktop show up on the TFT! Congrats, you've completed the first test perfectly. Hit Control-C in the console to quit the X server so we can continue configuration Next up we'll add support for the touch screen automatically on boot. Edit the module list with sudo nano /etc/modules and add stmpe-ts on a line at the end Save the file and reboot the Pi with sudo reboot and look at the console output (or run dmesg in the console window after logging in) you will see the modules install.
We can set up the touchscreen for rotate=90 configuration by doing the following (for more delicate calibration or for other rotate=XX values, see the next section) Create the directory and new calibration configuration file: sudo mkdir /etc/X11/xorg.conf.d sudo nano /etc/X11/xorg.conf.d/99-calibration.conf and enter in the following lines, then save.
You can now try to run X again with FRAMEBUFFER=/dev/fb1 startx Type Control-C to quit X If you don't ever want to have to type FRAMEBUFFER=/dev/fb1 before startx, you can make it a default state by editing your profile file: sudo nano ~/.profile and adding export FRAMEBUFFER=/dev/fb1 near the top and saving the file. Then reboot to reload the profile file.
