Connect OLED display to ESP32 using ESPHome

Connect OLED display to ESP32 using ESPHome

I wanted to connect an OLED display to my ESP32 using ESPHome. I will use an ESP12-f (will work the same for an ESP32). I have a sensor in Home Assistant, and I want that sensor value to be displayed on this display.

Please check this article if you need to flash your ESP32 with ESPHome: https://techstuff.leighonline.net/2025/06/29/flash-esp32-with-esphome-in-2025/

This is the OLED display I have: 128X64 OLED 0.96″ I2C IIC SPI Serial

On the ESP12-f, you need to use the following pins:

• GPIO02 must connect to SDA on the display
• GPIO14 must connect to SCL on the display

ESPHome Config

This is the config I am curently using. It gets a sensor value from Home Assistant and shows it on the display. It also paginates through 2 pages so you can cycle through lots of information.

esphome:
  name: esp12-f-oled
  friendly_name: esp32-oled

esp8266:
  board: esp01_1m

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "Gff7mxxx="

ota:
  - platform: esphome
    password: "xxx"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Esp32-Oled Fallback Hotspot"
    password: "Wk0m6UF859Vn"

captive_portal:

font:
  - file: "gfonts://Roboto"
    id: my_font
    size: 16

i2c:
  sda: GPIO02
  scl: GPIO14
  scan: True
  frequency: 300kHz

sensor:
  - platform: homeassistant
    name: "Current Water Pressure"
    entity_id: sensor.current_water_pressure
    id: water_pressure

display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    address: 0x3C
    id: yellow_blue_oled
    contrast: 40%
    pages:
      - id: page1 
        lambda: |-
            it.printf(0, 0, id(my_font), "Water Pressure: ");
            it.printf(0, 20, id(my_font), "%.1f bar", id(water_pressure).state);
      - id: page2
        lambda: |-
            it.printf(0, 0, id(my_font), "Something else to display here.");    

interval:
  - interval: 5s
    # Interval timer for page changes on OLED display
    then:
      - display.page.show_next: yellow_blue_oled
      - component.update: yellow_blue_oled

ESPHome Config Breakdown

font:

• This will download a Google font once and store it. You can have more than 1 font defined.

i2c:

• This is the interface the display uses.
• Scan will scan for the address location the screen is connected to.
• Frequency sets the speed of the i2c bus. If you don’t set this, you will get a bunch of errors in your logs about the display refresh taking too long.

sensor:

• This is my sensor from Home Assistant.

display:

• This basically just sets the display parameters, the display type, and the pages.

interval:

• This will cycle through your pages and refresh the display.