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.

Practice

1. What is the main purpose of the show() method when using an SSD1306 OLED display with I2C on a Raspberry Pi?

easy

A. To update the display with the current buffer content

B. To clear the display screen

C. To initialize the I2C communication

D. To set the brightness of the OLED display

Solution

1. Step 1: Understand the display buffer concept

   The OLED display uses a buffer to store what will be shown on the screen before updating.

2. Step 2: Role of show() method

   The show() method sends the buffer content to the OLED, updating the visible display.

3. Final Answer:

   To update the display with the current buffer content -> Option A

4. Quick Check:

   show() updates screen [OK]

Hint: Remember: show() sends buffer to screen [OK]

Common Mistakes:

• Confusing show() with clear()
• Thinking show() initializes I2C
• Assuming show() changes brightness

2. Which of the following is the correct way to clear the OLED display buffer before drawing new content in Python using the SSD1306 library?

easy

A. oled.reset()

B. oled.clear()

C. oled.fill(0)

D. oled.erase()

Solution

1. Step 1: Identify the method to clear the buffer

   The SSD1306 library uses fill(0) to fill the buffer with zeros, effectively clearing it.

2. Step 2: Confirm other options are incorrect

   Methods like clear(), reset(), or erase() are not standard in this library.

3. Final Answer:

   oled.fill(0) -> Option C

4. Quick Check:

   Clear buffer = fill(0) [OK]

Hint: Use fill(0) to clear screen buffer [OK]

Common Mistakes:

• Using non-existent clear() method
• Confusing fill(1) with clearing
• Trying reset() which is not in library

3. Given the following Python code snippet for an SSD1306 OLED display, what will be the visible output on the screen?

oled.fill(0)
oled.text('Hi', 0, 0)
oled.show()

medium

A. The text 'Hi' appears at the bottom-right corner

B. The screen remains blank

C. An error occurs because text() needs more arguments

D. The text 'Hi' appears at the top-left corner

Solution

1. Step 1: Analyze the code sequence

   The buffer is cleared with fill(0), then 'Hi' is drawn at coordinates (0,0).

2. Step 2: Understand coordinate system and show()

   Coordinates (0,0) place text at top-left. Calling show() updates the display.

3. Final Answer:

   The text 'Hi' appears at the top-left corner -> Option D

4. Quick Check:

   Text at (0,0) shows top-left [OK]

Hint: Text at (0,0) is top-left on OLED [OK]

Common Mistakes:

• Assuming text() needs more arguments
• Thinking (0,0) is bottom-right
• Forgetting to call show() to update

4. You wrote this code to display 'Hello' on the OLED but nothing appears:

oled.text('Hello', 10, 10)
oled.fill(0)
oled.show()

What is the problem?

medium

A. Coordinates (10,10) are outside the display range

B. Calling fill(0) after text() clears the buffer

C. Missing oled.init() before drawing

D. Text string must be uppercase

Solution

1. Step 1: Check the order of commands

   Text is drawn first, then fill(0) clears the buffer, erasing the text.

2. Step 2: Understand correct sequence

   Clear buffer first with fill(0), then draw text, then call show().

3. Final Answer:

   Calling fill(0) after text() clears the buffer -> Option B

4. Quick Check:

   Clear after draw erases text [OK]

Hint: Clear buffer before drawing, not after [OK]

Common Mistakes:

• Thinking coordinates are invalid
• Assuming init() is needed every time
• Believing text case matters

5. You want to display a scrolling message on the SSD1306 OLED using I2C on Raspberry Pi. Which approach correctly updates the display to show new text smoothly without leftover pixels?

hard

A. Clear buffer with fill(0), draw new text, then call show() each frame

B. Draw new text over old text without clearing, then call show()

C. Only call show() once after all text frames are drawn

D. Use oled.clear() after show() to erase old text

Solution

1. Step 1: Understand how to avoid leftover pixels

   Clearing the buffer before drawing new text removes old pixels that would remain otherwise.

2. Step 2: Proper update sequence for smooth scrolling

   Each frame: clear buffer with fill(0), draw new text, then call show() to update display.

3. Final Answer:

   Clear buffer with fill(0), draw new text, then call show() each frame -> Option A

4. Quick Check:

   Clear before draw + show() = smooth update [OK]

Hint: Always clear buffer before drawing new frame [OK]

Common Mistakes:

• Not clearing buffer causes ghosting
• Calling show() only once delays updates
• Using non-existent clear() method