Display

SSD1306 OLED, 0.96″ I²C

The small OLED in half the projects you’ve seen: 128×64 pixels on an SSD1306 controller, four pins, I²C. Most of the time it just works. When it doesn’t, the screen stays black and nothing says why: the library is talking to the wrong address, VCC and GND are the other way round on this batch, or the chip isn’t an SSD1306 at all.

SSD1306 OLED128 × 64GNDMAY SWAPVCCMAY SWAPSCLSDA
Pins in the most common order. Some batches swap GND and VCC: wire by the labels on your module.

Specs

ControllerSolomon Systech SSD1306
Display0.96″, 128 × 64 pixels, monochrome. Each pixel lights itself, no backlight
InterfaceI²C, up to 400 kHz
Address0x3C or 0x3D, set by a resistor on the back (printed 0x78 / 0x7A)
Chip logic supply1.65–3.3 V, absolute max 4 V. Modules sold for 3.3–5 V add a regulator
Panel supply7–15 V, made on the chip by its charge pump from the logic supply
Pins4: GND, VCC, SCL, SDA. Some batches swap GND and VCC
Frame buffer1 KB on the microcontroller with most libraries (128 × 64 bits)

Pins

PinRolesWhat to know
GNDGroundCheck the label on your board: some batches put VCC here.
VCCPowerPower it from the same 3.3 V rail as your microcontroller.
SCLI²C clockAny free GPIO on an ESP32. Needs a pull-up; many modules have one.
SDAI²C dataAny free GPIO on an ESP32. Needs a pull-up; many modules have one.

Rows in bold need care. Shown in the most common order. Wire by the labels printed on your module, not by position.

Wiring it to a 3.3 V board

Four wires: GND to GND, VCC to 3V3, SCL and SDA to two free GPIOs. On an ESP32 any GPIO can be I²C. On an ESP32-C3 SuperMini, use IO6 and IO7 rather than Arduino’s default IO8 and IO9, which are strapping pins wired to the LED and the BOOT button.

Power it from 3V3 even if the listing says 3.3–5 V. If the module has pull-ups, they hold SDA and SCL up to its supply or to its own regulator’s output, depending on the board, and an ESP32 pin takes at most 3.6 V. With VCC on 3V3 the bus can’t go above 3.3 V, whichever way your module is built.

Check VCC and GND before you power it

Two pin orders are sold under the same name: GND, VCC, SCL, SDA and VCC, GND, SCL, SDA. The board looks the same either way. Read the labels printed next to the pins on the module you have, and wire by those. It matters most when the module plugs into a socket or a PCB footprint made for the other order.

The screen stays black: the address

The SSD1306 answers at 0x3C or 0x3D, chosen by a resistor on the back. The back prints the 8-bit form, 0x78 or 0x7A: the same address shifted left one bit, so 0x78 is 0x3C.

The Adafruit library guesses 0x3D for any 128×64 display if you don’t pass an address, and its 128×64 examples use 0x3D too. If your module is at 0x3C, begin() still returns true (it doesn’t check that anything answered) and the screen stays black. Pass the address yourself, and if you’re not sure, run an I²C scanner sketch first.

#include <Wire.h>
#include <Adafruit_SSD1306.h>

// -1: 4-pin modules have no reset pin
Adafruit_SSD1306 display(128, 64, &Wire, -1);

void setup() {
  Wire.begin(6, 7); // SDA, SCL
  // Address from the back of the module.
  // false: Wire is already started.
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C,
                true, false);
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.println("Hello");
  display.display();
}

void loop() {}

SSD1306_SWITCHCAPVCC turns on the chip’s charge pump, which makes the panel voltage. The 4-pin modules depend on it. Pass false as the last argument when you’ve already called Wire.begin() with your own pins, so the library doesn’t start the bus a second time.

It might be an SH1106

Some modules sold as SSD1306, 1.3″ ones in particular, carry an SH1106. It’s a close relative with the same pins and address, but it has 132 columns of memory for 128 visible ones. Driven as an SSD1306, the image comes out shifted sideways. Switch to an SH1106 driver (U8G2_SH1106_128X64_NONAME_F_HW_I2C in U8g2, or Adafruit_SH110X). One forum tip for telling them apart: round mounting holes on the SSD1306 boards, oblong on the SH1106 ones.

Sharing the bus

I²C lets the display share two wires with your sensors, as long as every device has its own address: a BME280, for example, sits at 0x76 or 0x77. Two displays on one bus need one moved to 0x3D with the resistor on the back. Each module with pull-ups adds them in parallel to the others. A few modules are fine; with many, the combined pull-up gets too strong for the pins to pull the lines low.

Sources

Boardless checks your wiring against parts like this

I’m building Boardless to check your schematic, case and firmware against each other on every change. Each part page is what it knows about that part.

Used only to tell you when Boardless is ready and to decide what it supports first. No newsletter, no sharing. See the privacy note.