The Freetronics OLED128 is a 128x128 pixel full colour OLED display module. This is the QuickStart guide for connecting OLED128 to a Raspberry Pi, there is also an Arduino Quickstart guide.

 

The fbtft project by notro provides kernel modules which allow you to use the OLED128 as a standard display on the Pi - almost anything you can do with the Pi's HDMI output, only smaller!

 

 

About Framebuffer Devices

fbtft lets you use the OLED128 as a “framebuffer” device. This is the standard way Linux outputs to a visual display. Usually the Raspberry Pi has only one framebuffer device, /dev/fb0, for the built-in HDMI or Composite output (whichever is enabled, whether it's connected to anything or not.) fbtft allows you to add a small display like the OLED128 as a second framebuffer, /dev/fb1.

Connecting the OLED128

On the back of the OLED128 you’ll see there’s a 10 pin header, with numbers printed to indicate pins 1 & 2:

There are 7 pins that need to be connected to use the OLED128 as a display. Wire them up to the “P2” header on the Pi as shown:

(Click to see a larger version of the diagram, or refer to the table below.)

OLED PinSignalRaspberry Pi Pin
1 +5V  5V
2 GND  GND
6 MOSI MOSI
7 SCK SCLK
8 OLED CS CS0
9 DNC GPIO 25
10 RST GPIO 24

If you decide to use female-to-female breadboard wires (as shown above), you can bundle them up with twist ties or similar to keep things neat:

Installing fbtft

If you have a working Raspbian install, you can install fbtft via the rpi-update mechanism. You just need to update rpi-update itself, first. Your Pi will need to be connected to the internet:


sudo wget https://raw.github.com/Hexxeh/rpi-update/master/rpi-update -O /usr/bin/rpi-update
sudo chmod +x /usr/bin/rpi-update
sudo REPO_URI=https://github.com/notro/rpi-firmware rpi-update

(This is a simplified version of the Install steps on the fbtft wiki.)

After the update has finished running, it will prompt you to reboot your Pi to start using the new kernel with fbtft support:

sudo reboot

If you're not using a recent Raspbian, or you want more details, then the fbtft wiki page provides a complete guide to the install process.

If you ever want to update to a newer kernel, you can skip the first two lines shown above and just run:


sudo REPO_URI=https://github.com/notro/rpi-firmware rpi-update

 

Please direct any support inquiries regarding the OLED128 to us at Freetronics (forums or email), not to notro.

 

 

Loading the OLED128 fbtft modules

After you've rebooted to use the updated kernel, load the fbtft module support for the OLED128 as follows:

sudo modprobe spi-bcm2708
sudo modprobe fbtft_device name=freetronicsoled128

First Steps

The recommended way to interact with your Pi and the OLED128 is via an SSH session. Otherwise some of these commands may become confused about where keyboard and mouse input should be sent.

The easiest way to verify the display is working is by loading a graphical "X Windows" session on it. On recent versions of Raspbian, you'll need to first edit the configuration file /usr/share/X11/xorg.conf.d/99-fbturbo.conf on your Pi. Look for this line:

Option          "fbdev" "/dev/fb0"

Comment this line out by placing a # at the beginning, so it looks like this:

#Option          "fbdev" "/dev/fb0"

Then run the following command, either from an SSH terminal or from a non-graphical terminal on the Pi:

FRAMEBUFFER=/dev/fb1 startx

X will take a few seconds to load, and the default display environment is a bit cramped in 128x128, but there it is:

Use Ctrl-C from the console you loaded startx from in order to close the X session.

Starting a custom X Session

The full X11 session is pretty busy. If you just want to run one simple X program, rather than a full desktop environment, then you can create a file .xinitrc in your home directory that contains the name of a program to run.

For example, if we install the classic x11-apps including xeyes and xclock:

sudo apt-get install x11-apps

And then create a file .xinitrc in our home directory containing only one line of content:

/usr/bin/xeyes

Then “startx” will display the xeyes app full screen and nothing else (note that this applies to -all- X sessions, including any on /dev/fb0 ie the main TV output!)

 

Video Playback

Another fun way to test your new framebuffer is to download Blender Group’s 2008 open movie Big Buck Bunny, which I’ve reformatted to 128x128 pixel here.

To install mplayer and download the movie (5.5Mb):

sudo apt-get install mplayer
wget http://cdn.shopify.com/s/files/1/0045/8932/files/big_buck_bunny_128x128.avi

To play the movie on the framebuffer output:

mplayer -nolirc -vo fbdev2:/dev/fb1 big_buck_bunny_128x128.avi


If you're wondering, this is the command used to convert the full size big buck bunny video to 128x128 (first it was scaled down to 128 pixels high, and then cropped in to 128 pixels wide.)

mencoder big_buck_bunny_480p_stereo.ogg -vf scale=-3:128,crop=128:128 -ovc x264 -nosound -o big_buck_bunny_128.avi

The fbtft wiki has more tips about using mplayer with fbtft

Console on Framebuffer

To swap the system’s text console to the OLED128:

con2fbmap 1 1

You should see the system console with login prompt on the OLED128:

Fonts are a little large, of course! You can fit a bit more onscreen by choosing a smaller font:

sudo setfont -C /dev/console Uni3-Terminus12x6.psf

If you want your console output back on the main output fb0, run

con2fbmap 1 0

The fbtft wiki has more details about redirecting console output to an fbtft-based display, and also some details about displaying the boot kernel console on the display.

Automatic module loading

To load the fbtft module for OLED128 automatically at boot up, first edit the file /etc/modprobe.d/raspi-blacklist.conf and remove the following line (or comment it out by putting a # at the beginning):

 blacklist spi-bcm2708

This removes the need to modprobe this module explicitly before using fbtft.

Next, add a line to the file /etc/modules:

 fbtft_device name=freetronicsoled128

The fbtft_device module will then automatically load when the Raspberry Pi boots up.

The fbtft wiki has a section on how to automatically start an X session or a console session on /dev/fb1 at startup.

The fbtft wiki also has a section on other uses for the framebuffer (image viewer, etc.)

 

Display Going to sleep ("blanking")

The fbtft driver supports automatic framebuffer blanking (like a screensaver), where the output can go to sleep by turning off the display OLED. When this happens the display goes very dark (light areas will still be visible but only very dimly.)

 

By default most Raspberry Pi distros will blank the output if it is idle (ie no keyboard/mouse input) for a certain period of time. You may not want this if you don't intend for the display to be interactive. One way around the problem is to insert this one line into the file "/etc/rc.local". Place it on a line by itself above the line "exit 0" in that file, and it will disable screen blanking when the Pi starts up:

 

echo -ne "\033[9;0]" > /dev/console

 

Note that if you disable screen blanking, you should also beware of burnin.

 

Using pygame

If you want to display some custom graphics / interactive then pygame is a great option. Pygame is a framework that lets you easily create games or other interactive graphical programs using the Python programming language.

Here is a very simple pygame drawing example for the OLED128.

To run the Pygame examples, you need access to a terminal device and some other permissions. The easiest way is to run as root, for example:

sudo python oled128_simple.py

For more ideas take a look at the pygame example on the fbtft wiki or the Pygame tutorials.

Troubleshooting

If the OLED128 display is appearing garbled or not reliably updating, you may need to lower the SPI clock speed (that controls the rate that data is sent to the display.) This can particularly be the case if you are using long (>10cm) cables from the Pi to the OLED128.

You can do this by passing an additional argument "speed" to the fbtft_device module. Instead of:

fbtft_device name=freetronicsoled128

Try:

fbtft_device name=freetronicsoled128 speed=16000000

The default speed is 20MHz (20000000), try values lower than this and see if the screen starts updating reliably.

To make this change permanent, you can add the equivalent arguments to the line in the /etc/modules file on the Pi:

fbtft_device name=freetronicsoled128 speed=16000000