RGB LCD 驱动实战指南基于 esp-iot-solution 的接口模式、时序配置与驱动组件移植【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solutionRGB LCD 是 ESP32-S3 / ESP32-P4 等高算力芯片驱动大尺寸、高分辨率屏幕的主流方案它通过并行 RGB 接口以 DMA 从帧缓冲持续刷屏无内置 GRAM 的驱动 IC 直接显示收到的色彩数据。本文以 rgb_lcd.rst 为主线系统讲解 SPIRGB 与纯 RGB 两种接口模式、DE/SYNC 时序模式、颜色格式选择并结合 esp-iot-solution 仓库中 esp_lcd_panel_io_additions 与 esp_lcd_st7701 的源码与测试用例完整演示「初始化接口设备 → 移植驱动组件 → 初始化 LCD 设备」三阶段流程。读完本文你将掌握从硬件连线到软件配置的完整 RGB LCD 驱动能力。术语约定文中会反复出现以下概念其标准定义可参考仓库中的 LCD 术语表LCD_Terms_TableGRAM驱动 IC 内置的显存Graphic RAM。RGB LCD 的驱动 IC 通常没有GRAM需由主控提供整帧帧缓冲。Porch消隐区帧画面四周的空白时序区域包括水平/垂直方向的前肩front porch与后肩back porch。PCLK像素时钟RGB 接口逐像素采样的节拍。HSYNC / VSYNC水平/垂直同步信号。DE数据使能Data Enable信号用于区分有效像素区与消隐区。接口模式SPIRGB 与纯 RGB大多数 RGB LCD 采用SPI RGB双接口模式通过SPI 接口发送命令来初始化 LCD配置驱动 IC 寄存器初始化后还可动态修改垂直/水平镜像等配置灵活性更高通过RGB 接口并行传输整帧色彩数据由 DMA 持续刷新屏幕。另有一类 RGB LCD只使用 RGB 接口无需发送初始化命令驱动方式更简单但代价是无法修改任何配置。驱动 IC 通过硬件引脚选择接口模式。以ST7701S为例其通过IM[3:0]引脚选择SPI RGB接口配置典型的选型为3-wire SPI RGB对应手册中的RGB9b_SPI(rise/fall)其中9b_SPI表示 SPI 接口的 3-line3-wire模式即通常所说的 3 线制rise/fall表示SCL信号的有效沿。rise为上升沿有效对应 SPI 模式 0/3fall为下降沿有效对应 SPI 模式 1/2。ST7701S的 SPI 与 RGB 接口引脚定义如下RGB 接口引脚命名规范为CS、SCK(SCL)、SDA(MOSI)、HSYNC、VSYNC、PCLK、DE、D[23:0]部分屏为D[17:0]或D[7:0]。提示RGB LCD 的硬件驱动框架双接口分工、PSRAM 帧缓冲可参考 lcd_development_guide.rst 中的lcd_hw_framework_rgb示意图以及 lcd_guide.rst 中的 lcd_connection_rgb 连接图。时序模式DE Mode 与 SYNC Mode对于使用SPI RGB接口的 LCD通常可通过命令将 RGB 接口配置为DE 模式或SYNC 模式。不同驱动 IC 使用的配置命令不同例如ST7701S通过命令C3h配置而GC9503则通过命令B0h配置两种模式的时序图差异如下两种模式的核心区别在于是否使用 DE 信号线以及消隐区blanking porch寄存器的配置要求对比如下模式是否使用 DE 信号线消隐区寄存器配置ESP 支持DE Mode使用无需配置支持SYNC Mode不使用需要配置支持DE 模式DE 信号为高电平期间表示有效像素数据主控只需按行列持续送数据即可HSYNC/VSYNC 相关参数可依据期望刷新率灵活调整SYNC 模式不使用 DE 线屏幕靠 HSYNC/VSYNC 同步信号定位行、帧边界此时消隐区参数必须与软件初始化命令中的配置保持一致否则画面会偏移。颜色格式RGB565 / RGB666 / RGB888多数 RGB LCD 支持多种色彩输入数据格式通常通过命令COLMOD (3Ah)配置。以ST7701S为例ST7701S支持三种颜色格式16-bit RGB565、18-bit RGB666和24-bit RGB888。其中N-bit表示接口的数据线数量通过COLMOD (3Ah): VIPF[2:0]与COLCTRL (CDh): MDT命令组合选择。关键约束命令配置必须与硬件接口一致。例如 LCD 模组只引出 18 根数据线时软件绝不可配置为24-bit RGB888若数据线为D[21:16], D[13:8], D[5:0]也只能配置为16-bit RGB565。此外颜色格式的位深不一定等于接口的有效数据线数量。以ST77903为例其接口类型选择与颜色格式配置如下ST77903支持三种颜色格式6-bit RGB565、6-bit RGB666和8-bit RGB888对应位深分别为 16-bit、18-bit、24-bit。多数 LCD 的 RGB 接口在一个时钟周期内并行传输单个像素的全部色彩数据而ST77903这类接口需要多个时钟周期才能传完一个像素因此被称为Serial RGB InterfaceSRGB串行 RGB 接口。ESP32-S3 的硬件限制与对策ESP32-S3 仅支持16-bit RGB565与8-bit RGB888两种颜色格式但通过特殊硬件接线可以驱动18-bit RGB666或24-bit RGB888格式的 LCD。连接细节可参考开发板ESP32-S3-LCD-EV-Board及其 LCD Subboard 23.95 LCD_QMZX与 LCD Subboard 3 的原理图。RGB LCD 驱动流程总览RGB LCD 的驱动流程大致分为三部分初始化接口设备创建 3-wire SPI 面板 IO用于向驱动 IC 发送命令/参数移植驱动组件基于 ESP-IDF 的 RGB 接口驱动封装出与目标驱动 IC 对应的 LCD 设备创建函数初始化 LCD 设备创建esp_lcd_panel_handle_t句柄并调用通用 API 完成初始化与显示。第一步初始化接口设备3-wire SPI对于3-wire SPI RGB类型的 LCD由于 ESP 的 SPI 外设不直接支持 9 位数据传输3-wire SPI 中每帧 1 位 DC 位 8 位数据而该接口仅用于传输命令和参数、数据量小、带宽与时序要求不高因此可以使用GPIO 或 IO 扩展芯片引脚通过软件模拟 SPI 协议。仓库中的 esp_lcd_panel_io_additions 组件正是为此设计。创建 3-wire SPI 接口设备的示例代码如下#include esp_check.h // Header file dependency #include esp_lcd_panel_io.h #include esp_lcd_panel_io_additions.h esp_lcd_panel_io_3wire_spi_config_t io_config { .line_config { .cs_io_type IO_TYPE_GPIO, // Set to IO_TYPE_EXPANDER to use IO expander pins; otherwise, use GPIO .cs_gpio_num EXAMPLE_LCD_IO_SPI_CS, // GPIO number connected to the LCD CS signal // .cs_expander_pin EXAMPLE_LCD_IO_SPI_CS, // Expander IO chip pin number connected to the LCD CS signal .scl_io_type IO_TYPE_GPIO, // Set to IO_TYPE_EXPANDER to use IO expander pins; otherwise, use GPIO .scl_gpio_num EXAMPLE_LCD_IO_SPI_SCK, // GPIO number connected to the LCD SCK (SCL) signal // .scl_expander_pin EXAMPLE_LCD_IO_SPI_SCK, // Expander IO chip pin number connected to the LCD SCK (SCL) signal .sda_io_type IO_TYPE_GPIO, // Set to IO_TYPE_EXPANDER to use IO expander pins; otherwise, use GPIO .sda_gpio_num EXAMPLE_LCD_IO_SPI_SDO, // GPIO number connected to the LCD MOSI (SDO, SDA) signal // .sda_expander_pin EXAMPLE_LCD_IO_SPI_SDO, // Expander IO chip pin number connected to the LCD MOSI (SDO, SDA) signal .io_expander NULL, // If using IO expander pins, pass the initialized device handle }, .expect_clk_speed PANEL_IO_3WIRE_SPI_CLK_MAX, // Expected SPI clock frequency; due to software simulation, there may be a significant error // Default set to PANEL_IO_3WIRE_SPI_CLK_MAX .spi_mode 0, // SPI mode (0-3); determine based on the LCD driver IC data sheet and hardware configuration (e.g., IM[3:0]) .lcd_cmd_bytes 1, // Number of bytes per LCD command (1-4); usually set to 1 .lcd_param_bytes 1, // Number of bytes per LCD parameter (1-4); usually set to 1 .flags { .use_dc_bit 1, // Default set to 1 .del_keep_cs_inactive 1, // Default set to 1 }, } esp_lcd_panel_io_handle_t io_handle NULL; ESP_ERROR_CHECK(esp_lcd_new_panel_io_3wire_spi(io_config, io_handle));从 esp_lcd_panel_io_additions.h 头文件可以看到各字段的约束expect_clk_speed期望 SPI 时钟Hz取值范围 1 ~PANEL_IO_3WIRE_SPI_CLK_MAX即 500 kHz若为 0 则默认取最大值由于基于软件延时模拟实际频率可能偏差较大lcd_cmd_bytes/lcd_param_bytes命令/参数字节数各为 1~4flags.use_dc_bit使能后在每个命令/数据前发送 DC 位flags.dc_zero_on_data可翻转 DC 位语义flags.lsb_first控制发送位序flags.cs_high_active控制 CS 有效电平flags.del_keep_cs_inactive控制删除面板 IO 时是否保持 CS 无效。底层实现esp_lcd_panel_io_3wire_spi.c中spi_write_byte()会先发 DC 位、再发 8 位数据spi_write_package()负责 CS 拉低/拉高、按字节组包借助SPI_SWAP_DATA_TX处理字节序并通过esp_rom_delay_us()/vTaskDelay()产生 SCL 半周期延时。值得注意的是该接口为只写实现rx_param、tx_color、register_event_callbacks均返回ESP_FAIL仅用于低速、只写的命令/参数下发场景如 RGB 屏初始化。纯 RGB 接口的 LCD由于不支持命令/参数传输无需初始化接口设备直接进入「初始化 LCD 设备」步骤。第二步移植驱动组件纯 RGB 接口的 LCDESP-IDF 的 RGB 接口驱动esp_lcd_new_rgb_panel()已通过注册回调实现了 esp_lcd_panel_t 结构体定义的全部功能应用层可直接用 LCD 通用 API 操作无需移植驱动组件。3-wire SPI RGB 接口的 LCD除 RGB 接口驱动外还需通过 3-wire SPI 发送命令/参数。实现驱动组件遵循三个基本点通过esp_lcd_panel_io_handle_t类型的接口设备按指定格式发送命令与参数用esp_lcd_new_rgb_panel()创建 LCD 设备后利用注册回调保存并覆写部分功能实现一个返回esp_lcd_panel_handle_t句柄的函数供应用层使用 LCD 通用 API。在 esp_lcd_st7701_rgb.c 中可以看到完整的保存-覆写实现模式创建面板时先保存 RGB 面板的init/del/reset/mirror/disp_on_off函数指针再将其替换为 ST7701 的包装实现panel_st7701_init等并通过user_data携带私有上下文。各函数与 RGB 接口驱动、LCD 通用 API 的对应关系如下函数RGB 接口驱动LCD 通用 API实现说明reset()rgb_panel_reset()esp_lcd_panel_reset()若连接复位引脚则硬件复位否则用命令LCD_CMD_SWRESET (01h)软复位最后用rgb_panel_reset()复位 RGB 接口init()rgb_panel_init()esp_lcd_panel_init()若 3-wire SPI 与 RGB 引脚不复用则先发送初始化命令序列若复用则在创建 LCD 时完成初始化最后rgb_panel_init()del()rgb_panel_del()esp_lcd_panel_del()释放驱动资源内存、IO并用rgb_panel_del()删除 RGB 接口draw_bitmap()rgb_panel_draw_bitmap()esp_lcd_panel_draw_bitmap()直接透传不保存覆写mirror()rgb_panel_mirror()esp_lcd_panel_mirror()按用户配置通过命令或rgb_panel_mirror()镜像 X/Y 轴swap_xy()rgb_panel_swap_xy()esp_lcd_panel_swap_xy()软件交换 X/Y 轴不保存覆写set_gap()rgb_panel_set_gap()esp_lcd_panel_set_gap()软件修改绘制起止坐标不保存覆写invert_color()rgb_panel_invert_color()esp_lcd_panel_invert_color()硬件逐位反转像素颜色0xF0F0 - 0x0F0F不保存覆写disp_on_off()rgb_panel_disp_on_off()esp_lcd_panel_disp_on_off()未配置disp_gpio_num时用命令LCD_CMD_DISON (29h)/LCD_CMD_DISOFF (28h)已配置时调用rgb_panel_disp_on_off()移植步骤适用于绝大多数 RGB LCD其驱动 IC 命令/参数与上述实现细节兼容在 lcd_development_guide.rst 的 LCD 驱动组件列表中挑选与目标型号相近的组件例如st7701、st77903_rgb、st77922、gc9503、nv3052等3-wire SPI RGB类组件对照目标驱动 IC 数据手册确认所选组件各函数使用的命令与参数是否一致不一致则修改相应代码即使驱动 IC 型号相同不同厂商的屏也常需各自的初始化命令序列因此要修改init()中发送的命令/参数——这些初始化命令通常以特定格式存放在静态数组中同时注意不要把由驱动 IC 管控的命令如LCD_CMD_COLMOD (3Ah)写入初始化命令以保证 LCD 设备能成功初始化用编辑器的全局替换功能将组件中的驱动 IC 型号名替换为目标型号例如把gc9503替换为st7701。ST7701 组件在发送初始化命令时还有一个细节见 esp_lcd_st7701_rgb.c 中panel_st7701_send_init_cmds()它会先通过CND2BKxSEL命令进入 Command2 Bank0随后发送MADCTL依据rgb_ele_order的 RGB/BGR 决定LCD_CMD_BGR_BIT与COLMOD依据bits_per_pixel映射16→0x50、18→0x60、24→0x70再依次执行厂商初始化序列若外部初始化序列中再次出现MADCTL/COLMOD会打印警告并覆写内部保存的值。第三步初始化 LCD 设备方式一使用 ESP-IDF 通用 RGB 面板以下示例参考 ESP-IDFrelease/v6.0的rgb_panel例程配置注释可直接对照 esp_lcd_st7701_rgb.c 与测试用例 test_esp_lcd_st7701_rgb.c 中的rgb_config#include esp_check.h // Dependent header file #include esp_lcd_panel_ops.h #include esp_lcd_panel_rgb.h esp_lcd_panel_handle_t panel_handle NULL; esp_lcd_rgb_panel_config_t panel_config { // Configuration parameters for the RGB interface .data_width EXAMPLE_LCD_DATA_WIDTH, // Data line width of the RGB interface, e.g., 16-bit RGB565: 16, 8-bit RGB888: 8 .bits_per_pixel EXAMPLE_LCD_BIT_PER_PIXEL, // Number of bits for the color format, may not be equal to the data line width of the RGB interface, // e.g., 16-bit RGB565: 16, 8-bit RGB888: 24 .psram_trans_align 64, // Set to 64 by default .num_fbs EXAMPLE_LCD_NUM_FB, // Number of frame buffers for the RGB interface, set to 1 by default, greater than 1 for multiple buffering to prevent tearing .bounce_buffer_size_px 10 * EXAMPLE_LCD_H_RES, // Used to increase the data transfer bandwidth of the RGB interface, usually set to 10 * EXAMPLE_LCD_H_RES .clk_src LCD_CLK_SRC_DEFAULT, // Set to LCD_CLK_SRC_DEFAULT by default .disp_gpio_num EXAMPLE_PIN_NUM_DISP_EN, // Pin number connected to the LCD DISP signal, can be set to -1 to disable .pclk_gpio_num EXAMPLE_PIN_NUM_PCLK, // Pin number connected to the LCD PCLK signal .vsync_gpio_num EXAMPLE_PIN_NUM_VSYNC, // Pin number connected to the LCD VSYNC signal .hsync_gpio_num EXAMPLE_PIN_NUM_HSYNC, // Pin number connected to the LCD HSYNC signal .de_gpio_num EXAMPLE_PIN_NUM_DE, // Pin number connected to the LCD DE signal, can be set to -1 to disable .data_gpio_nums { // Pin numbers connected to the LCD D[15:0] signals, the valid quantity is specified by data_width, // set to D[7:0] for 8-bit EXAMPLE_PIN_NUM_DATA0, EXAMPLE_PIN_NUM_DATA1, EXAMPLE_PIN_NUM_DATA2, EXAMPLE_PIN_NUM_DATA3, EXAMPLE_PIN_NUM_DATA4, EXAMPLE_PIN_NUM_DATA5, EXAMPLE_PIN_NUM_DATA6, EXAMPLE_PIN_NUM_DATA7, EXAMPLE_PIN_NUM_DATA8, EXAMPLE_PIN_NUM_DATA9, EXAMPLE_PIN_NUM_DATA10, EXAMPLE_PIN_NUM_DATA11, EXAMPLE_PIN_NUM_DATA12, EXAMPLE_PIN_NUM_DATA13, EXAMPLE_PIN_NUM_DATA14, EXAMPLE_PIN_NUM_DATA15, }, .timings { // The following are parameters related to RGB timing, which need to be determined based on the datasheet of the LCD driver IC and hardware configuration .pclk_hz EXAMPLE_LCD_PIXEL_CLOCK_HZ, .h_res EXAMPLE_LCD_H_RES, .v_res EXAMPLE_LCD_V_RES, .hsync_back_porch 40, // In DE mode, parameters related to HSYNC and VSYNC can be adjusted according to the desired refresh rate .hsync_front_porch 20, // In SYNC mode, parameters related to HSYNC and VSYNC need to be consistent with the configuration in the software initialization command .hsync_pulse_width 1, .vsync_back_porch 8, .vsync_front_porch 4, .vsync_pulse_width 1, .flags { // Since some LCDs can configure these parameters through hardware pins, make sure they are consistent with the configuration, but usually set to 0 .hsync_idle_low 0, // Level when the HSYNC signal is idle, 0: high level, 1: low level .vsync_idle_low 0, // Level when the VSYNC signal is idle, 0: high level, 1: low level .de_idle_high 0, // Level when the DE signal is idle, 0: high level, 1: low level .pclk_active_neg 0, // Effective edge of the clock signal, 0: rising edge, 1: falling edge .pclk_idle_high 0, // Level when the PCLK signal is idle, 0: high level, 1: low level }, }, .flags.fb_in_psram 1, // Set to 1 by default }; ESP_ERROR_CHECK(esp_lcd_new_rgb_panel(panel_config, panel_handle)); ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle)); ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle)); /* The following functions can be called as needed */ // ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true)); // Invert pixel color data bitwise through hardware (0xF0F0 - 0x0F0F) // ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, true, true)); // Mirror X and Y axes through software // ESP_ERROR_CHECK(esp_lcd_panel_swap_xy(panel_handle, true)); // Swap X and Y axes through software // ESP_ERROR_CHECK(esp_lcd_panel_set_gap(panel_handle, 0, 0)); // Modify the starting and ending coordinates for drawing through software to achieve drawing offset // ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true)); // Control the on/off of LCD display through the disp_gpio_num pin, // only available when the pin is set and not equal to -1, otherwise an error will be reported时序参数对应关系代码中的时序参数与 DE/SYNC 时序图中的符号一一对应代码参数名时序图符号说明hsync_back_porchThbp水平同步后肩hsync_front_porchThfp水平同步前肩hsync_pulse_widthThpw水平同步脉冲宽度代码参数名时序图符号说明vsync_back_porchTvbp垂直同步后肩vsync_front_porchTvfp垂直同步前肩vsync_pulse_widthTvs垂直同步脉冲宽度关于刷新率的计算esp_lcd_st7701.h 中的注释给出了参考公式refresh_rate (pclk_hz * data_width) / (h_res hsync_pulse_width hsync_back_porch hsync_front_porch) / (v_res vsync_pulse_width vsync_back_porch vsync_front_porch) / bits_per_pixel仓库中的ST7701_480_480_PANEL_60HZ_RGB_TIMING()宏即为一个 480×48060Hz 的现成时序模板pclk_hz 16 MHz、h_res/v_res 480各 porch 见宏定义可直接套用或修改。方式二使用移植的驱动组件ST7701 示例对于3-wire SPI RGB接口的 LCD先用移植好的驱动组件创建 LCD 设备再使用 LCD 通用 API 初始化。示例#include esp_check.h // Header file dependency #include esp_lcd_panel_ops.h #include esp_lcd_panel_rgb.h #include esp_lcd_panel_vendor.h #include esp_lcd_st7701.h // Header file for the target driver component /** * Holds initialization commands and parameters for the LCD driver IC */ // static const st7701_lcd_init_cmd_t lcd_init_cmds[] { // // cmd data data_size delay_ms // {0xFF, (uint8_t []){0x77, 0x01, 0x00, 0x00, 0x13}, 5, 0}, // {0xEF, (uint8_t []){0x08}, 1, 0}, // {0xFF, (uint8_t []){0x77, 0x01, 0x00, 0x00, 0x10}, 5, 0}, // {0xC0, (uint8_t []){0x3B, 0x00}, 2, 0}, // ... // }; /* Create LCD device */ esp_lcd_rgb_panel_config_t rgb_config { // Configuration parameters for the RGB interface .data_width EXAMPLE_LCD_DATA_WIDTH, // Data line width of the RGB interface, e.g., 16-bit RGB565: 16, 8-bit RGB888: 8 .bits_per_pixel EXAMPLE_LCD_BIT_PER_PIXEL, // Bit depth of the color format, may differ from the data line width of the RGB interface, // e.g., 16-bit RGB565: 16, 8-bit RGB888: 24 .psram_trans_align 64, // Set to 64 by default .num_fbs EXAMPLE_LCD_NUM_FB, // Number of frame buffers for the RGB interface, set to 1 by default, greater than 1 for multi-buffering to prevent tearing .bounce_buffer_size_px 10 * EXAMPLE_LCD_H_RES, // Used to improve data transfer bandwidth of the RGB interface, usually set to 10 * EXAMPLE_LCD_H_RES .clk_src LCD_CLK_SRC_DEFAULT, // Set to LCD_CLK_SRC_DEFAULT by default .disp_gpio_num EXAMPLE_PIN_NUM_DISP_EN, // Pin number for connecting the LCD DISP signal, set to -1 to indicate not using .pclk_gpio_num EXAMPLE_PIN_NUM_PCLK, // Pin number for connecting the LCD PCLK signal .vsync_gpio_num EXAMPLE_PIN_NUM_VSYNC, // Pin number for connecting the LCD VSYNC signal .hsync_gpio_num EXAMPLE_PIN_NUM_HSYNC, // Pin number for connecting the LCD HSYNC signal .de_gpio_num EXAMPLE_PIN_NUM_DE, // Pin number for connecting the LCD DE signal, set to -1 to indicate not using .data_gpio_nums { // Pin numbers for connecting LCD D[15:0] signals, the valid quantity is specified by data_width, // for 8-bit, set D[7:0] is enough EXAMPLE_PIN_NUM_DATA0, EXAMPLE_PIN_NUM_DATA1, EXAMPLE_PIN_NUM_DATA2, EXAMPLE_PIN_NUM_DATA3, EXAMPLE_PIN_NUM_DATA4, EXAMPLE_PIN_NUM_DATA5, EXAMPLE_PIN_NUM_DATA6, EXAMPLE_PIN_NUM_DATA7, EXAMPLE_PIN_NUM_DATA8, EXAMPLE_PIN_NUM_DATA9, EXAMPLE_PIN_NUM_DATA10, EXAMPLE_PIN_NUM_DATA11, EXAMPLE_PIN_NUM_DATA12, EXAMPLE_PIN_NUM_DATA13, EXAMPLE_PIN_NUM_DATA14, EXAMPLE_PIN_NUM_DATA15, }, .timings { // The following are parameters related to RGB timing, which need to be determined based on the data sheet of the LCD driver IC and the configuration of software and hardware .pclk_hz EXAMPLE_LCD_PIXEL_CLOCK_HZ, .h_res EXAMPLE_LCD_H_RES, .v_res EXAMPLE_LCD_V_RES, .hsync_back_porch 40, // In DE mode, parameters related to HSYNC and VSYNC can be adjusted according to the desired refresh rate .hsync_front_porch 20, // In SYNC mode, parameters related to HSYNC and VSYNC need to be consistent with the configuration in the software initialization command .hsync_pulse_width 1, .vsync_back_porch 8, .vsync_front_porch 4, .vsync_pulse_width 1, .flags { // Since some LCDs can configure these parameters through hardware pins or software commands, make sure they are consistent with the configuration, .hsync_idle_low 0, // Level of HSYNC signal when idle, 0: high level, 1: low level .vsync_idle_low 0, // Level of VSYNC signal when idle, 0 means high level, 1: low level .de_idle_high 0, // Level of DE signal when idle, 0: high level, 1: low level .pclk_active_neg 0, // Effective edge of the clock signal, 0: rising edge, 1: falling edge .pclk_idle_high 0, // Level of PCLK signal when idle, 0: high level, 1: low level }, }, .flags.fb_in_psram 1, // Set to 1 by default }; st7701_vendor_config_t vendor_config { .rgb_config rgb_config, // Configuration parameters for the RGB interface // .init_cmds lcd_init_cmds, // Used to replace the initialization commands and parameters in the driver component // .init_cmds_size sizeof(lcd_init_cmds) / sizeof(st7701_lcd_init_cmd_t), .flags { // Configuration parameters for the LCD driver IC .mirror_by_cmd 1, // If 1, use LCD command to implement mirroring function (esp_lcd_panel_mirror()), if 0, implement through software .enable_io_multiplex 0, // If 1, automatically delete the interface device when deleting the LCD device, all parameters named *_by_cmd should be set to 0, // if 0, do not delete. If the pins of the 3-wire SPI interface are multiplexed with the RGB interface, set this parameter to 1 }, }; const esp_lcd_panel_dev_config_t panel_config { .reset_gpio_num EXAMPLE_LCD_IO_RST, // IO number for connecting the LCD reset signal, set to -1 to indicate not using .rgb_ele_order LCD_RGB_ELEMENT_ORDER_RGB, // Element order of pixel color (RGB/BGR), // generally controlled by command LCD_CMD_MADCTL(36h) .bits_per_pixel EXAMPLE_LCD_BIT_PER_PIXEL, // Bit depth of the color format (RGB565: 16, RGB666: 18, RGB888: 24), // generally controlled by command LCD_CMD_COLMOD(3Ah) .vendor_config vendor_config, // Configuration parameters for the RGB interface and LCD driver IC }; esp_lcd_panel_handle_t panel_handle NULL; ESP_ERROR_CHECK(esp_lcd_new_panel_st7701(io_handle, panel_config, panel_handle)); /* Initialize LCD device */ ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle)); ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle)); // The following functions can be used as needed // ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true)); // ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, true, true)); // ESP_ERROR_CHECK(esp_lcd_panel_swap_xy(panel_handle, true)); // ESP_ERROR_CHECK(esp_lcd_panel_set_gap(panel_handle, 0, 0)); // ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true));关键配置项说明st7701_vendor_config_t必须通过vendor_config字段传入esp_lcd_panel_dev_config_t其定义见 esp_lcd_st7701.h.init_cmds允许用static const数组替换组件内置的初始化命令序列组件默认序列见 esp_lcd_st7701_rgb.c 中的vendor_specific_init_default每条命令由cmd / data / data_bytes / delay_ms组成.flags.mirror_by_cmd 1时esp_lcd_panel_mirror()通过 ST7701 的SDIR命令与MADCTL的ML位实现见panel_st7701_mirror()源码置 0 则走软件镜像.flags.enable_io_multiplex 1时创建设备阶段esp_lcd_new_panel_st7701()内部会先完成硬件/软件复位与初始化命令下发随后立即删除 3-wire SPI 接口设备以释放引脚SDA、SCK 可与 RGB 接口的 HSYNC 等引脚复用省 GPIO此时所有*_by_cmd标志必须置 0——这与测试用例 test_esp_lcd_st7701_rgb.c 中use_io_multiplex场景的line_configSCK/SDA 复用RGB_DATA14/15完全对应。该测试用例同时验证了三种驱动场景纯 GPIO 3-wire SPI、IO 扩展器TCA95543-wire SPI、以及IO 扩展器 引脚复用并通过esp_lcd_panel_mirror()/esp_lcd_panel_swap_xy()循环 8 次模拟屏幕 8 个旋转方向test st7701 to rotate with RGB interface可作为驱动移植后的自测模板。RGB 接口的刷屏原理与特殊功能函数esp_lcd_panel_draw_bitmap() 的刷新机制使用esp_lcd_panel_draw_bitmap()刷新 RGB LCD 图像时有两点需要理解该函数通过内存拷贝将图像数据更新到帧缓冲中——调用返回后帧缓冲数据即已更新而 RGB 接口本身通过DMA 从帧缓冲取数刷新屏幕这两个过程是异步的若传入参数color_data恰好是 RGB 接口的内部帧缓冲地址则不会执行上述内存拷贝而是直接把 RGB 接口的 DMA 传输地址切换到该缓冲地址从而在多帧缓冲场景下实现双缓冲/多缓冲切换即按需切换帧。RGB 接口专用功能函数除 LCD 通用 API 外RGB 接口驱动还提供若干专用函数见 ESP-IDF 的 esp_lcd_panel_rgb.hesp_lcd_rgb_panel_set_pclk()LCD 初始化后动态修改像素时钟频率esp_lcd_rgb_panel_restart()重置数据传输用于屏幕出现偏移时恢复正常显示esp_lcd_rgb_panel_get_frame_buffer()获取帧缓冲地址可用数量由配置参数num_fbs决定用于多缓冲防撕裂esp_lcd_rgb_panel_register_event_callbacks()注册各类事件回调示例如下static bool example_on_vsync_event(esp_lcd_panel_handle_t panel, const esp_lcd_rgb_panel_event_data_t *edata, void *user_ctx) { /* Perform some operations here */ return false; } static bool example_on_bounce_event(esp_lcd_panel_handle_t panel, const esp_lcd_rgb_panel_event_data_t *edata, void *user_ctx) { /* Perform some operations here */ return false; } esp_lcd_rgb_panel_event_callbacks_t cbs { .on_vsync example_on_vsync_event, // Callback function when a frame of image is refreshed .on_bounce_frame_finish example_on_bounce_event, // Callback function when a frame of image is transferred through the Bounce Buffer mechanism // Note that the RGB interface has not completed the transmission of this frame at this time }; ESP_ERROR_CHECK(esp_lcd_rgb_panel_register_event_callbacks(panel_handle, cbs, example_user_ctx));相关文档与驱动组件仓库内配套文档lcd_development_guide.rstLCD 驱动框架与组件清单、lcd_terms_table.rst术语表、spi_lcd.rstSPI 3/4-line 模式、lcd_screen_tearing.rst撕裂与多缓冲、mipi_dsi_lcd.rstMIPI-DSI驱动 IC 数据手册ST7701S、ST77903、GC9503见原文档「Related Documentation」一节仓库中可直接参考的驱动组件位于 components/display/lcdesp_lcd_st7701、esp_lcd_st77903_rgb、esp_lcd_st77922、esp_lcd_gc9503_mipi、esp_lcd_nv3052以及 3-wire SPI 接口组件 esp_lcd_panel_io_additions显示屏示例工程仓库examples/display/lcd目录下的各 LCD 驱动示例含sdkconfig.defaults与引脚宏定义可直接作为移植起点【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
RGB LCD 驱动实战指南：基于 esp-iot-solution 的接口模式、时序配置与驱动组件移植
RGB LCD 驱动实战指南基于 esp-iot-solution 的接口模式、时序配置与驱动组件移植【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solutionRGB LCD 是 ESP32-S3 / ESP32-P4 等高算力芯片驱动大尺寸、高分辨率屏幕的主流方案它通过并行 RGB 接口以 DMA 从帧缓冲持续刷屏无内置 GRAM 的驱动 IC 直接显示收到的色彩数据。本文以 rgb_lcd.rst 为主线系统讲解 SPIRGB 与纯 RGB 两种接口模式、DE/SYNC 时序模式、颜色格式选择并结合 esp-iot-solution 仓库中 esp_lcd_panel_io_additions 与 esp_lcd_st7701 的源码与测试用例完整演示「初始化接口设备 → 移植驱动组件 → 初始化 LCD 设备」三阶段流程。读完本文你将掌握从硬件连线到软件配置的完整 RGB LCD 驱动能力。术语约定文中会反复出现以下概念其标准定义可参考仓库中的 LCD 术语表LCD_Terms_TableGRAM驱动 IC 内置的显存Graphic RAM。RGB LCD 的驱动 IC 通常没有GRAM需由主控提供整帧帧缓冲。Porch消隐区帧画面四周的空白时序区域包括水平/垂直方向的前肩front porch与后肩back porch。PCLK像素时钟RGB 接口逐像素采样的节拍。HSYNC / VSYNC水平/垂直同步信号。DE数据使能Data Enable信号用于区分有效像素区与消隐区。接口模式SPIRGB 与纯 RGB大多数 RGB LCD 采用SPI RGB双接口模式通过SPI 接口发送命令来初始化 LCD配置驱动 IC 寄存器初始化后还可动态修改垂直/水平镜像等配置灵活性更高通过RGB 接口并行传输整帧色彩数据由 DMA 持续刷新屏幕。另有一类 RGB LCD只使用 RGB 接口无需发送初始化命令驱动方式更简单但代价是无法修改任何配置。驱动 IC 通过硬件引脚选择接口模式。以ST7701S为例其通过IM[3:0]引脚选择SPI RGB接口配置典型的选型为3-wire SPI RGB对应手册中的RGB9b_SPI(rise/fall)其中9b_SPI表示 SPI 接口的 3-line3-wire模式即通常所说的 3 线制rise/fall表示SCL信号的有效沿。rise为上升沿有效对应 SPI 模式 0/3fall为下降沿有效对应 SPI 模式 1/2。ST7701S的 SPI 与 RGB 接口引脚定义如下RGB 接口引脚命名规范为CS、SCK(SCL)、SDA(MOSI)、HSYNC、VSYNC、PCLK、DE、D[23:0]部分屏为D[17:0]或D[7:0]。提示RGB LCD 的硬件驱动框架双接口分工、PSRAM 帧缓冲可参考 lcd_development_guide.rst 中的lcd_hw_framework_rgb示意图以及 lcd_guide.rst 中的 lcd_connection_rgb 连接图。时序模式DE Mode 与 SYNC Mode对于使用SPI RGB接口的 LCD通常可通过命令将 RGB 接口配置为DE 模式或SYNC 模式。不同驱动 IC 使用的配置命令不同例如ST7701S通过命令C3h配置而GC9503则通过命令B0h配置两种模式的时序图差异如下两种模式的核心区别在于是否使用 DE 信号线以及消隐区blanking porch寄存器的配置要求对比如下模式是否使用 DE 信号线消隐区寄存器配置ESP 支持DE Mode使用无需配置支持SYNC Mode不使用需要配置支持DE 模式DE 信号为高电平期间表示有效像素数据主控只需按行列持续送数据即可HSYNC/VSYNC 相关参数可依据期望刷新率灵活调整SYNC 模式不使用 DE 线屏幕靠 HSYNC/VSYNC 同步信号定位行、帧边界此时消隐区参数必须与软件初始化命令中的配置保持一致否则画面会偏移。颜色格式RGB565 / RGB666 / RGB888多数 RGB LCD 支持多种色彩输入数据格式通常通过命令COLMOD (3Ah)配置。以ST7701S为例ST7701S支持三种颜色格式16-bit RGB565、18-bit RGB666和24-bit RGB888。其中N-bit表示接口的数据线数量通过COLMOD (3Ah): VIPF[2:0]与COLCTRL (CDh): MDT命令组合选择。关键约束命令配置必须与硬件接口一致。例如 LCD 模组只引出 18 根数据线时软件绝不可配置为24-bit RGB888若数据线为D[21:16], D[13:8], D[5:0]也只能配置为16-bit RGB565。此外颜色格式的位深不一定等于接口的有效数据线数量。以ST77903为例其接口类型选择与颜色格式配置如下ST77903支持三种颜色格式6-bit RGB565、6-bit RGB666和8-bit RGB888对应位深分别为 16-bit、18-bit、24-bit。多数 LCD 的 RGB 接口在一个时钟周期内并行传输单个像素的全部色彩数据而ST77903这类接口需要多个时钟周期才能传完一个像素因此被称为Serial RGB InterfaceSRGB串行 RGB 接口。ESP32-S3 的硬件限制与对策ESP32-S3 仅支持16-bit RGB565与8-bit RGB888两种颜色格式但通过特殊硬件接线可以驱动18-bit RGB666或24-bit RGB888格式的 LCD。连接细节可参考开发板ESP32-S3-LCD-EV-Board及其 LCD Subboard 23.95 LCD_QMZX与 LCD Subboard 3 的原理图。RGB LCD 驱动流程总览RGB LCD 的驱动流程大致分为三部分初始化接口设备创建 3-wire SPI 面板 IO用于向驱动 IC 发送命令/参数移植驱动组件基于 ESP-IDF 的 RGB 接口驱动封装出与目标驱动 IC 对应的 LCD 设备创建函数初始化 LCD 设备创建esp_lcd_panel_handle_t句柄并调用通用 API 完成初始化与显示。第一步初始化接口设备3-wire SPI对于3-wire SPI RGB类型的 LCD由于 ESP 的 SPI 外设不直接支持 9 位数据传输3-wire SPI 中每帧 1 位 DC 位 8 位数据而该接口仅用于传输命令和参数、数据量小、带宽与时序要求不高因此可以使用GPIO 或 IO 扩展芯片引脚通过软件模拟 SPI 协议。仓库中的 esp_lcd_panel_io_additions 组件正是为此设计。创建 3-wire SPI 接口设备的示例代码如下#include esp_check.h // Header file dependency #include esp_lcd_panel_io.h #include esp_lcd_panel_io_additions.h esp_lcd_panel_io_3wire_spi_config_t io_config { .line_config { .cs_io_type IO_TYPE_GPIO, // Set to IO_TYPE_EXPANDER to use IO expander pins; otherwise, use GPIO .cs_gpio_num EXAMPLE_LCD_IO_SPI_CS, // GPIO number connected to the LCD CS signal // .cs_expander_pin EXAMPLE_LCD_IO_SPI_CS, // Expander IO chip pin number connected to the LCD CS signal .scl_io_type IO_TYPE_GPIO, // Set to IO_TYPE_EXPANDER to use IO expander pins; otherwise, use GPIO .scl_gpio_num EXAMPLE_LCD_IO_SPI_SCK, // GPIO number connected to the LCD SCK (SCL) signal // .scl_expander_pin EXAMPLE_LCD_IO_SPI_SCK, // Expander IO chip pin number connected to the LCD SCK (SCL) signal .sda_io_type IO_TYPE_GPIO, // Set to IO_TYPE_EXPANDER to use IO expander pins; otherwise, use GPIO .sda_gpio_num EXAMPLE_LCD_IO_SPI_SDO, // GPIO number connected to the LCD MOSI (SDO, SDA) signal // .sda_expander_pin EXAMPLE_LCD_IO_SPI_SDO, // Expander IO chip pin number connected to the LCD MOSI (SDO, SDA) signal .io_expander NULL, // If using IO expander pins, pass the initialized device handle }, .expect_clk_speed PANEL_IO_3WIRE_SPI_CLK_MAX, // Expected SPI clock frequency; due to software simulation, there may be a significant error // Default set to PANEL_IO_3WIRE_SPI_CLK_MAX .spi_mode 0, // SPI mode (0-3); determine based on the LCD driver IC data sheet and hardware configuration (e.g., IM[3:0]) .lcd_cmd_bytes 1, // Number of bytes per LCD command (1-4); usually set to 1 .lcd_param_bytes 1, // Number of bytes per LCD parameter (1-4); usually set to 1 .flags { .use_dc_bit 1, // Default set to 1 .del_keep_cs_inactive 1, // Default set to 1 }, } esp_lcd_panel_io_handle_t io_handle NULL; ESP_ERROR_CHECK(esp_lcd_new_panel_io_3wire_spi(io_config, io_handle));从 esp_lcd_panel_io_additions.h 头文件可以看到各字段的约束expect_clk_speed期望 SPI 时钟Hz取值范围 1 ~PANEL_IO_3WIRE_SPI_CLK_MAX即 500 kHz若为 0 则默认取最大值由于基于软件延时模拟实际频率可能偏差较大lcd_cmd_bytes/lcd_param_bytes命令/参数字节数各为 1~4flags.use_dc_bit使能后在每个命令/数据前发送 DC 位flags.dc_zero_on_data可翻转 DC 位语义flags.lsb_first控制发送位序flags.cs_high_active控制 CS 有效电平flags.del_keep_cs_inactive控制删除面板 IO 时是否保持 CS 无效。底层实现esp_lcd_panel_io_3wire_spi.c中spi_write_byte()会先发 DC 位、再发 8 位数据spi_write_package()负责 CS 拉低/拉高、按字节组包借助SPI_SWAP_DATA_TX处理字节序并通过esp_rom_delay_us()/vTaskDelay()产生 SCL 半周期延时。值得注意的是该接口为只写实现rx_param、tx_color、register_event_callbacks均返回ESP_FAIL仅用于低速、只写的命令/参数下发场景如 RGB 屏初始化。纯 RGB 接口的 LCD由于不支持命令/参数传输无需初始化接口设备直接进入「初始化 LCD 设备」步骤。第二步移植驱动组件纯 RGB 接口的 LCDESP-IDF 的 RGB 接口驱动esp_lcd_new_rgb_panel()已通过注册回调实现了 esp_lcd_panel_t 结构体定义的全部功能应用层可直接用 LCD 通用 API 操作无需移植驱动组件。3-wire SPI RGB 接口的 LCD除 RGB 接口驱动外还需通过 3-wire SPI 发送命令/参数。实现驱动组件遵循三个基本点通过esp_lcd_panel_io_handle_t类型的接口设备按指定格式发送命令与参数用esp_lcd_new_rgb_panel()创建 LCD 设备后利用注册回调保存并覆写部分功能实现一个返回esp_lcd_panel_handle_t句柄的函数供应用层使用 LCD 通用 API。在 esp_lcd_st7701_rgb.c 中可以看到完整的保存-覆写实现模式创建面板时先保存 RGB 面板的init/del/reset/mirror/disp_on_off函数指针再将其替换为 ST7701 的包装实现panel_st7701_init等并通过user_data携带私有上下文。各函数与 RGB 接口驱动、LCD 通用 API 的对应关系如下函数RGB 接口驱动LCD 通用 API实现说明reset()rgb_panel_reset()esp_lcd_panel_reset()若连接复位引脚则硬件复位否则用命令LCD_CMD_SWRESET (01h)软复位最后用rgb_panel_reset()复位 RGB 接口init()rgb_panel_init()esp_lcd_panel_init()若 3-wire SPI 与 RGB 引脚不复用则先发送初始化命令序列若复用则在创建 LCD 时完成初始化最后rgb_panel_init()del()rgb_panel_del()esp_lcd_panel_del()释放驱动资源内存、IO并用rgb_panel_del()删除 RGB 接口draw_bitmap()rgb_panel_draw_bitmap()esp_lcd_panel_draw_bitmap()直接透传不保存覆写mirror()rgb_panel_mirror()esp_lcd_panel_mirror()按用户配置通过命令或rgb_panel_mirror()镜像 X/Y 轴swap_xy()rgb_panel_swap_xy()esp_lcd_panel_swap_xy()软件交换 X/Y 轴不保存覆写set_gap()rgb_panel_set_gap()esp_lcd_panel_set_gap()软件修改绘制起止坐标不保存覆写invert_color()rgb_panel_invert_color()esp_lcd_panel_invert_color()硬件逐位反转像素颜色0xF0F0 - 0x0F0F不保存覆写disp_on_off()rgb_panel_disp_on_off()esp_lcd_panel_disp_on_off()未配置disp_gpio_num时用命令LCD_CMD_DISON (29h)/LCD_CMD_DISOFF (28h)已配置时调用rgb_panel_disp_on_off()移植步骤适用于绝大多数 RGB LCD其驱动 IC 命令/参数与上述实现细节兼容在 lcd_development_guide.rst 的 LCD 驱动组件列表中挑选与目标型号相近的组件例如st7701、st77903_rgb、st77922、gc9503、nv3052等3-wire SPI RGB类组件对照目标驱动 IC 数据手册确认所选组件各函数使用的命令与参数是否一致不一致则修改相应代码即使驱动 IC 型号相同不同厂商的屏也常需各自的初始化命令序列因此要修改init()中发送的命令/参数——这些初始化命令通常以特定格式存放在静态数组中同时注意不要把由驱动 IC 管控的命令如LCD_CMD_COLMOD (3Ah)写入初始化命令以保证 LCD 设备能成功初始化用编辑器的全局替换功能将组件中的驱动 IC 型号名替换为目标型号例如把gc9503替换为st7701。ST7701 组件在发送初始化命令时还有一个细节见 esp_lcd_st7701_rgb.c 中panel_st7701_send_init_cmds()它会先通过CND2BKxSEL命令进入 Command2 Bank0随后发送MADCTL依据rgb_ele_order的 RGB/BGR 决定LCD_CMD_BGR_BIT与COLMOD依据bits_per_pixel映射16→0x50、18→0x60、24→0x70再依次执行厂商初始化序列若外部初始化序列中再次出现MADCTL/COLMOD会打印警告并覆写内部保存的值。第三步初始化 LCD 设备方式一使用 ESP-IDF 通用 RGB 面板以下示例参考 ESP-IDFrelease/v6.0的rgb_panel例程配置注释可直接对照 esp_lcd_st7701_rgb.c 与测试用例 test_esp_lcd_st7701_rgb.c 中的rgb_config#include esp_check.h // Dependent header file #include esp_lcd_panel_ops.h #include esp_lcd_panel_rgb.h esp_lcd_panel_handle_t panel_handle NULL; esp_lcd_rgb_panel_config_t panel_config { // Configuration parameters for the RGB interface .data_width EXAMPLE_LCD_DATA_WIDTH, // Data line width of the RGB interface, e.g., 16-bit RGB565: 16, 8-bit RGB888: 8 .bits_per_pixel EXAMPLE_LCD_BIT_PER_PIXEL, // Number of bits for the color format, may not be equal to the data line width of the RGB interface, // e.g., 16-bit RGB565: 16, 8-bit RGB888: 24 .psram_trans_align 64, // Set to 64 by default .num_fbs EXAMPLE_LCD_NUM_FB, // Number of frame buffers for the RGB interface, set to 1 by default, greater than 1 for multiple buffering to prevent tearing .bounce_buffer_size_px 10 * EXAMPLE_LCD_H_RES, // Used to increase the data transfer bandwidth of the RGB interface, usually set to 10 * EXAMPLE_LCD_H_RES .clk_src LCD_CLK_SRC_DEFAULT, // Set to LCD_CLK_SRC_DEFAULT by default .disp_gpio_num EXAMPLE_PIN_NUM_DISP_EN, // Pin number connected to the LCD DISP signal, can be set to -1 to disable .pclk_gpio_num EXAMPLE_PIN_NUM_PCLK, // Pin number connected to the LCD PCLK signal .vsync_gpio_num EXAMPLE_PIN_NUM_VSYNC, // Pin number connected to the LCD VSYNC signal .hsync_gpio_num EXAMPLE_PIN_NUM_HSYNC, // Pin number connected to the LCD HSYNC signal .de_gpio_num EXAMPLE_PIN_NUM_DE, // Pin number connected to the LCD DE signal, can be set to -1 to disable .data_gpio_nums { // Pin numbers connected to the LCD D[15:0] signals, the valid quantity is specified by data_width, // set to D[7:0] for 8-bit EXAMPLE_PIN_NUM_DATA0, EXAMPLE_PIN_NUM_DATA1, EXAMPLE_PIN_NUM_DATA2, EXAMPLE_PIN_NUM_DATA3, EXAMPLE_PIN_NUM_DATA4, EXAMPLE_PIN_NUM_DATA5, EXAMPLE_PIN_NUM_DATA6, EXAMPLE_PIN_NUM_DATA7, EXAMPLE_PIN_NUM_DATA8, EXAMPLE_PIN_NUM_DATA9, EXAMPLE_PIN_NUM_DATA10, EXAMPLE_PIN_NUM_DATA11, EXAMPLE_PIN_NUM_DATA12, EXAMPLE_PIN_NUM_DATA13, EXAMPLE_PIN_NUM_DATA14, EXAMPLE_PIN_NUM_DATA15, }, .timings { // The following are parameters related to RGB timing, which need to be determined based on the datasheet of the LCD driver IC and hardware configuration .pclk_hz EXAMPLE_LCD_PIXEL_CLOCK_HZ, .h_res EXAMPLE_LCD_H_RES, .v_res EXAMPLE_LCD_V_RES, .hsync_back_porch 40, // In DE mode, parameters related to HSYNC and VSYNC can be adjusted according to the desired refresh rate .hsync_front_porch 20, // In SYNC mode, parameters related to HSYNC and VSYNC need to be consistent with the configuration in the software initialization command .hsync_pulse_width 1, .vsync_back_porch 8, .vsync_front_porch 4, .vsync_pulse_width 1, .flags { // Since some LCDs can configure these parameters through hardware pins, make sure they are consistent with the configuration, but usually set to 0 .hsync_idle_low 0, // Level when the HSYNC signal is idle, 0: high level, 1: low level .vsync_idle_low 0, // Level when the VSYNC signal is idle, 0: high level, 1: low level .de_idle_high 0, // Level when the DE signal is idle, 0: high level, 1: low level .pclk_active_neg 0, // Effective edge of the clock signal, 0: rising edge, 1: falling edge .pclk_idle_high 0, // Level when the PCLK signal is idle, 0: high level, 1: low level }, }, .flags.fb_in_psram 1, // Set to 1 by default }; ESP_ERROR_CHECK(esp_lcd_new_rgb_panel(panel_config, panel_handle)); ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle)); ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle)); /* The following functions can be called as needed */ // ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true)); // Invert pixel color data bitwise through hardware (0xF0F0 - 0x0F0F) // ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, true, true)); // Mirror X and Y axes through software // ESP_ERROR_CHECK(esp_lcd_panel_swap_xy(panel_handle, true)); // Swap X and Y axes through software // ESP_ERROR_CHECK(esp_lcd_panel_set_gap(panel_handle, 0, 0)); // Modify the starting and ending coordinates for drawing through software to achieve drawing offset // ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true)); // Control the on/off of LCD display through the disp_gpio_num pin, // only available when the pin is set and not equal to -1, otherwise an error will be reported时序参数对应关系代码中的时序参数与 DE/SYNC 时序图中的符号一一对应代码参数名时序图符号说明hsync_back_porchThbp水平同步后肩hsync_front_porchThfp水平同步前肩hsync_pulse_widthThpw水平同步脉冲宽度代码参数名时序图符号说明vsync_back_porchTvbp垂直同步后肩vsync_front_porchTvfp垂直同步前肩vsync_pulse_widthTvs垂直同步脉冲宽度关于刷新率的计算esp_lcd_st7701.h 中的注释给出了参考公式refresh_rate (pclk_hz * data_width) / (h_res hsync_pulse_width hsync_back_porch hsync_front_porch) / (v_res vsync_pulse_width vsync_back_porch vsync_front_porch) / bits_per_pixel仓库中的ST7701_480_480_PANEL_60HZ_RGB_TIMING()宏即为一个 480×48060Hz 的现成时序模板pclk_hz 16 MHz、h_res/v_res 480各 porch 见宏定义可直接套用或修改。方式二使用移植的驱动组件ST7701 示例对于3-wire SPI RGB接口的 LCD先用移植好的驱动组件创建 LCD 设备再使用 LCD 通用 API 初始化。示例#include esp_check.h // Header file dependency #include esp_lcd_panel_ops.h #include esp_lcd_panel_rgb.h #include esp_lcd_panel_vendor.h #include esp_lcd_st7701.h // Header file for the target driver component /** * Holds initialization commands and parameters for the LCD driver IC */ // static const st7701_lcd_init_cmd_t lcd_init_cmds[] { // // cmd data data_size delay_ms // {0xFF, (uint8_t []){0x77, 0x01, 0x00, 0x00, 0x13}, 5, 0}, // {0xEF, (uint8_t []){0x08}, 1, 0}, // {0xFF, (uint8_t []){0x77, 0x01, 0x00, 0x00, 0x10}, 5, 0}, // {0xC0, (uint8_t []){0x3B, 0x00}, 2, 0}, // ... // }; /* Create LCD device */ esp_lcd_rgb_panel_config_t rgb_config { // Configuration parameters for the RGB interface .data_width EXAMPLE_LCD_DATA_WIDTH, // Data line width of the RGB interface, e.g., 16-bit RGB565: 16, 8-bit RGB888: 8 .bits_per_pixel EXAMPLE_LCD_BIT_PER_PIXEL, // Bit depth of the color format, may differ from the data line width of the RGB interface, // e.g., 16-bit RGB565: 16, 8-bit RGB888: 24 .psram_trans_align 64, // Set to 64 by default .num_fbs EXAMPLE_LCD_NUM_FB, // Number of frame buffers for the RGB interface, set to 1 by default, greater than 1 for multi-buffering to prevent tearing .bounce_buffer_size_px 10 * EXAMPLE_LCD_H_RES, // Used to improve data transfer bandwidth of the RGB interface, usually set to 10 * EXAMPLE_LCD_H_RES .clk_src LCD_CLK_SRC_DEFAULT, // Set to LCD_CLK_SRC_DEFAULT by default .disp_gpio_num EXAMPLE_PIN_NUM_DISP_EN, // Pin number for connecting the LCD DISP signal, set to -1 to indicate not using .pclk_gpio_num EXAMPLE_PIN_NUM_PCLK, // Pin number for connecting the LCD PCLK signal .vsync_gpio_num EXAMPLE_PIN_NUM_VSYNC, // Pin number for connecting the LCD VSYNC signal .hsync_gpio_num EXAMPLE_PIN_NUM_HSYNC, // Pin number for connecting the LCD HSYNC signal .de_gpio_num EXAMPLE_PIN_NUM_DE, // Pin number for connecting the LCD DE signal, set to -1 to indicate not using .data_gpio_nums { // Pin numbers for connecting LCD D[15:0] signals, the valid quantity is specified by data_width, // for 8-bit, set D[7:0] is enough EXAMPLE_PIN_NUM_DATA0, EXAMPLE_PIN_NUM_DATA1, EXAMPLE_PIN_NUM_DATA2, EXAMPLE_PIN_NUM_DATA3, EXAMPLE_PIN_NUM_DATA4, EXAMPLE_PIN_NUM_DATA5, EXAMPLE_PIN_NUM_DATA6, EXAMPLE_PIN_NUM_DATA7, EXAMPLE_PIN_NUM_DATA8, EXAMPLE_PIN_NUM_DATA9, EXAMPLE_PIN_NUM_DATA10, EXAMPLE_PIN_NUM_DATA11, EXAMPLE_PIN_NUM_DATA12, EXAMPLE_PIN_NUM_DATA13, EXAMPLE_PIN_NUM_DATA14, EXAMPLE_PIN_NUM_DATA15, }, .timings { // The following are parameters related to RGB timing, which need to be determined based on the data sheet of the LCD driver IC and the configuration of software and hardware .pclk_hz EXAMPLE_LCD_PIXEL_CLOCK_HZ, .h_res EXAMPLE_LCD_H_RES, .v_res EXAMPLE_LCD_V_RES, .hsync_back_porch 40, // In DE mode, parameters related to HSYNC and VSYNC can be adjusted according to the desired refresh rate .hsync_front_porch 20, // In SYNC mode, parameters related to HSYNC and VSYNC need to be consistent with the configuration in the software initialization command .hsync_pulse_width 1, .vsync_back_porch 8, .vsync_front_porch 4, .vsync_pulse_width 1, .flags { // Since some LCDs can configure these parameters through hardware pins or software commands, make sure they are consistent with the configuration, .hsync_idle_low 0, // Level of HSYNC signal when idle, 0: high level, 1: low level .vsync_idle_low 0, // Level of VSYNC signal when idle, 0 means high level, 1: low level .de_idle_high 0, // Level of DE signal when idle, 0: high level, 1: low level .pclk_active_neg 0, // Effective edge of the clock signal, 0: rising edge, 1: falling edge .pclk_idle_high 0, // Level of PCLK signal when idle, 0: high level, 1: low level }, }, .flags.fb_in_psram 1, // Set to 1 by default }; st7701_vendor_config_t vendor_config { .rgb_config rgb_config, // Configuration parameters for the RGB interface // .init_cmds lcd_init_cmds, // Used to replace the initialization commands and parameters in the driver component // .init_cmds_size sizeof(lcd_init_cmds) / sizeof(st7701_lcd_init_cmd_t), .flags { // Configuration parameters for the LCD driver IC .mirror_by_cmd 1, // If 1, use LCD command to implement mirroring function (esp_lcd_panel_mirror()), if 0, implement through software .enable_io_multiplex 0, // If 1, automatically delete the interface device when deleting the LCD device, all parameters named *_by_cmd should be set to 0, // if 0, do not delete. If the pins of the 3-wire SPI interface are multiplexed with the RGB interface, set this parameter to 1 }, }; const esp_lcd_panel_dev_config_t panel_config { .reset_gpio_num EXAMPLE_LCD_IO_RST, // IO number for connecting the LCD reset signal, set to -1 to indicate not using .rgb_ele_order LCD_RGB_ELEMENT_ORDER_RGB, // Element order of pixel color (RGB/BGR), // generally controlled by command LCD_CMD_MADCTL(36h) .bits_per_pixel EXAMPLE_LCD_BIT_PER_PIXEL, // Bit depth of the color format (RGB565: 16, RGB666: 18, RGB888: 24), // generally controlled by command LCD_CMD_COLMOD(3Ah) .vendor_config vendor_config, // Configuration parameters for the RGB interface and LCD driver IC }; esp_lcd_panel_handle_t panel_handle NULL; ESP_ERROR_CHECK(esp_lcd_new_panel_st7701(io_handle, panel_config, panel_handle)); /* Initialize LCD device */ ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle)); ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle)); // The following functions can be used as needed // ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true)); // ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, true, true)); // ESP_ERROR_CHECK(esp_lcd_panel_swap_xy(panel_handle, true)); // ESP_ERROR_CHECK(esp_lcd_panel_set_gap(panel_handle, 0, 0)); // ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true));关键配置项说明st7701_vendor_config_t必须通过vendor_config字段传入esp_lcd_panel_dev_config_t其定义见 esp_lcd_st7701.h.init_cmds允许用static const数组替换组件内置的初始化命令序列组件默认序列见 esp_lcd_st7701_rgb.c 中的vendor_specific_init_default每条命令由cmd / data / data_bytes / delay_ms组成.flags.mirror_by_cmd 1时esp_lcd_panel_mirror()通过 ST7701 的SDIR命令与MADCTL的ML位实现见panel_st7701_mirror()源码置 0 则走软件镜像.flags.enable_io_multiplex 1时创建设备阶段esp_lcd_new_panel_st7701()内部会先完成硬件/软件复位与初始化命令下发随后立即删除 3-wire SPI 接口设备以释放引脚SDA、SCK 可与 RGB 接口的 HSYNC 等引脚复用省 GPIO此时所有*_by_cmd标志必须置 0——这与测试用例 test_esp_lcd_st7701_rgb.c 中use_io_multiplex场景的line_configSCK/SDA 复用RGB_DATA14/15完全对应。该测试用例同时验证了三种驱动场景纯 GPIO 3-wire SPI、IO 扩展器TCA95543-wire SPI、以及IO 扩展器 引脚复用并通过esp_lcd_panel_mirror()/esp_lcd_panel_swap_xy()循环 8 次模拟屏幕 8 个旋转方向test st7701 to rotate with RGB interface可作为驱动移植后的自测模板。RGB 接口的刷屏原理与特殊功能函数esp_lcd_panel_draw_bitmap() 的刷新机制使用esp_lcd_panel_draw_bitmap()刷新 RGB LCD 图像时有两点需要理解该函数通过内存拷贝将图像数据更新到帧缓冲中——调用返回后帧缓冲数据即已更新而 RGB 接口本身通过DMA 从帧缓冲取数刷新屏幕这两个过程是异步的若传入参数color_data恰好是 RGB 接口的内部帧缓冲地址则不会执行上述内存拷贝而是直接把 RGB 接口的 DMA 传输地址切换到该缓冲地址从而在多帧缓冲场景下实现双缓冲/多缓冲切换即按需切换帧。RGB 接口专用功能函数除 LCD 通用 API 外RGB 接口驱动还提供若干专用函数见 ESP-IDF 的 esp_lcd_panel_rgb.hesp_lcd_rgb_panel_set_pclk()LCD 初始化后动态修改像素时钟频率esp_lcd_rgb_panel_restart()重置数据传输用于屏幕出现偏移时恢复正常显示esp_lcd_rgb_panel_get_frame_buffer()获取帧缓冲地址可用数量由配置参数num_fbs决定用于多缓冲防撕裂esp_lcd_rgb_panel_register_event_callbacks()注册各类事件回调示例如下static bool example_on_vsync_event(esp_lcd_panel_handle_t panel, const esp_lcd_rgb_panel_event_data_t *edata, void *user_ctx) { /* Perform some operations here */ return false; } static bool example_on_bounce_event(esp_lcd_panel_handle_t panel, const esp_lcd_rgb_panel_event_data_t *edata, void *user_ctx) { /* Perform some operations here */ return false; } esp_lcd_rgb_panel_event_callbacks_t cbs { .on_vsync example_on_vsync_event, // Callback function when a frame of image is refreshed .on_bounce_frame_finish example_on_bounce_event, // Callback function when a frame of image is transferred through the Bounce Buffer mechanism // Note that the RGB interface has not completed the transmission of this frame at this time }; ESP_ERROR_CHECK(esp_lcd_rgb_panel_register_event_callbacks(panel_handle, cbs, example_user_ctx));相关文档与驱动组件仓库内配套文档lcd_development_guide.rstLCD 驱动框架与组件清单、lcd_terms_table.rst术语表、spi_lcd.rstSPI 3/4-line 模式、lcd_screen_tearing.rst撕裂与多缓冲、mipi_dsi_lcd.rstMIPI-DSI驱动 IC 数据手册ST7701S、ST77903、GC9503见原文档「Related Documentation」一节仓库中可直接参考的驱动组件位于 components/display/lcdesp_lcd_st7701、esp_lcd_st77903_rgb、esp_lcd_st77922、esp_lcd_gc9503_mipi、esp_lcd_nv3052以及 3-wire SPI 接口组件 esp_lcd_panel_io_additions显示屏示例工程仓库examples/display/lcd目录下的各 LCD 驱动示例含sdkconfig.defaults与引脚宏定义可直接作为移植起点【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 方法：把已挂载组件转为 HTML 后用 Cheerio 断言)
