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!
Install Raspberry Pi OS on an SD Card
You'll need to start with Raspberry Pi OS or Raspberry Pi OS Lite.
The last known for-sure tested-and-working version is Dec 11, 2023 (https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2023-12-11/) from https://downloads.raspberrypi.org/raspios_lite_arm64/images/
Raspberry Pi OS does often 'break' stuff when new versions come out so to be safe, if you are having problems try this version!
Setup Virtual Environment
If you are installing on the Bookworm version of Raspberry Pi OS or later, you will need to install your python modules in a virtual environment. You can find more information in the Python Virtual Environment Usage on Raspberry Pi guide. To Install and activate the virtual environment, use the following commands:
sudo apt install python3-venv python -m venv env --system-site-packages
To activate the virtual environment:
source env/bin/activate
Installer script
This script will do all the work for you, and install both device tree overlay support as well as configure rotation and any HDMI mirroring. PiTFT no longer needs any custom kernels or modules, so you can continue to update/upgrade your Pi and it will work with the most recent releases.
Here's the commands to run. Make sure your Pi has network access, it needs to download the software!
The latest installer script was rewritten in Python, so it can be installed with just a few commands. First, start by installing a few dependencies and downloading the repo:
cd ~ sudo apt-get update sudo apt-get install -y git python3-pip pip3 install --upgrade adafruit-python-shell click git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git cd Raspberry-Pi-Installer-Scripts
Easy Single Command Install Options
The latest script allows you to specify all of your options within the command so you can sit back and watch the installation. We'll cover interactive installation below if you want to answer each prompt for a customized installation.
“Console Mode” Install Commands
If you just want a Linux text console to appear on the display, use one of the following commands:
For the PiTFT 2.4", 2.8", or 3.2" Resistive touchscreens, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28r --rotation=90 --install-type=console
For the PiTFT 2.8" Capacitive touchscreen, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28c --rotation=90 --install-type=console
For the PiTFT 2.2" Display, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=22 --rotation=90 --install-type=console
For the PiTFT 3.5" Resistive touchscreen, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=35r --rotation=90 --install-type=console
For the Mini PiTFT 1.3", BrainCraft HAT, 1.3" Color TFT Bonnet, or 1.5" Display, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x240 --rotation=0 --install-type=console
For the Mini PiTFT 1.14" Display, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x135 --rotation=270 --install-type=console
Mirrored Install Commands
If you want to mirror the HDMI output to the display, known as “FrameBuffer Copy” or FBCP for short, use one of the following commands:
For the PiTFT 2.4", 2.8", or 3.2" Resistive touchscreens, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28r --rotation=90 --install-type=mirror
For the PiTFT 2.8" Capacitive touchscreen, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28c --rotation=90 --install-type=mirror
For the PiTFT 2.2" Display, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=22 --rotation=90 --install-type=mirror
For the PiTFT 3.5" Resistive touchscreen, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=35r --rotation=90 --install-type=mirror
For the Mini PiTFT 1.3", BrainCraft HAT, 1.3" Color TFT Bonnet, or 1.5" Display, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x240 --rotation=0 --install-type=mirror
For the Mini PiTFT 1.14" Display, use the following command:
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x135 --rotation=270 --install-type=mirror
Rebooting
When it asks you to reboot, then choose yes because the setting won't take full effect until you do so.
Interactive Installation
For an interactive install, you can just run the script without any options:
sudo -E env PATH=$PATH python3 adafruit-pitft.py
Once you run it you will be presented with menus for configuration.
Display Selection
Start by selecting the board that best corresponds with your PiTFT. There's lots of options and we will likely be adding more in the future.
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
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 Raspberry Pi OS '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. If you want the PiTFT to act as a text console you can expect:
- HDMI will be 'deactivated' - nothing appears on the HDMI output but a black screen
- The login prompt appears on the Pi
- The Pi is all text, not a GUI (no PIXEL desktop)
- Keyboard and mouse are used only by the PiTFT interface
- Framebuffer-capable software (such as fbi for displaying images, mplayer for videos, or pygame software, etc) appear on the PiTFT
- OpenGL accelerated software will not appear on the PiTFT (it is unaccelerated framebuffer only)
- But, non-OpenGL-accelerated graphics software is a bit faster than using HDMI mirroring (not tons faster but you're not running fbcp which will always make it faster)
If you want that, say Yes to the question Would you like the console to appear on the PiTFT display
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 Raspberry Pi OS with Desktop)
This option is easier to understand. This works more like a monitor, though slightly different depending on which desktop environment you are running.
As of Bookworm with the Wayland Graphical Environment, this operates a little different than it previously did. It works more in the way that multiple monitors do on desktop systems. The display is set up as its own monitor and will extend the desktop in addition to the HDMI.
With X11, this worked more as a mirror: 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. The down-side is its a little slower than drawing directly to the framebuffer. You may not notice it but it's worth us mentioning!
- HDMI will be 'activated' but at a lower resolution - you can change this later but it looks best at 320x240 (PiTFT 2.2", 2.4", 2.8" and 3.2") or 480x320 (PiTFT 3.5")
- The login prompt or GUI appears on both HDMI and PiTFT at the same time
- Keyboard and mouse are shared, since the display is mirrored
- All graphics appear on both HDMI and PiTFT, thanks to fbcp
If you want that, say Yes to the question Would you like the HDMI display to mirror to the PiTFT display?
(or in the case of Wayland it will ask Would you like the to use the PiTFT as a desktop display?
)
PiTFT as Raw Framebuffer Device
For advanced users who are comfortable using framebuffer devices, it is possible to have the PiTFT and HDMI graphics be both active and display different data.
- HDMI will be active and act like a normal Pi
- The login prompt or GUI (PIXEL) appears on the HDMI
- PiTFT appears black, nothing appears on it
- Keyboard and mouse are used by the HDMI interface but can, in theory, be captured and used to change graphics on PiTFT through programming
- Framebuffer-capable software (such as fbi for displaying images, mplayer for videos, or pygame software, etc) can appear on the PiTFT if you set it up to display to /dev/fb1
- OpenGL accelerated software will never appear on the PiTFT (it is unaccelerated framebuffer only)
If you want that, say No to both of the configuration questions!
Creating Your Own Automated Command
Under the Easy Single Command Install Options section, there are a bunch of different installation flags that you can choose between. If you want to create your own command, you can find the latest options by typing:
sudo python3 adafruit-pitft.py --help
The main options to pay attention to are the --display
, --rotation
, and --install-type
arguments.
For the display, you can either choose the number you type for the options or the display type, which has the options listed under help. For instance, to us the 2.8" Resisitive display you could use
--display=1
or --display=28r
For the rotation, you can either choose the number you type for the options or the angle, which has the options also listed under help. To use 90 degrees, you could use
--rotation=1
or --rotation=90
For install type, You can either choose mirror, console or uninstall. To mirror, you would simply supply
--install-type=mirror
Automated Reboot Option
To go with a fully automated installation, you can provide a --reboot
flag. To always reboot, use:
--reboot=yes
This is useful if you want to use the display right after running the script. To never reboot immediately, use
--reboot=no
This is useful if you want it as part of a larger script that installs many things.
Custom User Directory
By default, it is installed under the current user directory, but you can provide the -u
or --user
flag along with the folder that you want to install to.
Uninstalling The Driver
To uninstall, you would either run the script interactively and choose Uninstall or you can provide the uninstall flag:
--install-type=uninstall
Unsupported Full Images
Historically, we provided full 'images' of Raspbian, which is now called Raspberry Pi OS. This worked OK until Raspbian started doing releases every few 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
PiTFT 2.2" Images
- Raspbian Jessie 2016/10/23-based image
- Raspbian Jessie Lite 2016/10/23-based image
- Raspbian Jessie 2016/03/25-based image
- Raspbian Jessie Lite 2016/03/25-based image
- Raspbian Jessie 2015/09/24-based image
- Raspbian Wheezy 2015/09/09-based image
PiTFT 2.4"/2.8"/3.2" Resistive Images
- Raspbian Jessie 2016/9/23-based image
- Raspbian Jessie Lite 2016/9/23-based image
- Raspbian Jessie 2016/03/25-based image
- Raspbian Jessie Lite 2016/03/25-based image
- Raspbian Jessie 2015/09/24-based image
- Raspbian Wheezy 2015/09/09-based image
- Raspbian 2014/06/20-based image
- Raspbian 2014/09/09-based image
PiTFT 2.8" Capacitive
- Raspbian Jessie 2016-09-23-based image
- Raspbian Jessie Lite 2016-09-23-based image
- Raspbian Jessie 2016-03-25-based image
- Raspbian Jessie Lite 2016-03-25-based image
- Raspbian Jessie 2015/09/24-based image
- Raspbian Wheezy 2015/09/24-based image
- Raspbian 2014/09/18-based image
- Raspbian 2014/06/20-based image
- Raspbian image from 2015/03/03
PiTFT 3.5" Images
Text editor powered by tinymce.