OLED display with I2C (SSD1306) in Raspberry Pi

Introduction

An OLED display with I2C (SSD1306) lets you show text and images on a small screen using just two wires. It is great for adding simple visual output to your Raspberry Pi projects.

You want to display sensor readings like temperature or humidity.

You want to show simple menus or status messages on a small screen.

You want to add a clock or timer display to your project.

You want to create a small user interface without a big monitor.

You want to debug your program by showing messages on the screen.

Syntax

Raspberry Pi

import board
import busio
from adafruit_ssd1306 import SSD1306_I2C

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

# Create display object with width and height
display = SSD1306_I2C(128, 64, i2c)

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

# Write text on the display
from PIL import Image, ImageDraw, ImageFont

image = Image.new('1', (display.width, display.height))
draw = ImageDraw.Draw(image)

# Draw text at position (x, y)
draw.text((0, 0), 'Hello, Pi!', fill=255)

# Display image on OLED
display.image(image)
display.show()

You need the 'adafruit-circuitpython-ssd1306' and 'Pillow' libraries installed.

The I2C pins on Raspberry Pi are usually GPIO 2 (SDA) and GPIO 3 (SCL).

Examples

This example sets up the display and clears it to black.

Raspberry Pi

import board
import busio
from adafruit_ssd1306 import SSD1306_I2C

i2c = busio.I2C(board.SCL, board.SDA)
display = SSD1306_I2C(128, 64, i2c)
display.fill(0)
display.show()

This example draws the text 'Hi!' at position (10, 20) on the screen.

Raspberry Pi

from PIL import Image, ImageDraw

image = Image.new('1', (128, 64))
draw = ImageDraw.Draw(image)
draw.text((10, 20), 'Hi!', fill=255)
display.image(image)
display.show()

Sample Program

This program initializes the OLED display, clears it, draws the text 'Hello, Pi!' at the top-left corner, and shows it on the screen. It also prints a confirmation message to the console.

Raspberry Pi

import board
import busio
from adafruit_ssd1306 import SSD1306_I2C
from PIL import Image, ImageDraw, ImageFont

# Setup I2C and display
i2c = busio.I2C(board.SCL, board.SDA)
display = SSD1306_I2C(128, 64, i2c)

display.fill(0)
display.show()

# Create blank image for drawing
image = Image.new('1', (display.width, display.height))
draw = ImageDraw.Draw(image)

# Draw some text
text = 'Hello, Pi!'
draw.text((0, 0), text, fill=255)

# Show image on display
display.image(image)
display.show()

print('Text displayed on OLED screen.')

Important Notes

Make sure your Raspberry Pi I2C interface is enabled in the settings.

Use a 3.3V power supply for the OLED to avoid damage.

If the display does not show anything, check the I2C address with 'i2cdetect -y 1' command.

Summary

OLED displays with SSD1306 use I2C to communicate with Raspberry Pi using only two wires.

You can draw text and images by creating a small image and sending it to the display.

Remember to clear the display before drawing new content to avoid leftover pixels.