I am a big fan of those small TFT displays in the size of the Raspi. They even come with a resistive touch panel and allow you to realize small applications with full UI control. With the fine fbtft drivers from notro you can access them as regular framebuffers and use all software that runs otherwise only on “big screens” via HDMI.

While setting up the TFT support in a Raspbian system was quite complex and includes compiling an own patched kernel, nowadays things got really simple. In this post I’ll give you a overview on the setup and how easy it has become…

(And it works for good ol’ Model A/B, A+/B+, and shiny new Model B2!)

1. Kernel Update and DT Overlay Setup

notro has merged his drivers to the upstream kernel tree and therefore you get the fbtft drivers already with the current Raspbian kernel sources. Just make sure to get an updated kernel:

> sudo -s
# rpi-update
# reboot

Check the linux version:

> uname -a
Linux bert 3.18.9+ #768 PREEMPT Sun Mar 15 18:59:03 GMT 2015 armv6l GNU/Linux

Don’t forget to reboot before checking your kernel version. Version 3.18.9+ and later are all suitable. These kernels use the DeviceTree to configure external devices. This allows to add a new device by simply writing a configuration file (here a DT overlay) that describes what drivers to load and what resources to acquire.

You have to find a suitable DT overlay for your display. The overlays are stored in /boot/overlays. I have a Watterott rpi-display and there is already an overlay available:

> ls /boot/overlays/rpi*
/boot/overlays/rpi-display-overlay.dtb

Now let’s activate the display by adding this overlay: Open /boot/config.txt (as root) with your favorite editor

> sudo vi /boot/config.txt

add (at the end) of the file:

dtoverlay=rpi-display

Note: do not write the -overlay.dtb postfix of the filename here!

Now its time for a reboot:

> sudo reboot

You can check the existence of your new display by looking at the framebuffer devices available on the system:

> ls /dev/fb*dev/fb0  /dev/fb1

/dev/fb1 is your TFT!

2. Boot console on the TFT

Typically you want to see your device booting on the TFT. I.e. your boot console must be mapped to /dev/fb1.

Open /boot/cmdline.txt as root:

> sudo vi /boot/cmdline.txt

and add at the end of the first line:

fbcon=map:10 fbcon=font:VGA8x8 logo.nologo

This maps the boot console to framebuffer 1, selects a smaller font, and disables the Raspberry Pi logo on the top left as it consumes too much space on such a small display.

Now reboot and enjoy the boot messages 🙂

3. X11 on the TFT

My applications mostly run on X11 therefore I need to launch X11 on the TFT.

Nowadays this is done by editing /usr/share/X11/xorg.conf.d/99-fbdev.conf (as root):

> sudo vi /usr/share/X11/xorg.conf.d/99-fbdev.conf

Change the /dev/fb0 entry to /dev/fb1:

Section "Device"
  Identifier "bla"
  Driver "fbdev"
  Option "fbdev" "/dev/fb1"
EndSection

If you start X11 now you should see it on your TFT:

> startx

If you touch the display with your fingers then you should already see the mouse pointer moving, but in the wrong direction… Thus we need calibration next!

4. Calibrate touch on X11

To calibrate the touch panel on X11 we need a tool called xinput_calibrator that is unfortunately not available as a Raspbian package, yet. We compile it from source:

> apt-get install x11proto-input-dev x11proto-input-dev
> git clone https://github.com/tias/xinput_calibrator.git
> cd xinput_calibrator
> ./autogen.sh
> ./configure
> make
> sudo make install

Next step is to run X11 and the xinput_calibrator there. I suggest to use a remote shell (via ssh) to run these commands. The calibrator will ask you to tip on some corners of the display. Use a pen to hit the crosses with high precision.

> startx &
> /usr/local/bin/xinput_calibrator
> pkill x

On your remote shell console the calibrator tool will print your display’s calibration data that looks like this:

Section "InputClass"
  Identifier "calibration"
  MatchProduct "ADS7846 Touchscreen"
  Option "Calibration" "210 3955 3775 260"
  Option "SwapAxes" "1"
EndSection

Open a new file (as root) in /usr/share/X11/xorg.conf.d/99-calib.conf and copy the contents of the above section (Section … EndSection) into it.

If you start X11 again then the mouse pointer will follow your touch movements very closely.

5. Setup your X11 Application

I usually configure my Raspi so that it runs a fullscreen X11 application automatically in startup.

First we need to create a file called $HOME/.xinitrc and make it executable. There you state the X11 programs that will be run automatically after a startx.

> vi $HOME/.xinitrc
> chmod 755 $HOME/.xinitrc

The file typically looks like:

xset s off # don't activate screensaver
xset -dpms # disable DPMS (Energy Star) features.
xset s noblank # don't blank the video device
exec $HOME/raspi/piradio/piradio.py

Note that the last line uses exec to launch your X11 application! The xset command are used to disable blanking of the TFT display. You can omit or adjust these if you want to have blanking.

Test with startx… It will run your application full screen. BTW: Make sure to add some UI to exit your application otherwise you can’t leave X11 🙂 (or use pkill x from a remote shell)

> startx

6. Autorun X11

The final step is to launch X11 automatically. While raspbian already has this feature I don’t use it as it runs lightdm as a display manager and is IMHO too bulky for the startup. I disable automatic startup in raspi-config (if its enabled) first.

Edit /etc/rc.local as root and add this line:

su -l chris -c startx &

Note: My username is chris on the Rapsi. If you use the default user pi then adapt the line accordingly.

On the next reboot you will see your application on the TFT right after some seconds of booting…

That’s it! I hope this post helps you to get started with your TFT quickly!

Have fun!