ILI9xxx TFT LCD 系列

型号

使用此显示驱动程序，您可以控制以下显示屏：

GC9A01A
GC9D01N
ILI9341
ILI9342
ILI9481
ILI9481-18（ILI9481 的 18 位模式，即 262K 色彩模式）
ILI9486
ILI9488
ILI9488_A（ILI9488 的替代伽马配置）
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

PSRAM 在 ESP32 上不会自动启用（这在 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 的替代伽马配置）
- ILI9481、ILI9481-18（18 位模式）
- ST7789V、ST7796、ST7735
- GC9A01A、GC9D01N、CUSTOM
dc_pin (必填, 引脚模式)：DC 引脚。
reset_pin (可选, 引脚模式)：RESET 引脚。
cs_pin (可选, 引脚模式)：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 (可选)：屏幕尺寸，指定为宽度 x 高度（如 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 (可选, 布尔值)：如果为 true，交换 x 和 y 轴。
- mirror_x (可选, 布尔值)：如果为 true，镜像 x 轴。
- mirror_y (可选, 布尔值)：如果为 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 总线仅用于显示屏，则不需要 MISO 引脚。

附加初始化序列

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: 部分；请参阅 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:
  - file: "image.jpg"
    id: my_image
    resize: 200x200
    type: RGB24

...

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:
  - file: "sample_100x100.png"
    id: myimage
    resize: 100x100
    type: RGB24

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

使用 transform 选项在 Lilygo T-Embed 上进行硬件旋转显示屏。它有一个 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

ILI9xxx TFT LCD 系列

型号

用法

配置变量

附加初始化序列

CUSTOM 自定义型号

配置示例

另见