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.