MIPI DSI 显示驱动

简介

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

配备 ESP32-P4 的 M5STACK-TAB5

背景

MIPI（移动产业处理器接口）联盟发布各种硬件和软件接口规范，包括显示串行接口（DSI），它通过高速串行总线将像素数据传输到 LCD 显示屏。

驱动程序控制的显示面板可能是各种类型，包括 TFT、IPS 等。每个驱动芯片和面板组合需要特定的初始化命令集，为许多常见的开发板和芯片提供标准初始化序列，但该驱动程序也设计为可在 YAML 中针对其他显示屏进行自定义。

支持的开发板和驱动芯片

有几个带有集成显示屏的 ESP32 开发板的特定配置。对于这些开发板，预定义的配置将设置正确的引脚和显示屏尺寸。

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

驱动芯片

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

带有集成显示屏的开发板

型号	制造商	产品描述
JC1060P470	Guition	https://aliexpress.com/item/1005008328088576.html
JC4880P443	Guition	https://aliexpress.com/item/1005009618259341.html
JC8012P4A1	Guition	https://aliexpress.com/item/1005008789890066.html
M5STACK-TAB5	M5Stack	https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4
M5STACK-TAB5-V2	M5Stack	https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4
WAVESHARE-P4-NANO-10.1	Waveshare	https://www.waveshare.com/esp32-p4-nano.htm?sku=29031
WAVESHARE-P4-86-PANEL	Waveshare	https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm?sku=31570
WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-7B	Waveshare	https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-7B
WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-3.4C	Waveshare	https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-3.4C
WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-4C	Waveshare	https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-4C

NOTE

M5Stack Tab5 有两个硬件版本，具有不同的显示芯片，需要选择不同的型号。

2025年10月14日之前生产的设备使用 ILI9881C 显示驱动器和独立的 GT911 触摸驱动器（使用 M5STACK-TAB5）。 该日期或之后生产的设备使用集成的 ST7123 显示-触摸驱动器（使用 M5STACK-TAB5-V2）。

如果不确定您拥有哪个型号，请检查设备背面的贴纸上的显示驱动芯片名称。 标签位于 ESPressif 图标正上方。请参见下方图片了解 V2 硬件示例。

选择错误的显示驱动型号将导致显示屏无法工作，且没有相关日志。 然而，选择错误的触摸屏驱动程序会在日志输出中显示错误消息，因此如果不确定，请先验证正确的触摸屏驱动程序以准确识别开发板，然后再配置显示驱动程序。

配置

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

配置选项

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

• model (必填)：从上方支持的芯片和型号列表中选择，或 CUSTOM 用于自定义显示屏。

• reset_pin (可选, 引脚模式)：RESET 引脚（如果需要）。

• enable_pin (可选, 引脚模式)：可选的使能引脚（如果需要）。可以为需要多个使能引脚的显示屏提供引脚列表。可以提供完整的引脚配置来设置引脚模式和反转属性。默认情况下，引脚将被驱动为高电平以使能显示屏。

• color_order (可选)：应为 bgr（默认）或 rgb 之一。这指定了显示面板中颜色通道的顺序。大多数显示屏默认为 bgr，但某些显示屏可能需要 rgb。它不影响显示缓冲区的颜色顺序，显示缓冲区始终是 RGB。

• dimensions (可选)：屏幕尺寸，指定为 宽度 x 高度（如 320x240）或使用单独的配置键。如果未提供，尺寸将由所选型号确定。CUSTOM 型号需要此项，其他型号可选。尺寸以像素为单位指定，宽度和高度必须大于 0。可用以下键：

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

• invert_colors (可选, 布尔值)：指定是否反转显示屏颜色。选项为 true 或 false。默认为 false。

• rotation (可选)：在软件中旋转显示屏显示。选择 0°、90°、180° 或 270° 之一。如果驱动芯片支持给定方向的硬件旋转，这将转换为适当的硬件命令。如果不支持硬件旋转，显示屏将在软件中旋转。

• transform (可选)：如果 rotation 不够用，使用此选项变换显示屏。如果指定了此选项，则还必须提供 dimensions 选项。值可以是字符串 disabled 以禁用硬件变换，或一个字典。 对于 CUSTOM 型号，如果显示屏不支持变换，请使用 transform: disabled，这将防止 rotation 被转换为硬件变换，否则使用以下选项。请注意，DSI 显示屏不支持轴交换，因此只能镜像 x 和 y 轴，90 或 270 度的旋转必须由软件处理。

  • mirror_x (*必填, 布尔值)：如果为 true，镜像 x 轴。
  • mirror_y (*必填, 布尔值)：如果为 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 (可选, 布尔值)：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 的 Monochromatic 进行调光。

触摸屏

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

另见

• Display 显示组件
• LVGL 图形库
• API Reference: mipi_dsi.h