Adafruit PiTFT

Adafruit Industries produces whole series of resistive and capacitance touchscreens displays suited for all generations of Raspberry Pi computers. Original PiTFT 2.8" and PiTFT 3.5" screens fit on Raspberry Pi's A and B and overhang slightly over the USB-ports on more modern versions. 2x20 GPIO pins adapted PiTFT Plus 2.8" and 3.5" do not have this problem, however, they cannot be used with classical A and B models with 2x13 GPIO pins. 2.8" and 3.5" versions have 320x240 and 480x320 screen resolution, respectively; 2.8" model features additional GPIO-connected ports, which could be fit e.g. with hardware buttons. The screen resolutions available may be not enough for modern DE, however, the touchscreen can be used for some simple mini monitor with framebuffer console or even X11 output (e.g. conky).

Overview
Adafruit provides extensive installation instructions via the python. It is highly recommended to look through these instructions in case of any questions and further information. These instructions also cover not only 2.8" and 3.5" models, but the whole variety of the other Adafruit models, such as PiTFT 2.2", miniPiTFT 1.14", 1.3", 1.54", etc. However, the script adapted for Raspbian/Raspberry Pi OS does not work well under Gentoo. Following instructions are written based on the above mentioned script and this slightly outdated text. and tested on Raspberry Pi B and PiTFT 2.8" resistive screen. Still these instructions keep certain amount of generality and should work with the other models.

Installation consists of the following steps:


 * 1) enabling hardware configuration in ,
 * 2) checking kernel configuration and modules as well as the proper command line options,
 * 3) console configuration,
 * 4) X11 configuration.

Hardware and config.txt
Raspberry Pi kernels and firmware use a Device Tree (DT) and DT overlays to describe and configure the hardware present in the Pi board as well as the external hardware.

The PiTFT screen uses the hardware I2C Pins (SDA & SCL), SPI pins (SCK, MOSI, MISO, CE0) as well as GPIO #25 and #24. Additionally 2.8" version can use GPIO #18, #21-23 (or #27 instead of #21 on all newer models) for the hardware buttons, and 2.8" Plus version occupies GPIO #17, #22, #23, #27 for the same purpose instead. All other GPIO contacts remain unused.

The list of the DT for the screens and options for them can be found in by searching  Adafruit. Important options are screen rotation angle rotate and frame rate fps. Rotation angle rotate=90 will align the "horizontal" axis of the screen along the wide side.

By default Raspberry Pi will start using its HDMI interface for the video output on boot and PiTFT screen will become "secondary". To use solely PiTFT screen one should disable HDMI hotplug and set the maximum number of created framebuffers to 1. Additionally the output to PiTFT should be configured to 320x240 and 60Hz (or different supported depending on the screen) via hdmi_cvt option.

Last but not least is a choice of used graphics output. Raspberry Pi have in general 3 options: Legacy (default, when to DT overlay is used), "fake" and "real" KMS (with DTs such as {Path|vc4-fkms-v3d}). Technical differences between those choice are beyond the scope of this instruction, one just should note, that  resulted in booting failure. This may not be the case though for the screens which have DRM support e.g. Adafruit 2.4" and 3.5".

Keeping in mind all above the file should contain following lines in addition to the ones present:

Configuring the kernel
Raspberry Pi kernel distribution already has necessary module pre-compiled. Alternatively, using default kernel configuration,  ,   for the appropriate target will select necessary modules. Otherwise check if you have these modules selected. The chip model is also written on the backside of some PiTFTs.

Framebuffer console set-up
Append  to kernel command line either during build time or to the file.

A good idea is to use  service to change console font during system boot. Choose console font and size, e.g 12 pt.

Add  service to the boot sequence:

When working with the Raspberry Pi remotely, e.g. via ssh, one can check if framebuffer works correctly with of fbi part of  package.

or

where should be changed to e.g.  if HDMI is connected.

UDEV configuration
The installation script suggests creating following files, so the link to  of the PiTFT is created. This is required for the touchscreen functionality.

X11 configuration
Following files should be created to configure PiTFT with X11 system. First one ensures that /dev/fbX is attached to X-server with fbdev driver, as it seems not to work automatically.

Second file provides the calibration for the PiTFT as a touchscreen.

fbcp
All configuration above considers mainly setting up a framebuffer display separate from HDMI-connected display. However, the PiTFT is not GPU-accelerated (e.g. DRI2 is not working), so all 3D graphics is drawn by CPU, it is much slower compared to GPU-accelerated. The solution suggested by Adafruit is to copy HDMI output to framebuffer device via framebuffer copy utility (fbcp). Unfortunately, this part is currently beyond scope of this article.