Interfacing an OLED Display with the Raspberry Pi Pico Using Micropython

In this tutorial, we are going to interface an OLED display module with the Pico board. You will be able to perform an I2C communication on Raspberry Pi Pico at the end of this tutorial. Here, we are going to display some strings on an OLED display by using Micropython. We already have some articles and projects on the Interfacing of the OLED display. You can refer to those articles and projects to get a proper idea of the working of an OLED display.

 

Hardware Required

• 4pins I2C based 1.3 Inch 128×64 OLED display Module (SSD1306)
• Raspberry Pi Pico
• Breadboard
• Connecting Wires

Circuit Diagram to Interface SSD1306 OLED Display with Raspberry Pi Pico

 

You can refer the circuit connection of the Raspberry Pi Pico and OLED display module as shown below. The SDA pin of the OLED Display Module is connected to the GPIO16(Pin21) and the SCL pin is connected to the GPIO17(Pin22). The Vcc pin is connected to the 3.3v Pin of the Pico Board that is Pin36. The Ground pin of the Display module is connected to the Ground pin of the Pico board that is Pin38.

Library for OLED Display in MicroPython

At first, create a new folder where you want to save your code files. Then you need to download our complete GitHub repository on Raspberry Pi Pico Using MicroPython. Go to the “T3_Interfacing_An_OLED” folder. You need to copy the “main.py” and “ssd1306.py” files and then paste these files in the folder that you created to save your code files. So, we now have two files. The “main.py” file contains the code for displaying text and images. And the “ssd1306.py” is the library of the OLED display module. Before understanding the code, you need to perform an image to bitmap conversion to display an image on the OLED module. You can see another “img_to_bmp.py” file in the “T3_Interfacing_An_OLED” folder. You need a python environment to run this file. In my case, I have used Python3.6 to run this file.

Code Explanation of the img_to_bmp.py file

You need to install the following “PIL” library in your Python environment by using the “pip” command. The input_filename_with_path is containing the path of the file without extension. In my case, the image file and the img_to_bmp.py file are in the same folder. So, I mentioned only the name of the image file. The “Image.open(file_in)” is opening the targeted image file and then we are performing some image operation by using the transpose() and convert() functions. The save() function is used to save the converted image as an output file with the “.bmp” extension. Then the Image.open(file_out,mode='r') is used to open the “bmp” file and io.BytesIO() function is used to read the bitmaparray of the image. The img_bytes is used to store the bitmap array which we will get at the output. The print(img_bytes) will print the byte array of the input image. We need to copy this byte array for further reference in the “main.py” file. The print('Image Resolution: ({0},{1})'.format(img.width,img.height)) will print the resolution of the image. We need to use this resolution in our “main.py” file. Make sure that the resolution is not large. You can use any online converter to reduce the image resolution.

import io
from PIL import Image
input_filename_with_path = "rpilogo1"
file_in = input_filename_with_path + ".png"
file_out = input_filename_with_path+".bmp"
img = Image.open(file_in)
img = img.transpose(Image.FLIP_LEFT_RIGHT)
threshold = 65
func = lambda x : 255 if x > threshold else 0
img = img.convert('L').point(func,mode='1')
img.save(file_out)
img = Image.open(file_out,mode='r')
img_bytes = io.BytesIO()
img.save(img_bytes,format='BMP')
img_bytes = img_bytes.getvalue()
print("Copy this bitmap array:")
print('\n')
print(img_bytes)
print('\n')
print('Image Resolution: ({0},{1})'.format(img.width,img.height))

The above image is the output of the img_to_bmp.py. In my case, I have already converted the resolution of the input image into a 32x32 size.

So, now we have the byte array of the image. Let’s understand the code of the “main.py” file below. We are using the “machine” library to perform the basic hardware operations with the help of MicroPython. Then we are using the “ssd1306” library that we recently added to the Raspberry Pi Pico board. The “utime” library is used to access the inbuilt time feature of the raspberry pi pico board. The framebuf,sys library is used to perform the byte array operations.

from machine import Pin, I2C
from ssd1306 import SSD1306_I2C
import utime
import framebuf,sys
WIDTH  = 128                                            # oled display width
HEIGHT = 64    

The following image_byte_arr variable contains the byte array (bitmap array) of the image to be displayed. Paste the byte array which you have copied from the output of the img_to_bmp.py file. Then mention the same width and height of the image as per the output of the img_to_bmp.py file.

image_byte_arr = b'BM\xbe\x00\x00\x00\x00\x00\x00\x00>\x00\x00\x00(\x00\x00\x00 \x00\x00\x00 \x00\x00\x00\x01\x00\x01\x00\x00\x00\x00\x00\x80\x00\x00\x00\xc4\x0e\x00\x00\xc4\x0e\x00\x00\x02\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xff\xfc?\xff\xff\xfb\xcf\xff\xff\xe7\xf7\xff\xff\xc7\xf1\xff\xffs\xc6\x7f\xfe\xf1\xcf\xbf\xfd\xf7\xef\xbf\xfd\xf7\xf7\xdf\xff\xff\xf7\xdf\xfb\xef\xf3\xdf\xf9\xc7\xf1\x8f\xf6\x13\xeco\xf7|>w\xf7~\x7fw\xf7\xfe\x7fw\xf7\xff\x7fo\xfb\x7f\x7fo\xfc~~\x1f\xfd\xbc=\xff\xff\xe3\xe3\xbf\xfe\xf7\xf7\xbf\xff\x7f\xff\x7f\xff3\xe4\xff\xffx\x1f\x7f\xfe\xfc?\xbf\xfd\xfe?\xff\xfb\xff\x7f\xdf\xfb\xff\x7f\xdf\xfb\xfe\x7f\xef\xfb\xff\xbf\xef\xf9\xfb\xdf\x9f\xff\x0f\xf0\xff'
image_width = 32
image_height = 32

The following I2C() function is used to initialize the I2C communication. This function takes the number of the I2C channel as we have 2 channels of I2C in the pico board. In my case, I am using the I2C0. If you are using I2C1, then change the first parameter from 0 to 1. The next two parameters are used to indicate the SCL and SDL pins for the communication. In my case, I am using the 17 and 16 pins for SCL and SDL, respectively. Then the next parameter of the I2C function is refer to the I2C communication frequency. The i2c.scan() is used to get the targeted device address.

#OLED I2C Configuration
i2c = I2C(0, scl=Pin(17), sda=Pin(16), freq=200000) #Init I2C using pinsGP17&GP16 (defaultI2C0 pins)
print("I2C Address      : "+hex(i2c.scan()[0]).upper()) # Display device address
print("I2C Configuration: "+str(i2c))                   # Display I2C config

The SSD1306_I2C() function is used to initialize the OLED Display and store it in “oled” as an object. This function usually takes the width, height and the mode of the communication of the device. Then we have some predefined functions in the ssd1306 library which can be called by using the “oled” object. The oled.fill(0) is used to clear the screen.

oled = SSD1306_I2C(WIDTH, HEIGHT, i2c) # Init oled display

The following displayText() function is used to display the text on the OLED. You need to pass the text, position, clear_oled and the show_text parameter into the function. The position is set to (0,0) by default. But you can change the position of the text by this position parameter. The position of the text must be in the tuple format (for example: (x,y)). The clear_oled and the show_text is set to True by default but you can change the status by set these variables into False.

#OLED Text display Function
def displayText(text, position=(0,0),clear_oled=True,show_text=True):
    if clear_oled:
        oled.fill(0) # Clear the oled display in case it has junk on it.
    oled.text(text,position[0],position[1]) # dispaying text
    if show_text:
        oled.show()  # Updating the display

The below displayImage() function is used to display the image on the OLED display. This function has image_byte_array, image_resolution,position,clear_oled and show_img parameters. We need to pass the image_byte_arr variable in place of the image_byte_array parameter. Then the image_resolution is containing the image_width and the image_height must be in the tuple format. (example: (image_width, image_height)). Then you can pass the image position on OLED by using the position parameter. Again, the position needs to be in tuple format and it is set to (0,0) by default. The clear_oled and show_img parameters are set to False and True, respectively. We can change these status as per our need in the future. The bytearray() function is used to take the bitmap of the image. Then the framebuf.FrameBuffer() function is used to store the every bit of the bitmap. The frame buffer has several types. We are using the MONO_HMSB mode of the framebuffer. Then we need to use the oled.blit() function to display the frame of the image on the OLED module.

#OLED Image display function
def displayImage(image_byte_array, image_resolution,position=(0,0),clear_oled=False,show_img=True): 
    img = bytearray(image_byte_array)
    img = bytearray([img[i] for i in range(len(img)-1,-1,-1)])
    frame = framebuf.FrameBuffer(img, image_resolution[0], image_resolution[1], framebuf.MONO_HMSB) # frame buffer types: MONO_HLSB, MONO_VLSB, MONO_HMSB
    if clear_oled:
        oled.fill(0) # clear the OLED
        print("clear")
    if show_img:
        oled.blit(frame, position[0],position[1]) # show the image at location (x=0,y=0)
        oled.show()
        print("display")

The following code is used to display texts on the OLED and scroll those texts on the OLED. I called the displayText() function for two times under the for loop and passed the text1 and the text2 as string with their corresponding positions “(x,0)” and (WIDTH-x,20). I set the clear_oled as False and show_text as True for text1 and for text2 I set the clear_oled as True and show_text as True. It will allow us to display the texts on the OLED in every iteration. When the value of the “x” variable will reach to the end of the iteration that is the WIDTH of the OLED, then the for loop will break.

#Scrolling Text on OLED
text1 = "Welcome to"
text2 = "CircuitDigest"
for x in range(0, WIDTH):
    displayText(text1,(x,0),clear_oled=False,show_text=True)
    displayText(text2,(WIDTH-x,20),clear_oled=True, show_text=True)
    if x == WIDTH:
        break
    else:
        x+=5

Under the while loop, below I used for loop to animate the Image with text. I used the displayImage function to display the image. I provided the image_byte_arr, (image_width,image_height), (x,y), and clear_oled parameters. Here the “(x,y)” is the position of the image which are in the tuple format. The image_width and the image_height is representing the resolution of the image in the tuple format. Then I set the clear_oled as False and I did not set the show_img variable because it is set to True by default. So, you can also use the both displayImage() and the displayText() function to display image and text on OLED, respectively.

while True:
    y=0
    text = "Interfacing OLED"
    oled.fill(0)
    #Animating Text And Image Horizontaly
    for x in range(0,WIDTH-image_width):
        displayImage(image_byte_arr,(image_width,image_height),(x,y),clear_oled=False)
        displayText(text,(x,y+40),clear_oled=False,show_text=True)
        if x == (WIDTH-image_width)-1:
            break
        else:
            x+=2
            oled.fill(0)
    for x in range(WIDTH-image_width,-1,-1):
        displayImage(image_byte_arr,(image_width,image_height),(x,y),clear_oled=True)
        displayText(text,(x,y+40),clear_oled=False,show_text=True)
        if x == 0:
            break
        else:
            x-=2

Now, open the “main.py” file and the “ssd1306.py” file in the Thonny IDE. At first you need to save the “ssd1306.py” file on the Pico board by pressing “ctrl+shift+s” of your keyboard. Make sure that you have connected your Pico board with your Laptop before saving the files. When you will save the code it will show you a popup as the below image. You need to select the Raspberry Pi Pico and then name the file as “ssd1306.py” and click on save. Then do the same procedure for the “main.py” file. This procedure allows you to run the program when the Pico will be powered up.

Working demo of the Interfacing of the OLED Display Raspberry Pi Pico

In the following video, I have explained all the steps and codes in detail. You can refer the following video to interface an OLED with the Raspberry Pi Pico board.