Tom's Hardware is supported by its audience. When you purchase through links on our site, we may earn an affiliate commission. Here’s why you can trust us

By Les Pounder published 23 April 21

Let us show you how to get started with these great displays.

We've expanded this how to and it now includes sections on drawing shapes and objects to the display, how to convert bitmap images for OLED displays and how to animate images.

The Raspberry Pi Pico has no shortage of options when it comes to digital displays. We can use LCD screens, output to VGA / DVI or use bespoke screens such as the Pico Display or Pico Explorer Base’s IPS display. But sometimes we need a small, cheap option to get the job done. OLED screens such as the 0.96 inch model used in this tutorial, are trivial to use with MicroPython and they cost only a few bucks (or pounds) making them ideal for projects.

In this tutorial, we will learn how to connect an OLED screen to a Raspberry Pi Pico via the I2C interface, then we will install a MicroPython library via the Thonny editor and learn how to use it to write text to the display.

The OLED screen uses the I2C protocol to interface with the Raspberry Pi Pico. Which means that we only require.

Use the following wiring. 

1. Connect the GND of the screen to any GND on the Pico (Black wire).

2. Connect VDD / VCC to 3V3 on the Pico (Red wire).

3. Connect SCK / SCL to I2C0 SCL (GP1, Physical pin 2, Orange wire).

4. Connect SDA to I2C0 SDA (GP0, Physical pin 1, Yellow wire).

5. Connect your Raspberry Pi Pico to your computer and open the Thonny application.

With the hardware connected and Thonny open, we now need to install a library in order for Python to communicate with the screen.

6. Click on Tools > Manage Packages to open Thonny’s package manager for Python libraries.

7. Type “ssd1306” in the search bar and click “Search on PyPI”. 

8. Click on “micropython-ssd1306” in the returned results and then click on Install. This will copy the library to a folder, lib on the Pico. 

9.  Click Close to return to the main interface. 

To write a single line of text to the OLED screen we need just six lines of MicroPython.

1. From the machine library, import the Pin and I2C classes. These are used to communicate with the OLED screen, attached to the GPIO of the Pico. 

2.  Import the OLED screen library. 

3. Create an object, i2c, which stores the I2C channel in use, in this case zero,  the SDA and SCL pins that we are connected to, and finally the frequency at which we connect to the OLED screen. 

4. Create an object, oled, which will be used to communicate with the OLED screen. It has three arguments, the width and height of the screen (128 x 64 pixels) and the I2C connection details. 

5. Write a line of text to the top left of the screen, position 0,0. 

6. Finally  use the show command to render the output to the screen. 

The final code should look like this

7. Save and run your code. As with any Python script in Thonny, Click on File >> Save and save the file to your Raspberry Pi Pico as oled-test.py. When ready click on the Green play button to start the code and your text will appear on the OLED screen.

Simple shapes and lines can be drawn to the display with just a single command. Each of these commands will need oled.show() in order to be seen. Note that most of these methods have a color parameter but, with a monochrome screen, you’ll always put a color of “1” (0 means pixel off).

We can show much more than just text on the screen. Using a clever technique we can convert a JPEG image into a string of bytes. 

We are going to use the code above as a base to work from. So if you haven’t already done so, copy and paste the final code above into Thonny.

1. Import the framebuf library. This library enables the code to create bitmap images and show them on the display.

2. Create a new object, TH which will store an array of bytes that make up our image. For now leave the contents of the array blank, we will fill in the blank later.

3. Create an object, FB, which will load the image into the framebuffer. We pass the name of the bytearray object, the dimensions of the image (64 x 64 pixels) and then configure the image to be a 1-bit monochrome image.

4. Clear the screen, and then blit the image onto the screen. Then use show to update the screen. Blitting draws the image to the screen, in this case it places the 64 x 64 image dead center of the screen. Where 32 is the horizontal (x) position and 0 is the vertical (y) position.

Our object, TH, currently has no image to display. To create a bytearray of an image we first need a suitable image. The screen is 128 x 64 pixels in size, but an image 64 x 64 pixels will fit nicely into the center of the screen. The image must be in a JPEG format.

To convert the image to a bytearray we shall use Don Hui’s (Novaspirit) img2bytearray python script.

1. Download and extract the ZIP archive to your machine. This creates a folder, img2bytearray which stores the Hui’s Python file.

2. Copy your image to the img2bytearray folder.

3. Open a Command Prompt / Terminal window and navigate to the img2bytearray folder.

4. To convert the image we call the command img2bytearray. We need to provide three extra parameters. First is the name of the image file, the next two are the dimensions of the image, in this case 64 by 64 pixels.

5. The command outputs a stream of bytes. Copy the text from b’ … ‘ and paste it inside the parenthesis of our TH object.

The final code should look like this 

6. Save and run your code. As with any Python script in Thonny, Click on File >> Save and save the file to your Raspberry Pi Pico as oled-test.py. When ready click on the Green play button to start the code and your image will appear on the OLED screen. 

Creating an animation with the OLED display is a matter of moving or changing objects to give the illusion of movement. In the above GIF you can see the Tom’s Hardware hammer, and logo scrolling across the screen. To achieve this we used two byte arrays, for the hammer (TH) and the logo (LOGO). 

Again we will build upon the code from the previous examples.

1.  Import the previous libraries of code. 

2.  Setup the I2C pins for the OLED screen. 

3. Create a while True loop to continuously run the code.

4. Create the TH bytearray. In there we store the bytes that make up the Tom’s Hardware hammer. 

5. Create an object, FB, which will load the image into the framebuffer, then clear the screen. We pass the name of the bytearray object, the dimensions of the image (64 x 64 pixels) and then configure the image to be a 1-bit monochrome image.

6. Use a for loop with a range from -64 to 128, to create a basic sliding animation for the hammer. The negative value hides the hammer to the left of the screen, slowly scrolling the hammer from left to right until it goes out of visible range. By changing the value of “i” inside oled.blit() we create the illusion of movement. 

7. Create a new bytearray for the Tom’s Hardware logo. 

8. Create an object, FB, which will load the image into the framebuffer, then clear the screen. We pass the name of the bytearray object, the dimensions of the image (128 x 64 pixels) and then configure the image to be a 1-bit monochrome image.

9. The remaining code is largely the same as before, the only difference being the for loop range changes to -128 to 128 to accommodate the larger Tom’s Hardware logo scrolling across the screen.

Your code should look like this

Save and run your code. As with any Python script in Thonny, Click on File >> Save and save the file to your Raspberry Pi Pico as oled-test.py. When ready click on the Green play button to start the code and your animation will scroll across the OLED screen.

Les Pounder is an associate editor at Tom's Hardware. He is a creative technologist and for seven years has created projects to educate and inspire minds both young and old. He has worked with the Raspberry Pi Foundation to write and deliver their teacher training program "Picademy".

Get instant access to breaking news, in-depth reviews and helpful tips.

Thank you for signing up to Tom's Hardware. You will receive a verification email shortly.

There was a problem. Please refresh the page and try again.

Tom's Hardware is part of Future US Inc, an international media group and leading digital publisher. Visit our corporate site (opens in new tab) .

© Future US, Inc. Full 7th Floor, 130 West 42nd Street, New York, NY 10036.