Arduino MicroPython OLED 128x64

This guide shows you how to use an Arduino with an OLED 128x64 I2C display using MicroPython. You will learn:

Arduino MicroPython OLED I2C display

Hardware Preparation

1×Arduino Giga R1 WiFi
1×USB Cable Type-C
1×SSD1306 I2C OLED Display 128x64
1×Jumper Wires
1×(Recommended) Screw Terminal Block Shield for Arduino Uno/Mega/Giga
1×(Recommended) Breadboard Shield For Arduino Uno/Mega/Giga
1×(Recommended) Enclosure For Arduino Giga

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 vary in their communication methods, sizes, and colors.

  • Sizes: 128x64, 128x32
  • Colors available: white, blue, yellow...
  • Communication protocol: I2C, SPI
Arduino MicroPython OLED

SPI provides faster data transfer than I2C but needs more pins on the Arduino. I2C uses only two pins and can connect multiple devices. Your choice depends on whether you prefer fewer pins or higher speed. For I2C OLED displays, common drivers are SSD1306 and SH1106. This guide focuses on using the 128x64 SSD1306 I2C OLED display.

I2C OLED Display Pinout

  • GND pin: Connect to the ground (GND) on the Arduino.
  • VCC pin: Connect to the 5V or 3.3V pin on the Arduino for power.
  • SCL pin: This is the clock pin for I2C communication.
  • SDA pin: This is the data pin for I2C communication.
OLED Pinout

※ NOTE THAT:

OLED Module Pin Setup

  • Pin setups vary by manufacturer and model.
  • Follow the labels on your module.

This guide uses the SSD1306 I2C driver. We tested it with a DIYables OLED display.

Wiring Diagram

The wiring diagram between Arduino MicroPython OLED 128x64

This image is created using Fritzing. Click to enlarge image

Check the table below for details on other Arduino models.

OLED Module Arduino Giga R1 WiFi
VCC 3.3V
GND GND
SDA D9
SCL D8

Arduino MicroPython Code - Display Text, Integer and Float Number on OLED

""" This Arduino MicroPython script was developed by newbiely.com This Arduino MicroPython script is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/arduino-micropython/arduino-micropython-oled-128x64 """ from machine import I2C, Pin from DIYables_MicroPython_OLED import OLED_SSD1306_I2C # Initialize I2C i2c = I2C(1) # Arduino Giga R1 WiFi I2C1 pins: SCL-D8, SDA-D9 # 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

Here’s instructions on how to run the above MicroPython code on Arduino with Thonny IDE:

  • Make sure Thonny IDE is installed on your computer.
  • Make sure MicroPython firmware is installed on your Arduino board.
  • If you are new to Arduino with MicroPython, see the Getting Started with Arduino and MicroPython.
  • Connect the OLED display to the Arduino according to the provided diagram.
  • Connect the Arduino board to your computer with a USB cable.
  • Open Thonny IDE and go to Tools Options.
  • Under the Interpreter tab, select MicroPython (generic) from the dropdown menu.
  • Make sure the correct port is selected. Thonny IDE usually detects it automatically, but you might need to select it manually (like 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.
Arduino MicroPython OLED library
  • Copy the provided MicroPython code and paste it into Thonny\'s editor.
  • Save the MicroPython code to your Arduino by:
    • Clicking the Save button or pressing Ctrl+S.
    • In the save dialog, choose MicroPython device and name the file main.py.
  • Click the green Run button (or press F5) to execute the code.
  • Take a look at the result on the OLED display. It appears as shown below:
Arduino MicroPython 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 Arduino MicroPython script was developed by newbiely.com This Arduino MicroPython script is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/arduino-micropython/arduino-micropython-oled-128x64 """ from machine import I2C, Pin from DIYables_MicroPython_OLED import OLED_SSD1306_I2C import utime # Initialize I2C i2c = I2C(1) # Arduino Giga R1 WiFi I2C1 pins: SCL-D8, SDA-D9 # 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, you'll see a square, circle, and triangle on the OLED screen.

Arduino MicroPython OLED vertical and horizontal center align

Arduino MicroPython Code – Display Image on OLED

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

""" This Arduino MicroPython script was developed by newbiely.com This Arduino MicroPython script is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/arduino-micropython/arduino-micropython-oled-128x64 """ from machine import I2C, Pin from DIYables_MicroPython_OLED import OLED_SSD1306_I2C import utime # Initialize I2C i2c = I2C(1) # Arduino Giga R1 WiFi I2C1 pins: SCL-D8, SDA-D9 # 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'll see the image displayed on the OLED as shown below.

Arduino MicroPython 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 Arduino icon into a bitmap array.
image to bitmap array
  • Update the converted bitmap array into the Arduino MicroPython code with the new array code.
  • Change the image width and height in the Arduino MicroPython code to match the dimension of image.

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

Arduino MicroPython Code - Drawing Shapes on OLED

""" This Arduino MicroPython script was developed by newbiely.com This Arduino MicroPython script is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/arduino-micropython/arduino-micropython-oled-128x64 """ from machine import I2C, Pin from DIYables_MicroPython_OLED import OLED_SSD1306_I2C # Initialize I2C i2c = I2C(1) # Arduino Giga R1 WiFi I2C1 pins: SCL-D8, SDA-D9 # Initialize the OLED display oled = OLED_SSD1306_I2C(128, 64, i2c) # Clear the display oled.clear_display() # Draw a triangle #oled.draw_triangle(80, 62, 128, 62, 104, 32, 1) oled.fill_triangle(80, 62, 128, 62, 104, 32, 1) # Draw a rectangle #oled.draw_rect(0, 0, 40, 25, 1) oled.fill_rect(0, 0, 40, 25, 1) # Draw a circle oled.draw_circle(64, 32, 20, 1) ##oled.fill_circle(64, 32, 20, 1) oled.display()

After running the code, you'll see a rectangle, circle, and triangle on the OLED screen.

Arduino MicroPython draw rectangle, circle, an triagle on OLED

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 Arduino.
from machine import I2C, Pin import utime i2c = I2C(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 (generic) • Giga Virtual Comm Port in FS Mode @ COM33 ≡

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