Interactive Mission

Connect OLED Display with ESP32

Wire a four-pin SSD1306 I2C OLED to ESP32 using 3.3 V, GND, SDA on GPIO21, and SCL on GPIO22 in this site's examples, then show Hello, Maker on the screen.

Quick BuildBeginner10–15 minutesParent SafeTeacher Friendly
ESP32 OLED display guide with SSD1306 screen and I2C wiring

Review, Testing, and References

Author: Abdul Mubeen and the ESP32 Engine editorial team. Last updated: 2026-11-01. Reviewed: educational accuracy and beginner safety. Level: Beginner. Estimated time: 10–15 min.

This guide is written for learning and bench prototyping. Check the testing notes before adapting the circuit to different boards, batteries, relays, motors, or outdoor hardware.

Before you start

Board and software
Classic ESP32-WROOM DevKit / ESP32 Dev Module, Arduino IDE 2 and Arduino-ESP32 3.3.2 review baseline, not a latest-release claim. Match GPIO labels, not header positions.
Circuit and dependencies
Four-pin I2C SSD1306 128×64 module documented for 3.3 V supply/signals, SDA21/SCL22 and common GND. Check address/reset circuit; SPI and SH1106 modules are different.
Before this lesson
Read Temperature with DHT11
Evidence limits
Expected behavior describes the example, not a hardware test performed in this review. Contributor media, where present, is identified separately; no compilation, board upload or accuracy measurement is claimed.
Quick Build

Give Your Project a Face!

The Story

Blinking lights and sensor numbers are cool — but every great gadget has a screen. Game consoles, phones, even microwave ovens show you what's happening.

Your ESP32 will talk to a four-pin SSD1306 OLED display over I2C using VCC, GND, SDA, and SCL. This is not SPI wiring; SPI OLED modules use extra signal pins and different code. When you see "Hello, Maker!" glow on that blue screen, your project starts to feel like a real product.

Explain Like I'm 12

The OLED is a tiny TV screen with only four wires: power, ground, and two communication wires called SDA and SCL. They form a language called I2C — like a two-lane road where the ESP32 sends drawing instructions and the screen shows them.

Watch the tutorial

Follow this guide’s wiring and GPIO assignments when building; the video may use different pins or a different board.

Open on YouTube

Mission Goal

Wire a four-pin SSD1306 I2C OLED to ESP32 using 3.3 V, GND, SDA on GPIO21, and SCL on GPIO22 in this site's examples, then show Hello, Maker on the screen.

Estimated Time

10–15 min

Difficulty

Beginner

Prerequisites

Skills You'll Learn

  • Wire SSD1306 OLED via I2C (SDA, SCL, 3.3 V, GND)
  • Use Adafruit SSD1306 and GFX libraries
  • Draw text on a 128×64 screen

Components Required

What Is I2C?

ESP32 connected to OLED via SDA and SCL lines with shared ground, labeled 0x3C address

I2C lets multiple devices share two wires — SDA (data) and SCL (clock). Each device has an address; SSD1306 OLED modules usually use 0x3C and some use 0x3D.

This site uses GPIO21 for SDA and GPIO22 for SCL in ESP32 examples. Those pins are common, not universal fixed I2C pins. If you choose different ESP32 pins later, the wiring and Wire.begin(SDA, SCL) call must match.

The Adafruit SSD1306 library handles the hard work. You call display.println() like Serial, then display.display() to refresh the pixels.

Wiring Diagram

Follow these steps in order. Unplug USB before you change any wires.

OLED VCC to 3.3V, GND to GND, SDA to GPIO21, SCL to GPIO22
  1. 1

    Unplug USB. Place the OLED module on the breadboard or connect its pins directly.

  2. 2

    Connect OLED VCC to ESP32 3.3 V.

  3. 3

    Connect OLED GND to ESP32 GND.

  4. 4

    Connect OLED SDA to ESP32 GPIO21, the common SDA example pin used here.

  5. 5

    Connect OLED SCL to ESP32 GPIO22, the common SCL example pin used here.

  6. 6

    If your module is labeled differently or has SPI pins such as MOSI, CLK, DC, or CS, do not copy this I2C wiring.

  7. 7

    Install Adafruit SSD1306 and Adafruit GFX libraries in Arduino IDE.

GPIO Table

SignalESP32 PinModeNotes
OLED VCC3.3 VPowerUse 3.3 V for this ESP32 beginner build. Some modules tolerate 5 V, but do not assume it.
OLED GNDGNDGroundThe OLED and ESP32 must share ground.
OLED SDAGPIO21I2C dataCommon ESP32 Arduino example SDA pin used by this site; match Wire.begin(21, 22).
OLED SCLGPIO22I2C clockCommon ESP32 Arduino example SCL pin used by this site; match Wire.begin(21, 22).
OLED address0x3C or 0x3DI2C addressTry 0x3C first, then run an I2C scanner or test 0x3D if the screen stays blank.

Arduino Code

Copy this into Arduino IDE, then click Upload.

oled_hello.ino
#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define OLED_ADDRESS 0x3C

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

bool oledResponds() {
  Wire.beginTransmission(OLED_ADDRESS);
  return Wire.endTransmission() == 0; // ACK only, not controller identification.
}

void setup() {
  Serial.begin(115200);
  Wire.begin(21, 22);

  Wire.setTimeOut(50); // Per bus operation, not a whole-sketch deadline.
  if (!oledResponds()) {
    Serial.println("No I2C ACK at OLED_ADDRESS; check power, bus and address, then reset");
    while (true) delay(1000);
  }
  if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDRESS, true, false)) {
    Serial.println("SSD1306 buffer/init failed; this is not a presence test");
    while (true) delay(1000);
  }
  display.clearDisplay();
  display.setTextSize(2);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 20);
  display.println("Hello,");
  display.println("Maker!");
  display.display();
}

void loop() {
}

Classic ESP32-WROOM DevKit; Arduino-ESP32 3.3.2 review baseline (not latest). Selected display: a documented 3.3 V-compatible 128×64 I2C SSD1306 module with bus pull-ups to 3.3 V, four labelled VCC/GND/SDA/SCL pins and suitable reset circuitry. SH1106 and SPI displays need another driver/wiring. Pins are SDA21/SCL22; set OLED_ADDRESS from the module documentation/scanner. An ACK checks address response, not controller identity. Install Adafruit SSD1306 2.5.13, Adafruit GFX 1.12.1 and Adafruit BusIO 1.17.0. Documentation reviewed; no compilation or hardware testing performed.

Read Serial at 115200 before diagnosing a blank panel. ACK and buffer allocation are separate checks.

Line-by-line Explanation

  • Wire.begin(21, 22) selects the pins shown in the wiring table; the ACK probe runs before framebuffer initialization.
  • clearDisplay(), setCursor() and println() prepare the text in RAM. display.display() transfers that buffer to the panel.
  • loop() is empty because this static greeting is drawn once. Startup errors require checking the module with power off and restarting.

Supplied OLED wiring and Hello, Maker display

Explore the build photos and recorded results. Open any image to inspect the details.

About this recorded build

Contributor-supplied photos and IDE captures, not an independent hardware retest. IDE captures show Arduino IDE 2.3.10 / ESP32 Dev Module; COM7 or COM8 belongs to that computer. Installed core and library versions were not supplied. Photographs cannot prove every hidden breadboard connection; trace the documented pins on your own parts.

The supplied complete sketch matches the main example: SDA GPIO21, SCL GPIO22, address 0x3C and a 128×64 SSD1306 library configuration. The photograph shows Hello, Maker! on the display; it does not independently identify every OLED controller or establish a universal address. I2C ACK is not controller identification.

Four-pin OLED board with GND VCC SCL SDA labels visible
Image 01

Supplied OLED close-up with GND, VCC, SCL and SDA labels. Confirm module supply requirements and controller before adapting the example.

View full-size image
ESP32 breadboard connected to a four-pin OLED module with screen unlit
Image 02

Contributor wiring overview. Match the actual signal labels to SDA21 and SCL22; the blank photograph alone does not diagnose a fault.

View full-size image
Supplied Arduino IDE screenshot with SSD1306 configuration and Done uploading notice
Image 03

Contributor upload capture for the SSD1306 sketch. Upload completion is distinct from display-controller identification.

View full-size image
Connected OLED visibly displaying Hello comma Maker exclamation on two lines
Image 04

Contributor result: Hello, Maker! agrees with the supplied code’s two display.println calls.

View full-size image

Expected Behaviour

Illustrative expected output, not recorded hardware data:

Serial should remain available at 115200. A selected address with no ACK prints the bus/address diagnostic; framebuffer initialization failure prints a separate message. With the supported module, the intended output is Hello, then Maker! on the screen. These are expected checks, not recorded hardware results. An ACK or successful library begin does not prove that visible pixels appeared.

Troubleshooting

Most ESP32 problems are wiring, power, library, or timing issues. Check these first.

  • No I2C ACK at OLED_ADDRESS

    Likely cause: No responding device at the selected address.

    Fix: Power off to check VCC/GND/SDA21/SCL22. Run the linked scanner; choose 0x3C or 0x3D only when supported by your module.

  • SSD1306 buffer/init failed

    Likely cause: The library could not allocate/initialize its framebuffer; not proof of a missing OLED.

    Fix: Verify reviewed library versions and available memory; inspect the exact error. An ACK alone does not establish SSD1306 compatibility.

  • ACK present, panel still blank

    Likely cause: Controller/dimensions/reset/power may be incompatible, or drawing was not transferred.

    Fix: Verify 128×64 I2C SSD1306, module reset requirements and display.display(). Do not hot-rewire or assume SH1106 uses this driver.

Mini Challenge

No wrong answers — experiment and have fun!

Show live DHT11 temperature on the OLED after completing the Read Temperature with DHT11 quick build linked below — combine both sketches! Or animate text: scroll "ESP32 Engine" across the screen using setCursor in a loop.

Previous Mission

Continue Learning

Technical references

Continue beginner route: practise display skills