155 lines
6.3 KiB
ReStructuredText
155 lines
6.3 KiB
ReStructuredText
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>`__)
|
|
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 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 D0 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 64x48``
|
|
- ``SH1106 128x32``
|
|
- ``SH1106 128x64``
|
|
- ``SH1106 96x16``
|
|
- ``SH1106 64x48``
|
|
|
|
- **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°``.
|
|
- **brightness** (*Optional*): Set the screen brightness in percents 0.0-1.0. Defaults to `1.0` that corresponds 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``.
|
|
- **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 ``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.
|
|
- **brightness** (*Optional*, float): Manually override display brightness in %. Defaults to ``100%``
|
|
|
|
.. 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. If this is the only device on the SPI bus, the ``CS`` pin can be connected to GND.
|
|
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 64x48``
|
|
- ``SH1106 128x32``
|
|
- ``SH1106 128x64``
|
|
- ``SH1106 96x16``
|
|
- ``SH1106 64x48``
|
|
|
|
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin on the ESP that that the CS line is connected to.
|
|
The CS line can be connected to GND if this is the only device on the SPI bus.
|
|
- **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°``.
|
|
- **external_vcc** (*Optional*, boolean): Set this to true if you have the VCC pin connected to an external power supply.
|
|
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 ``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 <spi>` if you want
|
|
to use multiple SPI buses.
|
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
|
- **brightness** (*Optional*, float): Manually override display brightness in %. Defaults to ``100%``
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :doc:`index`
|
|
- :apiref:`ssd1306_base/ssd1306_base.h`
|
|
- `SSD1306 Library <https://github.com/adafruit/Adafruit_SSD1306>`__ by `Adafruit <https://www.adafruit.com/>`__
|
|
- :ghedit:`Edit`
|