OLED display with I2C (SSD1306) in Raspberry Pi - Step-by-Step Execution

Concept Flow - OLED display with I2C (SSD1306)

Start Raspberry Pi

↓

Initialize I2C bus

↓

Create SSD1306 display object

↓

Clear display buffer

↓

Draw text or graphics

↓

Send buffer to OLED via I2C

↓

Display updated

↓

End or repeat

The Raspberry Pi starts, sets up I2C communication, creates the OLED display object, clears the screen, draws content, sends it over I2C, and updates the display.

Execution Sample

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.text('Hello!', 0, 0, 1)
display.show()

This code initializes the OLED display over I2C and shows the text 'Hello!' on the screen.

Execution Table

Step	Action	I2C Bus State	Display Buffer State	Output
1	Import libraries	I2C bus not started	Empty	No output
2	Initialize I2C bus	I2C bus ready	Empty	No output
3	Create SSD1306 object	I2C bus ready	Empty buffer	No output
4	Clear display buffer (fill 0)	I2C bus ready	Buffer cleared (all pixels off)	No output
5	Draw text 'Hello!' at (0,0)	I2C bus ready	Buffer updated with text pixels	No output yet
6	Send buffer to OLED (display.show())	I2C bus active, data sent	Buffer unchanged	Text 'Hello!' appears on OLED
7	End or repeat	I2C bus ready	Buffer unchanged	Display shows 'Hello!'

💡 Display updated and text shown; program ends or waits for next command.

Variable Tracker

Variable	Start	After Step 2	After Step 4	After Step 5	After Step 6	Final
i2c	null	I2C object ready	I2C object ready	I2C object ready	I2C object ready	I2C object ready
display	null	null	SSD1306 object with cleared buffer	SSD1306 object with text buffer	SSD1306 object with text buffer	SSD1306 object with text buffer

Key Moments - 2 Insights

Why does the text not appear immediately after calling display.text()?

Because display.text() only updates the buffer in memory; the display.show() call sends the buffer over I2C to update the OLED screen, as shown in step 6 of the execution_table.

What happens if the I2C bus is not initialized before creating the display object?

The display object cannot communicate with the OLED, so no display updates occur. This is why step 2 (I2C initialization) must happen before step 3 (creating the display object).

Visual Quiz - 3 Questions

Look at the execution_table, what is the display buffer state after step 5?

A Buffer unchanged from start

B Buffer cleared with all pixels off

C Buffer updated with text pixels

D Buffer sent to OLED

💡 Hint

Check the 'Display Buffer State' column at step 5 in the execution_table.

At which step does the OLED screen actually show the text 'Hello!'?

A Step 4

B Step 6

C Step 5

D Step 7

💡 Hint

Look at the 'Output' column in the execution_table to see when the text appears.

If the I2C bus was not ready at step 3, what would happen?

A The display object could not communicate with the OLED

B The display object would still work normally

C The display buffer would clear automatically

D The text would appear without calling display.show()

💡 Hint

Refer to the key_moments explanation about I2C initialization before creating the display object.

Concept Snapshot

Initialize I2C bus on Raspberry Pi
Create SSD1306_I2C display object with width, height, and I2C
Clear display buffer with fill(0)
Draw text with text(string, x, y, color)
Update OLED screen with show()
Always initialize I2C before display object

Full Transcript

This example shows how to use an OLED display with I2C on a Raspberry Pi. First, the I2C bus is initialized using busio.I2C with the board's SCL and SDA pins. Then, the SSD1306_I2C display object is created with the display size and the I2C bus. The display buffer is cleared with fill(0), which turns off all pixels in memory. Next, text is drawn into the buffer using display.text with the string 'Hello!' at position (0,0). The text does not appear on the screen yet because it is only in the buffer. Finally, display.show() sends the buffer data over I2C to the OLED, making the text visible. The program can then end or update the display again. Key points include initializing I2C before creating the display object and calling show() to update the screen after drawing.

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