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...
This guide was first published on Jan 03, 2014. It was last updated on Jan 03, 2014. This page (Programming and using your display) was last updated on Jul 22, 2019.