Display Text on OLED
with ESP32 & MicroPython
Connect a 0.96-inch SSD1306 OLED to ESP32 using I2C, write two lines of MicroPython, and see "Hello, Wokwi!" light up in minutes — all in your browser!
Overview
What You'll Build
A working OLED display showing custom text — your first step toward IoT dashboards, weather monitors, and smart devices.
Components
What You Need
Only 2 virtual components — the simplest ESP32 display project you'll find!
ssd1306 module is included with the firmware. Just import it and start drawing.About the Display
Understanding the SSD1306 OLED
The SSD1306 is the most popular OLED driver chip — used in everything from smartwatches to maker projects.
OLED Pin Description
| OLED Pin | Function | Description |
|---|---|---|
| VCC | Power Supply | 3.3V from ESP32 — not 5V! |
| GND | Ground | Common ground reference |
| SCL | I2C Clock | Synchronises data transfer timing |
| SDA | I2C Data | Carries display commands and pixel data |
Wiring
ESP32 Default I2C Pins
The ESP32 DevKit uses GPIO 22 for SCL and GPIO 21 for SDA by default — just 4 wires total!
Full Connection Table
| OLED Pin | ESP32 Pin | Wire Color |
|---|---|---|
| VCC | 3V3 | 🔴 Red |
| GND | GND | ⬛ Black |
| SCL | GPIO 22 | 🟢 Green |
| SDA | GPIO 21 | 🔵 Blue |
Instructions
Step-by-Step Guide
6 simple steps from zero to "Hello, Wokwi!" on your OLED.
-
Open the Wokwi Simulation
Click wokwi.com/projects/305568836183130690 to open the pre-built project, or go to wokwi.com → New Project → ESP32 to start from scratch.
-
Select MicroPython as the language
In Wokwi, the board board-esp32-devkit-c-v4 has a
envattribute set tomicropython-20231005-v1.21.0. This is already configured in the diagram.json — pasting it sets MicroPython automatically. -
Paste the diagram.json
Click the diagram.json tab in Wokwi, select all, and paste the JSON from the Diagram JSON section below. This auto-places the ESP32 and OLED with all 4 wires connected.
-
Add the MicroPython code
Open the main.py tab and paste the code from the Code section below. Just 6 lines of Python — that's all it takes!
-
Click ▶ Start Simulation
Press the green play button. The virtual ESP32 boots MicroPython, initialises the I2C bus on GPIO 21/22, and sends the text to the OLED. The display should light up with "Hello, Wokwi!" within 1–2 seconds.
Expected result: OLED shows white text "Hello, Wokwi!" at position (10, 10). No errors in the Serial Monitor console. -
Customise and experiment!
Try changing the text string, coordinates, or add more
oled.text()lines to display multiple rows. Useoled.fill(0)to clear the screen between updates.
Diagram JSON
Wokwi diagram.json
Paste this into the diagram.json tab. It configures MicroPython firmware on the ESP32 and wires the OLED with correct routed paths.
diagram.json tab → Select all → Delete2. Paste the JSON below — ESP32 + OLED appear pre-wired
3. MicroPython v1.21.0 is auto-configured via the
env attribute4. Serial Monitor is also connected via the TX/RX lines
{
"version": 1,
"author": "Uri Shaked",
"editor": "wokwi",
"parts": [
{
"type": "board-esp32-devkit-c-v4",
"id": "esp",
"top": 9.6,
"left": -100.76,
"attrs": {
"env": "micropython-20231005-v1.21.0"
}
// ↑ This sets MicroPython firmware automatically
},
{
"type": "board-ssd1306",
"id": "oled1",
"top": 99.14,
"left": 57.83,
"attrs": {}
}
],
"connections": [
// Serial Monitor connections (for debugging)
[ "esp:TX", "$serialMonitor:RX", "", [] ],
[ "esp:RX", "$serialMonitor:TX", "", [] ],
// OLED I2C connections
[ "oled1:SCL", "esp:22", "green", ["v0"] ],
[ "oled1:SDA", "esp:21", "blue", ["v-19.2", "h-124.73"] ],
// OLED power
[ "oled1:GND", "esp:GND.2", "black", ["v-67.2", "h-96"] ],
[ "oled1:VCC", "esp:3V3", "red", ["v-28.8", "h0.15", "v-76.8", "h-201.75"] ]
],
"dependencies": {}
}
📋 Connection Reference
| Connection | Purpose |
|---|---|
| esp:TX → serialMonitor:RX | Enables Serial Monitor output for debugging print() statements |
| oled1:SCL → esp:22 | I2C clock — GPIO 22 is the default SCL pin on ESP32 DevKit |
| oled1:SDA → esp:21 | I2C data — GPIO 21 is the default SDA pin on ESP32 DevKit |
| oled1:GND → esp:GND.2 | Ground reference for OLED circuit |
| oled1:VCC → esp:3V3 | 3.3V power — the SSD1306 is a 3.3V device |
Source Code
MicroPython Code
Just 6 lines of Python — paste this into the main.py tab in Wokwi.
# ESP32 OLED Display — SSD1306 with MicroPython # MakeMindz Summer Class | makemindz.com # Simulation: https://wokwi.com/projects/305568836183130690 from machine import Pin, I2C import ssd1306 # ── I2C setup using ESP32 default pins ── # GPIO 22 = SCL (clock) GPIO 21 = SDA (data) i2c = I2C(0, scl=Pin(22), sda=Pin(21)) # ── OLED dimensions ── oled_width = 128 oled_height = 64 # ── Create OLED display object ── oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c) # ── Display text ── # oled.text(string, x, y) — top-left is (0, 0) oled.text('Hello, Wokwi!', 10, 10) # Row 1 oled.text('MakeMindz.com', 10, 30) # Row 2 # ── Push buffer to screen ── oled.show()
oled.fill(0) before drawing to clear the screen, or use oled.invert(1) to flip to a black-on-white display. Each pixel position is (x, y) where (0,0) is the top-left corner.Explanation
How It Works
I2C Communication
I2C (Inter-Integrated Circuit) is a 2-wire protocol that lets the ESP32 control the OLED using just SDA (data) and SCL (clock). The MicroPython line i2c = I2C(0, scl=Pin(22), sda=Pin(21)) creates an I2C bus on ESP32's hardware I2C bus 0. The SSD1306 listens on I2C address 0x3C by default. Multiple devices can share the same I2C bus as long as they have different addresses.
SSD1306 Frame Buffer
The ssd1306.SSD1306_I2C() class maintains a 128×64 pixel frame buffer in ESP32 memory. When you call oled.text(), it writes characters into this buffer — but nothing appears on screen yet. Only when you call oled.show() does the ESP32 transfer the entire buffer to the OLED over I2C. This two-step approach prevents flickering during complex animations.
Text Positioning
oled.text(string, x, y) positions text where x is pixels from the left edge and y is pixels from the top. The built-in font is 8×8 pixels per character, so each row of text is 8 pixels tall. With a 64-pixel height, you can fit up to 8 rows of text. Columns: 128 / 8 = 16 characters per row maximum.
Output
Expected Output
After running the simulation, here's what you should see:
OLED Display Output
Hello, Wokwi!
MakeMindz.com
128×64 px · I2C addr 0x3C · GPIO 21/22
Education
What You'll Learn
Use Cases
Real-World Applications
Mastering this project unlocks a huge range of IoT and embedded display applications.
Comments
Post a Comment