diff --git a/components/display/images/st7567-full.jpg b/components/display/images/st7567-full.jpg new file mode 100644 index 000000000..5abdd49a7 Binary files /dev/null and b/components/display/images/st7567-full.jpg differ diff --git a/components/display/st7567.rst b/components/display/st7567.rst new file mode 100644 index 000000000..3c59a7e4a --- /dev/null +++ b/components/display/st7567.rst @@ -0,0 +1,191 @@ +ST7567 LCD Graphic Display +========================== + +.. seo:: + :description: Instructions for setting up ST7567 Mono STN-LCD display drivers. + :image: st7567.jpg + +.. _st7567: + +Usage +----- + +The ``st7567`` display platform allows you to use wide range of 128x64 display modules based on +Sitronix ST7567 chipset family (ST7567A, ST7567S, ST7567G, etc.) (`datasheet `__, +`Sitronix `__, +`Aliexpress `__) with ESPHome. + +Note that this component is for displays that are connected via the :ref:`I²C Bus ` (see :ref:`st7567-i2c`) +or 3-Wire or 4-Wire :ref:`SPI bus ` (see :ref:`st7567-spi`). +It's a monochrome LCD graphic display. + +.. figure:: images/st7567-full.jpg + :align: center + :width: 75.0% + + ST7567A based LCD Graphic Display (I²C) + +.. note:: + + **Voltage:** Check your module specs for required power. Most of the modules are tolerant to range of voltages from 3.3V to 5V, but some might require either 5V or 3.3V. + + **Electrical interference:** To reduce malfunction caused by noise, datasheet recommends to "use the refresh sequence regularly in a specified interval". + + Noone knows what exact interval is - it varies based on your electrical environment - some might need it every hour, for example. + Without doing refresh sequence picture on LCD might get glitchy after some time. + + You can plan refresh by using ``interval:`` section and calling ``request_refresh()`` function, after that it will perform display + refresh sequence on next component update. + + +.. _st7567-i2c: + +Over I²C +-------- + +Connect ``SDA`` and ``SCL`` pins on a module to pins you chose for the :ref:`I²C Bus `. +If your display module has ``RESET`` pin you may optionally connect it to a pin on the +ESP which may improve reliability. For power, connect ``VCC`` to 3.3V and ``GND`` to ``GND``. + + +.. code-block:: yaml + + # Example minimal configuration entry + i2c: + sda: D1 + scl: D2 + + display: + - platform: st7567_i2c + id: my_display + lambda: |- + it.print(0, 0, id(my_font), "Hello World!"); + + interval: + - interval: 1h + then: + - lambda: id(my_display).request_refresh(); + + +Configuration variables: +************************ + +- **address** (*Optional*, int): Manually specify the :ref:`I²C ` address of the display. Defaults to 0x3F. +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you want + to use multiple I²C buses. +- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. Defaults to not connected. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **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`. +- **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display. +- **invert_colors** (*Optional*, boolean): Display hardware color invesion. Defaults to ``false``. +- **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°``. +- **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. + - **mirror_x** (*Optional*, boolean): If true, mirror the physical X axis. + - **mirror_y** (*Optional*, boolean): If true, mirror the physical Y axis. + + +**Speeding up the bus:** To speed up the display update process you can select higher I²C frequencies, for example: + +.. code-block:: yaml + + # Example increased I²C bus speed + i2c: + sda: D1 + scl: D2 + frequency: 400kHz + +**Hardware rotation:** 180 degree rotation can be implemented in hardware as in the following example: + +.. code-block:: yaml + + # Example using transform section to achieve 180° rotation using hardware + display: + - platform: st7567_i2c + id: my_display + transform: + mirror_x: true + mirror_y: true + lambda: |- + it.print(0, 0, id(my_font), "Hello World!"); + + +.. _st7567-spi: + +Over SPI +-------- + +Connect ``D0`` to the ``CLK`` pin you chose for the :ref:`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. + +.. code-block:: yaml + + # Example minimal configuration entry + spi: + clk_pin: D1 + mosi_pin: D2 + + display: + - platform: st7567_spi + id: my_display + dc_pin: D3 + lambda: |- + it.print(0, 0, id(my_font), "Hello World!"); + + interval: + - interval: 1h + then: + - lambda: id(my_display).request_refresh(); + + +Configuration variables: +************************ + +- **dc_pin** (**Required**, :ref:`Pin Schema `): The DC pin. +- **cs_pin** (*Optional*, :ref:`Pin Schema `): The Chip Select (CS) pin. +- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. Defaults to not connected. +- **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. +- **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`. +- **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display. +- **invert_colors** (*Optional*, boolean): Display hardware color invesion. Defaults to ``false``. +- **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°``. +- **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. + - **mirror_x** (*Optional*, boolean): If true, mirror the physical X axis. + - **mirror_y** (*Optional*, boolean): If true, mirror the physical Y axis. + + +**Hardware rotation:** 180 degree rotation can be implemented in hardware as in the following example: + +.. code-block:: yaml + + # Example using transform section to achieve 180° rotation using hardware + display: + - platform: st7567_spi + id: my_display + dc_pin: D3 + transform: + mirror_x: true + mirror_y: true + lambda: |- + it.print(0, 0, id(my_font), "Hello World!"); + + + + +See Also +-------- + +- :doc:`index` +- :ref:`display-engine` +- :ref:`Display Menu ` +- :ref:`i2c` +- :ref:`spi` +- :apiref:`st7567/st7567.h` +- :ghedit:`Edit` diff --git a/images/st7567.jpg b/images/st7567.jpg new file mode 100644 index 000000000..b38a111e6 Binary files /dev/null and b/images/st7567.jpg differ diff --git a/index.rst b/index.rst index 3af314342..0bcdd3e79 100644 --- a/index.rst +++ b/index.rst @@ -667,6 +667,7 @@ Display Components SSD1327, components/display/ssd1327, ssd1327.jpg SSD1331, components/display/ssd1331, ssd1331.jpg SSD1351, components/display/ssd1351, ssd1351.jpg + ST7567, components/display/st7567, st7567.jpg ST7735, components/display/st7735, st7735.jpg ST7789V, components/display/st7789v, st7789v.jpg ST7796, components/display/ili9xxx, st7796.svg