SSD1306 OLED Display

Over I²C

The ssd1306_i2c display platform allows you to use SSD1306 (datasheet, Adafruit), SSD1305 (datasheet), SH1107 (datasheet, Adafruit) and SH1106 (datasheet, electrodragon) displays with ESPHome. Note that this component is for displays that are connected via the I²C Bus. If your SSD1306/SSD1305 or SH1106 is connected via the 4-Wire SPI bus, see Over SPI.

../../_images/ssd1306-full.jpg

SSD1306 OLED Display

Connect D2 to the SCL pin you chose for the I²C Bus, and connect D1 to the SDA pin. For power, connect VCC to 3.3V and GND to GND. Optionally you can also connect the RESET pin to a pin on the ESP which may improve reliability.

# Example configuration entry
i2c:
  sda: D1
  scl: D2

display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    reset_pin: D0
    address: 0x3C
    lambda: |-
      it.print(0, 0, id(font), "Hello World!");

Configuration variables:

  • model (Required): The model of the display. Options are:

    • SSD1306 128x32 - SSD1306 with 128 columns and 32 rows

    • SSD1306 128x64

    • SSD1306 96x16

    • SSD1306 72x40

    • SSD1306 64x48

    • SH1106 128x32

    • SH1106 128x64

    • SH1106 96x16

    • SH1106 64x48

    • SH1107 128x64

    • SH1107 128x128

    • SSD1305 128x32

    • SSD1305 128x64

  • reset_pin (Optional, Pin Schema): The RESET pin. Defaults to not connected.

  • address (Optional, int): Manually specify the I²C address of the display. Defaults to 0x3C.

  • rotation (Optional): Set the rotation of the display. Everything you draw in lambda: will be rotated by this option. One of 0° (default), 90°, 180°, 270°.

  • contrast (Optional, percentage): Set display contrast in %. Defaults to 100%.

  • brightness (Optional, percentage): Set display brightness in %. Only can be used with SSD1305. Defaults to 100%.

  • external_vcc (Optional, boolean): Set this to true if you have the VCC pin connected to an external power supply. Defaults to false.

  • flip_x (Optional, boolean): Flip the horizontal axis on the screen. Defaults to true.

  • flip_y (Optional, boolean): Flip the vertical axis on the screen. Defaults to true.

  • offset_x (Optional, int): Set this option if some horizontal pixel is missing. Numbers are only allowed between 0~128. Defaults to 0.

  • offset_y (Optional, int): Set this option if some vertical pixel is missing. Numbers are only allowed between 0~128. Defaults to 0.

  • invert (Optional, boolean): Invert all pixel state on the display. Defaults to false.

  • lambda (Optional, lambda): The lambda to use for rendering the content on the display. See Display Rendering Engine for more information.

  • update_interval (Optional, Time): The interval to re-draw the screen. Defaults to 1s.

  • pages (Optional, list): Show pages instead of a single lambda. See Display Pages.

  • id (Optional, ID): Manually specify the ID used for code generation.

Note

To speed up the display update process you can select higher I²C frequencies.

Over SPI

The ssd1306_spi display platform allows you to use SSD1306 (datasheet, Adafruit) and SH1106 (datasheet, electrodragon) displays with ESPHome. Note that this component is for displays that are connected via the 4-Wire SPI bus. If your SSD1306 or SH1106 is connected via the I²C Bus, see Over I²C.

../../_images/ssd1306-full.jpg

SSD1306 OLED Display

Connect D0 to the CLK pin you chose for the SPI bus, connect D1 to the MOSI pin and DC and CS to some GPIO pins on the ESP. For power, connect VCC to 3.3V and GND to GND. Optionally you can also connect the RESET pin to a pin on the ESP which may improve reliability.

# Example configuration entry
spi:
  clk_pin: D0
  mosi_pin: D1

display:
  - platform: ssd1306_spi
    model: "SSD1306 128x64"
    cs_pin: D2
    dc_pin: D3
    reset_pin: D4
    lambda: |-
      it.print(0, 0, id(font), "Hello World!");

Configuration variables:

  • model (Required): The model of the display. Options are:

    • SSD1306 128x32 (SSD1306 with 128 columns and 32 rows)

    • SSD1306 128x64

    • SSD1306 96x16

    • SSD1306 72x40

    • SSD1306 64x48

    • SH1106 128x32

    • SH1106 128x64

    • SH1106 96x16

    • SH1106 64x48

    • SH1107 128x64

    • SH1107 128x128

    • SSD1305 128x32

    • SSD1305 128x64

  • cs_pin (Required, Pin Schema): The Chip Select (CS) pin.

  • dc_pin (Required, Pin Schema): The DC pin.

  • reset_pin (Optional, Pin Schema): The RESET pin. Defaults to not connected.

  • rotation (Optional): Set the rotation of the display. Everything you draw in lambda: will be rotated by this option. One of 0° (default), 90°, 180°, 270°.

  • contrast (Optional, percentage): Set display contrast in %. Defaults to 100%.

  • brightness (Optional, percentage): Set display brightness in %. Only can be used with SSD1305. Defaults to 100%.

  • external_vcc (Optional, boolean): Set this to true if you have the VCC pin connected to an external power supply. Defaults to false.

  • flip_x (Optional, boolean): Flip the horizontal axis on the screen. Defaults to true.

  • flip_y (Optional, boolean): Flip the vertical axis on the screen. Defaults to true.

  • offset_x (Optional, int): Set this option if some horizontal pixel is missing. Numbers are only allowed between 0~128. Defaults to 0.

  • offset_y (Optional, int): Set this option if some vertical pixel is missing. Numbers are only allowed between 0~128. Defaults to 0.

  • invert (Optional, boolean): Invert all pixel state on the display. Defaults to false.

  • lambda (Optional, lambda): The lambda to use for rendering the content on the display. See Display Rendering Engine for more information.

  • update_interval (Optional, Time): The interval to re-draw the screen. Defaults to 1s.

  • pages (Optional, list): Show pages instead of a single lambda. See Display Pages.

  • spi_id (Optional, ID): Manually specify the ID of the SPI Component if you want to use multiple SPI buses.

  • id (Optional, ID): Manually specify the ID used for code generation.

See Also