Skip to content

adafruit_displayio_ssd1306

Works with

Any board with I2C (or SPI). Most commonly used with Feather, Metro, QT Py, and similar boards. The SSD1306 chip drives the common 128x64 and 128x32 monochrome OLED breakouts.

What it does

Drives SSD1306-based monochrome OLED displays over I2C or SPI using CircuitPython's displayio framework. Once initialized, the display behaves like any other displayio display — you attach a Group, add Label and shape objects, and the display renders them automatically. Supports the common 0.96" (128x64) and 0.91" (128x32) OLED sizes.

Installing the library

Copy adafruit_displayio_ssd1306.mpy and the adafruit_bus_device/ folder from the bundle's lib/ folder to your board's lib/ folder.

Quick start

import board
import busio
import displayio
import terminalio
from adafruit_displayio_ssd1306 import SSD1306
from adafruit_display_text import label

# Required before any displayio setup
displayio.release_displays()

i2c = busio.I2C(board.SCL, board.SDA)
display_bus = displayio.I2CDisplay(i2c, device_address=0x3C)

# 128x64 display
display = SSD1306(display_bus, width=128, height=64)

# Build a display group and add a text label
splash = displayio.Group()
display.root_group = splash

text_label = label.Label(terminalio.FONT, text="Hello world", color=0xFFFFFF, x=5, y=20)
splash.append(text_label)
# The display refreshes automatically

Key things you can do

What you want How to do it
Initialize over I2C displayio.I2CDisplay(i2c, device_address=0x3C)
Initialize over SPI displayio.FourWire(spi, command=dc_pin, chip_select=cs_pin)
Use alternate I2C address Pass device_address=0x3D (when SA0 pin is high)
Show content Append objects to a displayio.Group, set as display.root_group
Clear the screen display.root_group = displayio.Group()
Invert display colors display.invert = True
Adjust contrast display.contrast = 128 (0–255)

Always call displayio.release_displays() first

If you forget this line and re-run your code (e.g., after a save), the display bus from the previous run is still allocated and initialization will fail with a resource error.

Reading the official docs

https://docs.circuitpython.org/projects/displayio-ssd1306/en/latest/

The API reference documents the full constructor signature including rotation and auto_refresh parameters. For drawing content (text, shapes, bitmaps), you will also need the adafruit_display_text and adafruit_display_shapes library docs — the SSD1306 library only handles the display driver; all graphics go through displayio.

Projects using this library

  • CircuitPython Display Support Using displayio — Comprehensive guide to the displayio system; uses SSD1306 as one of the example displays. Credit: Adafruit Learning System
  • Monochrome OLED Breakouts — Hardware guide for Adafruit's 128x32 and 128x64 OLED boards with CircuitPython wiring and code. Credit: Adafruit Learning System
  • OLED FeatherWing — Covers the FeatherWing version of the 128x32 OLED including the three onboard buttons. Credit: Adafruit Learning System