Is SSD1306 0.96 OLED Display (128x64) Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Compact 0.96 inch monochrome OLED connected via I2C for showing live sensor telemetry IP addresses and status icons.
Wiring SSD1306 0.96 OLED Display (128x64) to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC | 3V3 | Most modules take 3.3–5V. Check the pin order first — GND-VCC-SCL-SDA and VCC-GND-SCL-SDA both exist, and reversed power destroys the display. |
| GND | GND | |
| SDA | GPIO21 | |
| SCL | GPIO22 |
Host pins are the ones the configuration on this page uses. Move a pin here and change it in the YAML — they are documented together so they cannot disagree.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | I2C Bus / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | OLED Graphic Screen Text Buffer Brightness Control Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Plug-and-Play |
| Factory Reset Instruction | Hold EN and BOOT buttons down for 2s then release EN. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The ESP32 pins there are the ones the configuration uses, so if you move one, change it in both places.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_ssd1306_ard.yaml and run esphome run emb_esp32_ssd1306_ard.yaml. The first flash goes over USB. If it is not detected, hold EN and BOOT buttons down for 2s then release EN to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
The I2C scan at boot lists 0x3C and Hello World appears at the top left. A display that stays dark with the address present is the model string or the reset; an image with a noisy edge is an SH1106.
ESPHome Configuration
Starting configuration for SSD1306 0.96 OLED Display (128x64) on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for SSD1306 0.96 OLED Display (128x64)
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_ssd1306_ard
friendly_name: "SSD1306 0.96 OLED Display (128x64)"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
i2c:
id: i2c_main
sda: GPIO21
scl: GPIO22
scan: true
font:
- file: "gfonts://Roboto"
id: roboto
size: 14
display:
- platform: ssd1306_i2c
model: "SSD1306 128x64"
address: 0x3C
lambda: |-
it.print(0, 0, id(roboto), "Hello World");
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
If the device is not found:
it is usually the I2C address, not the config. Many breakouts strap their address with
solder jumpers, so two boards of the same part can differ. This config leaves
scan: true on — the boot log lists every address
actually present on the bus, and you can copy the right one from there.
What Appears in Home Assistant
Displays have no entity in Home Assistant. Pull states into the node with text_sensor: platform: homeassistant or sensor: platform: homeassistant, and print them in the lambda.
Known Problems and Fixes
The 1.3" one is usually an SH1106
Sold as SSD1306, driven by a different controller. The tell is an image shifted a couple of pixels with a column of noise down one edge. The platform for it is sh1106_i2c, and there is a separate page for that part.
Model string
"SSD1306 128x64" for the 0.96" module; "SSD1306 128x32" for the short ones. The wrong height shows half an image or a doubled one.
0x3C, or 0x3D
Almost all modules sit at 0x3C. Some have a resistor jumper on the back for 0x3D, and a few ship with it set. The boot scan says which.
Burn-in is real
OLED pixels that stay lit for months dim permanently. Keep the static parts of the layout moving, drop contrast, or blank the screen when nobody is looking.
gfonts needs the internet
gfonts://Roboto downloads the font at compile time. On an offline build machine, point file: at a TTF you have locally instead.
Shares I²C address 0x3C
These parts default to the same address. At least one can be re-strapped, so they can coexist once you change it:
- SH1106 1.3 Inch OLED Display (128x64) — resolvable
Usually 0x3C; some modules expose a 0x3D jumper. Check a full build in the planner
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for SSD1306 0.96 OLED Display (128x64)? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-ssd1306-ard)
Frequently Asked Questions
Does SSD1306 0.96 OLED Display (128x64) work without an internet connection?
How is SSD1306 0.96 OLED Display (128x64) powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
SH1106 1.3 Inch OLED Display (128x64)
The 1.3" panel that is usually inside a "1.3 inch SSD1306" listing.
ST7735 1.8 Color TFT Display (128x160)
Colour, 128x160, on SPI.
Waveshare 2.13 E-Paper Display
E-paper holds an image with no power and no burn-in, for something read once an hour.