MIPI DSI 显示驱动

简介

此驱动适用于使用 ESP32-P4 中可用的 MIPI DSI 显示接口的显示。

背景

MIPI（Mobile Industry Processor Interface）联盟发布各种硬件和软件接口规范包括显示串行接口（DSI），它通过高速串行总线将像素数据传输到 LCD 显示。

驱动控制的显示面板可以是各种类型，包括 TFT、IPS 等。每个驱动芯片和面板组合需要一组特定的初始化命令，并为许多常见板卡和芯片提供了标准的初始化序列，但驱动也设计为可通过 YAML 自定义其他显示。

支持的驱动芯片、显示面板和板卡

驱动芯片

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

驱动芯片	典型尺寸
CUSTOM	可自定义

独立显示

这些是集成驱动芯片和显示面板的独立显示面板。可能需要指定 transform、rotation 或其他布局参数以适应特定的使用场景。这些显示器通常不会物理暴露复位或使能引脚，但可能有用于触摸屏或控制背光的 I²C 总线连接器。请查看制造商的文档以了解如何使用它们。其中一些显示器被下一节中定义的 ESP32 板卡使用。

型号	制造商	尺寸	产品链接
WAVESHARE-10.1-DSI-TOUCH-A	Waveshare	800x1280	10.1-DSI-TOUCH-A 产品页面
WAVESHARE-8-DSI-TOUCH-A	Waveshare	800x1280	8-DSI-TOUCH-A 产品页面
WAVESHARE-7-DSI-TOUCH-A	Waveshare	720x1280	7-DSI-TOUCH-A 产品页面
WAVESHARE-4-DSI-TOUCH-C	Waveshare	720x720（圆形）	4-DSI-TOUCH-C 产品页面
WAVESHARE-3.4-DSI-TOUCH-C	Waveshare	800x800（圆形）	3.4-DSI-TOUCH-C 产品页面

带集成显示的板卡

这些是针对几款带集成显示的 ESP32 板卡的特定配置。预定义配置将为显示设置正确的引脚和尺寸。

型号	制造商	产品链接
JC1060P470	Guition	JC1060P470 产品页面
JC4880P443	Guition	JC4880P443 产品页面
JC8012P4A1	Guition	JC8012P4A1 产品页面
M5STACK-TAB5	M5Stack	TAB5 产品页面
M5STACK-TAB5-ST7123	M5Stack	TAB5 产品页面
M5STACK-TAB5-ST7121	M5Stack	TAB5 产品页面
SEEED-RETERMINAL-D1001	Seeed Studio	D1001 产品页面
WAVESHARE-P4-NANO-10.1	Waveshare	P4-NANO-10.1 产品页面
WAVESHARE-P4-86-PANEL	Waveshare	P4-86-PANEL 产品页面
WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-7B	Waveshare	P4-WIFI6-TOUCH-LCD-7B 产品页面
WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-3.4C	Waveshare	P4-WIFI6-TOUCH-LCD-3.4C 产品页面
WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-4C	Waveshare	P4-WIFI6-TOUCH-LCD-4C 产品页面

NOTE

M5Stack Tab5 根据制造时间配备不同的显示和触摸控制器，需要使用不同的型号选择。

2025 年 10 月 14 日之前生产的设备使用 ILI9881C 显示驱动和独立的 GT911 触摸驱动；请使用 M5STACK-TAB5。

后来的设备使用集成的显示-触摸控制器，要么是 ST7123 要么是 ST7121。这两种需要不同的显示初始化序列，不能互换，因此选择 M5STACK-TAB5-ST7123 或 M5STACK-TAB5-ST7121 以匹配你的设备。M5STACK-TAB5-V2 是 M5STACK-TAB5-ST7123 的已弃用别名；它仍然有效，但新配置应使用明确的名称，否则将记录弃用警告。

选择错误的显示驱动会导致显示无法工作，且没有任何相关日志，而触摸屏驱动如果在配置错误时会记录错误。因此，如果不确定，请先验证正确的触摸屏驱动以识别板卡；如果显示保持空白且没有错误而触摸屏正常工作，尝试另一个集成型号（用 M5STACK-TAB5-ST7121 替换 M5STACK-TAB5-ST7123，反之亦然）。

你可以查看设备背面贴纸上的显示驱动芯片名称。标签在 Espressif 图标上方。参见下面的图像，是较新硬件的示例。不过，标有”ST7123”的设备可能具有 ST7123 或 ST7121 显示驱动 —— 除了尝试两种型号外，没有其他简单的方法来区分它们。

配置

# 示例最小配置条目
display:
    - platform: mipi_dsi
      model: WAVESHARE-P4-NANO-10.1

配置选项

所有图形显示配置选项均可用，此外还有以下选项。对于集成显示板大部分配置将默认设置，如有需要可以覆盖。

model (必需): 从上面支持的芯片和型号列表中选择，或 CUSTOM 用于自定义显示。
reset_pin (可选, Pin Schema): 如果需要的 RESET 引脚。
enable_pin (可选, Pin Schema): 一个可选的使能引脚，如果需要的话。可以提供引脚列表用于需要多个使能引脚的显示。可以提供完整的引脚配置来设置引脚模式和反转属性。默认引脚将被驱动为高电平以启用显示。
color_order (可选): 应为 bgr（默认）或 rgb 之一。这指定了显示面板中颜色通道的顺序。大多数显示默认为 bgr，但有些显示可能需要 rgb。它不影响显示缓冲区的颜色顺序，后者始终为 RGB。
dimensions (可选): 屏幕尺寸，可以 width x height（例如 320x240 ）或分别用配置键指定。如果不提供，尺寸将由所选型号确定。CUSTOM 型号需要此选项，其他型号可选。尺寸以像素为单位，宽度且高度必须大于 0。以下键可用：
- height (必需, int): 以像素指定显示的高度。
- width (必需, int): 指定显示的宽度。
- offset_width (可选, int): 指定显示的 x 方向偏移量，通常用于 LCD 小于驱动芯片最大支持尺寸时。默认为 0
- offset_height (可选, int): 指定显示的 y 方向偏移量。默认为 0。
invert_colors (可选, boolean): 指定显示颜色是否应反转。可选值为 true 或 false。默认为 false。
rotation (可选): 在软件中旋转显示。可选值为 0°、90°、180° 或 270°。如果驱动芯片支持给定方向的硬件旋转，这将转换为适当的硬件命令。如果不支持硬件旋转，将在软件中旋转显示。
transform (可选): 如果 rotation 不够用，使用此选项来转换显示。如果指定此选项，则必须同时提供 dimensions 选项。值可以是字符串 disabled 以禁用硬件转换，或一个字典。对于 CUSTOM 型号，如果显示不支持，使用 transform: disabled，这将防止 rotation 被转换为硬件转换，否则使用以下选项。注意 DSI 显示不支持轴交换，因此只能镜像 x 和 y 轴， 90 或 270 的旋转必须由软件处理。
- mirror_x (必需, boolean): 如果为 true，则镜像 x 轴。
- mirror_y (必需, boolean): 如果为 true，则镜像 y 轴。
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 (可选): 设置像素时钟速度。默认为 40MHz。
pclk_inverted (可选, bool): 如果 pclk 是负触发（默认为 True）
lanes (可选, int): 使用的串行数据通道数 - 1 或 2。默认为 2。
lane_bit_rate (可选, int): 串行数据通道的比特率。除非选择了非自定义型号，否则没有默认值。

高级选项

init_sequence (可选): 允许添加自定义初始化序列。有关更多信息，请参见下文。
pixel_mode (可选): 选择显示驱动的接口模式。可选值为 16bit（默认）和 24bit。
color_depth (可选): 显示缓冲区的颜色深度，以位为单位。可选值为 16（默认）和 24。最好与 pixel_mode 选项相同。
draw_rounding (可选): 绘制操作的舍入因子。默认为 2。某些芯片需要更高的值以避免显示伪影。必须是 2 的幂。
use_axis_flips (可选): 如果为 true，驱动将使用 MADCTL 寄存器中的替代位来实现 x 和 y 镜像。默认为 false。
byte_order (可选): 显示缓冲区的字节顺序。可选值为 big_endian 和 little_endian（默认）。这会影响使用 16 位颜色深度时的字节顺序。默认适用于大多数显示。

附加初始化序列

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

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

每个条目代表一个单字节命令，后跟零个或多个数据字节。可以使用 delay 关键字后跟毫秒数来插入延迟。延迟不精确，但至少是指定时间。如果从其他代码转换，请确保（如果存在）长度字节没有被复制，因为每个命令序列的长度由列表中的字节数确定。

CUSTOM 型号

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

使用 `transform` 选项

在大多数情况下，rotation 选项足以正确定向显示。然而，一些显示可能需要额外的转换，例如镜像 x 或 y 轴，这可以通过 transform: 选项实现。

transform:
  mirror_x: true
  mirror_y: false
rotation: 90

LCD 背光

许多显示器有集成背光，可能需要打开背光才能显示。此背光不由驱动控制，但可以通过单独的 GPIO 引脚控制。根据显示器不同，背光可能是高电平有效或低电平有效，并且可能能够使用单色配合 Ledc 调光。

触摸屏

如果存在触摸屏，必须单独配置。更多信息请参见触摸屏文档。