Home
Raspberry Pi Pico

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:

Raspberry Pi Pico OLED I2C display

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×Breadboard
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
Raspberry Pi Pico OLED

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.
OLED Pinout

※ 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
The wiring diagram between Raspberry Pi and Pico OLED 128x64

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.
Raspberry Pi Pico 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.

""" 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 OLED vertical and horizontal center align

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 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

Raspberry Pi Pico display image on OLED

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.
image to 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!
DISCLOSURE
Newbiely.com is a participant in the Amazon Services LLC Associates Program, an affiliate advertising program designed to provide a means for sites to earn advertising fees by advertising and linking to Amazon.com, Amazon.it, Amazon.fr, Amazon.co.uk, Amazon.ca, Amazon.de, Amazon.es, Amazon.nl, Amazon.pl and Amazon.se
Copyright © 2024 Newbiely.com. All rights reserved.
Terms and Conditions | Privacy Policy
Email: newbiely.com@gmail.com