FBTFT image

notro edited this page Feb 22, 2015 · 22 revisions

This wiki page holds information about the FBTFT images for the Raspberry Pi.

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 tty1

raspberrypi login:

Touchpanel calibration

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

# no need to specify FRAMEBUFFER
# sudo is only needed when doing calibration
sudo startx

Some applications like PyGame, uses tslib for touch support.

sudo ts_calibrate

Test tslib

sudo ts_test


  • How do I change the display rotation?
    In /boot/cmdline.txt change fbtft_device.rotate (0,90,180,270)
    If using touchpanel and rotation is changed 90 degrees to the left or right, remember to flip the value of SwapAxes (0/1) in /etc/X11/xorg.conf.d/99-calibration.conf. Recalibration is also needed.

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

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

  • 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 increase the framerate?
    Add to /boot/cmdline.txt: fbtft_device.speed=48000000 fbtft_device.fps=50 (details)
    This is the default on hy28b.

  • 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?
    Using fbtft-spindle

  • How do I disable the filesystem expansion?
    Before the first boot, remove the file firstboot.sh 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")

    2015-02-23 There will be no more updates to the builtin kernel. Remove BRANCH from /etc/profile.d/rpi-update.sh and login/logout for rpi-update to get the Device Tree kernel (how to use).

  • How do I enable X windows to start automatically on boot?
    Use raspi-config menu choice: Enable Boot to Desktop/Scratch -> Desktop

  • How can I have X windows on both HDMI and the LCD?
    See: X windows multiseat

Known issues

  • startx must be run as root for the calibration script to store the calibration data



Play movies

sudo apt-get install -y mplayer
wget http://fredrik.hubbe.net/plugger/test.mpg

mplayer -nolirc -vo fbdev2:/dev/fb1 -vf scale=320:-3 test.mpg

Image viewer

sudo apt-get -y install fbi
wget http://art110.wikispaces.com/file/view/Mystery-100x100.jpg/30649064/Mystery-100x100.jpg

sudo fbi -d /dev/fb1 -T 1 -noverbose -a Mystery-100x100.jpg


The boot console font can be changed in /boot/cmdline.txt


Choices: MINI4x6, VGA8x8, Acorn8x8, PEARL8x8, ProFont6x11, 7x14, VGA8x16, SUN8x16, 10x18, SUN12x22


By default the console goes blank and turns off backlight after 30 minutes.
This is set in /etc/kbd/config:


Setting it to zero disables blanking.
Note: When using Plymouth this doesn't work. Use the kernel command line parameter consoleblank= (Plymouth switches the boot console to a virtual console, and the setterm -blank command from /etc/init.d/kbd is applied to that console)

Change temporarily:

  • From console: setterm -blank 1
  • From SSH: sudo sh -c "TERM=linux setterm -blank 1 >/dev/tty0"

Show current value (in seconds)

cat /sys/module/kernel/parameters/consoleblank


X windows


By default X windows blanks the display after 10 minutes.
It does not turn of the backlight (workaround).

To turn off blanking (source):

sudo apt-get install x11-xserver-utils

add to /etc/xdg/lxsession/LXDE/autostart

@xset s off
@xset -dpms
@xset s noblank

fbcp - Framebuffer copy

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


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

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


sudo service fbcp stop

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



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 backlight with GPIO18, a work around is to use the gpio utility to set this pin in PWM mode.
Note: This will mess up audio in one of the channels.

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

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

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



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

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
# Some themes to try: adapiluv, joy, fade-in
sudo plymouth-set-default-theme adapiluv

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

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




  • FBTFT kernel 2014-06-14 (3.12.21+)
  • Add xstroke gesture recognition
  • Add matchbox-keyboard
  • Remove FRAMEBUFFER=/dev/fb1 environment variable. Already set in /usr/share/X11/xorg.conf.d/99-fbturbo.conf.
  • Add rpi-source
  • Fix issue 105 (SDL_MOUSEDEV)


  • Touchpanel xy axes swapping is moved to /etc/X11/xorg.conf.d/99-calibration.conf
  • Remove FRAMEBUFFER env var. X windows relies on the fbdev option value to know which framebuffer to use.
  • Firstboot filesystem expansion code is moved to /boot/firstboot.sh
  • The latest kernel has a helper script for installing the kernel source
  • ts_test is updated and includes a Quit button.
    Previously ts_test could not be stopped when started from the console (Ctrl-C doesn't work).


  • Add tslib
  • Add xinput_calibrator
  • Add WiringPi
  • Add fbcp
  • Add adapiluv plymouth theme
  • Expand fs on first boot
  • Set /dev/fb1 as default for X and tslib
  • Enable touch calibration on first startx
  • Add udev rule for /dev/input/touchscreen
  • Add SDL_ env variables

Previous releases was identical to Raspian except for the kernel.