CircuitPython and Python Usage

It's easy to use OLEDs with CircuitPython and the Adafruit CircuitPython SSD1306 module.  This module allows you to easily write Python code to control the display.

You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.

To demonstrate the usage, we'll initialise the library and use Python code to control the OLED from the board's Python REPL.

I2C Initialization

If your display is connected to the board using I2C (like if using a Feather and the FeatherWing OLED) you'll first need to initialize the I2C bus.  First import the necessary modules:

Download: file
import board
import busio

Now for either board run this command to create the I2C instance using the default SCL and SDA pins (which will be marked on the boards pins if using a Feather or similar Adafruit board):

Download: file
i2c = busio.I2C(board.SCL, board.SDA)

After initializing the I2C interface for your firmware as described above you can create an instance of the SSD1306 I2C driver by running:

Download: file
import adafruit_ssd1306
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)

Note that the first two parameters to the SSD1306_I2C class initializer are the width and height of the display in pixels.  Be sure to use the right values for the display you're using!

128 x 64 size OLEDs (or changing the I2C address)

If you are using a 128x64 display, the I2C address is probably different (0x3d), unless you've changed it by soldering some jumpers:

Download: file
oled = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c, addr=0x3d)

Adding hardware reset pin

If you have a reset pin (which may be required if your OLED does not have an auto-reset chip like the FeatherWing) also pass in a reset pin like so:

Download: file
import digitalio

reset_pin = digitalio.DigitalInOut(board.D9) # any pin!
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c, reset=reset_pin)

If you're using a Raspberry Pi, run the following commands:

Download: file
import digitalio

reset_pin = digitalio.DigitalInOut(board.D4) # any pin!
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c, reset=reset_pin)

At this point the I2C bus and display are initialized. Skip down to the drawing section.

SPI Initialization

If your display is connected to the board using SPI you'll first need to initialize the SPI bus. 

If you're using a microcontroller board, run the following commands:

Download: file
import adafruit_ssd1306
import board
import busio
import digitalio

spi = busio.SPI(board.SCK, MOSI=board.MOSI)
dc_pin = digitalio.DigitalInOut(board.D6)    # any pin!
reset_pin = digitalio.DigitalInOut(board.D9) # any pin!
cs_pin = digitalio.DigitalInOut(board.D5)    # any pin!

oled = adafruit_ssd1306.SSD1306_SPI(128, 32, spi, dc_pin, reset_pin, cs_pin)

Note the first two parameters to the SSD1306_SPI class initializer are the width and height of the display in pixels.  Be sure to use the right values for the display you're using!

The next parameters to the initializer are the pins connected to the display's DCreset, and CS lines in that order.  Again make sure to use the right pin names as you have wired up to your board!

Drawing

The SSD1306 module currently supports a basic set of commands to draw on the display.  You can set individual pixels, fill the screen, and write lines of text. 

To fill or clear the entire screen use the fill function.  This function takes a parameter which specifies the color to fill with, either 0 for black or 1 for white.  For example to fill the screen white:

Download: file
oled.fill(1)
oled.show()

Notice the fill function doesn't actually change the display.  You must call show after making drawing commands to send the updated pixel data to the display!

To clear the screen to black just call fill again but with the color 0:

Download: file
oled.fill(0)
oled.show()

To set a pixel use the pixel function.  This function takes the following parameters:

  • Pixel X position
  • Pixel Y position
  • Pixel color (0 = black, 1 = white)

For example to set the first pixel white:

Download: file
oled.pixel(0, 0, 1)
oled.show()

Try setting other pixels white by changing the X and Y position.  Remember you have to call show after setting pixels to see them appear!

Text

To write text to your display, you must download a font file and copy it to your CIRCUITPY drive. Click the button below to download the file, and then copy font5x8.bin to your CIRCUITPY drive.

You can write a line of text with the text function.  This function takes the following parameters:

  • String of text
  • Text X position
  • Text Y position
  • Text color (0 = black, 1 = white)

For example to clear the screen and then write two lines of text:

Download: file
oled.fill(0)
oled.text('Hello', 0, 0, 1)
oled.text('World', 0, 10, 1)
oled.show()

Notice the second line of text starts at Y position 10, this moves it down the display 10 pixels so it's below the first line of text.  The font used by the text function is 8 pixels tall so a size of 10 gives a bit of room between the lines.

Invert

Finally you can invert the display colors with the invert function:

Download: file
oled.invert(True)

Note that the invert function doesn't need to have show called after it to see the change.

To go back to a non-inverted display run:

Download: file
oled.invert(False)

That's all there is to drawing on the SSD1306 OLED display with CircuitPython!  The drawing functions are basic but provide building blocks for more advanced usage.  For example you can display text with sensor readings or other state, or even program a simple game like pong!

Full Example Code

# Basic example of clearing and drawing pixels on a SSD1306 OLED display.
# This example and library is meant to work with Adafruit CircuitPython API.
# Author: Tony DiCola
# License: Public Domain

# Import all board pins.
from board import SCL, SDA
import busio

# Import the SSD1306 module.
import adafruit_ssd1306


# Create the I2C interface.
i2c = busio.I2C(SCL, SDA)

# Create the SSD1306 OLED class.
# The first two parameters are the pixel width and pixel height.  Change these
# to the right size for your display!
display = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)
# Alternatively you can change the I2C address of the device with an addr parameter:
#display = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c, addr=0x31)

# Clear the display.  Always call show after changing pixels to make the display
# update visible!
display.fill(0)
display.show()

# Set a pixel in the origin 0,0 position.
display.pixel(0, 0, 1)
# Set a pixel in the middle 64, 16 position.
display.pixel(64, 16, 1)
# Set a pixel in the opposite 127, 31 position.
display.pixel(127, 31, 1)
display.show()
This guide was first published on Apr 26, 2016. It was last updated on Apr 26, 2016. This page (CircuitPython and Python Usage) was last updated on May 20, 2019.