How to Connect and Display Text on OLED Screen Using ESP32 – Complete Beginner Guide

 

Introduction

Learn how to connect a 0.96-inch OLED display to an ESP32 and print custom text like "Hello, Wokwi!" using I2C communication. This simple beginner-friendly tutorial will get you started in just minutes.

Diagram.json:

{

  "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" }

    },

    { "type": "board-ssd1306", "id": "oled1", "top": 99.14, "left": 57.83, "attrs": {} }

  ],

  "connections": [

    [ "esp:TX", "$serialMonitor:RX", "", [] ],

    [ "esp:RX", "$serialMonitor:TX", "", [] ],

    [ "oled1:SCL", "esp:22", "green", [ "v0" ] ],

    [ "oled1:SDA", "esp:21", "blue", [ "v-19.2", "h-124.73" ] ],

    [ "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": {}

}

---

Components Required

• ESP32 Development Board
• 0.96-inch OLED Display (128x64, I2C)
• Jumper Wires (4 wires – Black, Red, Green, Blue)
• USB Cable (for programming)

CODE:

from machine import Pin, I2C

import ssd1306

# ESP32 Pin assignment

i2c = I2C(0, scl=Pin(22), sda=Pin(21))

oled_width = 128

oled_height = 64

oled = ssd1306.SSD1306_I2C(oled_width, oled_height, i2c)

oled.text('Hello, Wokwi!', 10, 10)      

oled.show()

Components Required in Wokwi

Hardware (Virtual):

• 1x ESP32 DevKit v1 board
• 1x SSD1306 OLED Display (128x64, I2C interface)
• 4x Jumper wires (automatic in Wokwi)

Software/Libraries:

• Adafruit SSD1306 library
• Adafruit GFX library
• Wire library (built-in for I2C)

---

Step-by-Step Wokwi Setup Instructions

Step 1: Create New ESP32 Project in Wokwi

1. Navigate to https://wokwi.com
2. Click "New Project" button
3. Select "ESP32" from the board options
4. The ESP32 board will appear on your canvas

Step 2: Add OLED Display Component

1. Click the blue "+" (Add Part) button in the sidebar
2. Type "SSD1306" or "OLED" in the search box
3. Select "SSD1306 128x64 I2C OLED Display"
4. Click to place it on the canvas next to the ESP32

Step 3: Understanding OLED Pin Configuration

The OLED display has 4 pins:

• GND - Ground (power reference)
• VCC - Power supply (3.3V or 5V)
• SCL - Serial Clock Line (I2C clock)
• SDA - Serial Data Line (I2C data)

ESP32 Default I2C Pins:

• GPIO 22 - SCL (Clock)
• GPIO 21 - SDA (Data)

Step 4: Wire the Circuit in Wokwi

Connection Table:

OLED Pin	ESP32 Pin	Wire Color (Suggestion)
VCC	3V3	Red
GND	GND	Black
SCL	GPIO 22	Yellow
SDA	GPIO 21	Green

Wiring Instructions:

1. VCC Connection:
   • Click the OLED's VCC pin
   • Drag wire to ESP32's 3V3 pin (provides 3.3V power)

2. GND Connection:
   • Click the OLED's GND pin
   • Drag wire to any GND pin on ESP32

3. SCL Connection:
   • Click the OLED's SCL pin
   • Drag wire to ESP32's GPIO 22 (default I2C clock pin)

4. SDA Connection:
   • Click the OLED's SDA pin
   • Drag wire to ESP32's GPIO 21 (default I2C data pin)

Visual Check: Your wiring should match the uploaded screenshot with 4 colored wires connecting the boards.

Step 5: Configure Libraries in Wokwi

1. Click on the "Library Manager" icon (book icon) or check the libraries section
2. Wokwi automatically includes common libraries, but verify these are present:
   • Adafruit SSD1306
   • Adafruit GFX Library

If you need to add them manually, edit the wokwi.toml file

Step 6: Run the Simulation

1. Click the green "Start Simulation" play button
2. Watch the OLED display show "Hello, Wokwi!"
3. Check the Serial Monitor (bottom panel) for debug messages
4. The simulation timer shows elapsed time (top right)

Step 7: Verify Display Output

Expected Results:

• OLED screen lights up with white text on black background
• Text displays: "Hello, Wokwi!" in size 2 font
• Serial Monitor shows: "OLED initialized successfully!"
• No error messages appear