ILI9xxx TFT LCD 系列

型号

使用此显示驱动你可以控制以下显示：

GC9A01A
GC9D01N
ILI9341
ILI9342
ILI9481
ILI9481-18（ILI9481 的 18 位模式，即 262K 色模式）
ILI9486
ILI9488
ILI9488_A（ILI9488 的替代 Gamma 配置）
M5STACK
S3BOX
S3BOX_LITE
ST7735
ST7796
ST7789V
TFT 2.4
TFT 2.4R
WAVESHARE_RES_3_5（Waveshare Pico-ResTouch-LCD-3.5）

将来会有更多的显示驱动。

用法

此组件是 ILI9341 组件的继任者，支持来自 ILI 及相关家族的更多显示驱动芯片。

ILI9xxx 显示平台允许你使用 ESPHome 的 ILI9341（数据手册）及其他同芯片系列的显示器。由于这是较高分辨率的显示，需要超出基本 SPI 连接之外的额外引脚，以及相当数量的 RAM，因此它不太适合 ESP8266。

WARNING

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

NOTE

ESP32 上不会自动启用 PSRAM（这在 2025.2 版本中发生了变更）。如果 PSRAM 可用，你应通过 PSRAM 配置启用它。使用 16 位颜色所需的 RAM 是 8 位的两倍，如果没有 PSRAM 可能无法使用。

NOTE

默认颜色深度为 16 位（RGB565）。也支持 8 位颜色，但颜色调色板必须设置为可用选项之一。使用 16 位颜色所需的 RAM 是 8 位的两倍，如果没有 PSRAM 可能无法使用。

# 示例最小配置条目
display:
  - platform: ili9xxx
    model: ili9341
    dc_pin: GPIOXX
    reset_pin: GPIOXX
    invert_colors: false
    show_test_card: true

配置变量

所有图形显示配置选项均可用，此外还有以下选项。

model (必需): 显示的型号。可选值有：
- M5STACK、TFT 2.4、TFT 2.4R、S3BOX、S3BOX_LITE、WSPICOLCD
- ILI9341、ILI9342、ILI9486、ILI9488、ILI9488_A（ILI9488 的替代 Gamma 配置）
- ILI9481、ILI9481-18（18 位模式）
- ST7789V、ST7796、ST7735
- GC9A01A、GC9D01N、CUSTOM
dc_pin (必需, Pin Schema): DC 引脚。
reset_pin (可选, Pin Schema): RESET 引脚。
cs_pin (可选, Pin Schema): CS 引脚。

NOTE

DC 引脚始终必需，CS 引脚和 RESET 引脚只有在特定板将这些引脚连接到 GPIO 时才需要。

color_palette (可选): 使用 8 位颜色时，此选项控制 ESP 内部 8 位/像素缓冲中将使用的颜色调色板类型。可用于提高图像的颜色深度质量。例如，如果你知道显示只将显示灰度图像，可以通过将可用颜色集中在灰度上来提高显示的清晰度。可选值有：
- NONE（默认）颜色将为 16 位 RGB565
- 8BIT 颜色将为 8 位 RGB332
- GRAYSCALE 颜色将为 8 位灰度
- IMAGE_ADAPTIVE 颜色将为 8 位，颜色调色板将根据下面 color_palette_images 列表中的图像生成。
color_order (可选): 应为 bgr（默认）或 rgb 之一。
color_palette_images (可选): 用于生成显示颜色调色板的图像文件列表。仅应与 color_palette: IMAGE_ADAPTIVE 配合使用。图像将在编译时分析，并根据最常见的颜色创建自定义颜色调色板。典型的设置是一个代表完全填充显示的样本图像。这可以显著提高显示图像的质量。请注意，这些图像不会存储在 ESP 设备上，仅存储从它们创建的 256 字节颜色调色板。
dimensions (可选): 屏幕尺寸，可以 width x height（例如 320x240 ）或分别用配置键指定。如果不提供，尺寸将由所选型号确定。
- height (必需, int): 以像素指定显示的高度。
- width (必需, int): 指定显示的宽度。
- offset_width (可选, int): 指定显示的 x 方向偏移量，通常用于 LCD 小于驱动芯片最大支持尺寸时。默认为 0
- offset_height (可选, int): 指定显示的 y 方向偏移量。默认为 0。
invert_colors (必需): 指定显示颜色是否应反转。可选值为 true 或 false - 如果你不确定，使用 false，如果颜色与预期不符则更改。
pixel_mode (可选): 允许强制显示进入 18 位或 16 位模式。可选值为 18bit 或 16bit。如果不指定，像素模式将由型号选择确定。并非所有显示都两种模式都能工作。
rotation (可选): 在软件中旋转显示。可选值为 0°、90°、180° 或 270°。此选项不能与 transform 一起使用。
transform (可选): 使用硬件转换显示。所有默认值均为 false。此选项不能与 rotation 一起使用。
- swap_xy (可选, boolean): 如果为 true，则交换 x 和 y 轴。
- mirror_x (可选, boolean): 如果为 true，则镜像 x 轴。
- mirror_y (可选, boolean): 如果为 true，则镜像 y 轴。

NOTE

rotation 变量将执行基于软件的旋转。更好的做法是使用 transform 选项在硬件中旋转显示。使用以下组合之一：

90 度 - 使用 swap_xy 配合 mirror_x
180 度 - 使用 mirror_x 配合 mirror_y
270 度 - 使用 swap_xy 配合 mirror_y

对于 90 和 270 旋转，你还需要在 dimensions 中交换 height 和 width（见下面的示例）。

init_sequence (可选): 允许添加自定义初始化序列。有关更多信息，请参见下文。

要修改 SPI 设置，请参见 SPI 总线。默认的 data_rate 设置为 40MHz，spi_mode 模式为 MODE0，但一些显示需要 MODE3（*）。

注意： 最大可实现的数据速率将取决于芯片类型（例如 ESP32 与 ESP32-S3）、使用的引脚（在 ESP32 上使用默认 SPI 引脚允许更高的速率）和连接类型（板载连接将比长电缆或杜邦线支持更高的速率）。如果不确定，请从低速开始并测试更高的速率以找到可用的速率。应尽量避免指定 MISO 引脚，因为这将在某些情况下限制最大速率，如果 SPI 总线仅用于显示，则不需要。

附加初始化序列

init_sequence 选项允许对驱动芯片进行附加配置。提供的命令将在选定型号的预定义命令之后发送到驱动芯片。它需要一个字节序列列表：

init_sequence:
  - [ 0xD0, 0x07, 0x42, 0x18]
  - [ 0xD1, 0x00, 0x07, 0x10]

每个条目代表一个单字节命令，后跟零个或多个数据字节。

CUSTOM 型号

CUSTOM 型号选择用于其他不受支持的显示，需要同时指定 dimensions: 和 init_sequence:。没有预定义的初始化序列。

配置示例

要使用硬件旋转，请使用 dimensions 和 transform，例如以下配置将高度为 320、宽度为 480 的横向显示变为纵向。注意，尺寸是最终显示的尺寸。

transform:
  swap_xy: true
  mirror_x: true
dimensions:
  height: 480
  width: 320

要利用此显示模块的颜色功能，你可能需要在你的 YAML 配置中添加一个 color: 部分；有关此配置部分的更多详细信息，请参见颜色。

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

要配置可调光背光：

# 在 ESP32 上定义 PWM 输出
output:
  - platform: ledc
    pin: GPIOXX
    id: backlight_pwm

# 定义单色、可调光背光灯光
light:
  - platform: monochromatic
    output: backlight_pwm
    name: "Display Backlight"
    id: back_light
    restore_mode: ALWAYS_ON

要配置图像自适应颜色调色板，以便在 RAM 受限的屏幕缓冲中显示超过 8 位的颜色深度：

image:
  - platform: file
    file: "sample_100x100.png"
    id: myimage
    resize: 100x100
    type: RGB

display:
  - platform: ili9xxx
    model: ili9341
    dc_pin: GPIOXX
    reset_pin: GPIOXX
    rotation: 90
    id: tft_ha
    color_palette: IMAGE_ADAPTIVE
    color_palette_images:
      - "sample_100x100.png"
      - "display_design.png"
    lambda: |-
      it.image(0, 0, id(myimage));

在 Lilygo T-Embed 上使用 transform 选项在硬件中旋转显示。它使用 st7789v，但只使用 240 宽度中的 170 像素。此配置使用驱动芯片将显示旋转到横向模式。

display:
  - platform: ili9xxx
    model: st7789v
    dimensions:
      height: 170
      width: 320
      offset_height: 35
      offset_width: 0
    transform:
      swap_xy: true
      mirror_x: false
      mirror_y: true
    color_order: bgr
    invert_colors: true
    data_rate: 80MHz
    cs_pin: GPIOXX
    dc_pin: GPIO13
    reset_pin: GPIO9

对于 Lilygo TTGO 板，如果从 st7789v 迁移到此组件，需要以下设置才能使其工作。

display:
  - platform: ili9xxx
    model: st7789v
    #TTGO TDisplay 135x240
    dimensions:
      height: 240
      width: 135
      offset_height: 40
      offset_width: 52
    # 必需，否则颜色全部反转，黑屏变为白屏
    invert_colors: true