Blog
ESP32 OLED: SSD1306, I2C Wiring
How to connect oled display to esp32 in four wires, print text on it, turn it off when done — the SSD1306 is the chip behind most 0.96-inch and 1.3-inch OLED panels, and one library covers nearly all of them.
How to Connect OLED Display to ESP32?
Four wires: VCC to 3V3, GND to GND, SCL to GPIO22, SDA to GPIO21 — the I2C defaults on the classic ESP32. Most 0.96-inch SSD1306 modules are I2C, run at 3.3V, and need no level shifter or pull-ups — the module carries them. On an ESP32-C3 or -S3 the pins move (GPIO8/9 on the C3 SuperMini), so read the pinout first.
How to Use OLED Display with ESP32?
Install Adafruit_SSD1306 and Adafruit_GFX, construct SSD1306_I2C(128, 64, &Wire, address), and call display() in setup. The address is 0x3C on nearly all panels and 0x3D on some clones; a wrong address shows as a silent screen. People asking “which esp32 uses cp2101 oled” usually hold a TTGO or LilyGO pack — same chip, one library.
How to Print Text on OLED ESP32?
display.setCursor(x, y), display.setTextSize(n), display.print("...") — then display.display(), or nothing shows. The panel is 128×64 pixels: size-1 text fits about 21 characters per line, size-2 about 10, and no wrapping past the right edge.
How to Turn Off OLED ESP32?
display.ssd1306_command(0xAE) puts the panel to sleep while the chip keeps running — the biggest battery win in a low-power build, dropping the module from ~20 mA to ~1 mA. Wake it with 0xAF, or just call display() again. The power FAQ covers the rest.
Which I2C pins must I use?
None are sacred — Wire.begin(SDA, SCL) puts the SSD1306 on any two GPIOs. The defaults exist only because sketches assume them: 21/22 on WROOM, 8/9 on the C3 SuperMini, 8/9 on many S3 boards. On boards with a built-in panel, match its pins or the displays fight for the bus.
My OLED shows nothing — what now?
Run an I2C scanner first; it either reports the address or proves the bus is dead. Then check power (3.3V rail — 5V works but runs hot) and make sure SDA and SCL are not swapped. If the scanner sees 0x3C but the screen stays dark, the brightness register can be zero: ssd1306_command(0x81) then (0xCF) restores it.
Do OLEDs need a reset pin wired up?
Not on I2C modules — the SSD1306 resets over the bus, and Adafruit’s library accepts -1 as “no pin”. If your panel freezes mid-boot with the RST pad loose, tie it to a GPIO and toggle it once in setup — it is the panel’s habit, not your code.
What OLED Is on the ESP32 Heltec?
The Heltec WiFi Kit 32 carries a 0.96-inch 128×64 SSD1306 — the answer to what oled is on the esp32 heltec is the same chip as any cheap panel, which is why Heltec code samples run on any SSD1306 library. The difference is pins: SCL to GPIO15, SDA to GPIO4, so the classic 21/22 sketch needs Wire.begin(4, 15) first.
What about 1.3-inch panels — same library?
Mostly. 1.3-inch modules split into SSD1306 128×64 (same code) and SH1106 128×64 (same wiring, different driver — text prints, graphics shift with the wrong one). The seller page usually says which you got. When I wired a 1.3-inch SH1106 to an ESP32-C3 SuperMini, the SSD1306 driver drew garbage until I switched to Adafruit_SH1106 — same pins, same address, one different constructor.
How do I clear the screen or scroll it?
display.clearDisplay() then display.display() — one without the other is the classic “text stacking” bug. Scrolling runs on the panel itself: scrollRight() and scrollLeft() cost no CPU. On fast loops keep update areas small — a full 128×64 redraw over 400 kHz I2C takes a few milliseconds and reads as flicker. Try the free ESP32 simulator to tune timing first.
Bring Up an SSD1306 — In Your Browser
The full OLED bring-up sequence, including the failure you will hit first, runs free in our simulator:
- OLED graphics demo — the healthy path and the sick one, both printable:
SSD1306 not found! ← address or wiring wrong
OLED ready! ← bus sane
Frame: 42 ← drawing, and countingPair it with the I2C scanner to chase the address (0x3C vs 0x3D is the classic), and the 4-pin wiring variant for the exact pinout — then transfer the same sketch to hardware unchanged.