FBTFT shield image

notro edited this page Mar 13, 2014 · 17 revisions

This wiki page gives information about the custom Raspberry Pi image made to work with some LCD shields.

First boot

Video: Watterott RPi-Display first boot with FBTFT image

On first boot, the filesystem will be expanded to fill the entire SD-card. This triggers a reboot.

On the regular Rasbian release, raspi-config is started automatically on the console. This image has turned off that feature.
raspi-config is made for larger screens, so it doesn't fit these small LCD displays.
It's best to connect to the Pi with SSH, and run raspi-config from there (putty can be used on Windows).

When networked, the IP address is shown after boot:

My IP address is

Raspbian GNU/Linux 7 raspberrypi ttyAMA0

raspberrypi login:

Touchpanel calibration

The touchpanel needs calibration to be precise. On first start of LXDE, a calibration window will be shown.
Use a stylus to to touch the points shown.

# no need to specify FRAMEBUFFER

Some applications like PyGame, uses tslib for touch support.

sudo ts_calibrate

Test tslib

# install a new version with Quit button. Ctrl-C doesn't work from the console
sudo wget -O /usr/bin/ts_test http://tronnes.org/downloads/ts_test && sudo chmod +x /usr/bin/ts_test

sudo ts_test


  • How do I change the display rotation?
    In /boot/cmdline.txt change fbtft_device.rotate (0,90,180,270)
    If touchpanel with ads7846 is in use, and rotation is changed 90 degrees to the left or right, remember to flip the value of swap_xy (0/1) in /etc/modules. Recalibration is also needed.

  • Why does the backlight turn off after 30 minutes?
    It is console blanking (more)

  • How do I change the boot console font?
    In /boot/cmdline.txt change fbcon=font: (more)

  • How to I recalibrate the touchpanel for X windows?
    Delete /etc/pointercal.xinput, and then startx

  • How do I switch the console back to HDMI?
    con2fbmap 1 0 (more)
    Do it permanently: remove fbcon=map from /boot/cmdline.txt

  • How do I start X windows on the HDMI output?
    FRAMEBUFFER=/dev/fb0 startx
    Do it permanently: Delete /etc/profile.d/startx_fb1.sh

  • How do I enable FBTFT driver debug output?
    In /boot/cmdline.txt change fbtft.debug (more)
    Example: Want to see fps numbers which is bit 5, running echo $((1<<5)) gives fbtft.debug=32

  • How is this image made?
    See: FBTFT-shield-image build process

  • How do I disable the filesystem expansion?
    Before the first boot, remove the file expand_rootfs from the boot partition

  • How can I update the kernel?
    sudo rpi-update (the correct environment variables are already set: sudo env | egrep "REPO_URI|BRANCH")

Known issues

  • On the RPi-Display when using the 'quiet' kernel command line parameter, one error message is shown.
    This has been muted in the source code and will not be shown in the next kernel release.
  • raspi-config menu choice: Enable Boot to Desktop/Scratch -> Desktop does not work
    Workaround: add to /usr/share/X11/xorg.conf.d/99-fbturbo.conf Option "fbdev" "/dev/fb1"

fbcp - Framebuffer copy

By mirroring /dev/fb0 onto /dev/fb1, we can take advantage of the GPU for hardware accelrated video playback (more).


# We need to switch the console to fb0 first
con2fbmap 1 0
sudo service fbcp start


sudo service fbcp stop

Play video on /dev/fb0, which will also show up on /dev/fb1

# Big Buck Bunny
wget http://download.blender.org/peach/bigbuckbunny_movies/big_buck_bunny_480p_surround-fix.avi
omxplayer big_buck_bunny_480p_surround-fix.avi

Enable automatic startup

# remove from /boot/cmdline.txt: fbcon=map:10

sudo update-rc.d fbcp defaults

Disable automatic startup

sudo update-rc.d fbcp remove

To remove the border on fb1, add this to /boot/config.txt


Adafruit Camera app

If you have the Pi camera, you can turn your Raspberry Pi into a simple point-and-shoot digital camera.

Enable camera

sudo raspi-config

Calibrate if you haven't done so already

sudo ts_calibrate

Install picamera version 0.8

sudo pip install picamera==0.8

Install the Adafruit camera app

wget https://github.com/adafruit/adafruit-pi-cam/archive/master.zip
unzip master.zip

Run it

cd adafruit-pi-cam-master
sudo python cam.py



Backlight is controlled by the backlight subsystem.

# Turn off backlight
echo 1 | sudo tee /sys/class/backlight/*/bl_power

# Turn on backlight
echo 0 | sudo tee /sys/class/backlight/*/bl_power

Since there is no PWM kernel driver for the Raspberry Pi, brightness can't be controlled the usual way.
For displays that control backligh with GPIO18, a work around is to use the gpio utility to set this pin in PWM mode.
Note: This will mess up audio

# set gpio18 pin in PWM mode
gpio -g mode 18 pwm

# values: 0-1023
gpio -g pwm 18 200


Bootsplash is a term for a graphical representation of the boot process of the operating system.

Using fbi after the filesystem is mounted

This is a quick and dirty solution for an unanimated custom splash screen during boot (source).

Install fbi

sudo apt-get install fbi

Get an image and test

wget http://adafruit-download.s3.amazonaws.com/adapiluv320x240.jpg
sudo fbi -vt 2 -d /dev/fb1 -noverbose -autozoom adapiluv320x240.jpg

Make startup script

sudo nano /etc/init.d/asplashscreen


#! /bin/sh
# Provides:          asplashscreen
# Required-Start:
# Required-Stop:
# Should-Start:      
# Default-Start:     S
# Default-Stop:
# Short-Description: Show custom splashscreen
# Description:       Show custom splashscreen

do_start () {

    /usr/bin/fbi -T 1 -noverbose -a /etc/splash.jpg
    exit 0

case "$1" in
    echo "Error: argument '$1' not supported" >&2
    exit 3
    killall fbi
    exit 0
    echo "Usage: asplashscreen [start|stop]" >&2
    exit 3


make executable

sudo chmod a+x /etc/init.d/asplashscreen

Copy image

sudo cp adapiluv320x240.jpg /etc/splash.jpg

Test from SSH session

sudo service asplashscreen start

sudo service asplashscreen stop


# add to /boot/cmdline.txt: quiet

sudo insserv /etc/init.d/asplashscreen
sudo reboot

When the display disappears and goes black, press Ctrl-F3 then Ctrl-F1 to get to the login screen. I haven't found a way around this.


sudo insserv /etc/init.d/asplashscreen -r

Showing a movie during boot


Using Plymouth

Plymouth is an application that runs very early in the boot process (even before the root filesystem is mounted!) that provides a graphical boot animation while the boot process happens in the background.


sudo apt-get install plymouth-drm

echo "export FRAMEBUFFER=/dev/fb1" | sudo tee /etc/initramfs-tools/conf.d/fb1
sudo plymouth-set-default-theme fade-in

sudo update-initramfs -c -k $(uname -r)

The bootloader has to be told to pass this initramfs to the kernel

sudo nano /boot/config.txt


initramfs initrd.img-X.XX.XX+

Use the filename reported by the update-initramfs command.

Enable plymouth

sudo nano /boot/cmdline.txt

add to the beginning of the line (plymouthd can only read the first 512 bytes of the Linux kernel command line which can hold 1024 bytes)

splash quiet plymouth.ignore-serial-consoles

Reboot to see it work.
Use the ESC key to toggle between graphics and boot messages.

Change theme

plymouth-set-default-theme --list

# set theme and rebuild initrd
sudo plymouth-set-default-theme -R <theme>

sudo reboot

Disable plymouth
At a minimum, remove 'splash' from /boot/cmdline.txt
Then remove 'quiet plymouth.ignore-serial-consoles' from /boot/cmdline.txt and 'initramfs' from /boot/config.txt to be fully restored.

Some more details: Bootsplash

Get rid of the console message: Loading, please wait...

If there are no errors, this will give no console output before the graphics is loaded.

sudo nano /usr/share/initramfs-tools/init


#echo "Loading, please wait..."

Update initramfs

sudo update-initramfs -u
sudo reboot
Simple example theme: pi

Here's a simple theme only using an image and nothing else.
It's assumed that another Plymouth theme is tested and working.

Make theme directory

sudo mkdir /usr/share/plymouth/themes/pi

Add config file

sudo nano /usr/share/plymouth/themes/pi/pi.plymouth


[Plymouth Theme]
Name=pi theme
Description=Raspberry Pi theme


Add script file

sudo nano /usr/share/plymouth/themes/pi/pi.script


# only PNG is supported
pi_image = Image("Raspi_Colour_R.png");

screen_ratio = Window.GetHeight() / Window.GetWidth();
pi_image_ratio = pi_image.GetHeight() / pi_image.GetWidth();

if (screen_ratio > pi_image_ratio)
  {  # Screen ratio is taller than image ratio, we will match the screen width
     scale_factor =  Window.GetWidth() / pi_image.GetWidth();
  {  # Screen ratio is wider than image ratio, we will match the screen height
     scale_factor =  Window.GetHeight() / pi_image.GetHeight();

scaled_pi_image = pi_image.Scale(pi_image.GetWidth()  * scale_factor, pi_image.GetHeight() * scale_factor);
pi_sprite = Sprite(scaled_pi_image);

# Place in the centre
pi_sprite.SetX(Window.GetWidth()  / 2 - scaled_pi_image.GetWidth () / 2);
pi_sprite.SetY(Window.GetHeight() / 2 - scaled_pi_image.GetHeight() / 2);

Add image

sudo wget -O /usr/share/plymouth/themes/pi/Raspi_Colour_R.png http://www.raspberrypi.org/wp-content/uploads/2012/03/Raspi_Colour_R.png

Enable this theme

sudo plymouth-set-default-theme pi

Test the theme
In one SSH session start Plymouth daemon in debug mode. Errors is logged to a file.

sudo plymouthd --no-daemon --debug --debug-file=/var/log/plymouthd.log

In another SSH session control the daemon

sudo plymouth --show-splash
sudo plymouth --quit

Remember to rebuild initrd before trying it for real

sudo plymouth-set-default-theme -R pi
sudo reboot

Plymouth theming guide part 1, part 2, part 3, part 4, scripts

Trigger commands with switches

It's possible to execute commands on the Pi when switches connected to GPIO's are activated.
This is done with the help of the triggerhappy daemon and the gpio_keys module.

The RPi-Display has pads that can be used with a switch. It is connected to GPIO22.


The gpio_keys module creates a keyboard that listens on GPIO's for keypresses.
Keypresses generates events that other processes can receive.
The driver is configured with the gpio_keys_device module.

Here is an example creating a keyboard with one key:

sudo modprobe gpio_keys

# KEY_POWER 116 /* SC System Power Down */
sudo modprobe gpio_keys_device active_low keys=22:116

Make it permanent by adding it to /etc/modules

gpio_keys_device active_low keys=22:116

Note: If there is no external pullup/down resistor, the internal ones must be activated with the pullup or pullup argument to gpio_keys_device.

Test this "keyboard":

pi@raspberrypi:~$ evtest
No device specified, trying to scan all of /dev/input/event*
Not running as root, no devices may be available.
Available devices:
/dev/input/event0:      Microsoft Basic Optical Mouse
/dev/input/event1:      LITEON Technology USB Multimedia Keyboard
/dev/input/event2:      LITEON Technology USB Multimedia Keyboard
/dev/input/event3:      ADS7846 Touchscreen
/dev/input/event4:      gpio-keys
Select the device event number [0-4]: 4
Input driver version is 1.0.1
Input device ID: bus 0x19 vendor 0x1 product 0x1 version 0x100
Input device name: "gpio-keys"
Supported events:
  Event type 0 (EV_SYN)
  Event type 1 (EV_KEY)
    Event code 116 (KEY_POWER)
Testing ... (interrupt to exit)
Event: time 1390964791.200396, type 1 (EV_KEY), code 116 (KEY_POWER), value 1
Event: time 1390964791.200396, -------------- SYN_REPORT ------------
Event: time 1390964791.260402, type 1 (EV_KEY), code 116 (KEY_POWER), value 0
Event: time 1390964791.260402, -------------- SYN_REPORT ------------

triggerhappy (thd)

The triggerhappy daemon listens for input events, and executes actions based on it's configuration files. In the default setup, the daemon is run as user nobody. This makes it difficult to execute priviliged commands. By changing the user to pi, we can use sudo for the priviliged commands.

sudo nano /etc/init.d/triggerhappy

change user from nobody to pi

DAEMON_ARGS="--daemon --triggers /etc/triggerhappy/triggers.d/ --socket /var/run/thd.socket --pidfile $PIDFILE --user pi /dev/input/event*"

Now we find the event for our key:

pi@raspberrypi:~$ thd --dump /dev/input/event* | grep ^#
# KEY_POWER     1       command
# KEY_POWER     0       command

Let's make a config file that poweroff the Pi when this key is pressed

sudo nano /etc/triggerhappy/triggers.d/poweroff.conf


KEY_POWER   1   sudo /sbin/poweroff

Restart triggerhappy

sudo service triggerhappy restart

If you get: Unable to parse trigger line:, remove trailing empty lines from the config file.

Pressing the switch should now poweroff the Pi.

Toggle backlight

by pressing Music key on USB keyboard

thd --dump /dev/input/event* | grep ^#
# KEY_CONFIG    1       command
# KEY_CONFIG    0       command

Make config file

sudo nano /etc/triggerhappy/triggers.d/backlight.conf


KEY_CONFIG    1       sudo /usr/local/bin/bl_toggle

Restart daemon

sudo service triggerhappy restart

Backlight toggle script

sudo nano /usr/local/bin/bl_toggle



dev=$(echo /sys/class/backlight/*)
state=$(cat $dev/bl_power)

if [ $state -ne 0 ]; then
    sudo sh -c "echo 0 > $dev/bl_power"
    sudo sh -c "echo 1 > $dev/bl_power"

Make it executable

sudo chmod +x /usr/local/bin/bl_toggle


Enable spidev for userspace SPI access. This can only be done on shields without a touch controller, as the Pi only has 2 available chip selects.

sudo modprobe spi-config devices=bus=0:cs=1:modalias=spidev:speed=500000

dmesg | tail
[ 7721.899378] spi_config_register: device description: bus=0:cs=1:modalias=spidev:speed=500000
[ 7721.899471]  spi_config_match_cs: SPI0: check CS=0 to be 1
[ 7721.903949] spi_config_register:spi0.1: registering modalias=spidev with max_speed_hz=500000 mode=0 and no interrupt

ls -l /dev/spi*
crw-rw---T 1 root spi 153, 0 Jan 27 20:43 /dev/spidev0.1