How to use an OLED display with CircuitPython

In this simple guide we will be using a widely available SSD1306 OLED display with the Raspberry Pi Pico to display some basic shapes. For this guide we will use CircuitPython and Adafruit helper libraries.

What you need

• Raspberry Pi Pico or compatible board with CircuitPython installed
• SSD1306 OLED display
• Breadboard and 4 jumper wires

Wiring

Connect OLED display power in to existing 3v3 OUT and ground to any ground pin on Raspberry Pi Pico. Now connect SCL from OLED to Pin GP17 and SDA to Pin GP16 on the Raspberry Pi Pico.

Connect the Raspberry Pi Pico to USB and we are now ready to program.

Libraries

Download the following Adafruit CircuitPython libraries for SSD1306, unzip and place copy the files to your board. This Zip contains adafruit_framebuf and adafruit_ssd1306 CircuitPython scripts.

The code

Finally the fun part! let's try to create simple eyes using the existing shape helpers defined in the libraries. Once you know the basics, you can take it far.

Create a new file and name it code.py. Now import the required libraries and define connection and display objects, see the inline comments for details. adafruit_ssd1306 depends on adafruit_framebuf so you must have both scripts copied to your board.

import time
import board
import busio # to communicate over I2C

# Helper print to see whats available on the connected board
print(dir(board))

# Import the SSD1306 module, see the lib downloads on this page
import adafruit_ssd1306

# Create the I2C interface for OLED, use any pins you like, we are going with GP0 (SDA) & GP1 (SCL)
# busio.I2C(SCL, SDA)
i2c = busio.I2C(board.GP17, board.GP16)
display = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c)

Save the code to the board and run code.py to check for error, if there are any errors check to make sure if you are running CircuitPython and have downloaded the mentioned libraries.

We are now ready to draw shapes. Let's define a method 'eyes' which takes a single argument and display circles at different positions and type based on the argument.

# Eyes graphic type
EYES_NORMAL = 0
EYES_AFRAID = 1
EYES_SPINNING = 2
EYES_BLINK = 3

def eyes(type):
    display.fill(0) # clear
    if type == EYES_NORMAL:
        display.circle(47, 30, 10, 1)
        display.circle(82, 30, 10, 1)
    elif type == EYES_AFRAID:
        display.circle(47, 64, 10, 1)
        display.circle(82, 64, 10, 1)
    elif type == EYES_SPINNING:
        display.circle(47, 30, 4, 1)
        display.circle(47, 30, 7, 1)
        display.circle(47, 30, 10, 1)
        display.circle(47, 30, 13, 1)
        display.circle(82, 30, 4, 1)
        display.circle(82, 30, 7, 1)
        display.circle(82, 30, 10, 1)
        display.circle(82, 30, 13, 1)
    elif type == EYES_BLINK:
        display.circle(82, 30, 10, 1)
    display.show() # show

Now we have all imports and methods ready and we can start displaying some simple but really cool eyes.

while True:
    eyes(EYES_NORMAL)
    time.sleep(1)
    eyes(EYES_BLINK)
    time.sleep(0.1)
    eyes(EYES_NORMAL)
    time.sleep(1)
    eyes(EYES_AFRAID)
    time.sleep(1)
    eyes(EYES_NORMAL)
    time.sleep(1)
    eyes(EYES_SPINNING)
    time.sleep(1)

Save everything to the board and run code.py - If everything is connected properly, you should now see your OLED display come to life.

Since we have named our script code.py, whenever you will connect the Raspberry Pi Pico to the power it will automatically run.

File adafruit_framebuf.py defines many different shapes which you can explore and display pretty much anything. Use the pixel method to display complex shapes.

Hope you have learned something new today. Ohh, before we go, now that you know how to display graphics, how about combining it with a simple motion detector? Here is a handy guide for you - Tilt ball switch as a vibration sensor.