Wiring guide

How to wire an SSD1306 OLED to an ESP32-S3

To wire an SSD1306 OLED to an ESP32-S3, connect VCC to 3V3, GND to G, SDA to GPIO 8 and SCL to GPIO 9. The ESP32-S3 is a 3.3 V board, so power the module from 3.3 V and its I2C pull-ups pull SDA and SCL to 3.3 V too. The sketch below uses the Adafruit SSD1306 and Adafruit GFX (Adafruit_SSD1306.h) library. It draws the board name, a box and a counter of the seconds since power-up.

  • 3.3 V logic
  • Library: Adafruit_SSD1306.h
  • 4 wires
ESP32-S3 · SSD1306 OLEDlive0.000 s 0.00x
Click to open it in the editor
The circuit itself, running on the simulator with the sketch below. Press what can be pressed; click anything else to open it in the editor.
Pin to pin

SSD1306 OLED to ESP32-S3 wiring table

Every wire in the circuit above, with the part’s pin names and the board’s own labels. The wire colors are the ones the circuit uses; on a real bench any colors work.

SSD1306 OLED pinESP32-S3 pinWire colorWhy
VCC3V3redThe usual blue module runs from 3.3 V, and its I2C pull-ups then pull to 3.3 V too.
GNDGblueCommon ground.
SDAGPIO 8violetESP32-S3’s I2C data line, where Wire.begin() puts it.
SCLGPIO 9cyanESP32-S3’s I2C clock line.
Voltage

Power and logic levels for SSD1306 OLED and ESP32-S3

Logic level

The ESP32-S3’s GPIO pins are 3.3 V logic and are not 5 V tolerant. Nothing wired to a pin may go above 3.3 V.

Supply

The SSD1306 OLED takes 3.3 V from 3V3. That pin is the ESP32-S3’s own regulated 3.3 V output.

This pair

On the ESP32-S3, Wire.begin() uses GPIO 8 for SDA and GPIO 9 for SCL. The silkscreen names each pin by its GPIO number, so the labels match the code. The display answers at address 0x3C, the address almost every 0.96 inch module ships with.

Pins to leave alone

GPIO 19 and 20 are the USB port’s data lines, GPIO 35 to 37 belong to the PSRAM on octal-PSRAM boards such as the N8R8, and GPIO 0, 3, 45 and 46 are strapping pins.

The sketch

The working code for the ESP32-S3

Library: Adafruit SSD1306 and Adafruit GFX (Adafruit_SSD1306.h). This is the sketch the circuit above runs.

SSD1306 on ESP32-S3 I2C
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

// 128 x 64 pixels, on the I2C bus: SDA GPIO 8, SCL GPIO 9
Adafruit_SSD1306 display(128, 64, &Wire, -1);

void setup() {
  Serial.begin(115200);
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    Serial.println("No SSD1306 at 0x3C");
    for (;;) {}
  }
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(2);
  display.setCursor(0, 0);
  display.println("ESP32-S3");
  display.setTextSize(1);
  display.println("SSD1306 OLED");
  display.drawRect(0, 40, 128, 24, SSD1306_WHITE);
  display.display();
  Serial.println("OLED ready");
}

void loop() {
  // A counter in the box, redrawn twice a second.
  display.fillRect(2, 42, 124, 20, SSD1306_BLACK);
  display.setCursor(8, 48);
  display.print("Up for ");
  display.print(millis() / 1000);
  display.print(" s");
  display.display();
  delay(500);
}
Output

What you should see

The panel shows ESP32-S3 in large letters, SSD1306 OLED below it, and a box with Up for followed by a number of seconds that counts up. The serial monitor, at 115200 baud, prints OLED ready once.

If the monitor prints No SSD1306 at 0x3C instead, nothing answered on the bus: check SDA and SCL first. The font in the simulator has capitals only, so lower case prints as capitals.

The serial monitor prints this, recorded from the circuit above running:

OLED ready
Pitfalls

Common mistakes wiring an SSD1306 OLED to an ESP32-S3

Forgetting display()

Every call before display() only changes the copy in RAM. A sketch that draws and never calls display() leaves the screen black, and that is the most common "my OLED does not work" there is.

Expecting the bus on the old ESP8266 pins

Tutorials written for the ESP8266 put I2C on GPIO 4 and 5. On an ESP32-S3 DevKitC-1 Wire.begin() uses GPIO 8 and GPIO 9. Either wire it there or call Wire.begin(sda, scl) before display.begin() with the pins you used.

Mixing up the 128x32 module

The 128 by 32 OLED uses the same chip and the same address, but the constructor needs 128, 32. Built for 64 rows, everything is drawn half off the panel.

Build your own SSD1306 OLED project

Open this circuit in the editor, change the wiring or the code, and keep your version in a free account.