ESP32 MicroPython OLED 128x32
This tutorial instructs you how to use a ESP32 and MicroPython with an OLED 128x32 I2C display. You will learn:
- How to connect a 128x32 OLED display to the ESP32.
- How to write MicroPython code for ESP32 to display text and numbers on the 128x32 OLED screen using ESP32.
- How to write MicroPython code for ESP32 to draw on the 128x32 OLED screen with ESP32.
- How to write MicroPython code for ESP32 to show images on the 128x32 OLED screen using ESP32.
- How to write MicroPython code for ESP32 to align text and numbers in the middle of the 128x32 OLED screen.
Hardware Preparation
| 1 | × | ESP-WROOM-32 Dev Module | |
| 1 | × | USB Cable Type-C | |
| 1 | × | SSD1306 I2C OLED Display 128x32 | |
| 1 | × | Jumper Wires | |
| 1 | × | Breadboard | |
| 1 | × | (Recommended) Screw Terminal Expansion Board for ESP32 |
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 128x32 I2C OLED Display
128x32 I2C OLED Display Pinout
- GND pin: Connect to ESP32's ground.
- VCC pin: Connect to the 5 volts pin on ESP32 for power.
- SDA pin: This is the data pin for I2C communication.
- SCL pin: This is the clock pin for I2C communication.
Wiring Diagram
- How to connect ESP32 and oled 128x32 using breadboard
This image is created using Fritzing. Click to enlarge image
- How to connect ESP32 and oled 128x32 using screw terminal block breakout board
The below is the wiring table between 128x32 OLED Module and ESP32
| 128x32 OLED Module | ESP32 |
|---|---|
| VCC | 3.3V |
| GND | GND |
| SDA | GPIO21 |
| SCL | GPIO22 |
ESP32 MicroPython Code - Display Text, Integer and Float Number on OLED
"""
This ESP32 MicroPython code was developed by newbiely.com
This ESP32 MicroPython code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-oled-128x32
"""
from machine import I2C, Pin
from DIYables_MicroPython_OLED import OLED_SSD1306_I2C
# Initialize I2C
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=400000)
# Initialize the OLED display
oled = OLED_SSD1306_I2C(128, 32, 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.678
oled.set_cursor(0, 0)
oled.println(text)
oled.set_cursor(0, 19)
oled.println(str(integer_value)) # Print integer and move to the next line
oled.set_cursor(50, 19)
oled.println("{:.3f}".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 ESP32 board by.
- If this is your first time using a ESP32 with MicroPython, refer to the ESP32 MicroPython Getting Started tutorial for detailed instructions.
- Connect the OLED display to the ESP32 according to the provided diagram.
- Connect the ESP32 board to your computer with a USB cable.
- Open Thonny IDE on your computer.
- In Thonny IDE, go to Tools Options.
- Under the Interpreter tab, choose MicroPython (ESP32) 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 COM12 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 ESP32 board by:
- Click the Save button, or use Ctrl+S keys.
- In the save dialog, you will see two sections: This computer and MicroPython device. Select MicroPython device
- Save the file as main.py
- Click the green Run button (or press F5) to run the script. The script will execute.
- Check out on the OLED display. It looks like the below:
ESP32 MicroPython Code - Drawing on OLED
"""
This ESP32 MicroPython code was developed by newbiely.com
This ESP32 MicroPython code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-oled-128x32
"""
from machine import I2C, Pin
from DIYables_MicroPython_OLED import OLED_SSD1306_I2C
# Initialize I2C
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=400000)
# Initialize the OLED display
oled = OLED_SSD1306_I2C(128, 32, 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)
# Draw a circle
oled.draw_circle(64, 16, 15, 1)
#oled.fill_circle(64, 16, 15, 1)
# Draw a triangle
#oled.draw_triangle(80, 31, 128, 31, 104, 0, 1)
oled.fill_triangle(80, 31, 128, 31, 104, 0, 1)
oled.display()
When you run the code above, a rectangle, circle, and triangle will appear on the OLED screen, as demonstrated below.
ESP32 MicroPython Code – Display Image on OLED
The below code draws an image to LCD display. The image is DIYables icon.
"""
This ESP32 MicroPython code was developed by newbiely.com
This ESP32 MicroPython code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-oled-128x32
"""
from machine import I2C, Pin
from DIYables_MicroPython_OLED import OLED_SSD1306_I2C
import utime
# Initialize I2C
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=400000)
# Create the SSD1306 display object
oled = OLED_SSD1306_I2C(128, 32, i2c)
# Clear the display buffer
oled.clear_display()
utime.sleep(2)
# 16x16 heart bitmap in RGB565 format
heart_bitmap = [
# 'DIYables Icon', 72x32
0x00, 0x0f, 0xff, 0xff, 0x8f, 0xf8, 0x07, 0x38, 0x07, 0x00, 0x0f, 0xff, 0xff, 0x8f, 0xfe, 0x07,
0x1c, 0x0e, 0x00, 0x0f, 0xff, 0xff, 0x8f, 0xff, 0x07, 0x1c, 0x1c, 0x00, 0x0f, 0xff, 0xff, 0x8e,
0x07, 0x87, 0x0e, 0x1c, 0x00, 0x0f, 0xff, 0xff, 0x8e, 0x03, 0xc7, 0x0f, 0x38, 0x00, 0x0f, 0xff,
0xff, 0x8e, 0x01, 0xc7, 0x07, 0x38, 0x00, 0x0f, 0xff, 0xff, 0x8e, 0x01, 0xc7, 0x03, 0xf0, 0xf0,
0x0f, 0xff, 0xff, 0x8e, 0x01, 0xc7, 0x03, 0xe0, 0xfc, 0x0f, 0xff, 0xff, 0x8e, 0x01, 0xc7, 0x01,
0xe0, 0xfe, 0x0f, 0xff, 0xff, 0x8e, 0x03, 0xc7, 0x01, 0xc0, 0xff, 0x8f, 0xff, 0xff, 0x8e, 0x03,
0x87, 0x01, 0xc0, 0xff, 0x8f, 0xff, 0xff, 0x8e, 0x0f, 0x87, 0x01, 0xc0, 0xff, 0xcf, 0xff, 0xff,
0x8f, 0xff, 0x07, 0x01, 0xc0, 0xff, 0xef, 0xff, 0xff, 0x8f, 0xfc, 0x07, 0x01, 0xc0, 0xff, 0xef,
0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00,
0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0x80, 0x00, 0x00,
0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0x8f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x8f,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x0f, 0xfc, 0xfd, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0x0f, 0xfc, 0xfc, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x0f, 0xfc, 0xfc, 0xff, 0xff, 0xff,
0xef, 0xff, 0xff, 0x0e, 0x0c, 0x0c, 0xc3, 0x07, 0xff, 0xef, 0xff, 0xfe, 0x0f, 0xec, 0xec, 0x99,
0x7f, 0xff, 0xef, 0xff, 0xfe, 0x0f, 0x04, 0xe4, 0x81, 0x0f, 0xff, 0xcf, 0xff, 0xfc, 0x0e, 0x32,
0xe4, 0x9f, 0xc7, 0xff, 0x8f, 0xff, 0xf8, 0x0e, 0x32, 0x4c, 0x9b, 0x67, 0xff, 0x0f, 0xff, 0xf0,
0x0e, 0x04, 0x0c, 0xc3, 0x0f, 0xfe, 0x0f, 0xff, 0xe0, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x0f,
0xff, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xe0, 0x0f, 0xfc, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff
]
# Draw the bitmap on the display
oled.draw_bitmap(0, 0, heart_bitmap, 72, 32, 1)
# Update the display with the new image
oled.display()
utime.sleep(3)
#oled.invert_display(True)
When you run the code above, the image will appear on the OLED screen, as shown below.
To display a different image on the OLED screen, follow these steps:
- Convert the image (in any format) to a bitmap array. You can use this online tool for conversion. Refer to the image below for guidance on how to convert an image to a bitmap array. In this example, I converted the ESP32 icon into a bitmap array.
- Replace the existing bitmap array in your ESP32 MicroPython code with the newly converted array.
- Adjust the image width and height in your ESP32 MicroPython code to match the dimensions of the new image.
Note: Ensure the image size is equal to or smaller than the OLED screen size.
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 screen.
"""
This ESP32 MicroPython code was developed by newbiely.com
This ESP32 MicroPython code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-oled-128x32
"""
from machine import I2C, Pin
from DIYables_MicroPython_OLED import OLED_SSD1306_I2C
import utime
# Initialize I2C
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=400000)
# Initialize the OLED display
oled = OLED_SSD1306_I2C(128, 32, 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.
