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:

sudo raspi-config

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…

wget https://github.com/adafruit/Adafruit_Userspace_PiTFT/archive/master.zip
unzip master.zip

And then a quick test…

cd Adafruit_Userspace_PiTFT-master
sudo ./tftcp

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:

sudo cp tftcp /usr/local/bin

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

sudo nano /etc/rc.local

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

/usr/local/bin/tftcp &

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

sudo nano /boot/config.txt

Append the following lines to the bottom of the file:

disable_overscan=1
hdmi_force_hotplug=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt=320 240 60 1 0 0 0

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:

sudo apt-get update
sudo apt-get install python-pip python-smbus python-dev
sudo pip install evdev

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

cd Adafruit_Userspace_PiTFT-master
sudo python touchmouse.py

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:

sudo cp touchmouse.py /usr/local/bin
sudo nano /etc/rc.local

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

/usr/bin/python /usr/local/bin/touchmouse.py &

reboot and both PiTFT and touch should be active now.

This guide was first published on Nov 29, 2013. It was last updated on Mar 08, 2024.

This page (Userspace Tools) was last updated on Mar 08, 2024.

Text editor powered by tinymce.