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
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.
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
"""
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
# Initialize I2C
i2c = I2C(0, scl=Pin(1), sda=Pin(0), freq=400000) # Adjust Raspberry Pi Pico pins according to your setup
# Initialize the OLED display
oled = OLED_SSD1306_I2C(128, 64, i2c)
# Clear the display
oled.clear_display()
oled.display()
oled.set_text_size(2)
# Print a message to the display
text = "DIYables"
integer_value = 123
float_value = 45.67
oled.set_cursor(0, 0)
oled.println(text)
oled.set_cursor(0, 25)
oled.println(str(integer_value)) # Print integer and move to the next line
oled.set_cursor(0, 50)
oled.println("{:.2f}".format(float_value)) # Print formatted float and move to the next line
oled.display() # Ensure you update the display after writing to it
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:
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.
"""
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
# Initialize the OLED display
oled = OLED_SSD1306_I2C(128, 64, i2c)
# Clear the display
oled.clear_display()
oled.display()
def oled_display_center(oled, text):
# Get the text bounds (width and height) of the string
x1, y1, width, height = oled.get_text_bounds(text, 0, 0)
# Set cursor to the calculated centered position
cursor_x = (oled.WIDTH - width) // 2
cursor_y = (oled.HEIGHT - height) // 2
oled.set_cursor(cursor_x, cursor_y)
# Print the text on the display
oled.println(text)
# Refresh the display to show the text
oled.display()
oled.set_text_size(2)
oled_display_center(oled, "DIYables")
After running the code, the text will be centered both vertically and horizontally on the OLED screen.
Raspberry Pi Pico Code - Drawing on OLED
"""
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
# Initialize I2C
i2c = I2C(0, scl=Pin(1), sda=Pin(0), freq=400000) # Adjust Raspberry Pi Pico pins according to your setup
# Initialize the OLED display
oled = OLED_SSD1306_I2C(128, 64, i2c)
# Clear the display
oled.clear_display()
oled.display()
# Draw a rectangle
oled.draw_rect(0, 0, 40, 25, 1)
#oled.fill_rect(0, 0, 40, 25, 1)
oled.display()
# Draw a circle
#oled.draw_circle(64, 32, 20, 1)
oled.fill_circle(64, 32, 20, 1)
oled.display()
# Draw a triangle
oled.draw_triangle(80, 62, 128, 62, 104, 32, 1)
#oled.fill_triangle(80, 62, 128, 62, 104, 32, 1)
oled.display()
By running the above code, you'll see a rectangle, circle, and triangle displayed on the OLED as shown below.
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 ≡