Meet the OLED: Pixels, Coordinates, and show()

VCC supplies power to the OLED. GND gives the Pico and OLED a shared electrical reference.

SCL is the serial clock. It supplies the timing for I²C communication. SDA is the serial data line that carries information between the devices. Most of our useful data travels from the Pico to the OLED, although SDA can carry data in either direction.

You do not need to trace individual clock pulses or bits yet. For now, it is enough to know that SCL coordinates the conversation and SDA carries it.

A precondition is something that must already be true before a program can work. Python can control signals at the Pico’s pins, but it cannot move a wire from the wrong pin to the right one.

The program therefore assumes that the hardware is connected correctly. If that assumption is false, the code may fail even when every Python statement is valid. Software often depends on facts outside itself; naming those facts makes a system easier to test.

On a typical breadboard, holes A through E in one numbered row form a connected group. Holes F through J form another. The center gap separates the two groups, and different numbered rows are separate.

Plan four continuous paths before applying power:

OLED SDA → GP0
OLED SCL → GP1
OLED VCC → 3V3
OLED GND → GND

The exact row numbers do not matter. Each signal needs an unbroken path, and unrelated signals must not share a connected row.

The Shell should usually report:

I2C devices: [60]

The OLED should display two lines:

Hello, yush
Pico WH

This first run establishes that the complete system works. Once the known-good program succeeds, we can change one part at a time and learn from the result.

It is the OLED’s I²C address, not a pin number or a count of devices. I²C allows several devices to share the same pair of communication lines, so each device needs an address.

The SSD1306 commonly uses hexadecimal address 0x3C. Python prints the same value here in decimal:

60 decimal = 0x3C hexadecimal

An empty list, [], means that no device answered the scan.

With SDA connected, the scan commonly returns [60]. Without SDA, it should return [] because the OLED cannot answer.

The comparison gives us evidence that SDA is essential to the exchange. Reconnect SDA before continuing.

Create an I²C connection using the Pico’s I²C hardware controller 0. Carry the clock signal through GP1, carry the data signal through GP0, and use a clock frequency of 200,000 cycles per second.

The first 0 selects the RP2040’s I2C0 controller. It does not mean GP0; Pin(0) names GP0 separately.

They describe the display’s resolution: 128 pixels wide and 64 pixels tall. The screen is a rectangular grid with 128 columns and 64 rows.

It contains:

128 × 64 = 8,192 pixels

If only the width doubled to 256, the display would contain 16,384 pixels. Doubling one dimension doubles the total area.

(0, 0)       top-left
(127, 0)     top-right
(0, 63)      bottom-left
(127, 63)    bottom-right
(64, 32)     approximate center

Both dimensions are even, so the exact geometric center lies between pixels. (64, 32) is a useful nearby position.

The coordinates use zero-based indexing. The 128 horizontal positions are numbered 0 through 127, and the 64 vertical positions are numbered 0 through 63.

The final valid index is therefore one less than the number of positions.

oled.fill(0)

oled.pixel(0, 0, 1)
oled.pixel(127, 0, 1)
oled.pixel(0, 63, 1)
oled.pixel(127, 63, 1)
oled.pixel(64, 32, 1)

oled.show()

Inspect the physical display. The pixels are tiny, but their positions should agree with the coordinate model.

Only three horizontal positions—125, 126, and 127—remain. A letter requires a group of pixels, so the word cannot fit.

The coordinates passed to text() mark where the drawing begins. They do not place the entire word inside one pixel. Anything beyond the edge is not visible.

The point (64, 32) is near the center of the screen, but it becomes the text’s starting position. The message then extends to the right.

To center text, you need its width and must move the starting x-coordinate left by about half that width. Position and size are separate properties.

This display is monochrome, so each pixel has two states:

0 → off
1 → on

fill(0) makes the entire drawing area black. fill(1) turns every pixel on. Why one bit can represent these states is a question for the next lesson.

The display remains blank. text() changes an image being prepared in the Pico’s memory; it does not immediately update the physical OLED.

show() transfers the prepared image to the display. That separation gives the program time to assemble a complete frame before the viewer sees it.

The memory holding the prepared image is called a frame buffer. We will examine its representation later.

fill(), pixel(), and text() are drawing operations. Each changes the frame buffer—the prepared picture in memory.

show() is a display operation. It sends that picture to the SSD1306 so the physical screen reflects it.

draw in memory → show the completed image

It creates a Python object representing a 128 × 64 SSD1306 display and tells the driver to communicate through the connection stored in i2c.

That explanation describes what the constructor accomplishes. It does not explain how the driver implements the constructor—and it does not need to yet. A useful model can be accurate without exposing every layer beneath it.

It proceeds in four stages:

establish I²C communication
            ↓
create an object that represents the OLED
            ↓
prepare an image in memory
            ↓
send that image to the physical display

The wiring must already be correct. The program then establishes communication, describes the screen to the driver, draws into a frame buffer, and calls show() to make the result visible.

There is no single correct arrangement. A solution should have this shape:

oled.fill(0)

oled.text("MESSAGE 1", x1, y1)
oled.text("MESSAGE 2", x2, y2)
oled.text("MESSAGE 3", x3, y3)

oled.show()

Choose values that keep each message inside the screen. Be ready to explain why each coordinate is reasonable and what you changed after seeing the first result.

We can now wire the OLED, find it on the I²C bus, place pixels and text, and control when a prepared image becomes visible. Several useful questions remain open:

• Where is the frame buffer stored?
• How does text become pixels?
• How are those pixels packed into bytes?
• What travels along SDA when show() runs?
• What does the SSD1306 do with the data it receives?

Those questions lead naturally from drawing pictures to representing pictures as data:

pixel → bit → byte → frame buffer → display

For now, the essential model is enough: drawing methods prepare an image in memory, and show() sends it to the screen.