mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-12 20:10:50 +01:00
Add documentation for ST7789V display module (as on TTGO T-Display) (#594)
* Added ST7789 documentation * Fix indentation * Added color component, copy fixes * Copy correction * Update for Colors * Updated changelog * rename colors to color Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>
This commit is contained in:
parent
d8b50119c8
commit
7f45841551
@ -54,7 +54,8 @@ Notable Changes & New Features
|
||||
|
||||
- Dashboard Interface Revamped
|
||||
- Bang Bang Controller now implements ESPHome actions for all available Home Assistant climate actions,
|
||||
climate modes, fan modes, and fan swing modes
|
||||
climate modes, fan modes, and fan swing modes (#1061)
|
||||
- Color (and grayscale) display support! (#1050)
|
||||
|
||||
All changes
|
||||
-----------
|
||||
|
BIN
components/display/images/st7789v-full.jpg
Normal file
BIN
components/display/images/st7789v-full.jpg
Normal file
Binary file not shown.
After Width: | Height: | Size: 445 KiB |
264
components/display/st7789v.rst
Normal file
264
components/display/st7789v.rst
Normal file
@ -0,0 +1,264 @@
|
||||
ST7789V TFT LCD
|
||||
===============
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up ST7789V TFT LCD display drivers.
|
||||
:image: st7789v-full.jpg
|
||||
|
||||
.. _st7789v:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
The ``st7789v`` display platform allows you to use
|
||||
ST7789V (`datasheet <https://github.com/Xinyuan-LilyGO/TTGO-T-Display>`__,
|
||||
`Tindie <https://www.tindie.com/products/ttgo/lilygor-ttgo-t-display/>`__)
|
||||
displays with ESPHome. Note that this component utilizes the 4-Wire :ref:`SPI bus <spi>`; the physical
|
||||
connection is already in place on the TTGO T-Display module as shown below.
|
||||
|
||||
.. figure:: images/st7789v-full.jpg
|
||||
:align: center
|
||||
:width: 75.0%
|
||||
|
||||
ST7789V TFT LCD on TTGO T-Display module
|
||||
|
||||
This module has a USB-C connector with an on-board serial adapter for programming. Simply connect to a
|
||||
USB-C port to get started! (Depending on your operating system of choice, you might need to install an
|
||||
appropriate driver.) It is also possible to power the module via the 5V and G (ground) pins along
|
||||
the edges of the module, or via a battery attached to the connector on the bottom of the board. The
|
||||
ESP32's UART pins are not brought out to the headers, so the on-board serial adapter must be used for
|
||||
hardwired programming. (OTA updates are of course possible after ESPHome is initially installed.)
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example minimal configuration entry
|
||||
spi:
|
||||
clk_pin: GPIO18
|
||||
mosi_pin: GPIO19
|
||||
|
||||
display:
|
||||
- platform: st7789v
|
||||
backlight_pin: GPIO4
|
||||
cs_pin: GPIO5
|
||||
dc_pin: GPIO16
|
||||
reset_pin: GPIO23
|
||||
lambda: |-
|
||||
it.print(0, 0, id(font), "Hello World!");
|
||||
|
||||
.. warning::
|
||||
|
||||
When using the TTGO T-Display module, the GPIO pin numbers above *cannot be changed* as they are
|
||||
hardwired within the module/PCB.
|
||||
|
||||
Configuration variables
|
||||
***********************
|
||||
|
||||
- **backlight_pin** (:ref:`Pin Schema <config-pin_schema>`): The display's backlight pin.
|
||||
- **cs_pin** (:ref:`Pin Schema <config-pin_schema>`): The CS pin.
|
||||
- **dc_pin** (:ref:`Pin Schema <config-pin_schema>`): The DC pin.
|
||||
- **reset_pin** (:ref:`Pin Schema <config-pin_schema>`): The RESET pin.
|
||||
- **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.
|
||||
|
||||
Configuration examples
|
||||
**********************
|
||||
|
||||
As of version 1.15, ESPHome supports color displays. To utilize the color capabilities of this display
|
||||
module, you'll likely want to add a ``color:`` section to your YAML configuration; please see
|
||||
:ref:`color <config-color>` for more detail on this configuration section.
|
||||
|
||||
To use colors in your lambada:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
color:
|
||||
- id: my_red
|
||||
red: 100%
|
||||
green: 3%
|
||||
blue: 5%
|
||||
|
||||
...
|
||||
|
||||
display:
|
||||
...
|
||||
lambda: |-
|
||||
it.rectangle(0, 0, it.get_width(), it.get_height(), id(my_red);
|
||||
|
||||
|
||||
To bring in color images:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
image:
|
||||
- file: "image.jpg"
|
||||
id: my_image
|
||||
resize: 200x200
|
||||
type: RGB565
|
||||
|
||||
...
|
||||
|
||||
display:
|
||||
...
|
||||
lambda: |-
|
||||
it.image(0, 0, id(my_image));
|
||||
|
||||
Complete example
|
||||
****************
|
||||
|
||||
The following is a complete example YAML configuration that does a few things beyond the usual
|
||||
Wi-Fi, API, and OTA configuration. It defines:
|
||||
|
||||
- three fonts (well, one font in three sizes)
|
||||
- a ``binary_sensor`` that indicates the state of connectivity to the API
|
||||
- a ``binary_sensor`` for each of the two buttons on the TTGO module
|
||||
- a ``switch``, allowing control of the backlight from HA
|
||||
- several colors
|
||||
- a color image to be shown on the display
|
||||
- time, for display...on the display
|
||||
- the SPI configuration for communicating with the display
|
||||
- the display component itself, for use on the TTGO module
|
||||
- a lambada which paints the screen as shown in the picture above:
|
||||
|
||||
- blue borders, with a sort of "title bar" along the top
|
||||
- "ESPHome" in yellow in the top left corner
|
||||
- the API connection status, "Online" in green when connected, "Offline" in red when not
|
||||
- the time and date, more or less in the center of the display
|
||||
|
||||
To use this example, you need only to provide the font file, "Helvetica.ttf" (or update it to
|
||||
a font of your choosing) and an image file, "image.png" (it may also be a ".jpg"). Place these
|
||||
into the same directory as the YAML configuration file itself. Comment/Uncomment/Modify the
|
||||
appropriate lines of C code in the lambada to hide or show the image or text as you wish.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
esphome:
|
||||
name: esp_tdisplay
|
||||
platform: ESP32
|
||||
board: featheresp32
|
||||
|
||||
wifi:
|
||||
ssid: "ssid"
|
||||
password: "password"
|
||||
|
||||
# Enable fallback hotspot (captive portal) in case wifi connection fails
|
||||
ap:
|
||||
ssid: "esp_tdisplay"
|
||||
password: "some_password"
|
||||
|
||||
captive_portal:
|
||||
|
||||
# Enable logging
|
||||
logger:
|
||||
|
||||
# Enable Home Assistant API
|
||||
api:
|
||||
password: "some_api_password"
|
||||
|
||||
ota:
|
||||
password: "some_ota_password"
|
||||
|
||||
color:
|
||||
- id: my_red
|
||||
red: 100%
|
||||
green: 0%
|
||||
blue: 0%
|
||||
- id: my_yellow
|
||||
red: 100%
|
||||
green: 100%
|
||||
blue: 0%
|
||||
- id: my_green
|
||||
red: 0%
|
||||
green: 100%
|
||||
blue: 0%
|
||||
- id: my_blue
|
||||
red: 0%
|
||||
green: 0%
|
||||
blue: 100%
|
||||
- id: my_gray
|
||||
red: 50%
|
||||
green: 50%
|
||||
blue: 50%
|
||||
|
||||
font:
|
||||
- file: "Helvetica.ttf"
|
||||
id: helvetica_48
|
||||
size: 48
|
||||
- file: "Helvetica.ttf"
|
||||
id: helvetica_24
|
||||
size: 24
|
||||
- file: "Helvetica.ttf"
|
||||
id: helvetica_12
|
||||
size: 12
|
||||
|
||||
binary_sensor:
|
||||
- platform: status
|
||||
name: "Node Status"
|
||||
id: system_status
|
||||
- platform: gpio
|
||||
pin:
|
||||
number: GPIO0
|
||||
inverted: true
|
||||
name: "T-Display Button Input 0"
|
||||
id: tdisplay_button_input_0
|
||||
- platform: gpio
|
||||
pin:
|
||||
number: GPIO35
|
||||
inverted: true
|
||||
name: "T-Display Button Input 1"
|
||||
id: tdisplay_button_input_1
|
||||
|
||||
# We can still control the backlight independently
|
||||
switch:
|
||||
- platform: gpio
|
||||
pin: GPIO4
|
||||
name: "Backlight"
|
||||
id: backlight
|
||||
|
||||
image:
|
||||
- file: "image.png"
|
||||
id: my_image
|
||||
resize: 200x200
|
||||
type: RGB565
|
||||
|
||||
time:
|
||||
- platform: homeassistant
|
||||
id: esptime
|
||||
|
||||
spi:
|
||||
clk_pin: GPIO18
|
||||
mosi_pin: GPIO19
|
||||
|
||||
display:
|
||||
- platform: st7789v
|
||||
backlight_pin: GPIO4
|
||||
cs_pin: GPIO5
|
||||
dc_pin: GPIO16
|
||||
reset_pin: GPIO23
|
||||
rotation: 270
|
||||
lambda: |-
|
||||
it.rectangle(0, 0, it.get_width(), it.get_height(), id(my_blue));
|
||||
it.rectangle(0, 20, it.get_width(), it.get_height(), id(my_blue)); // header bar
|
||||
|
||||
it.strftime((240 / 2), (140 / 3) * 1 + 5, id(helvetica_24), id(my_gray), TextAlign::CENTER, "%Y-%m-%d", id(esptime).now());
|
||||
it.strftime((240 / 2), (140 / 3) * 2 + 5, id(helvetica_48), id(my_gray), TextAlign::CENTER, "%H:%M:%S", id(esptime).now());
|
||||
it.print(5, 5, id(helvetica_12), id(my_yellow), TextAlign::TOP_LEFT, "ESPHome");
|
||||
|
||||
// Comment out the above lines to see the image without text overlaid
|
||||
// it.image(0, 0, id(my_image));
|
||||
|
||||
if (id(system_status).state) {
|
||||
it.print(235, 5, id(helvetica_12), id(my_green), TextAlign::TOP_RIGHT, "Online");
|
||||
}
|
||||
else {
|
||||
it.print(235, 5, id(helvetica_12), id(my_red), TextAlign::TOP_RIGHT, "Offline");
|
||||
}
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`index`
|
||||
- :apiref:`st7789v_base/st7789v_base.h`
|
||||
- :ghedit:`Edit`
|
@ -108,6 +108,26 @@ More exotic Pin Modes are also supported, but rarely used:
|
||||
- ``FUNCTION_5`` (only on ESP32)
|
||||
- ``FUNCTION_6`` (only on ESP32)
|
||||
|
||||
.. _config-color:
|
||||
|
||||
Color
|
||||
-----
|
||||
|
||||
When using RGB-capable displays or LEDs/lighting in ESPHome you may wish to use custom colors.
|
||||
A ``color`` component exists for just this purpose:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
color:
|
||||
- id: my_light_red
|
||||
red: 100%
|
||||
green: 20%
|
||||
blue: 25%
|
||||
white: 0%
|
||||
|
||||
RGB displays use red, green, and blue, while grayscale displays may use white. LEDs or LED-based light bulbs
|
||||
may use all four color elements depending on their capabilities.
|
||||
|
||||
.. _config-time:
|
||||
|
||||
Time
|
||||
@ -232,7 +252,7 @@ and the following command:
|
||||
.. code-block:: bash
|
||||
|
||||
esphome -s name device01 -s board esp01_1m example.yaml config
|
||||
|
||||
|
||||
You will get something like the following output (please note the unchanged ``platform``,
|
||||
added ``board``, and overridden ``name`` substitutions):
|
||||
|
||||
|
BIN
images/st7789v.jpg
Normal file
BIN
images/st7789v.jpg
Normal file
Binary file not shown.
After Width: | Height: | Size: 12 KiB |
@ -267,6 +267,7 @@ Display Components
|
||||
Nextion, components/display/nextion, nextion.jpg
|
||||
SSD1306, components/display/ssd1306, ssd1306.jpg
|
||||
SSD1325, components/display/ssd1325, ssd1325.jpg
|
||||
ST7789V, components/display/st7789v, st7789v.jpg
|
||||
Waveshare E-Paper, components/display/waveshare_epaper, waveshare_epaper.jpg
|
||||
PCD8544 (Nokia 5110/ 3310), components/display/pcd8544, pcd8544.jpg
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user