Raspberry Pi 3, PiTFT and a modern kernel (bluetooth support!)

Note 2017-02-17: Some slight changes have been made after testing this guide against raspbian 2017-01-11.

Adafruit’s PiTFT is a very neat little addition to the Raspberry Pi. It combines a 2.8″ 320×240 touchscreen (either resistive or capacitive) with 4 buttons hooked up to the Pi’s GPIO. Adafruit even sells a case topper for their standard pi case to fit the screen.

Installation and use of the screen is easily done by following the instructions. The  easy install script takes care of everything and after a reboot the screen works flawlessly.

Unfortunately this will install a fairly old kernel, 4.1, which does not support certain features of the Pi 3. Bluetooth support is one of them and the WiFi driver seems less reliable. There have been multiple forum posts requesting an updated kernel since the Pi 3 was released, but nothing has surfaced yet.

This guide sets up the screen with a standard raspbian install and gets the touchscreen to work for TSLIB by applying a small kernel patch. I’ ll primarily be using the screen with pygame, a simple and light way of getting images up on the screen. pygame relies on TSLIB for it’s touchscreen input, hence the need for the patch.

First of all, my “setup”  is as follows:

  • Raspberry Pi 3
  • Adafruit 2.8″ capacitive PiTFT Plus
  • Adafruit Case and PiTFT case Topper
  • Raspbian jessie lite 2016-05-27 (and 2017-01-11)

Let’s start by everything that’s needed to get the screen to run. I’ll follow up with some more details to what’s what below.

Step by Step

These steps are based on adafruit’s instructions but without using the adafruit kernel. This will probably only work for a  Pi 2 and 3.

Start by having raspbian jessie installed and running on your Pi. Make sure all the software is up to date by running sudo apt-get update && sudo apt-get upgrade

Append the following to /boot/config.txt. If you are using the resistive version use the pitft28-resistive.dtbo overlay instead.

Adafruit’s steps to get the console to show up on boot are still valid. Modify the kernel options by appending fbcon=map:10 fbcon=font:VGA8x8 to /boot/cmdline.txt It should look something like this:

After a reboot (not required at this point though) the screen now works! Next is getting the touchscreen to work. This is a bit more complicated and requires a modified kernel to be built.

Start by cloning the raspbian kernel sources and installing required packages:

Download and apply the ft6236 patchfile:

Build and install the modified kernel. Especially the build step will take forever. More information on pi kernel building and also cross compiling can be found here.

2016-07-11 21_39_12-pi@raspberrypi_ ~_linux

And reboot to start your fresh kernel:

As per the adafruit guide, create a udev rule for consistent naming of the device by creating /etc/udev/rules.d/95-ft6236.rules

The final step is to set the TSLIB calibration in /etc/pointercal:

All that remains is to reload the kernel module and to test the screen!

ts_test screen

And to be sure that the module is loaded modify /etc/modules and add ft6236 to the list:

dmesg can be used to check if everything is loading:

2016-07-10 20_59_59-pi@raspberrypi_ ~

This shows that both fbtft and ft6236 are loaded and have created their devices.

For decent pygame support libsdl has to be downgraded, here adafruit’s steps can be followed 1:1. Create a file pinsdl.sh and paste in this code:

Execute the file by issuing these commands:

Your Pi is now ready to use pygame based and touchscreen input!

Detailed Reasoning

Adafruit does supply a set of patches, but the file’s datestamps indicate that the patch was created in 2013. This is even more outdated than adafruits kernel sources. and will not help patching the newer kernel. It does however give some insight in what Adafruit has modified and which modules are used.

Time to do some digging!


In the adafruit kernel the module that creates the framebuffer device /dev/fb1 is called fbtft. This module also exists in the raspbian sources, so it should also support the pitft. Lets dig a little deeper! In the instructions adafruit modifies the /boot/config.txt file to add an overlay and this initializes the module with the right parameters. The exact same overlay does not exist but seems to have been renamed to pitft28-capacitive.dtbo or pitft28-resistive.dtbo. This overlay can be used and the screen works immediately, that was easy! Adafruit’s other tweaks to get the console to show work without any change too.

I think X should also work as the framebuffer device is created similar to the adafruit kernel.


The touchscreen required a little more work. Adafruit’s kernel contains the module ft6x06_ts  but it does not exist in the raspbian sources. However it does contain a module ft6236, might this work? Adafruit’s udev rule does create the /dev/input/touchscreen symlink and running evtest shows incoming coordinates when the screen is touched. So Succes? Unfortunately not, when running a TSLIB test it outputs “Error Message is: selected device is not a touchscreen I understand”. A bit of googling led me to a post on 0xf8 where Pieter Hollants ran into the same problems. He does a great job of identifying why TSLIB does not understand the event output: Basically, TSLIB requires a touch pressure value to function. Unfortunately he does not have a solution for the problem.

This made me dig a little more in the differences between the sources of the two modules. Turns out the ft6x06_ts does not read the actual force data from the controller but just uses a defined constant! The kernel patch implements exactly the same for the newer ft6236 module and bingo! it works!

Loose Ends

Obviously there are some loose ends because of my hardware and because I simply haven’t tried everything yet:

  • PWM Backlight control
  • GPIO Power Switch: Module rpi_power_switch does not exist.
  • I have not tried to get X to run, as I’ll be using Pygame/SDL for the graphics. It will probably work fine without the kernel modifications as these were only needed to get LIBTS to work.

Patch File