Kernel Framebuffer Device Support

For many displays, including SPI based ones, the Linux kernel offers direct support in form of framebuffer devices. Often the displays will be auto-detected without configuration. (Check here for a list of supported displays.)

The devices are named /dev/fbX and have a unified API. This means you do have to deal with the details of the driver chip. When programming in Python the performance will likely be better too.

A framebuffer device (/dev/fb0) is also associated with the Pi’s HDMI port whether a display is attached or not. The first additional displays will hence be accessed as /dev/fb1.

In order to present a uniform abstraction the framebuffer device will only support a subset of the features of the display, e.g.

Also, the number of ways of connecting the display may be restricted. For SPI based devices usually only a few a standard pin configurations are used (cf. drivers).

Sometimes the system will auto detect the wrong display and then continue to load the wrong kernel driver module. Always check whether the output of

fbset --info ...  # see below 

matches the description of the display. If there is a mismatch it can often be remedied by loading the proper kernel driver module with this command:

$ sudo modprobe <module> <arg1> <arg2> ..
# e.g.:
# sudo modprobe fbtft_device custom name=fb_sh1106 debug=1 speed=2000000 gpios=reset:25,dc:24


Many tools and games work with framebuffer devices out of the box. Here we highlight a few of them.

Simple Testing

$ cat /dev/urandom > /dev/fb1 

Configuration Tools

fbset1 is a handy tool for display info and changing setting of the framebuffer.


$ fbset -fb /dev/fb1 --info
# show current resolution, color depth, etc 

Python Framebuffer Imageviewer

This is part of the Pytorinox Python Library

Run it like so

$ ./ /dev/fb1 <png-jpeg-or-other-image>

The code for is very short and worth studying.

Tips For Specific Devices

ssh1106 , 128x64 bw, spi

using spi pin-config-1



Use mplayer2 to view the movie stored in test.mpg like so:

mplayer -nolirc -vo fbdev2:/dev/fb1 test.mpg

Video Lan Client (VLC)

Use vlc-nox3 to view the movie stored in test.mpg like so:


Using GPU Acceleration for /dev/fb1

The Pi’s GPU can only be used in conjunction with /dev/fb0. To utilize GPU acceleration for /dev/fb1 a common approach is:

Displaying Content with PIL and Pytorinox

from PIL import Image, ImageDraw
from framebuffer import Framebuffer  # pytorinox

fb = Framebuffer(1)  # for /dev/fb1
buffer ="RGB", size=fb.size)
draw = ImageDraw.Draw(buffer)
cx = fb.size[0] // 2
cy = fb.size[1] // 2
draw.rectangle((cx - 10, cy -10, cx + 10,  cy + 10), "white")


  1. sudo apt install fbset↩︎

  2. sudo apt install mplayer↩︎

  3. sudo apt install vlc-nox↩︎