OLED display with I2C (SSD1306) in Raspberry Pi - Mini Project: Build & Apply

OLED display with I2C (SSD1306)

📖 Scenario: You have a Raspberry Pi connected to a small OLED screen using the I2C protocol. This screen uses the SSD1306 driver chip. You want to display simple text messages on the screen.

🎯 Goal: Build a Python program that initializes the OLED display, sets up a message, and shows it on the screen.

📋 What You'll Learn

Use the board and busio modules to set up I2C communication.

Use the adafruit_ssd1306 library to control the OLED display.

Create a message string to display.

Clear the display before showing the message.

Show the message on the OLED screen.

💡 Why This Matters

🌍 Real World

OLED displays with I2C are common in small devices like weather stations, clocks, and IoT gadgets to show information clearly and efficiently.

💼 Career

Knowing how to control hardware displays using Python and I2C is useful for embedded systems developers, IoT engineers, and hobbyists working with Raspberry Pi or similar boards.

1

Set up I2C communication and OLED display

Write code to import board, busio, and adafruit_ssd1306. Then create an I2C object called i2c using busio.I2C(board.SCL, board.SDA). Finally, create an OLED display object called oled using adafruit_ssd1306.SSD1306_I2C(128, 32, i2c).

Raspberry Pi

# Your code here

Hint

Use busio.I2C(board.SCL, board.SDA) to create the I2C bus. Then pass it to adafruit_ssd1306.SSD1306_I2C with width 128 and height 32.

2

Create the message to display

Create a variable called message and set it to the string "Hello, OLED!".

Raspberry Pi

import board
import busio
import adafruit_ssd1306

i2c = busio.I2C(board.SCL, board.SDA)
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)

# Your code here

Hint

Just assign the string "Hello, OLED!" to the variable message.

3

Clear the display and write the message

Use oled.fill(0) to clear the display. Then use oled.text(message, 0, 0, 1) to write the message at the top-left corner. Finally, call oled.show() to update the screen.

Raspberry Pi

import board
import busio
import adafruit_ssd1306

i2c = busio.I2C(board.SCL, board.SDA)
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)

message = "Hello, OLED!"

# Your code here

Hint

Clear the screen with oled.fill(0). Write text with oled.text(). Update the display with oled.show().

4

Print confirmation message

Write a print statement to display the text "Message shown on OLED" in the console.

Raspberry Pi

import board
import busio
import adafruit_ssd1306

i2c = busio.I2C(board.SCL, board.SDA)
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)

message = "Hello, OLED!"

oled.fill(0)
oled.text(message, 0, 0, 1)
oled.show()

# Your code here

Hint

Use print("Message shown on OLED") to confirm the message was displayed.

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