跳转到内容
ESPHome - 让智能家居更简单2026.7.0

MIPI RGB 显示驱动

显示类型

Section titled “显示类型”

此显示驱动支持具有 16 位并行接口的显示，通常称为”RGB”。 两类显示属于此类别，第一类只有 RGB 接口且不需要 驱动芯片的特殊配置。第二类同时具有 RGB 接口和 SPI 接口， 用于配置驱动芯片。

支持的板卡和驱动芯片

Section titled “支持的板卡和驱动芯片”

驱动支持许多显示驱动芯片，并可配置为自定义显示。除了支持 驱动芯片外，还有针对几款带集成显示的 ESP32 板卡的特定配置。对于这些板卡 预定义配置将为显示设置正确的引脚和尺寸。

对于自定义显示，驱动可以用正确的引脚和尺寸配置，并指定驱动芯片， 或提供自定义的初始化序列。

驱动芯片

Section titled “驱动芯片”
驱动芯片典型尺寸
ST7701S480x480
RPI各异
CUSTOM各异

RPI 驱动芯片代表没有 SPI 接口的显示，因此不需要初始化序列。CUSTOM 型号没有预定义的配置选项，因此需要完整的 YAML 配置。

支持的集成显示板卡

Section titled “支持的集成显示板卡”

这些板卡有完全预填的显示驱动配置，因此唯一需要的配置 选项是 model。

板卡驱动芯片制造商产品链接
GUITION-4848S040ST7701sGuitionhttps://devices.esphome.io/devices/Guition-ESP32-S3-4848S040
T-PANEL-S3ST7701sLilygohttps://lilygo.cc/products/t-panel-s3
T-RGB-2.1ST7701sLilygohttps://lilygo.cc/products/t-rgb
T-RGB-2.8ST7701sLilygohttps://lilygo.cc/products/t-rgb
SEEED-INDICATOR-D1ST7701sSeeed Studiohttps://www.seeedstudio.com/SenseCAP-Indicator-D1L-p-5646.html
ESP32-8048S050RPISuntonhttps://www.makerfabs.com/sunton-esp32-s3-5-inch-ips-with-touch.html
ESP32-8048S070RPISuntonhttps://www.makerfabs.com/sunton-esp32-s3-7-inch-tn-display-with-touch.html
ESP32-S3-TOUCH-LCD-4.3RPIWavesharehttps://www.waveshare.com/esp32-s3-touch-lcd-4.3.htm
ESP32-S3-TOUCH-LCD-7-800X480RPIWavesharehttps://www.waveshare.com/esp32-s3-touch-lcd-7.htm
WAVESHARE-3.16-320X820ST7701sWavesharehttps://www.waveshare.com/esp32-s3-lcd-3.16.htm
WAVESHARE-4-480X480RPIWavesharehttps://www.waveshare.com/esp32-s3-touch-lcd-4.htm
WAVESHARE-5-1024X600RPIWavesharehttps://www.waveshare.com/esp32-s3-touch-lcd-5.htm

用法

Section titled “用法”

此组件需要 ESP32（通常是 ESP32-S3，因为需要大量的 GPIO 引脚）并使用 ESP-IDF。由于显示缓冲区的大小，PSRAM 是必需的。

Sensecap Indicator 显示
# 示例最小配置条目
display:
  - platform: mipi_rgb
    model: WAVESHARE-4-480x480
    id: my_display

配置选项

Section titled “配置选项”

  • rotation (可选): 在软件中旋转显示。可选值为 0°、90°、180° 或 270°。 此选项不能与 transform 一起使用。

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

  • auto_clear_enabled (可选, boolean): 显示是否在每次更新前清除。默认为 true 如果配置了 lambda 或页面，否则为 false。

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

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

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

  • dimensions (必需): 屏幕尺寸，可以 width x height（例如 320x240） 或分别用配置键指定。

    • height (必需, int): 以像素指定显示的高度。
    • width (必需, int): 指定显示的宽度。
    • offset_width (可选, int): 指定显示的 x 方向偏移量，通常用于 LCD 小于驱动芯片最大支持尺寸时。默认为 0
    • offset_height (可选, int): 指定显示的 y 方向偏移量。默认为 0。

  • data_pins (必需): 用于数据总线的引脚列表。分为 3 组指定。

    • red (必需, Pin Schema): 红色数据位的恰好 5 个引脚，按从最低 到最高有效位排列。
    • green (必需, Pin Schema): 绿色数据位的恰好 6 个引脚，按从 最低到最高有效位排列。
    • blue (必需, Pin Schema): 蓝色数据位的恰好 5 个引脚，按从 最低到最高有效位排列。

  • de_pin (必需, Pin Schema): DE 引脚。

  • pclk_pin (必需, Pin Schema): PCLK 引脚。

  • hsync_pin (可选, Pin Schema): 水平同步引脚。

  • vsync_pin (可选, Pin Schema): 垂直同步引脚。

  • reset_pin (可选, Pin Schema): RESET 引脚。

  • hsync_pulse_width (可选, int): 水平同步脉冲宽度。

  • hsync_front_porch (可选, int): 水平前廊长度。

  • hsync_back_porch (可选, int): 水平后廊长度。

  • vsync_pulse_width (可选, int): 垂直同步脉冲宽度。

  • vsync_front_porch (可选, int): 垂直前廊长度。

  • vsync_back_porch (可选, int): 垂直后廊长度。

  • pclk_frequency (可选): 设置像素时钟速度。默认为 8MHz。

  • pclk_inverted (可选, bool): 如果 pclk 是负触发（默认为 True）

水平和垂直的 pulse_width、front_porch 和 back_porch 值是可选的，但 很可能需要根据特定显示更改默认值。请参考制造商的示例代码 以获取合适的值。这些指定了显示的时间要求。

非 RPI 显示的附加配置

Section titled “非 RPI 显示的附加配置”

需要自定义初始化序列的显示需要配置 SPI 总线，以及这些选项：

  • dc_pin (可选, Pin Schema): DC 引脚。

  • data_rate (可选): 设置显示 SPI 接口的数据速率。可选值为 80MHz、40MHz、 20MHz、10MHz、5MHz、2MHz、1MHz（默认）、200kHz、75kHz 或 1kHz。

  • spi_mode (可选): 设置显示 SPI 接口的模式。默认为 MODE0，但一些显示 需要 MODE3。

  • spi_id (可选, ID): 要使用的 SPI 接口的 ID - 如果只配置了一个 SPI 总线 可以省略。

  • init_sequence (可选, 字节数组列表): 指定显示的初始化序列。 预定义板卡 有默认的初始化序列，可以覆盖。自定义板卡可以使用此 变量指定初始化序列（RPI 显示应提供空序列，此时不需要 SPI 总线。）

  • pixel_mode (可选, string): 设置 RGB 总线接口的像素模式 - 可选值为 16bit（默认）或 18bit。

  • invert_colors (可选): 反转显示颜色（白色变为黑色）。默认为 false。

  • color_order (可选): 应为 bgr（默认）或 rgb 之一。

  • transform (可选): 使用硬件转换显示。 这通常仅用于纠正 x 或 y 驱动接反的显示。要旋转 显示，首选使用 rotation 选项 - 它将在可能的情况下自动使用硬件转换。 mirror_x 和 mirror_y 选项的默认值取决于型号。 对于 CUSTOM 型号，使用 transform: disabled 将防止 rotation 被转换为硬件转换。

    • mirror_x (可选, boolean): 如果为 true，则镜像 x 轴。
    • mirror_y (可选, boolean): 如果为 true，则镜像 y 轴。 注意： 要在硬件中将显示旋转 180 度，将 mirror_x 和 mirror_y 都设置为 true。

init_sequence 需要一个元素列表，必须是字节数组，提供附加的 初始化命令，每个命令由一个命令字节后跟零个或多个数据字节组成。

可以使用 delay <N>ms 指定延迟。

这些将在初始化期间通过 SPI 收集并发送到显示。SPI 总线不需要 硬件实现（即可以使用 interface: software），并且它将在初始化后释放，在 RGB 驱动配置之前。这适用于将 SPI 总线引脚用作 RGB 引脚的板卡。

如果从其他代码复制初始化序列，请注意数组长度不应包含，因为 它将根据提供的字节数推断。SLPOOUT、PIXFMT、INVON、INVOFF 和 DISPLAY_ON 命令将根据配置选项自动追加，不应包含在 YAML 中的初始化序列中。

配置示例

Section titled “配置示例”

这是一个自定义配置的示例。

display:
  - platform: mipi_rgb
    model: custom
    id: rpi_disp
    update_interval: never
    auto_clear_enabled: false
    color_order: RGB
    pclk_frequency: 16MHz
    dimensions:
      width: 800
      height: 480
    reset_pin:
      ch422g:
      number: 3
    enable_pin:
      ch422g:
      number: 2
    de_pin:
      number: 5
    hsync_pin:
      number: 46
      ignore_strapping_warning: true
    vsync_pin:
      number: 3
      ignore_strapping_warning: true
    pclk_pin: 7
    pclk_inverted: true
    hsync_back_porch: 30
    hsync_front_porch: 210
    hsync_pulse_width: 30
    vsync_back_porch: 4
    vsync_front_porch: 4
    vsync_pulse_width: 4
    data_pins:
      red:
        - 1         #r3
        - 2         #r4
        - 42        #r5
        - 41        #r6
        - 40        #r7
      blue:
        - 14        #b3
        - 38        #b4
        - 18        #b5
        - 17        #b6
        - 10        #b7
      green:
        - 39        #g2
        - 0         #g3
        - 45        #g4
        - 48        #g5
        - 47        #g6
        - 21        #g7


    init_sequence:
      - [0x01]
      - [0x3A, 0x66]

参见

Section titled “参见”