Skip to main content
Adafruit 128x64 OLED Bonnet for Raspberry Pi

Adafruit 128x64 OLED Bonnet for Raspberry Pi

Image for user adafruit2
by lady ada
published June 09, 2017, last updated October 06, 2024
posted in Raspberry Pi/ Pi A+, B+, 2, 3 Raspberry Pi/ Pi Zero LCDs & Displays/ OLED
Save Subscribe Download
23
Beginner
Product guide

Overview

If you'd like a compact display, with buttons and a joystick - we've got what you're looking for. The Adafruit 128x64 OLED Bonnet for Raspberry Pi is the big sister to our mini PiOLED add-on. This version has 128x64 pixels (instead of 128x32) and a much larger screen besides. With the OLED display in the center, we had some space on either side so we added a 5-way joystick and two pushbuttons. Great for when you want to have a control interface for your project.

raspberry_pi_3531_iso_demo_ORIG.jpg

These displays are small, only about 1.3" diagonal, but very readable due to the high contrast of an OLED display. This screen is made of 128x64 individual white OLED pixels and because the display makes its own light, no backlight is required. This reduces the power required to run the OLED and is why the display has such high contrast; we really like this miniature display for its crispness!

raspberry_pi_3531_top_lit_demo_ORIG.jpg

Please note that this display is too small to act as a primary display for the Pi (e.g. it can't act like or display what would normally be on the HDMI screen). Instead, we recommend using pygame for drawing or writing text.

Using the display and controls in python is very easy, we have a library ready-to-go for the SSD1306 OLED chipset and the joystick/buttons are connected to GPIO pins on the Pi. Our example code allows you to draw images, text, whatever you like, using the Python imaging library. We also have example code for using the joystick/buttons/OLED together. Our tests showed 15 FPS update rates once you bump the I2C speed to 1MHz, so you can do animations or simple video.

raspberry_pi_3531_revised_quarter_ORIG.jpg

Comes completely pre-assembled and tested so you don't need to do anything but plug it in and install our Python code! Works with any Raspberry Pi computer, including the original Pi 1, B+, Pi 2, Pi 3 and Pi Zero.

Text editor powered by tinymce.

This guide assumes you have your Raspberry Pi all set up with an operating system, network connectivity and SSH!

Install CircuitPython 

This guide assumes that you've gotten your Raspberry Pi up and running, and have CircuitPython installed. If not, check out the guide:

To install the library for the Pi OLED, enter the following into the terminal:

Download File
Copy Code 
sudo pip3 install adafruit-circuitpython-ssd1306

If that complains about pip3 not being installed, then run this first to install it:

Download File
Copy Code 
sudo apt-get install python3-pip

We also need PIL to allow using text with custom fonts. There are several system libraries that PIL relies on, so installing via a package manager is the easiest way to bring in everything:

Download File
Copy Code 
sudo apt-get install python3-pil

Enable I2C

To enable i2c, you can follow our detailed guide on configuring the Pi with I2C support here.

You also need to install Blinka support as detailed here

After you've enabled I2C you will need to shutdown with sudo shutdown -h now

Once the Pi has halted, plug in the PiOLED. Now you can power the Pi back up, and log back in. Run the following command from a terminal prompt to scan/detect the I2C devices

sudo i2cdetect -y 1

You should see the following, indicating that address 0x3c (the OLED display) was found

pi_a___b___2__3_raspberry_pi_adafruit_products_i2c.png

Verify I2C Device

You can run our buttons example, which will let you press various buttons and see them mimicked on the OLED.

Create a new file with nano ~pi/bonnet_buttons.py and paste this code below in! Then save it.

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2017 James DeVito for Adafruit Industries
# SPDX-License-Identifier: MIT

# This example is for use on (Linux) computers that are using CPython with
# Adafruit Blinka to support CircuitPython libraries. CircuitPython does
# not support PIL/pillow (python imaging library)!

import board
import busio
from digitalio import DigitalInOut, Direction, Pull
from PIL import Image, ImageDraw
import adafruit_ssd1306

# Create the I2C interface.
i2c = busio.I2C(board.SCL, board.SDA)
# Create the SSD1306 OLED class.
disp = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c)


# Input pins:
button_A = DigitalInOut(board.D5)
button_A.direction = Direction.INPUT
button_A.pull = Pull.UP

button_B = DigitalInOut(board.D6)
button_B.direction = Direction.INPUT
button_B.pull = Pull.UP

button_L = DigitalInOut(board.D27)
button_L.direction = Direction.INPUT
button_L.pull = Pull.UP

button_R = DigitalInOut(board.D23)
button_R.direction = Direction.INPUT
button_R.pull = Pull.UP

button_U = DigitalInOut(board.D17)
button_U.direction = Direction.INPUT
button_U.pull = Pull.UP

button_D = DigitalInOut(board.D22)
button_D.direction = Direction.INPUT
button_D.pull = Pull.UP

button_C = DigitalInOut(board.D4)
button_C.direction = Direction.INPUT
button_C.pull = Pull.UP


# Clear display.
disp.fill(0)
disp.show()

# 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)


while True:
    if button_U.value:  # button is released
        draw.polygon([(20, 20), (30, 2), (40, 20)], outline=255, fill=0)  # Up
    else:  # button is pressed:
        draw.polygon([(20, 20), (30, 2), (40, 20)], outline=255, fill=1)  # Up filled

    if button_L.value:  # button is released
        draw.polygon([(0, 30), (18, 21), (18, 41)], outline=255, fill=0)  # left
    else:  # button is pressed:
        draw.polygon([(0, 30), (18, 21), (18, 41)], outline=255, fill=1)  # left filled

    if button_R.value:  # button is released
        draw.polygon([(60, 30), (42, 21), (42, 41)], outline=255, fill=0)  # right
    else:  # button is pressed:
        draw.polygon(
            [(60, 30), (42, 21), (42, 41)], outline=255, fill=1
        )  # right filled

    if button_D.value:  # button is released
        draw.polygon([(30, 60), (40, 42), (20, 42)], outline=255, fill=0)  # down
    else:  # button is pressed:
        draw.polygon([(30, 60), (40, 42), (20, 42)], outline=255, fill=1)  # down filled

    if button_C.value:  # button is released
        draw.rectangle((20, 22, 40, 40), outline=255, fill=0)  # center
    else:  # button is pressed:
        draw.rectangle((20, 22, 40, 40), outline=255, fill=1)  # center filled

    if button_A.value:  # button is released
        draw.ellipse((70, 40, 90, 60), outline=255, fill=0)  # A button
    else:  # button is pressed:
        draw.ellipse((70, 40, 90, 60), outline=255, fill=1)  # A button filled

    if button_B.value:  # button is released
        draw.ellipse((100, 20, 120, 40), outline=255, fill=0)  # B button
    else:  # button is pressed:
        draw.ellipse((100, 20, 120, 40), outline=255, fill=1)  # B button filled

    if not button_A.value and not button_B.value and not button_C.value:
        catImage = Image.open("happycat_oled_64.ppm").convert("1")
        disp.image(catImage)
    else:
        # Display image.
        disp.image(image)

    disp.show()
View on GitHub

Run sudo python3 bonnet_buttons.py to run the demo, you should see something like the below:

pi_a___b___2__3_raspberry_pi_3531_iso_demo_ORIG.jpg

Press buttons to interact with the demo. Press the joystick + buttons at once for an Easter egg!

Running Scripts on Boot

You can pretty easily make it so this program (or whatever program you end up writing) run every time you boot your Pi.

The fastest/easiest way is to put it in /etc/rc.local

Run sudo nano /etc/rc.local and add the line

sudo python /home/pi/bonnet_buttons.py  &

on its own line right before exit 0

Then save and exit. Reboot to verify that the screen comes up on boot!

pi_a___b___2__3_bonnetbtns.png

For more advanced usage, check out our linux system services guide

Library Usage

In the examples subdirectory of the Adafruit_CircuitPython_SSD1306 repository, you'll find more examples which demonstrate the usage of the library.

To help you get started, I'll walk through the bonnet_buttons.py code below, that way you can use this file as the basis of a future project.

Python Library Setup

Download File
Copy Code 
import board
import busio
from digitalio import DigitalInOut, Direction, Pull
from PIL import Image, ImageDraw
import adafruit_ssd1306

First, a few modules are imported, including the adafruit_ssd1306 module which contains the OLED driver classes. The code also imports board (containing the Raspbery Pi pin definitions), busio (communication with the i2c and spi buses), and digitalio (to control the Raspberry Pi's pins).

You can also see some of the Python Imaging Library modules like Image, ImageDraw, and ImageFont being imported. Those are, as you can imagine, are for drawing images, shapes and text/fonts!

Display Setup

Download File
Copy Code 
# Create the I2C interface.
i2c = busio.I2C(board.SCL, board.SDA)
# Create the SSD1306 OLED class.
disp = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c)

The next bit of code creates the I2C interface (which the display on the bonnet communicates over) and creates a SSD1306 OLED class. Note that we are passing SSD1306_I2C 128 and 64, those values correspond to the bonnet's OLED display.

Pin Setup

Download File
Copy Code 
# Input pins:
button_A = DigitalInOut(board.D5)
button_A.direction = Direction.INPUT
button_A.pull = Pull.UP

button_B = DigitalInOut(board.D6)
button_B.direction = Direction.INPUT
button_B.pull = Pull.UP

button_L = DigitalInOut(board.D27)
button_L.direction = Direction.INPUT
button_L.pull = Pull.UP

button_R = DigitalInOut(board.D23)
button_R.direction = Direction.INPUT
button_R.pull = Pull.UP

button_U = DigitalInOut(board.D17)
button_U.direction = Direction.INPUT
button_U.pull = Pull.UP

button_D = DigitalInOut(board.D22)
button_D.direction = Direction.INPUT
button_D.pull = Pull.UP

button_C = DigitalInOut(board.D4)
button_C.direction = Direction.INPUT
button_C.pull = Pull.UP

Next up we define the pins that are used for the joystick and buttons. The Joystick has Left, Right, Center (press in), Up and Down. There's also the A and B buttons on the right. Each one should be set as an input with pull-up resistor (Pull.UP in the code)

Display Initialization

Download File
Copy Code 
# Clear display.
disp.fill(0)
disp.show()

# 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 chunk of code clears the display by inverting its fill with fill(0) and then writing to the display with show().

Then it will 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.

We then re-draw a large black rectangle to clear the screen. In theory we don't have to clear the screen again, but its a good example of how to draw a shape!

Button Input and Drawing

Download File
Copy Code 
while True:
    if button_U.value: # button is released
        draw.polygon([(20, 20), (30, 2), (40, 20)], outline=255, fill=0)  #Up
    else: # button is pressed:
        draw.polygon([(20, 20), (30, 2), (40, 20)], outline=255, fill=1)  #Up filled

    if button_L.value: # button is released
        draw.polygon([(0, 30), (18, 21), (18, 41)], outline=255, fill=0)  #left
    else: # button is pressed:
        draw.polygon([(0, 30), (18, 21), (18, 41)], outline=255, fill=1)  #left filled

    if button_R.value: # button is released
        draw.polygon([(60, 30), (42, 21), (42, 41)], outline=255, fill=0) #right
    else: # button is pressed:
        draw.polygon([(60, 30), (42, 21), (42, 41)], outline=255, fill=1) #right filled

    if button_D.value: # button is released
        draw.polygon([(30, 60), (40, 42), (20, 42)], outline=255, fill=0) #down
    else: # button is pressed:
        draw.polygon([(30, 60), (40, 42), (20, 42)], outline=255, fill=1) #down filled

    if button_C.value: # button is released
        draw.rectangle((20, 22, 40, 40), outline=255, fill=0) #center
    else: # button is pressed:
        draw.rectangle((20, 22, 40, 40), outline=255, fill=1) #center filled

    if button_A.value: # button is released
        draw.ellipse((70, 40, 90, 60), outline=255, fill=0) #A button
    else: # button is pressed:
        draw.ellipse((70, 40, 90, 60), outline=255, fill=1) #A button filled

    if button_B.value: # button is released
        draw.ellipse((100, 20, 120, 40), outline=255, fill=0) #B button
    else: # button is pressed:
        draw.ellipse((100, 20, 120, 40), outline=255, fill=1) #B button filled

    if not button_A.value and not button_B.value and not button_C.value:
        catImage = Image.open('happycat_oled_64.ppm').convert('1')
        disp.image(catImage)
    else:
        # Display image.
        disp.image(image)

    disp.show()

Once the display is initialized and a drawing object is prepared, you can draw shapes, text and graphics using PIL's drawing commands.

This is a basic polling example - we'll check each button.value in order, and draw a different shape - a directional arrow or a round circle) depending on whether the button is pressed. If the button is pressed we have the shape filled in. If the button is not pressed, we draw an outline only

Then we run disp.image(image) and disp.show() to actually push the updated image to the OLED. This is required to actually make the changes appear!

Speeding up the Display

For the best performance, especially if you are doing fast animations, you'll want to tweak the I2C core to run at 1MHz. By default it may be 100KHz or 400KHz

To do this edit the config with sudo nano /boot/config.txt

and add to the end of the file

dtparam=i2c_baudrate=1000000

pi_a___b___2__3_adafruit_products_i2c_baud.png

reboot to 'set' the change.

Text editor powered by tinymce.

Files

Software

Schematic & Fabrication Print

Dimensions in mm

raspberry_pi_schem.png
raspberry_pi_print.png

Text editor powered by tinymce.

Related Guides
Introducing the Raspberry Pi 2 - Model B
By lady ada
12
Beginner
Adafruit MacroPad RP2040
By Kattni Rembor
257
Beginner
Updated
Battery Powered Raspberry Pi Displays w/RaspiRobot...
By Simon Monk
10
Beginner
Raspberry Pi SelfieBlock
By Thijs S
7
Beginner
Super Game Pi
By Ruiz Brothers
128
Intermediate
Adding Basic Audio Ouput to Raspberry Pi Zero
By lady ada
64
Beginner
Adafruit Pi Box Plus
By Phillip Burgess
2
Beginner
Google Glass talks to Raspberry Pi with XMPP
By Deqing Sun
5
Intermediate
Adafruit PiTFT 3.5" Touch Screen for Raspberry Pi
By lady ada
95
Beginner
Running Minecraft on a Raspberry Pi
By Simon Monk
7
Beginner
Running Programs Automatically on Your Tiny Computer
By Brennen Bearnes
70
Beginner
DotStar Pi Painter
By Phillip Burgess
120
Intermediate
Updated
Adafruit's Raspberry Pi Lesson 11. DS18B20...
By Simon Monk
90
Beginner
Adafruit 2.2" PiTFT HAT - 320x240 Display
By lady ada
24
Beginner
Updated
Adafruit Grayscale 1.5" 128x128 OLED Display
By M. LeBlanc-Williams
18
Beginner
Search

Search

Categories