Guide by Michael; PiicoDev OLED Module SSD1306 - Raspberry Pi Guide

I have just shared content in Guides > Raspberry Pi: "PiicoDev OLED Module SSD1306 - Raspberry Pi Guide"

Read more

1 Like

Hi team,

I have changed one of the examples to print how long it takes for the module to display plain text.
for the given code, it takes more than 2 sec. I am testing the module on Pi Zero. is this delay acceptable? Have I missed anything as the delay is even worst for other sample codes, e.g. Animation?

Thank you!

from PiicoDev_SSD1306 import *
display = create_PiicoDev_SSD1306()
import datetime

myString = "This is Farhad"
myNumber = 123.4567

start_time =

display.text("Hello, World!", 0,0, 1) # literal string
display.text(myString, 0,15, 1) # string variable
display.text(str(myNumber), 0,30, 1) # print a variable
display.text("{:.2f}".format(myNumber), 0,45, 1) # use formatted-print

print(( - start_time).total_seconds())

Hi Farhad,

I’d try blanking the display variable with display.fill(0). before drawing anything on the module. I’ve found this to speed things up a lot when animating/looking for fast refreshes.
The Magnetometer project on the Core website has a really fast refresh rate using that method, I’m keen to see your results!

1 Like

Hey Liam,

I’m also having fps issues too. I’m trying to make pong but before i can even get to making the game ive got to improve my roughly 1 fps to about 30 :(. I’ve ran Farhads code as well and it takes me about 1 second to display the message. I’ve also noticed that in the video tutorial for the motion sensor, the guy is getting a pretty high fps with very similar code so i don’t know if ive unknowingly done something wrong along the way. Additionally, i’ve determined that my pi is capable of looping through a while loop crazy fast (like 1000 times a second) but when i loop through this while loop below its trash. Any help would be greatly appreciated.

from PiicoDev_SSD1306 import *
import RPi._GPIO as GPIO


GPIO.setup(PONE_UP_PIN, GPIO.IN, pull_up_down = GPIO.PUD_DOWN) #sets a pin and pulls its voltage down by default
GPIO.setup(PONE_DOWN_PIN, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(PTWO_UP_PIN, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(PTWO_DOWN_PIN, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(QUIT_PIN, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)

display = create_PiicoDev_SSD1306()

y = 10
while True:
    if GPIO.input(QUIT_PIN) == True: #quit if set high
    display.rect(0, 0, 127, 63, 1) #Game border
    display.line(125, 2, 125, 12, 1) #A paddle
    #testing fps by moving a pixel down by one px each iteration of the while loop (takes 1sec per Ypos)
    display.pixel(20, y, 1)
    y += 1


Hi Max,

Welcome to the forum!! Sorry its taken so long to get to your question!

Unfortunately the Pi isnt amazing at clocking out quick frames for the OLED
Highlighted from Michaels example here:
That code is running without any delays. but the Pi’s processor is also handling the whole OS and other background tasks and simply thinks that I2C isnt as important (unfortunately I’m not aware of any work-arounds at the moment, @Michael might be able to chip in).

I used a Pico in this project since that is all that the project was made to do, and without a delay, 30FPS+ was achieved.

There’s an issue raised on the GitHub to try and increase the framerate: Slow framerates on RPi (and micro:bit) · Issue #3 · CoreElectronics/CE-PiicoDev-SSD1306-MicroPython-Module · GitHub


The issue linked by @Liam summarises the cause - there is a fundamental limitation with how data is streamed out by the library.
On an RPi, the entire frame buffer is streamed out in single byte transactions which is not ideal. On a Pico, the frame buffer is streamed out in much larger transactions which removes a lot of overheads.

Unfortunately this is PiicoDev implementation-level

the good news is that the SSD1306 is very common, and there may be other I2C drivers available that you can use alongside PiicoDev to handle just the display. These (Pi specific) drivers won’t wear the same burdens as unifying PiicoDev, so they will potentially be higher performance on a PI

1 Like

How do I install the PiicoDev package on a raspberry pi with no desktop environment. I’ve tried pip install piicodev from the command line and also connected using Thonny via ssh. In both cases I get the error:
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to

hey @Matthew211684

There’s a great writeup on virtual environments here.
To use PiicoDev, you’ll have to use pip3 which is for Python3 (pip installs for Python2.7)

You’ll also have to run your scripts using eg. Python3 or sudo Python3

The virtual environment worked. Thank you.

1 Like

Woo! Result :partying_face: