SSD1327 OLED Display ==================== .. seo:: :description: Instructions for setting up SSD1327 OLED display drivers. :image: ssd1327.jpg .. _ssd1327-i2c: 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 :ref:`I²C Bus `. If your SSD1327 is connected via the 4-Wire :ref:`SPI bus `, see :ref:`ssd1327-spi`. .. figure:: images/ssd1327-full.jpg :align: center :width: 75.0% SSD1327 OLED Display Connect CLK to the SCL (clock) pin you chose for the :ref:`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. .. code-block:: yaml # 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*, :ref:`Pin Schema `): The RESET pin. Defaults to not connected. - **address** (*Optional*, int): Manually specify the :ref:`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*, :ref:`lambda `): The lambda to use for rendering the content on the display. See :ref:`display-engine` for more information. - **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``. - **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. .. note:: To speed up the display update process you can select higher I²C frequencies. .. _ssd1327-spi: 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 :ref:`SPI bus `. If your SSD1327 is connected via the :ref:`I²C Bus `, see :ref:`ssd1327-i2c`. .. figure:: images/ssd1327-full.jpg :align: center :width: 75.0% SSD1327 OLED Display Connect CLK to the SCK (clock) pin you chose for the :ref:`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. .. code-block:: yaml # 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**, :ref:`Pin Schema `): The Chip Select (CS) pin. - **dc_pin** (**Required**, :ref:`Pin Schema `): The DC pin. - **reset_pin** (*Optional*, :ref:`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*, :ref:`lambda `): The lambda to use for rendering the content on the display. See :ref:`display-engine` for more information. - **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``. - **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`. - **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component ` if you want to use multiple SPI buses. - **id** (*Optional*, :ref:`config-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 :ref:`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: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml 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 -------- - :doc:`index` - :apiref:`ssd1327_base/ssd1327_base.h` - :ghedit:`Edit`