TFT Display HATs

From UpWiki
Jump to: navigation, search

The ubilinux kernel includes the "fbtft" driver modules, enabling a selection of small TFT displays, typically connected via SPI. This enables the use of many RPi display HATs on UP, such as those available from Adafruit and Watterott, as an auxiliary low-performance graphics display.

It is possible to display images, movies, custom GUIs, and even desktops, on these little displays.

Verified on UP

The following TFT displays have been reported as working with UP:


Using Adafruit PiTFT 2.8" 320x240 on UP

Instructions for using the Adafruit 2.8" PiTFT display HAT on UP.

  • With the UP board powered off, plug the display HAT on the 40-pin I/O header, making sure that the HAT connector is aligned to pin 1 on the 40-pin I/O header.
  • Power on the UP board and enter the following commands in a terminal window to load the drivers for this HAT:
sudo modprobe fbtft dma=0
sudo modprobe fbtft_device name=pitft busnum=2 rotate=90
  • The display goes from white to black.

Using Watterott RPi Display B+ 2.8" 320x240 on UP

  • Info: You need for this display on the UP-Board 4 x M2.5 13mm standoff's to bring distance between heatsink and screen.
sudo modprobe fbtft dma=0
sudo modprobe fbtft_device name=rpi-display speed=32000000 rotate=270 busnum=2
  • The display goes from white to black.

Using Adafruit PiTFT 3.5" 480x320 on UP

  • The display has no default configuration, it must be passed manually.
sudo modprobe fbtft dma=0
sudo modprobe fbtft_device custom name=fb_hx8357d rotate=270 speed=42000000 buswidth=8 bgr=1 gpios=dc:25 busnum=2 
  • The display goes from white to black.

Console con2fbmap

sudo apt-get install fbset
# Map console 1 to framebuffer 1, login screen will show up on the display
con2fbmap 1 1

Test your display

  • To test the display using fbi to display a small jpeg image (note: if your desktop disappears while the jpeg is displayed, press Esc to return):
sudo apt-get -y install fbi
sudo fbi -d /dev/fb1 -T 1 -noverbose -a Mystery-100x100.jpg
  • To test the display using mplayer to display a short mpeg video clip:
sudo apt-get install -y mplayer
sudo SDL_VIDEODRIVER=fbcon SDL_FBDEV=/dev/fb1 mplayer -vo sdl -framedrop test.mpg

Most of the instructions above were taken from Notro's wiki pages.

Note that this HAT also includes a touch-screen input controller, but this is not currently enabled by the instructions above. Some additional work is required to get the necessary kernel drivers for that particular touch-screen controller working on non-DeviceTree platforms such as UP.

To add display to function at startup

Create file /etc/modprobe.d/fbtft.conf (as root)with the contents (options from whichever TFT display from above, this example uses the options for the AdaFruit 3.5" TFT):

options fbtft dma=0
options fbtft_device custom name=fb_hx8357d rotate=270 speed=42000000 buswidth=8 bgr=1 gpios=dc:25 busnum=2

Create file /etc/modules-load.d/fbtft.conf with the following contents to load modules making sure SPI loads first:


You will need to run the con2fbmap 1 1 (as root) command from the instructions above, after a reboot.

To get X running on the display

Create file /usr/share/X11/xorg.conf.d/99-fbdev.conf (as root) with the contents:

Section "Device"  
  Identifier "myfb"
  Driver "fbdev"
  Option "fbdev" "/dev/fb1"

This will bring up the login dialog on next boot.

To configure display to boot to a specific user desktop

Create directory /etc/systemd/system/getty@tty1.service.d/ (as root)

Create a file /etc/systemd/system/getty@tty1.service.d/override.conf (as root) with the following content, Note <user name> is replaced with the name of the auto login user:

ExecStart=-/sbin/agetty --autologin <user name> --noclear %I $TERM

Add this to the users ~/.profile (as <user name>):

[ "$(tty)" = "/dev/tty1" ] && exec startx


systemctl set-default

To undo Run:

systemctl set-default

For a more convenient way of dealing with the tiny screen

You can setup a VNC server to access this screen remotely using any one of a number of VNC viewers from a regular desktop, or even a phone app. Anything you do on the remote viewer will also be displayed on the screen. You will need to use x11vnc to do this if you want to access the session on the display (as root):

apt-get update
apt-get install x11vnc

As the <user name> used above Run (you will be prompted to enter a password for remote access):

x11vnc -storepasswd

To run x11vnc from command line (run as the <user name>):

x11vnc -display :0 -forever -shared -o /home/theuser/x11vnc.log -bg -rfbauth /home/<user name>/.vnc/passwd

To automatically run on startup of desktop, create a script, I suggest creating it in a local bin directory of the user account to be used:

mkdir ~/bin
chmod 755 ~/bin

Create a file, X11vnc in that directory with contents and 755 permissions:


if [ ${DISPLAY} = ':0' ]
    /usr/bin/x11vnc -display ${DISPLAY} -rfbport 5900 -desktop `uname -n`-Console -forever -shared -o /home/<user name>/x11vnc.log -bg -rfbauth /home/<user name>/.vnc/passwd

This script will check if run from the X display :0, you can additionally add another VNC server (like tightvncserver) on another socket, other than 5900 if you want a full size (higher resolution) remote desktop, although it will not be associated with with the frame buffer of the TFT. This will give you multiple graphical sessions to the Up Board.

Finally to autostart the script we created add the following line to ~/.config/lxsession/LXDE/autostart (as <user name>):

@/home/<user name>/bin/X11vnc


All this should auto initialize the display, log it in as a specified user (not root) and make that display available remotely through a VNC viewer on port 5900. The Up Board will not require any local keyboard or mouse to access it, everything can be done from another desktop. Both the local and remote display can be interacted with so if you choose to bring up, say a kiosk browser, that runs local CGI, java or javascript, that is triggered by system events, it makes for an easy means of creating a graphical display or interface using familiar means.

This should also work with any of the other displays (with some initialization modifications) on this page as well. Once touch interaction is sorted out, this process should also allow you to easily create useable touch displays as the original AdaFruit implementation simply mimics mouse like actions, although they are somewhat impractical on a 3.5" screen and a .5" finger when the desktop displays touch points only a few pixels wide. You need a means of creating and debugging an interface on the actual display, this does that.