SENSORS/ACTUATORS

Raspberry Pi Pico - OLED 128x64

This tutorial instructs you how to use a Raspberry Pi Pico with an OLED 128x64 I2C display. We will cover:

How to connect a 128x64 OLED screen with a Raspberry Pi Pico.
How to program the Raspberry Pi Pico to display text, integer and float number on an OLED.
How to automatically vertical and horizontal center align text/number on OLED.
How to program the Raspberry Pi Pico to draw shape on an OLED.
How to program the Raspberry Pi Pico to display image on an OLED.

Hardware Preparation

1	×	Raspberry Pi Pico W
1	×	Raspberry Pi Pico (Alternatively)
1	×	Micro USB Cable
1	×	SSD1306 I2C OLED Display 128x64
1	×	Jumper Wires
1	×	(Optional) Screw Terminal Expansion Board for Raspberry Pi Pico

Or you can buy the following sensor kits:

1	×	DIYables Sensor Kit (30 sensors/displays)
1	×	DIYables Sensor Kit (18 sensors/displays)

Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you.
Additionally, some of these links are for products from our own brand, DIYables.

Overview of OLED Display

OLED displays come in various types, each differing in communication protocols, sizes, and color options.

Communication protocols: I2C, SPI
Sizes: 128x64, 128x32
Available colors**: white, blue, yellow, and more

SPI vs I2C for OLED Displays

SPI: Faster but requires more pins on the Raspberry Pi Pico.
I2C: Uses fewer pins and allows connection to multiple devices.

Choose SPI for faster data transfer or I2C for fewer pins. This guide uses the 128x64 SSD1306 I2C OLED Display.

I2C OLED Display Pinout

GND pin: Connect to Raspberry Pi Pico ground.
VCC pin: Connect to 5V or 3.3V on Raspberry Pi Pico.
SCL pin: Clock pin for I2C interface.
SDA pin: Data pin for I2C interface.

※ NOTE THAT:

This guide is for using an OLED display with the SSD1306 I2C driver. We tested it with an OLED display from DIYables, and it worked flawlessly.

Wiring Diagram

How to Connect Raspberry Pi Pico to OLED 128x64 Screen

This image is created using Fritzing. Click to enlarge image

Check the table below for details on other Raspberry Pi Pico models.

OLED Module	Raspberry Pi Pico
VCC	3.3V
GND	GND
SDA	GP0
SCL	GP1

Raspberry Pi Pico Code - Display Text, Integer and Float Number on OLED

Detailed Instructions

Please follow these instructions step by step:

Ensure that Thonny IDE is installed on your computer.
Ensure that MicroPython firmware is installed on your Raspberry Pi Pico.
If this is your first time using a Raspberry Pico, refer to the Raspberry Pi Pico - Getting Started tutorial for detailed instructions.
Connect the OLED display to the Raspberry Pi Pico according to the provided diagram.
Connect the Raspberry Pi Pico to your computer using a USB cable.
Launch the Thonny IDE on your computer.
On Thonny IDE, select MicroPython (Raspberry Pi Pico) Interpreter by navigating to Tools Options.
In the Interpreter tab, select MicroPython (Raspberry Pi Pico) from the drop-down menu.
Ensure the correct port is selected. Thonny IDE should automatically detect the port, but you may need to select it manually (e.g., COM3 on Windows or /dev/ttyACM0 on Linux).
Navigate to the Tools Manage packages on the Thonny IDE.
Search “DIYables-MicroPython-OLED”, then find the OLED library created by DIYables.
Click on DIYables-MicroPython-OLED, then click Install button to install OLED library.

Copy the above code and paste it to the Thonny IDE's editor.
Save the script to your Raspberry Pi Pico by:

Click the Save button, or use Ctrl+S keys.
In the save dialog, you will see two sections: This computer and Raspberry Pi Pico. Select Raspberry Pi Pico
Save the file as main.py

Click the green Run button (or press F5) to run the script. The script will execute.
Take a look at the output on the OLED display. It looks like this:

Raspberry Pi Pico OLED display text, integer and float number

How to automatically vertical and horizontal center align text/number on OLED

The MicroPython code below automatically centers the text both vertically and horizontally on the OLED display.

After running the code, the text will be centered both vertically and horizontally on the OLED screen.

Raspberry Pi Pico OLED vertical and horizontal center align

Raspberry Pi Pico Code - Drawing on OLED

By running the above code, you'll see a rectangle, circle, and triangle displayed on the OLED as shown below.

Raspberry Pi Pico draw rectangle, circle, an triagle on OLED

Raspberry Pi Pico Code – Display Image on OLED

The below code draws an image to LCD display. The image is DIYables icon.

""" This Raspberry Pi Pico MicroPython code was developed by newbiely.com This Raspberry Pi Pico code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/raspberry-pico/raspberry-pi-pico-oled-128x64 """ from machine import I2C, Pin from DIYables_MicroPython_OLED import OLED_SSD1306_I2C import utime # Initialize I2C i2c = I2C(0, scl=Pin(1), sda=Pin(0), freq=400000) # Adjust Raspberry Pi Pico pins according to your setup # Create the SSD1306 display object oled = OLED_SSD1306_I2C(128, 64, i2c) # Clear the display buffer oled.clear_display() # 16x16 heart bitmap in RGB565 format heart_bitmap = [ # 'DIYables Icon', 128x57px 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xfe, 0x00, 0x03, 0xf1, 0xf8, 0x00, 0x3e, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xc0, 0x03, 0xf1, 0xf8, 0x00, 0x7e, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xf0, 0x03, 0xf0, 0xfc, 0x00, 0x7c, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xf8, 0x03, 0xf0, 0xfc, 0x00, 0xfc, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xfc, 0x03, 0xf0, 0x7e, 0x00, 0xf8, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x01, 0xfe, 0x03, 0xf0, 0x3f, 0x01, 0xf8, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x7f, 0x03, 0xf0, 0x3f, 0x03, 0xf0, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x3f, 0x03, 0xf0, 0x1f, 0x83, 0xe0, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x3f, 0x83, 0xf0, 0x1f, 0x87, 0xe0, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x0f, 0xc7, 0xc0, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x07, 0xef, 0xc0, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x07, 0xff, 0x80, 0xf0, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x03, 0xff, 0x00, 0xfe, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x03, 0xff, 0x00, 0xff, 0xc0, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x01, 0xfe, 0x00, 0xff, 0xe0, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x00, 0xfe, 0x00, 0xff, 0xf8, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x1f, 0x83, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xfc, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x3f, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xfe, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0x7f, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0x03, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x00, 0xff, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0x83, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xf8, 0x03, 0xfe, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0xc3, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xfc, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0xc3, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xf8, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0xe3, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xe0, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0xe3, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0x80, 0x03, 0xf0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0xf3, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xf8, 0x00, 0x03, 0xe0, 0x00, 0xfc, 0x00, 0xff, 0xff, 0xf3, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xc7, 0xff, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0xff, 0xff, 0xc7, 0xff, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0x80, 0xff, 0xff, 0xc7, 0xff, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0x80, 0xff, 0xff, 0xc7, 0xff, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0x80, 0xff, 0x9f, 0xc6, 0x7f, 0x1f, 0xdf, 0xf9, 0xff, 0xff, 0xff, 0xfb, 0xff, 0xff, 0xff, 0xff, 0x00, 0xfc, 0x03, 0xc0, 0x0f, 0x1e, 0x03, 0xe0, 0x3f, 0xff, 0xff, 0xf3, 0xff, 0xff, 0xff, 0xff, 0x00, 0xfc, 0x03, 0xc0, 0x07, 0x1c, 0x01, 0xc0, 0x3f, 0xff, 0xff, 0xf3, 0xff, 0xff, 0xff, 0xfe, 0x00, 0xfd, 0xf1, 0xc3, 0xc7, 0x18, 0xf8, 0x8f, 0xff, 0xff, 0xff, 0xe3, 0xff, 0xff, 0xff, 0xfe, 0x00, 0xff, 0xf1, 0xc7, 0xe3, 0x18, 0xf8, 0x8f, 0xff, 0xff, 0xff, 0xe3, 0xff, 0xff, 0xff, 0xfc, 0x00, 0xfe, 0x01, 0xc7, 0xe3, 0x18, 0x00, 0xc0, 0xff, 0xff, 0xff, 0xc3, 0xff, 0xff, 0xff, 0xfc, 0x00, 0xfc, 0x01, 0xc7, 0xe3, 0x18, 0x00, 0xe0, 0x3f, 0xff, 0xff, 0xc3, 0xff, 0xff, 0xff, 0xf8, 0x00, 0xf8, 0xf1, 0xc7, 0xe3, 0x18, 0xff, 0xfe, 0x1f, 0xff, 0xff, 0x83, 0xff, 0xff, 0xff, 0xf0, 0x00, 0xf8, 0xf1, 0xc3, 0xc7, 0x18, 0xff, 0xff, 0x1f, 0xff, 0xff, 0x03, 0xff, 0xff, 0xff, 0xe0, 0x00, 0xf8, 0x61, 0xc0, 0x07, 0x1c, 0x01, 0xc0, 0x3f, 0xff, 0xfe, 0x03, 0xff, 0xff, 0xff, 0xc0, 0x00, 0xfc, 0x01, 0xc0, 0x0f, 0x1e, 0x01, 0x80, 0x3f, 0xff, 0xfc, 0x03, 0xff, 0xff, 0xff, 0x80, 0x00, 0xfe, 0x19, 0xc4, 0x3f, 0x1f, 0x87, 0xe0, 0xff, 0xff, 0xf8, 0x03, 0xff, 0xff, 0xff, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x03, 0xff, 0xff, 0xfc, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc0, 0x03, 0xff, 0xff, 0xf0, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x03, 0xff, 0xff, 0xc0, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xf0, 0x00, 0x03, 0xff, 0xfc, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff ] # Draw the bitmap on the display oled.draw_bitmap(0, 0, heart_bitmap, 128, 57, 1) # Update the display with the new image oled.display() utime.sleep(3) #oled.invert_display(True)

By running the above code, you will see the image displayed on the OLED as below

To show any other image on an OLED screen, you can follow the below steps:

Change the image (in any format) into a bitmap array. You can use this online tool for conversion. See the picture below to learn how to convert an image into a bitmap array. I converted the Raspberry Pi Pico icon into a bitmap array.

Update the converted bitmap array into the Raspberry Pi Pico code with the new array code.
Change the image width and height in the Raspberry Pi Pico code to match the dimension of image.

Please note that the image size must be equal to or smaller than the screen size.

OLED Troubleshooting

If nothing appears on the OLED screen, please follow these steps:

Check that the wiring is correct.
Make sure your I2c OLED has an SSD1306 driver.
Find out the I2C address of your OLED by using this I2C Address Scanner code on Raspberry Pi Pico.

from machine import I2C, Pin import utime i2c = I2C(0, sda=Pin(0), scl=Pin(1)) print('Scanning I2C bus...') devices = i2c.scan() if len(devices) == 0: print("No I2C devices found") else: print('I2C devices found:',len(devices)) for device in devices: print("Decimal address: ",device," | Hex address: ",hex(device)) utime.sleep(2)

Output in the Shell at the bottom of Thonny:

Shell x

>>> %Run -c $EDITOR_CONTENT

MPY: soft reboot Scanning... I2C device found at address 0x3C ! done Scanning... I2C device found at address 0x3C ! done

MicroPython (Raspberry Pi Pico) • Board CDC @ COM29 ≡

Learn More

※ OUR MESSAGES

As freelancers, We are AVAILABLE for HIRE. See how to outsource your project to us
Please feel free to share the link of this tutorial. However, Please do not use our content on any other websites. We invested a lot of effort and time to create the content, please respect our work!