pi2oled

A TINY OLED DISPLAY FOR THE PI

These little displays are just too cute to not attach to a Pi, and with the SSD1307 framebuffer driver included in the latest Rasbian they're very easy to use!

BUILDING THE HARDWARE

You could use jumper wires to connect the display to the Pi, but I've opted instead to use a small circuit board so the display can be plugged directly into the Pi.

Order the circuit board from OSH Park here. You can also use your vendor of choice using the source files in this project's files section.

Order the display from AliExpress or your favorite supplier. It should be around two dollars. The search term to use is "0.91 INCH OLED 128X32". Try to buy one that does NOT have the header soldered to the board. Make sure the pinout is like the photo below: 

Order a 5 pin single row 2.54mm female header connector. AliExpress has them for around a dollar for ten pieces, or you can get it in single piece quantities from DigiKey for a bit more.

You'll also need four pieces of bare wire to connect the board to the display. I used solid wire from a Cat 5 cable with the insulation removed. You could even use the pins from the header strip that comes with the display.

Lay the board on top of the display, with the "pi2oled" lettering up. Insert the wires through the four holes and solder them to the display and circuit board. It's best to leave a bit of space between the two boards: the thickness of a credit card is about right. Solder the connector into the remaining holes, facing down. It looks like this when done:

The finished assembly connects to the Pi on pins 1,3,5,7 and 9, like this:

SOFTWARE CONFIGURATION

UPDATE: my ssd1306.dtbo file has been accepted by the Pi foundation, and is now included in the latest experimental Pi kernel. To get it run rpi-update and reboot. When it's included in Raspbian I'll update these instructions.

Copy the ssd1306.dtbo file from this project's files section to /boot/overlays. The source for it is the ssd1306-overlay.dts file if you want to compile your own. (This overlay can also be used to run a 128 x 64 display: see the README file.)

Add the following two lines to /boot/config.txt:

dtoverlay=ssd1306,inverted,sequential

dtparam=i2c_arm=on,i2c_baudrate=1000000

One of the many useful things you can do with the display is display the Pi's IP address. Just run the following commands:

setfont Lat7-Terminus16

con2fbmap 8 1

chvt 8

echo -n -e "\ec`hostname -I`\n" > /dev/tty8

The above can be put in /etc/rc.local so it runs at startup. If you're thinking of putting this in a shell script so you can update the IP address periodically it won't work. Why? because this code stops working once you change away from console 8 - for instance to log into a text console or start X. To work around this you have to write directly to the display framebuffer. Here's how:

First install the convert utility:

apt-get install imagemagick

Then run the following command:

convert -size 128x32 -depth 1 xc:white -fill black -font "Lato-Hairline" -pointsize 14 -annotate +3+20 `hostname -I` mono:- > /dev/fb1

The font and pointsize in the command can be adjusted to suit your tastes. It only works with vector fonts, however, and in my opinion is not very readable. To fix this I wrote a little program to write text to the display using the Linux console fonts. Here's how to use it:

Download the text2fb1.c program from this project's files section, then compile it using the following command:

gcc -lz -o text2fb1 text2fb1.c

Then run the following command:

hostname -I | tr -d [:cntrl:] | ./text2fb1 /usr/share/consolefonts/Lat7-Terminus16.psf.gz

The font can be changed to whatever you like as long is it's a PSF1 font, and it's height is 32 lines or less. Further instructions are at the top of the source code.

There you go! For extra credit, see if you can figure out how to get the display to show the Pi's processor speed and temperature!