How to Use OLED Display SSD1306 with Raspberry Pi

To use an SSD1306 OLED display with a Raspberry Pi, connect it via I2C pins and install the Adafruit SSD1306 Python library. Then, write a Python script to initialize the display and show text or graphics using the library's functions.

Syntax

Here is the basic syntax to initialize and use the SSD1306 OLED display with Raspberry Pi in Python:

• import board, busio: Import I2C communication modules.
• import adafruit_ssd1306: Import the SSD1306 display driver.
• i2c = busio.I2C(board.SCL, board.SDA): Set up I2C communication using Raspberry Pi pins.
• display = adafruit_ssd1306.SSD1306_I2C(width, height, i2c): Create display object with screen size.
• display.fill(0): Clear the display.
• display.text('Your Text', x, y, color): Write text at position (x,y).
• display.show(): Update the display to show changes.

python

import board
import busio
import adafruit_ssd1306

# Initialize I2C interface

i2c = busio.I2C(board.SCL, board.SDA)

# Create SSD1306 OLED display object
width = 128
height = 64
display = adafruit_ssd1306.SSD1306_I2C(width, height, i2c)

# Clear display

display.fill(0)
display.show()

# Write text

display.text('Hello, Pi!', 0, 0, 1)
display.show()

Example

This example shows how to initialize the SSD1306 OLED display on Raspberry Pi and display the message "Hello, Pi!" on the screen.

python

import board
import busio
import adafruit_ssd1306
import time

# Setup I2C

i2c = busio.I2C(board.SCL, board.SDA)

# Define display dimensions
width = 128
height = 64

# Initialize display

display = adafruit_ssd1306.SSD1306_I2C(width, height, i2c)

# Clear display

display.fill(0)
display.show()

# Display text

display.text('Hello, Pi!', 0, 0, 1)
display.show()

# Keep message for 5 seconds

time.sleep(5)

# Clear display before exit

display.fill(0)
display.show()

Common Pitfalls

Common mistakes when using SSD1306 OLED with Raspberry Pi include:

• Not enabling I2C interface on Raspberry Pi via raspi-config.
• Incorrect wiring of SDA and SCL pins (use GPIO 2 for SDA and GPIO 3 for SCL).
• Missing required Python libraries like adafruit-circuitpython-ssd1306 and adafruit-circuitpython-framebuf.
• Not clearing the display before writing new content, causing overlapping text.
• Using wrong display dimensions (common sizes are 128x64 or 128x32 pixels).

Example of wrong and right usage:

python

# Wrong: Missing display.show() after text

display.text('Hello', 0, 0, 1)
# display.show() missing - text won't appear

# Right: Always call display.show() to update

display.text('Hello', 0, 0, 1)
display.show()

Quick Reference

Summary tips for using SSD1306 OLED with Raspberry Pi:

• Enable I2C interface on Raspberry Pi before connecting the display.
• Use GPIO 2 (SDA) and GPIO 3 (SCL) pins for I2C communication.
• Install required libraries with pip3 install adafruit-circuitpython-ssd1306 and dependencies.
• Always clear the display with display.fill(0) before writing new content.
• Call display.show() after drawing to update the screen.

Key Takeaways

Enable I2C on Raspberry Pi and connect OLED to SDA (GPIO 2) and SCL (GPIO 3) pins.

Install Adafruit SSD1306 Python library to control the display easily.

Always clear the display and call display.show() to update the screen.

Use correct display dimensions matching your OLED model (usually 128x64 or 128x32).

Check wiring and I2C address if the display does not respond.