Usage

Save Subscribe
This code is discontinued - Check out our newer tutorial at - https://learn.adafruit.com/monochrome-oled-breakouts/python-wiring

Dependencies

Before using the library you will need to make sure you have a few dependencies installed. Connect to your device using SSH and follow the steps below.


If you're using a Raspberry Pi, install the RPi.GPIO library by executing:
sudo apt-get update
sudo apt-get install build-essential python-dev python-pip
sudo pip install RPi.GPIO


If you're using a BeagleBone Black, install the Adafruit_BBIO library by executing:
sudo apt-get update
sudo apt-get install build-essential python-dev python-pip
sudo pip install Adafruit_BBIO

Finally, on both the Raspberry Pi and Beaglebone Black install the Python Imaging Library and smbus library by executing:
sudo apt-get install python-imaging python-smbus

Now to download and install the SSD1306 python library code and examples, execute the following commands:
sudo apt-get install git
git clone https://github.com/adafruit/Adafruit_Python_SSD1306.git
cd Adafruit_Python_SSD1306
sudo python setup.py install

Usage

Inside the examples subdirectory you'll find python scripts which demonstrate the usage of the library. To help you get started, I'll walk through the shapes.py code below:
Download File
Copy Code 
import time

import Adafruit_GPIO.SPI as SPI
import Adafruit_SSD1306

import Image
import ImageDraw
import ImageFont
First a few modules are imported, including the Adafruit_SSD1306 module which contains the OLED display driver classes. You can also see some of the Python Imaging Library modules like Image, ImageDraw, and ImageFont being imported.
Download File
Copy Code 
# Raspberry Pi pin configuration:
RST = 24
# Note the following are only used with SPI:
DC = 23
SPI_PORT = 0
SPI_DEVICE = 0

# Beaglebone Black pin configuration:
# RST = 'P9_12'
# Note the following are only used with SPI:
# DC = 'P9_15'
# SPI_PORT = 1
# SPI_DEVICE = 0

Next some configuration values are set depending on the platform.  If you're using the BeagleBone Black you'll need to comment the Raspberry Pi pin configuration lines and uncomment the BeagleBone Black configuration lines.

If you want to change to a different RST or DC pin, you can update the RST and DC pin values respectively. You can also change the SPI port and device, but I recommend sticking with those interfaces above as they've been tested and are known to work.

Download File
Copy Code 
# 128x32 display with hardware I2C:
disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST)

# 128x64 display with hardware I2C:
# disp = Adafruit_SSD1306.SSD1306_128_64(rst=RST)

# Alternatively you can specify an explicit I2C bus number, for example
# with the 128x32 display you would use:
# disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST, i2c_bus=2)

# 128x32 display with hardware SPI:
# disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST, dc=DC, spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=8000000))

# 128x64 display with hardware SPI:
# disp = Adafruit_SSD1306.SSD1306_128_64(rst=RST, dc=DC, spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=8000000))

# Alternatively you can specify a software SPI implementation by providing
# digital GPIO pin numbers for all the required display pins.  For example
# on a Raspberry Pi with the 128x32 display you might use:
# disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST, dc=DC, sclk=18, din=25, cs=22)

Below the configuration values is the display class setup. There are two classes you can create, SSD1306_128_32 or SSD1306_128_64. The SSD1306_128_32 class represents a 128x32 pixel display, and the SSD1306_128_64 class represents a 128x64 pixel display.

Along with the size of the display you also configure what interface the display uses in these lines. The first couple examples use the I2C interface and only need to specify an RST pin. Internally the SSD1306 library will look up the default I2C bus number for the platform and use it--if you've followed the wiring in this guide you should be all set! However if you need to explicitly control the I2C bus number, the third example shows how to specify it with an i2c_bus parameter.

The last three examples show how to configure the SPI interface. For hardare-based SPI you only need to specify the RST pin, DC pin, and hardware SPI device. Use one of these examples if you've followed the wiring in this guide. However if you want to use a software-based SPI interface, the last example shows how to specify each SPI pin for a Raspberry Pi (for a BeagleBone Black just change the pin values based on the pins you're using).

Uncomment the appropriate display line based on the size of your display and the interface you're using to talk to the display.  The code assumes you're using a 128x32 pixel display that's communicating over hardware I2C, however if you're using a different display or protocol uncomment the appropriate line.  Make sure to comment all the other lines that aren't being used!

Download File
Copy Code 
# Initialize library.
disp.begin()

# Clear display.
disp.clear()
disp.display()

# Create blank image for drawing.
# Make sure to create image with mode '1' for 1-bit color.
width = disp.width
height = disp.height
image = Image.new('1', (width, height))

# Get drawing object to draw on image.
draw = ImageDraw.Draw(image)

# Draw a black filled box to clear the image.
draw.rectangle((0,0,width,height), outline=0, fill=0)
The next bit of code will initialize the display library, clear the display, and configure a PIL drawing class to prepare for drawing graphics. Notice that the image buffer is created in 1-bit mode with the '1' parameter, this is important because the display only supports black and white colors.
Download File
Copy Code 
# Draw some shapes.
# First define some constants to allow easy resizing of shapes.
padding = 2
shape_width = 20
top = padding
bottom = height-padding
# Move left to right keeping track of the current x position for drawing shapes.
x = padding
# Draw an ellipse.
draw.ellipse((x, top , x+shape_width, bottom), outline=255, fill=0)
x += shape_width+padding
# Draw a rectangle.
draw.rectangle((x, top, x+shape_width, bottom), outline=255, fill=0)
x += shape_width+padding
# Draw a triangle.
draw.polygon([(x, bottom), (x+shape_width/2, top), (x+shape_width, bottom)], outline=255, fill=0)
x += shape_width+padding
# Draw an X.
draw.line((x, bottom, x+shape_width, top), fill=255)
draw.line((x, top, x+shape_width, bottom), fill=255)
x += shape_width+padding
Once the display is initialized and a drawing object is prepared, you can draw shapes and graphics using PIL's drawing commands. The code first does a little work to scale drawings based on the display size, then it moves left to right drawing each shape.
Download File
Copy Code 
# Load default font.
font = ImageFont.load_default()

# Alternatively load a TTF font.
# Some other nice fonts to try: http://www.dafont.com/bitmap.php
#font = ImageFont.truetype('Minecraftia.ttf', 8)

# Write two lines of text.
draw.text((x, top),    'Hello',  font=font, fill=255)
draw.text((x, top+20), 'World!', font=font, fill=255)
Next the code loads a built-in default font and draws a few lines of text. You can also load your own TrueType font and use it to render text!
Download File
Copy Code 
# Display image.
disp.image(image)
disp.display()
Finally the image that was created is written to the display buffer, and the display is told to show its buffer. Remember, every time you make a change to the image that you want it to be visible on the display you need to call the image and display functions!

That's all there is to the shapes.py code! You can run the code by executing this command in the examples directory:
sudo python shapes.py

Make sure to run as root with the sudo command so the program has access to the hardware.

If you run the shapes.py example you should see something like this (on a 128x64 display):
raspberry_pi_DSC00468_copy.jpg
Check out the other examples included in the library, such as animate.py which displays an animated text scroller and image.py which displays an image loaded from a file. Modify the configuration at the top of each example just like you did for the shapes.py example above, then run them just like running shapes.py but substituting the appropriate file name.

Enjoy using your OLED display with a Raspberry Pi or BeagleBone Black! If you have issues or want to contribute to the library, feel free to do so on the library's GitHub home.
 Wiring

This guide was first published on Jun 25, 2014. It was last updated on Jun 25, 2014.

This page (Usage) was last updated on Jun 24, 2014.

Text editor powered by tinymce.