SSD1306 OLED Display ==================== .. seo:: :description: Instructions for setting up SSD1306 OLED display drivers. :image: ssd1306.jpg .. _ssd1306-i2c: Over I²C -------- The ``ssd1306_i2c`` display platform allows you to use SSD1306 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf>`__, `Adafruit <https://www.adafruit.com/product/326>`__), SSD1305 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1305.pdf>`__), SH1107 (`datasheet <https://cdn-learn.adafruit.com/assets/assets/000/094/580/original/SH1107_datasheet.pdf>`__, `Adafruit <https://www.adafruit.com/product/4650>`__) and SH1106 (`datasheet <https://www.elecrow.com/download/SH1106%20datasheet.pdf>`__, `electrodragon <https://www.electrodragon.com/product/1-3-12864-blue-oled-display-iicspi/>`__) displays with ESPHome. Note that this component is for displays that are connected via the :ref:`I²C Bus <i2c>`. If your SSD1306/SSD1305 or SH1106 is connected via the 4-Wire :ref:`SPI bus <spi>`, see :ref:`ssd1306-spi`. .. figure:: images/ssd1306-full.jpg :align: center :width: 75.0% SSD1306 OLED Display Connect D2 to the SCL pin you chose for the :ref:`I²C Bus <i2c>`, 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. .. code-block:: yaml # 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*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin. Defaults to not connected. - **address** (*Optional*, int): Manually specify the :ref:`I²C <i2c>` 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*, :ref:`lambda <config-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 ``1s``. - **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. .. _ssd1306-spi: Over SPI -------- The ``ssd1306_spi`` display platform allows you to use SSD1306 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf>`__, `Adafruit <https://www.adafruit.com/product/326>`__) and SH1106 (`datasheet <https://www.elecrow.com/download/SH1106%20datasheet.pdf>`__, `electrodragon <https://www.electrodragon.com/product/1-3-12864-blue-oled-display-iicspi/>`__) displays with ESPHome. Note that this component is for displays that are connected via the 4-Wire :ref:`SPI bus <spi>`. If your SSD1306 or SH1106 is connected via the :ref:`I²C Bus <i2c>`, see :ref:`ssd1306-i2c`. .. figure:: images/ssd1306-full.jpg :align: center :width: 75.0% SSD1306 OLED Display Connect D0 to the CLK pin you chose for the :ref:`SPI bus <spi>`, 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. .. code-block:: yaml # 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**, :ref:`Pin Schema <config-pin_schema>`): The Chip Select (CS) pin. - **dc_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DC pin. - **reset_pin** (*Optional*, :ref:`Pin Schema <config-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*, :ref:`lambda <config-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 ``1s``. - **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 <spi>` if you want to use multiple SPI buses. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. See Also -------- - :doc:`index` - :apiref:`ssd1306_base/ssd1306_base.h` - `SH110x Library <https://github.com/adafruit/Adafruit_SH110x>`__ by `Adafruit <https://www.adafruit.com/>`__ - `SSD1306 Library <https://github.com/adafruit/Adafruit_SSD1306>`__ by `Adafruit <https://www.adafruit.com/>`__ - `SSD1305 Library <https://github.com/adafruit/Adafruit_SSD1305>`__ by `Adafruit <https://www.adafruit.com/>`__ - :ghedit:`Edit`