By Kevin McAleer, 6 Minutes
Page last updated November 21, 2026
![]()
Everything so far has run on the simulated device. This lesson moves the face to a real screen. If you don’t have the parts yet, read along anyway. The change to your code is tiny, and that’s the lesson.
You’ll need:
The display has four pins. Connect them like this:
| OLED pin | Pico pin | Why |
|---|---|---|
| GND | GND | Ground |
| VCC | 3V3(OUT) | Power, 3.3 volts |
| SDA | GP0 | Data |
| SCL | GP1 | Clock |
Check the labels on your own display before you connect power. Some boards have VCC and GND the other way round from the picture you’re copying.
These are the same pins Snakie’s Display instrument shows under its screen: SDA GP0, SCL GP1, address 0x3C. If you’d like to plan the wiring on screen first, Wire It Up - Electronics in Snakie shows how.
ssd1306 and install it. That puts the display driver on the boardeye.py to the real board with right-click, Upload to board. The simulated device and your Pico have separate file systems, so the files you uploaded earlier aren’t on the PicoHere’s the top of face.py as you wrote it:
from simscreen import SimScreen
import eye
screen = SimScreen()
And here it is for a real OLED:
from machine import Pin, I2C
from ssd1306 import SSD1306_I2C
import eye
i2c = I2C(0, sda=Pin(0), scl=Pin(1))
screen = SSD1306_I2C(128, 64, i2c)
Nothing else changes. fill, blit, text, fill_rect and show all work the same, because the real driver is a frame buffer with a show() too. That’s why we built SimScreen to match it.
Run face.py and your eyes appear on the glass.
Editing the top of every file each time you switch gets tiresome. A small helper can choose for you. Make myscreen.py:
def make_screen():
"""A real SSD1306 if one is connected, otherwise the simulated screen."""
try:
from machine import Pin, I2C
from ssd1306 import SSD1306_I2C
return SSD1306_I2C(128, 64, I2C(0, sda=Pin(0), scl=Pin(1)))
except Exception as problem:
print("No OLED found (" + str(problem) + "), using the Display instrument")
from simscreen import SimScreen
return SimScreen()
Upload it, then start your programs like this:
from myscreen import make_screen
import eye
screen = make_screen()
try attempts the real display. If the driver isn’t installed or no screen answers, the except part runs and you get the simulated one instead. The same file now works on the simulator, on a bare Pico and on a Pico with an OLED.
Try it on the simulated device first. You’ll see the “No OLED found” message in the console, and the face on the Display instrument as before.
To make the face start by itself when the robot is switched on:
robot_face.py and change its first lines to use make_screenmain.pymain.py, myscreen.py, simscreen.py and eye.py to the PicoMicroPython runs main.py automatically at power-up. Unplug the Pico from your computer, power it from a battery pack or a USB charger, and the face wakes up.
blink.py on the real screenscreen.invert(1) after making the screen. The SSD1306 driver can swap light and dark for the whole displayProblem: ImportError: no module named 'ssd1306'.
Solution: Install ssd1306 from the Packages panel while connected to the Pico.
Why: The driver isn’t part of MicroPython. It has to be copied to each board that uses it.
Problem: OSError: [Errno 5] EIO or ETIMEDOUT.
Solution: Check the four wires, especially that SDA and SCL aren’t swapped. Then run the I²C detect instrument to see whether anything answers at 0x3C.
Why: The Pico asked the display to respond and heard nothing.
Problem: The picture is there but shifted or wrapped.
Solution: Check your display’s size. Some small OLEDs are 128×32, in which case use SSD1306_I2C(128, 32, i2c) and redo the positions.
Why: The driver has to know the real size to send the buffer correctly.
Problem: It works from Snakie but not from a battery.
Solution: Make sure the program is saved on the Pico as main.py, along with every module it imports.
Why: Only main.py runs at power-up, and it can only import files that are on the board.
Quick quiz 1 of 3
Why does the same drawing code work on the real OLED?
Quick quiz 2 of 3
What does the try and except in make_screen do?
Quick quiz 3 of 3
What must a program be called to start by itself when the Pico powers up?
You can use the arrows ← → on your keyboard to navigate between lessons.
Comments