ST7789V TFT LCD

用法

st7789v 显示平台允许你使用 ESPHome 的 ST7789V（数据手册、 Tindie）。注意，此组件使用 4 线 SPI 总线。

TTGO T-Display 模块上的 ST7789V TFT LCD

图中所示的 TTGO T-Display 模块的显示已连接到模块板上，与 ESP32 的连接 无法更改。其他显示模块有引脚头或其他连接器，必须适当连接到 ESP 模块。

WARNING

由于 ST7789V 现已由 MIPI SPI 显示驱动 支持，此组件已被取代。 此组件将在未来的版本中被移除。

NOTE

比图中所示 TTGO T-Display 上的 135x240 像素显示更大的显示需要大量 RAM 才能正确运行。一些 ESP 设备（如 ESP8266）没有足够的内存来支持此显示。 如果你尝试使用此组件并遇到反复崩溃，这很可能是问题的原因。 MIPI SPI 显示驱动 组件具有可用于解决此问题的功能。

# 示例最小配置条目
display:
  - platform: st7789v
    model: TTGO TDisplay 135x240
    backlight_pin: GPIOXX
    cs_pin: GPIOXX
    dc_pin: GPIOXX
    reset_pin: GPIOXX
    lambda: |-
      it.print(0, 0, id(font), "Hello World!");

font:
  - file: "gfonts://Roboto"
    id: font
    size: 20

NOTE

有关字体选项的更多信息，请参见：字体渲染器组件。

配置变量

以下标记为 必需 的选项可能为某些型号设置了默认值，无需设置。 如果你指定了它们，将覆盖任何默认值。

• model (必需, string): 要使用的显示型号。可选值为以下之一：

  • TTGO TDisplay 135x240
  • Adafruit Funhouse 240x240
  • Adafruit RR 280x240（圆角矩形显示 —— 从角落”删除”了一些像素以形成圆角形状）
  • Adafruit S2 TFT FEATHER 240X135
  • LILYGO T-Embed 170X320
  • Waveshare 1.47in 172X320（圆角矩形显示 —— 从角落”删除”了一些像素以形成圆角形状）
  • Custom 用于上面未列出的其他显示

• height (可选, int): 以像素设置显示的高度。默认取决于 model。

• width (可选, int): 设置显示的宽度。默认取决于 model。

• offset_height (可选, int): 当 model 设置为”Custom”时，使用此选项指定显示的垂直 偏移（像素）。当 model 未设置为”Custom”时，不得指定此选项。默认取决于 model。

• offset_width (可选, int): 当 model 设置为”Custom”时，使用此选项指定显示的水平 偏移（像素）。当 model 未设置为”Custom”时，不得指定此选项。默认取决于 model。

• cs_pin (可选, Pin Schema): CS 引脚。默认取决于 model。

• dc_pin (可选, Pin Schema): DC 引脚。默认取决于 model。

• reset_pin (可选, Pin Schema): RESET 引脚。默认取决于 model。

• eightbitcolor (可选, boolean): 将支持的颜色深度限制为 8 位。对于 内存受限的设备可能有用。默认为 false。

• backlight_pin (可选, Pin Schema): 显示的背光引脚。根据 硬件配置，可能需要。要禁用预置背光引脚（例如由另一个组件控制），请将其设置为 no。

• power_supply (可选, ID): 如果硬件需要，要连接到此显示的 电源。在尝试初始化显示之前，将打开电源。

• lambda (可选, lambda): 用于在显示上渲染内容的 lambda。 更多信息请参见 显示渲染引擎。

• update_interval (可选, Time): 重新绘制屏幕的间隔。默认为 5s。

• pages (可选, list): 显示页面而非单个 lambda。请参见 显示页面。

• id (可选, ID): 手动指定用于代码生成的 ID。

• data_rate (可选, frequency): SPI 数据速率（默认 20MHz）。如果需要可以降低，例如 补偿长数据电缆。

• spi_mode (可选, 0-3): 要使用的 SPI 时钟模式（默认：mode0 ）。ST7789V 数据手册指定模式 0， 但一些显示似乎需要模式 3。应为 mode0、mode1、mode2 或 mode3（或 0-3 中的数字）之一。

预置配置

对于特定型号，有一些预置配置可以满足部分 必需 的除非预置值。 所有型号（Custom 除外）都预置了 height、width 和 offset_... 值。 下表总结了其他预置值。注意，SPI CLK 和 SDO（mosi）引脚以及电源引脚必须在 spi: 和 power_supply: 块中单独 配置 —— 为方便起见，引脚在下表中注明。

标记为 RQ 的项目是硬件依赖的，必需但未预置。标记为 ? 的项目取决于硬件而可选。

型号预置

型号	高度/宽度	偏移量	CS	DC	复位	背光	电源	SPI 时钟	SPI mosi
TTGO TDisplay 135x240	240/135	52/40	5	6	23	4		18	19
Adafruit Funhouse 240x240	240/240	0/0	40	39	41	21		36	35
Adafruit RR 280x240	240/240	0/20	RQ	RQ	RQ	?	?	RQ	RQ
Adafruit S2 TFT FEATHER 240X135	240/135	52/40	7	39	40	45	21	36	35
LILYGO T-Embed 170X320	320/170	35/0	10	13	9	15	46	12	11
Waveshare 1.47in 172X320	320/172	34/0	21	22	23	4		18	19
Custom	RQ	RQ	RQ	RQ	RQ	?	?	RQ	RQ

对于所有板卡，你可以通过指定任何配置选项来覆盖预置值。某些 板卡上的引脚分配可能在不同版本间发生变化，因此如果预置值不起作用，请检查板卡引脚并覆盖选项 （根据需要）。

NOTE

在内存受限的设备上，通过指定比实际显示更小的 height 和/或 width，可能可以使用显示区域的一部分。

配置示例

在 lambda 中使用颜色：

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));

引入彩色图像：

image:
  - platform: file
    file: "image.jpg"
    id: my_image
    resize: 200x200
    type: RGB

...

display:
    ...
    lambda: |-
      it.image(0, 0, id(my_image));

完整示例

以下是一个你可以添加到基础设备配置中的示例 YAML 配置。它定义了：

• 三种字体（实际上是一种字体的三种大小）

• 一个指示 API 连接状态的 binary_sensor

• TTGO 模块上两个按钮各自的 binary_sensor

• 一个 switch，允许从 HA 控制背光

• 几种颜色

• 要在显示上显示的彩色图像

• 用于显示的时间……在显示上

• 用于与显示通信的 SPI 配置

• 显示组件本身，用于 TTGO 模块

• 一个 lambda，将屏幕绘制为上图所示：

  • 蓝色边框，顶部有一个类似”标题栏”的区域
  • 左上角的黄色”ESPHome”
  • API 连接状态，连接时显示绿色”Online”，未连接时显示红色”Offline”
  • 时间和日期，大致在显示中心

要使用此示例，你只需提供字体文件 “Helvetica.ttf”（或更新为你选择的字体）和图像文件 “image.png”（也可以是 “.jpg”）。将它们 放在与 YAML 配置文件相同的目录中。通过注释/取消注释/修改 lambda 中的相应 C 代码行来隐藏或显示图像或文本。

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
      mode:
        input: true
        pullup: 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

# 允许背光的可调光控制（引脚 GPIO4）
output:
  - platform: ledc
    pin: GPIO4
    id: gpio4

light:
  - platform: monochromatic
    output: gpio4
    name: "Backlight"

image:
  - platform: file
    file: "image.png"
    id: my_image
    resize: 200x200
    type: RGB

time:
  - platform: homeassistant
    id: esptime

spi:
  clk_pin: GPIO18
  mosi_pin: GPIO19

display:
  - platform: st7789v
    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));   // 标题栏

      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");

      // 注释掉上面的行以在不叠加文本的情况下查看图像
      // 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");
      }

参见

• 显示组件
• 电源组件
• API 参考：st7789v_base.h