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.
Specs
| Controller | Solomon Systech SSD1306 |
|---|---|
| Display | 0.96″, 128 × 64 pixels, monochrome. Each pixel lights itself, no backlight |
| Interface | I²C, up to 400 kHz |
| Address | 0x3C or 0x3D, set by a resistor on the back (printed 0x78 / 0x7A) |
| Chip logic supply | 1.65–3.3 V, absolute max 4 V. Modules sold for 3.3–5 V add a regulator |
| Panel supply | 7–15 V, made on the chip by its charge pump from the logic supply |
| Pins | 4: GND, VCC, SCL, SDA. Some batches swap GND and VCC |
| Frame buffer | 1 KB on the microcontroller with most libraries (128 × 64 bits) |
Pins
| Pin | Roles | What to know |
|---|---|---|
| GND | Ground | Check the label on your board: some batches put VCC here. |
| VCC | Power | Power it from the same 3.3 V rail as your microcontroller. |
| SCL | I²C clock | Any free GPIO on an ESP32. Needs a pull-up; many modules have one. |
| SDA | I²C data | Any 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
- SSD1306 datasheet, Rev 1.1: 128×64 driver, VDD 1.65–3.3 V and 4 V maximum (Tables 11-1, 12-1), VCC 7–15 V, charge pump (8Dh), I²C address 0111100/0111101 by SA0, 2.5 µs I²C clock cycle (400 kHz).
- Adafruit SSD1306 library: begin() defaults to 0x3D for 128×64 and 0x3C for 128×32, returns true without checking for an answer, and calls Wire.begin() unless told not to; 1 KB buffer from malloc.
- Adafruit: Monochrome OLED breakouts, power requirements: Modules without a regulator need 3.3 V.
- Arduino forum: 0.96″ I2C OLED power inputs: Modules with GND, VCC, SCL, SDA and with VCC, GND, SCL, SDA; round vs oblong mounting holes.
- SH1106 datasheet (Sino Wealth, via Crystalfontz): 132 × 64 display RAM, I²C at 400 kHz.
- U8g2: Separate SSD1306 and SH1106 drivers.
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.
You're on the list.
Got a minute? Tell me which boards you use and I'll know what to support first.