Introduction

OLED graphic displays are awesome... And it is a well known fact that the smaller they are, the more awesome they become! Adafruit stock a whole host of small monochrome OLED displays and in this tutorial I am going to show you how you can get one working with your Raspberry Pi. This guide will cover everything from wiring up your display... To programming it in Python.

By the end of this tutorial you will be able to make your OLED display do a number of things. You will understand how to print text to it and then use that to show the internal IP address of your Pi. You will also be able to turn your OLED into a scrolling clock that alternates between the date and the time. Finally you will be able to take any image and, through some clever Python code, show it on your display.

This guide accompanies my YouTube tutorial here: http://www.youtube.com/watch?v=BeBfpJnN9SE
Before we get started I am just going to tell you a bit about OLED displays and the benefits of using them. One of the great things about these Adafruit OLEDs is that they are graphic displays... This means that they are not limited to text; you can display all sorts of cool images and games as well (Just take a look below). This is perfect because it really opens up the the variation of projects that you can do. Also these OLEDs have very high resolutions and are very legible, no matter what light you are in. Believe me when I say that 128x64 pixels in a 1" space is plenty: the display looks stunning!

Another benefit of using an OLED display is that they are very low power. This is because the pixels only consume electricity when they are on - so the more black you are showing on your display the less electricity it will be using. Because of this low power usage we will not even need an external power supply - we can simply plug it in to our Pi's 3.3v pin.

Lets get started! View the next page to find out what you will need...

Components list

In this tutorial you will need:

The links to buy these items are on the right hand side of the page =>

A Raspberry Pi.

Either model A or B, it does not matter. Revision number is not important either - this tutorial will work with all Pis! Please make sure that your Raspberry Pi has an SD card with the latest version of Raspbian installed. And also note that your Pi will have to be connected to the internet in this tutorial - otherwise we won't be able to download all of the stuff that we need!
One of Adafruit's monochrome OLED graphic displays.

There are several models available, however this tutorial will only work for the ones that use SPI (I'll explain more about SPI in a second). You'll also need to do a tiny bit of basic soldering in order to attach the pin headers to the PCB but don't worry, you shouldn't have any trouble with that! The picture below is the one I will be using, however if you look down the side you will see all of the ones that are compatible with this guide:
A Breadboard.

It doesn't matter what size or shape your breadboard is! I'm using a half size one:
7 Male to Female Jumper Wires.

You will need no more than 7 Male to Female Jumper Wires - remember that you need these to connect the Pi to your OLED display.

You can also use a Pi Cobbler and some plain jumper wires, but this technique takes up less breadboard space

And that is it! Click on the next page to learn more about how we are going to use our display...
Just before we wire up our OLED display let's learn a little bit about how we are actually going to use it. So, we will be communicating with our display through the SPI pins on the Pi. What is SPI? I won't go into it in too much detail (if you are dying to know then give it a Google), but it is essentially a 4-wire bus... No, not one of the buses that drives around everywhere... In electronics a 'bus' simply describes the wiring of multiple compatible devices together. In our case we will be using it to send data from the Pi to our OLED. SPI stands for Serial Peripheral Interface and it is very useful for a number of reasons - mainly because it is so fast and this is perfect for our display.

We will be communicating with our display through Python. A great, understandable language that is perfect for the Pi. Sadly the tools we need to 'talk' to our OLED are not installed in the default Raspbian image and so we will need to download them ourselves! Don't worry - I have created a nice and easy process that will do this all for us.

Now let's wire up our OLED display!
Now that we understand how we are going to use our display let's connect it up to our Pi! You might find this bit easier to understand if you watch my video tutorial here:

Skip to 1:57 in order to see the wiring up parts!
Also it is worth noting that I am going to refer to the Pi's GPIO pins using their physical names. So try not to get confused. This is the numbering system I will be using:
There is also a circuit diagram at the bottom of the page!

1)
First off insert your OLED display into your breadboard like this:
2) Now grab one of your male to female jumper wires and attach the male end to ground on your OLED display. Then attach the female end to pin 6 on the Pi. Pin 6 is also ground!
3) Using another male to female jumper wire attach the pin on your OLED labelled 'Vin' to pin 1 on your Pi. This is our power line...
4) Now we are going to skip over the pin on our OLED display that is labelled '3v3' - we won't be needing it today... So using a male to female jumper wire connect the pin on your OLED labelled 'CS' to pin 24 on your Pi.
5) Now grab another male to female jumper wire and attach the pin labelled 'Rst' on your OLED display (the reset pin) to pin 8 of your Pi.
6) Now attach the pin labelled DC on your OLED display to pin 10 on your Pi...
7) Now grab your second-to-last male to female jumper wire and attach it to the 'Clk' pin on your OLED display. Then attach the other end to pin 23 on your Pi.
8) Finally grab your last jumper wire and attach the male end to the last remaining pin of your OLED display: the data pin... Then attach the other end to pin 19 on the Pi.
And that is it! That might seem a little complicated but if you just go through it logically and check your wiring then you shouldn't have too much trouble.

Some of you might find it easier to understand a circuit diagram so I have provided one here:
And a little closer up...


Now let's move on to setting up our Pi so we can communicate with our OLED display...

Installing the software

Now that we have our OLED display wired up we can get on and install the necessary software we will need to program it. As I have said before the tools we need to do so aren't included in the default Raspbian image so we are going to need to install them.

The Python library that we will be using to communicate with our display is called py-gaugette and it was created by Guy Carpenter, who has kindly given me permission to use it. The process of installing py-gaugette is quite complicated because it has a lot of dependencies (ie: software that it depends on)... Because it is complicated I have made a simple script to automate the entire process for us. But before we can download and install it we will need to do a few simple commands and modifications. Lets get going.

1) Boot up your Raspberry Pi and login. There will be no need to start up the desktop - all of the stuff we need to do can be accomplished in the terminal!
2) The first thing that we are going to need to install is a piece of software called 'git-core'. This will allow us to download my script and example Python programs. Most of you will already have it but for those that don't simply download it with the command below. If yours is already up to date you will see something like this, however if you need to install it then when it prompts you if you want to continue hit 'y' and then enter!
Download: file
sudo apt-get install git-core
3) Now we need to unblock the SPI pins on the Pi. Sadly these are unusable by default and if we don't unblock them then we will not be able to communicate with our OLED display!

In order to make our SPI pins usable we need to edit the blacklist text file so that it doesn't turn them off when the Pi starts up. This is really easy to do!

To access the text file we will need to use this command:
Download: file
sudo nano /etc/modprobe.d/raspi-blacklist.conf
You should see ^ this appear on your screen. What we are going to do is change this line:
Download: file
blacklist spi-bcm2708
And here is what we are going to change it to... Simply add a hash in front of that line:
Download: file
# blacklist spi-bcm2708
So it should now look like this:

Now exit and save by pressing ctrl+x and when it prompts you whether you want to save press y and then enter...

Finally there's one last step to make sure the I2C kernel modules are loaded at boot.  In the nano text editor open the following file as root with sudo:

sudo nano /etc/modules

Make sure the following two lines are listed in the file, add them if they are not:

i2c-bcm2708
i2c-dev

Then save and exit the editor just like you did for the previous file.


4) The Pi needs to reboot for these additions to take effect so you can do with this command:

Download: file
sudo reboot
5) So now that your Pi has rebooted login again. Remember that you do not need to start up the desktop!

We can now grab that all-in-one script that I mentioned earlier! It is available in my GitHub repository and so you can download it on to your Pi with this command:
Download: file
git clone https://github.com/the-raspberry-pi-guy/OLED
6) Now that we have downloaded my script and my Python examples we can run the installation process. First change into the OLED directory with the command:
Download: file
cd OLED
If we list the contents of that directory we will see a brief README, my python-examples folder and the installation script.
7) Now let's run the installation script, named 'OLEDinstall.sh'... This will download py-gaugette and all its dependencies. It will take around 7 minutes to download and install everything. Run it with this command:
Download: file
sh OLEDinstall.sh


And that is it! Everything we need should now be installed - including the Python examples that I have included. Lets have a look at those and actually get our display to do something!

Programming and using your display

Now that we have everything installed and setup we can finally get on and actually program our display with Python!

I have included 4 Python example programs that cover everything from text to images. Let's navigate to those and take a look at them.

Currently you should be in the OLED directory - our Python programs aren't stored there. They are in the 'python-examples' directory, so let's change into it with the command:
Download: file
cd python-examples
Now if you list the contents of this directory with the command 'ls' you should see 4 Python programs and an image file - more of that in a second!
As you can see the 4 programs are in grey and their names are:

  • OLEDtext.py
  • OLEDip.py
  • OLEDclock.py
  • OLEDimage.py

Now I will explain what the programs do and how to use them!

Displaying text:

So the first one we will take a look at is OLEDtext.py - it is the most basic example of the 4 that I have included. The output of the program is 3 variations of the word 'Hello'... This demonstrates several things, including how positioning and text sizing works. More is explained in the comments of the actual program here:
Download: file
# OLEDtext.py

# This Python code is meant for use with the Raspberry Pi and Adafruit's monochrome displays!

# This program is the simplest in the whole repo. All it does is print 3 'Hello!'s in various forms on the OLED display.
# It illustrates how to change the font size and positioning of text on the OLED... As well as showing how to do 
# basic text!

# This program was created by The Raspberry Pi Guy!

# Imports the necessary libraries... Gaugette 'talks' to the display ;-)
import gaugette.ssd1306
import time
import sys

# Setting some variables for our reset pin etc.
RESET_PIN = 15
DC_PIN    = 16

# Very important... This lets py-gaugette 'know' what pins to use in order to reset the display
led = gaugette.ssd1306.SSD1306(reset_pin=RESET_PIN, dc_pin=DC_PIN)
led.begin()
led.clear_display() # This clears the display but only when there is a led.display() as well!

# led.draw_text2(x-axis, y-axis, whatyouwanttoprint, size) < Understand?
# So led.drawtext2() prints simple text to the OLED display like so:

text = 'Hello!'
led.draw_text2(0,0,text,2)
text2 = 'Hello!'
led.draw_text2(0,16,text2,1)
text3 = 'Hello!'
led.draw_text2(32,25,text3,1)
led.display()
If you read the comments (the parts of the program for humans only, they start in #s) you will soon be able to decipher how to display different text!

How do we run this program? Make sure you are in the python-examples directory and then type this command and hit enter:
Download: file
sudo python OLEDtext.py
Now check your OLED display - you'll see this!

Displaying your internal IP address:

Now that we understand how to print text to our display with the draw text command let's make something a bit more useful. Let's take a look at OLEDip.py... This program grabs your IP address - either from your Wi-Fi dongle or Ethernet cable - and then it writes it to your OLED display. If you don't have an internet connection then it displays 'NO INTERNET!'... Let's take a look at the code:
Download: file
# OLEDip.py

# Meant for use with the Raspberry Pi and an Adafruit monochrome OLED display!

# This program interfaces with the OLED display in order to print your current IP address to it. The program trys
# several methods in order to accquire an IP address. For example if you are using a WiFi dongle your IP will be 
# different to when you are using a Ethernet cable. This program tests for both and if it can not detect one prints:
# 'NO INTERNET!' to the display. This code is perfect to run on boot when you want to find your Pi's IP address for
# SSH or VNC.

# This was coded by The Raspberry Pi Guy!

# Imports all of the necessary modules
import gaugette.ssd1306
import time
import sys
import socket
import fcntl
import struct
from time import sleep

# This function allows us to grab any of our IP addresses
def get_ip_address(ifname):
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    return socket.inet_ntoa(fcntl.ioctl(
        s.fileno(),
        0x8915,  # SIOCGIFADDR
        struct.pack('256s', ifname[:15])
    )[20:24])

# Sets our variables to be used later
RESET_PIN = 15
DC_PIN    = 16
TEXT = ''

led = gaugette.ssd1306.SSD1306(reset_pin=RESET_PIN, dc_pin=DC_PIN)
led.begin()
led.clear_display()

# This sets TEXT equal to whatever your IP address is, or isn't
try:
    TEXT = get_ip_address('wlan0') # WiFi address of WiFi adapter. NOT ETHERNET
except IOError:
    try:
        TEXT = get_ip_address('eth0') # WiFi address of Ethernet cable. NOT ADAPTER
    except IOError:
        TEXT = ('NO INTERNET!')

# The actual printing of TEXT
led.clear_display()
intro = 'Hello!'
ip = 'Your IP Address is:'
led.draw_text2(0,25,TEXT,1)
led.draw_text2(0,0,intro,2)
led.draw_text2(0,16, ip, 1)
led.display()
Read the comments and you will be able to see how this program works!

Now to run this simply type this command:
Download: file
sudo python OLEDip.py
And you should see this appear:

Displaying a scrolling clock:

In the past two programs we did static text - that's useful but wouldn't it be better if it was a bit more... well... scrolly? That is what OLEDclock.py does! This program displays the date (day, month, year) and then scrolls to the current 24 hour time. This program was included in the py-gaugette library by default - I have added a few more comments to it though. Here is the program:
Download: file
# OLEDclock.py

# This program interfaces with one of Adafruit's OLED displays and a Raspberry Pi (over SPI). It displays the current 
# date (Day, Month, Year) and then scrolls to the current time. The program waits for 2 seconds between scrolls.

# Example code from the py-gaugette library... Commented by The Raspberry Pi Guy

# Imports the necessary modules
import gaugette.ssd1306
import time
import sys

# Sets up our pins again
RESET_PIN = 15
DC_PIN    = 16


led = gaugette.ssd1306.SSD1306(reset_pin=RESET_PIN, dc_pin=DC_PIN)
led.begin()
led.clear_display()

offset = 0 # flips between 0 and 32 for double buffering

# While loop has bulk of the code in it!

while True:

    # write the current time to the display on every other cycle
    if offset == 0:
        text = time.strftime("%A")
        led.draw_text2(0,0,text,2)
        text = time.strftime("%e %b %Y")
        led.draw_text2(0,16,text,2)
        text = time.strftime("%X")
        led.draw_text2(0,32+4,text,3)
        led.display()
        time.sleep(1)
    else:
        time.sleep(1)

    # vertically scroll to switch between buffers
    for i in range(0,32):
        offset = (offset + 1) % 64
        led.command(led.SET_START_LINE | offset)
        time.sleep(0.01)
Again have a look at the comments to see how the Python program works!

To run this simply type the command below. Because this is in an infinite loop it will never stop unless you tell it to. Interrupt the program with ctrl+c.
Download: file
sudo python OLEDclock.py
You will see this:

Displaying images:

Now for the grand finale - displaying images on your OLED display. This program is the most complicated... It takes an image and then displays it onto your OLED. It does this by first converting the image and then individually mapping the pixels. More information in the code here:
Download: file
# OLEDimage.py

# Meant for use with the Raspberry Pi and an Adafruit monochrome OLED display!

# This program takes any image (recommended: landscape) and converts it into a black and white image which is then 
# displayed on one of Adafruit's monochrome OLED displays. 

# To run the code simply change directory to where it is saved and then type: sudo python OLEDimage.py <image name>
# For example: sudo python OLEDimage.py penguins900x600.jpg 
# The image penguins900x600.jpg is included in this repo as an example! Download any image that you want and simply change the
# image name!

# This program was created by The Raspberry Pi Guy

# Imports the necessary software - including PIL, an image processing library
import gaugette.ssd1306
import time
import sys
from PIL import Image

# Sets up our pins and creates variables for the size of the display. If using other size display you can easily change them.

RESET_PIN = 15
DC_PIN    = 16
width = 128
height = 32

led = gaugette.ssd1306.SSD1306(reset_pin=RESET_PIN, dc_pin=DC_PIN)
led.begin()
led.clear_display()

# This bit converts our image into black and white and resizes it for the display

image = Image.open(sys.argv[1])
image_r = image.resize((width,height), Image.BICUBIC)
image_bw = image_r.convert("1")

# Finally this bit maps each pixel (depending on whether it is black or white) to the display.
# Note here we are not using the text command like in previous programs. We use led.draw_pixel:
# That way we can individually address each pixel and tell it to be either on or off (on = white, off = black)

for x in range(width):
        for y in range(height):
                led.draw_pixel(x,y,bool(int(image_bw.getpixel((x,y)))))

led.display()
Once again, read the comments so that you can get a better understanding of how the code works...

This Python program it is a little different. This is because we need to tell the Pi what image to convert and then display on our OLED. So your picture will need to be in the same directory as the program. That is the python-examples directory. To run OLEDimage.py we use this command in this format:
Download: file
sudo python OLEDimage.py yourimage.fileextension
So for example purposes let's say that I have a picture of a car saved in my directory as car.png. I would display that on my OLED with this command here:
Download: file
sudo python OLEDimage.py car.png
I have included a picture of a few penguins (because who doesn't like adorable penguins?) as an example picture. They should be saved in your current directory as 'penguins900x600.jpg'

So in order to display that image we do:
Download: file
sudo python OLEDimage.py penguins900x600.jpg
And you should see this:
And just to show that it isn't limited to that take a look at a few of these pictures:

Congratulations! You have successfully got your OLED display to work! Click on the next page for the conclusion and challenge...

Conclusion and challenge

And so concludes my guide on how to get one of Adafruit's monochrome OLED displays working with the Raspberry Pi. We have covered everything from wiring up our display to programming it in Python. Well done! What are you going to get up to with your OLED display? Have you got a killer project in mind? Let me know! I can be reached at: [email protected]

I hope that you have enjoyed this tutorial and if you have you might find it interesting to check out some of my other Raspberry Pi tutorials here: www.youtube.com/theraspberrypiguy

Challenge:

How about you tie everything that you have learnt together and create a scrolling picture viewer? Make it so that it displays all of the images in a certain directory and have it scroll vertically between them every few seconds! Send me a picture or short video when you have finished it!


That's all folks! Until next time!

Matt

The Raspberry Pi Guy
www.youtube.com/theraspberrypiguy
www.theraspberrypiguy.com
@RaspberryPiGuy1
[email protected]
This guide was first published on Jan 03, 2014. It was last updated on Jan 03, 2014.