MIPI SPI 显示驱动
此驱动程序适用于使用 MIPI DBI 接口的显示屏，通过 SPI 实现。这是许多显示屏的常见接口，用于许多基于 ESP32 的显示开发板。该驱动程序设计灵活，支持广泛的显示屏，可以通过 SPI、四线 SPI 和 8 位并行接口驱动显示屏。
MIPI（移动产业处理器接口）联盟发布各种硬件和软件接口规范，包括显示总线接口（DBI），定义了串行和并行硬件接口，以及显示命令集（DCS），定义了一组用于控制显示屏的命令。这些标准用于许多嵌入式系统的显示屏，此驱动程序针对这些显示类型。
驱动程序控制的显示面板可能是各种类型，包括 TFT、IPS、AMOLED 等。每个驱动芯片和面板组合需要特定的初始化命令集，为许多常见的开发板和芯片提供标准初始化序列，但该驱动程序也设计为可在 YAML 中针对其他显示屏进行自定义。
支持的开发板和驱动芯片
Section titled “支持的开发板和驱动芯片”该驱动程序支持多种显示驱动芯片，并且可以为自定义显示屏进行配置。除了支持驱动芯片外，还有几个带有集成显示屏的 ESP32 开发板的特定配置。对于这些开发板，预定义的配置将设置正确的引脚和显示屏尺寸。
对于自定义显示屏，可以配置正确的引脚和尺寸，并指定驱动芯片，或提供自定义初始化序列。通过使用八线 SPI 总线支持具有 8 位并行接口的显示屏，因此这里对并行和八线 SPI 的引用是等效的。
| 驱动芯片 | 典型尺寸 |
|---|---|
| RM690B0 | 320x240 |
| ILI9341 | 320x240 |
| ILI9342 | 240x320 |
| ILI9481 | 320x480 |
| ILI9486 | 320x480 |
| ILI9488 | 320x480 |
| ILI9488_A | 320x480 |
| ST7796 | 320x480 |
| ST7789V | 240x320 |
| GC9A01A | 240x240 |
| GC9D01N | 240x240 |
| AXS15231 | 320x240 |
| ST7735 | 128x160 |
| CO5300 | 466x466 |
| CUSTOM | 可自定义 |
这些型号代表具有已知尺寸但没有微控制器的显示屏面板。配置需要指定用于连接显示屏的引脚。
| 面板 | 制造商 | 产品描述 |
|---|---|---|
| WAVESHARE-1.83-V2 | Waveshare | https://www.waveshare.com/1.83inch-LCD-Module.htm |
带有集成显示屏的开发板
Section titled “带有集成显示屏的开发板”SPI 总线
Section titled “SPI 总线”使用 Spi 与显示驱动芯片通信。驱动程序支持单线 SPI、四线 SPI 和八线 SPI。SPI 总线必须单独配置，并且必须是显示驱动芯片正确的类型。
# 最小配置示例display: - platform: mipi_spi model: T_EMBED所有图形显示配置选项均可用，此外还有以下选项。对于集成显示开发板，大多数配置将默认设置，但如果需要可以覆盖。
- model (必填)：从上方支持的芯片和型号列表中选择，或
CUSTOM用于自定义显示屏。 - bus_mode (可选)：选择显示驱动程序的 SPI 总线模式。选项有
single（默认）、quad和octal。 - dc_pin (必填, 引脚模式)：DC 引脚。四线 SPI 不需要或不允许。
- reset_pin (可选, 引脚模式)：RESET 引脚。
- cs_pin (可选, 引脚模式)：CS 引脚。
NOTE
单线 SPI 和 8 位并行接口需要 DC 引脚，只有当特定开发板将这些引脚连接到 GPIO 时才需要 CS 引脚和 RESET 引脚。使用集成显示屏的开发板时，引脚将默认设置为正确的值，但如果需要可以在配置中覆盖。
-
enable_pin (可选, 引脚模式)：可选的使能引脚，如果需要的话。可以为需要多个使能引脚的显示屏提供引脚列表。可以提供完整的引脚配置来设置引脚模式和反转属性。默认情况下，引脚将被驱动为高电平以使能显示屏。
-
brightness (可选, int)：显示屏的初始亮度，仅用于 AMOLED 显示屏。这应该是一个 0 到 255 的值，默认为 0xD0。
-
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被转换为硬件变换，否则使用以下选项：- swap_xy (*必填, 布尔值)：如果为 true，交换 x 和 y 轴。
- mirror_x (*必填, 布尔值)：如果为 true，镜像 x 轴。
- mirror_y (*必填, 布尔值)：如果为 true，镜像 y 轴。
-
color_depth (可选)：显示缓冲区的颜色深度，以位表示。选项有
16（默认）和8。8 位深度只会产生 256 种可能的颜色，只有在微控制器内存有限时才应使用。驱动程序会将 8 位颜色转换为显示芯片所需的格式。 -
buffer_size (可选)：分配缓冲内存的屏幕大小百分比。当配置了 PSRAM 时默认为
100%，否则将计算为缓冲区大小小于 20K 字节。请参阅下方关于缓冲区大小的讨论。
- init_sequence (可选)：允许添加自定义初始化序列。详见下文。
- pixel_mode (可选)：选择显示驱动程序的接口模式。选项有
16bit（默认）和18bit。大多数显示屏需要 16 位模式，除非显示屏需要 18 位模式，否则首选 16 位模式。 - spi_16 (可选)：在使用单线 SPI 但通过 16 位移位寄存器并行驱动显示屏的开发板上设置为
true。 - data_rate (可选)：SPI 数据速率。默认为 10MHz，但开发板预设可能会覆盖此值。
- spi_mode (可选)：SPI 模式。选项有
MODE0、MODE1、MODE2和MODE3。单线 SPI 默认为MODE0，八线 SPI（并行总线）默认为MODE3。 - draw_rounding (可选)：绘图操作的四舍五入因子。默认为 2。某些芯片需要更高的值以避免显示伪影。必须是 2 的幂。
- use_axis_flips (可选)：如果为 true，驱动程序将使用 MADCTL 寄存器中的替代位来实现 x 和 y 镜像。默认为 false。
- byte_order (可选)：显示缓冲区的字节顺序。选项有
big_endian（默认）和little_endian。这影响使用 16 位颜色深度时缓冲区的字节顺序。默认值适用于大多数显示屏。
注意： 可实现的最大数据速率取决于芯片类型（如 ESP32 与 ESP32-S3）、使用的引脚（在 ESP32 上使用默认 SPI 引脚可以实现更高速率）和连接类型（板载连接比长电缆或杜邦线支持更高速率。）如果不确定，请从低速开始测试更高速率以找到可行方案。最好不要指定 MISO 引脚，因为在某些情况下这会限制最大速率，而且如果 SPI 总线仅用于显示屏，则不需要 MISO 引脚。
显示驱动程序将数据从缓冲区写入显示芯片。当使用 Lvgl 时，显示驱动程序本身不需要缓冲区，因为 LVGL 将分配并使用自己的缓冲区。
当改为使用 lambda 函数更新显示屏（而不是 LVGL）时，需要由显示驱动程序分配缓冲区。
此缓冲区的大小由 buffer_size 选项确定。当配置了 PSRAM 时默认为 100%，否则将计算为缓冲区大小小于 20K 字节。例如，320x240 的显示屏将具有 320 * 240 * 2 字节（RGB565）= 153600 字节的缓冲区大小。
如果缓冲区大小设置为 50%，则缓冲区将占用 76800 字节。如果使用 8 位颜色深度，则每个像素只占用 1 字节。
对绘图性能的影响
Section titled “对绘图性能的影响”缓冲区大小是在缓冲区大小和显示驱动程序性能之间的权衡。较大的缓冲区大小将提供更好的性能，但在内存有限的开发板上，可能需要较小的缓冲区大小以避免内存不足。当使用小于 100% 的缓冲区时，驱动程序将多次调用绘图 lambda 来绘制显示屏的每个块。例如，使用 25% 的缓冲区大小时，驱动程序将调用绘图 lambda 四次来绘制显示屏。 这会影响性能，在设置缓冲区大小时应考虑这一点，但绘图 lambda 不应有副作用也很重要——这无论如何都应该避免，但在使用小于 100% 的缓冲区时变得更加关键。
附加初始化序列
Section titled “附加初始化序列”init_sequence 选项允许对驱动芯片进行额外配置。提供的命令将在所选型号的预定义命令之外，并在之后发送到驱动芯片。它需要一个字节序列列表：
init_sequence: - [ 0xD0, 0x07, 0x42, 0x18] - delay 10ms - [ 0xD1, 0x00, 0x07, 0x10]每个条目代表一个单字节命令，后跟零个或多个数据字节。可以使用 delay 关键字后跟毫秒时间插入延迟。延迟不精确，但至少为指定时间。
如果从其他代码转换，请确保不要复制长度字节（如果存在），因为每个命令序列的长度由列表中的字节数确定。
CUSTOM 自定义型号
Section titled “CUSTOM 自定义型号”CUSTOM 型号选择用于其他不支持的显示屏，需要同时指定 dimensions: 和 init_sequence:。没有预定义的初始化序列。
使用 transform 选项
Section titled “使用 transform 选项”在大多数情况下，rotation 选项足以正确调整显示屏方向。但是，某些显示屏可能需要额外的变换。transform 选项允许以 8 种不同的组合应用这些变换。可能需要尝试不同的组合才能获得所需的结果。使用 transform 选项时，不应设置 rotation 选项，除非显示屏不支持轴交换。
如果设置了 swap_xy 选项，则需要 dimensions 选项，并且 width 和 height 值应设置为反映旋转后的最终屏幕尺寸。
transform: swap_xy: true mirror_x: true mirror_y: falsedimensions: height: 480 width: 320当使用带有旋转的 CUSTOM 型号时，如果芯片不支持硬件变换，请使用 transform: disabled 禁用硬件变换并确保软件旋转。
LCD 背光
Section titled “LCD 背光”许多显示屏有集成背光，可能需要打开才能显示。此背光不由驱动程序控制，但可以由单独的 GPIO 引脚控制。根据显示屏的不同，背光可能是高电平有效或低电平有效，并且可以使用带有 Ledc 的 Monochromatic 进行调光。AMOLED 显示屏没有背光，但可以使用 brightness 选项设置其亮度。这也可以通过 lambda API 调用控制。
如果存在触摸屏，必须单独配置。请参阅 Touchscreen 文档了解更多信息。