SSD1327 OLED Display

Over I²C

The ssd1327_i2c display platform allows you to use SSD1327 (datasheet, Waveshare) displays with ESPHome. Note that this component is for displays that are connected via the I²C Bus. If your SSD1327 is connected via the 4-Wire SPI bus, see Over SPI.

../../_images/ssd1327-full.jpg

SSD1327 OLED Display

Connect CLK to the SCL (clock) pin you chose for the I²C Bus and connect DIN to the SDA (data) pin. For power, connect VCC to 3.3V and GND to GND. You may also connect the RESET pin to an available pin on the ESP; this is recommended as it improves reliability.

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

display:
  - platform: ssd1327_i2c
    model: "SSD1327 128x128"
    reset_pin: D0
    address: 0x3D
    lambda: |-
      it.print(0, 0, id(font), "Hello World!");

Configuration variables:

  • model (Required): The model of the display. At present, only one option is available:

    • SSD1327 128x128

  • 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 0x3D.

  • 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°.

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

  • 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 5s.

  • 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 ssd1327_spi display platform allows you to use SSD1327 (datasheet, Adafruit) displays with ESPHome. Note that this component is for displays that are connected via the 4-Wire SPI bus. If your SSD1327 is connected via the I²C Bus, see Over I²C.

../../_images/ssd1327-full.jpg

SSD1327 OLED Display

Connect CLK to the SCK (clock) pin you chose for the SPI bus, connect DIN to the MOSI/SDO pin, and connect DC to another pin of your choosing. CS may connect to a pin on the ESP or it may connect to ground if the display is the only device connected to the SPI bus. For power, connect VCC to 3.3V and GND to GND. You may also connect the RESET pin to an available pin on the ESP; this is recommended as it improves reliability.

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

display:
  - platform: ssd1327_spi
    model: "SSD1327 128x128"
    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. At present, only one option is available:

    • SSD1327 128x128

  • 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°.

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

  • 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 5s.

  • 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.

Configuration examples

To utilize the grayscale capabilities of this display module, add a color: section to your YAML configuration; please see color for more details. As this is a grayscale display, it only uses the white color element as shown below.

To use grayscale in your lambda:

color:
  - id: medium_gray
    white: 50%

...

display:
    ...
    lambda: |-
      it.rectangle(0,  0, it.get_width(), it.get_height(), id(medium_gray));

To bring in grayscale images:

image:
  - file: "image.jpg"
    id: my_image
    resize: 120x120
    type: GRAYSCALE

...

display:
    ...
    lambda: |-
      it.image(0, 0, id(my_image));

In this case, the image will be converted to grayscale (regardless of its original format) and rendered as such when drawn on the display. Note that the original image may require some adjustment as not all images immediately convert nicely to the 4-bit grayscale format this display supports.

Note that if type: GRAYSCALE is omitted, the image will render as a binary image (no grayscale); in this case, a color attribute may be passed to the image() method as follows:

image:
  - file: "image.jpg"
    id: my_image
    resize: 120x120

...

display:
    ...
    lambda: |-
      it.image(0, 0, id(medium_gray), id(my_image));

This will draw the complete image with the given shade of gray.

To create a new color as needed in code:

display:
    ...
    lambda: |-
      float white_intensity = 0.5;
      Color variable_gray(0, 0, 0, white_intensity);
      it.rectangle(0,  0, it.get_width(), it.get_height(), variable_gray);

The last argument of the Color constructor is the intensity of the white element; it is a percentage (value of range 0 to 1). It may be defined by another variable so it is adjustable in code.

See Also