1. 创建 SPI 总线。详情请参阅 SPI 主机 API 文档

    spi_bus_config_t buscfg = {
        .sclk_io_num = EXAMPLE_PIN_NUM_SCLK,
        .mosi_io_num = EXAMPLE_PIN_NUM_MOSI,
        .miso_io_num = EXAMPLE_PIN_NUM_MISO,
        .quadwp_io_num = -1, // 目前不支持 Quad SPI LCD 驱动
        .quadhd_io_num = -1, // 目前不支持 Quad SPI LCD 驱动
        .max_transfer_sz = EXAMPLE_LCD_H_RES * 80 * sizeof(uint16_t), // 单次最多可传输 80 行像素(假设像素格式为 RGB565)
    ESP_ERROR_CHECK(spi_bus_initialize(LCD_HOST, &buscfg, SPI_DMA_CH_AUTO)); // 启用 DMA
  2. 从 SPI 总线分配一个 LCD IO 设备句柄。在此步骤中,需要提供以下信息:

    esp_lcd_panel_io_handle_t io_handle = NULL;
    esp_lcd_panel_io_spi_config_t io_config = {
        .dc_gpio_num = EXAMPLE_PIN_NUM_LCD_DC,
        .cs_gpio_num = EXAMPLE_PIN_NUM_LCD_CS,
        .pclk_hz = EXAMPLE_LCD_PIXEL_CLOCK_HZ,
        .lcd_cmd_bits = EXAMPLE_LCD_CMD_BITS,
        .lcd_param_bits = EXAMPLE_LCD_PARAM_BITS,
        .spi_mode = 0,
        .trans_queue_depth = 10,
    // 将 LCD 连接到 SPI 总线
    ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)LCD_HOST, &io_config, &io_handle));
  3. 安装 LCD 控制器驱动程序。LCD 控制器驱动程序负责向 LCD 控制器芯片发送命令和参数。在此步骤中,需要指定上一步骤中分配到的 SPI IO 设备句柄以及一些面板特定配置:

    • esp_lcd_panel_dev_config_t::reset_gpio_num 设置 LCD 的硬件复位 GPIO 编号。如果 LCD 没有硬件复位管脚,则将此设置为 -1

    • esp_lcd_panel_dev_config_t::rgb_ele_order 设置每个颜色数据的 RGB 元素顺序。

    • esp_lcd_panel_dev_config_t::bits_per_pixel 设置像素颜色数据的位宽。LCD 驱动程序使用此值计算要发送到 LCD 控制器芯片的字节数。

    • esp_lcd_panel_dev_config_t::data_endian 指定传输到屏幕的数据的字节序。不超过一字节的颜色格式(如 RGB232)不需要指定数据字节序。若驱动程序不支持指定数据字节序,则将忽略此字段。

    esp_lcd_panel_handle_t panel_handle = NULL;
    esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
        .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_BGR,
        .bits_per_pixel = 16,
    // 为 ST7789 创建 LCD 面板句柄,并指定 SPI IO 设备句柄
    ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));

API 参考

Header File

  • components/esp_lcd/include/esp_lcd_io_spi.h

  • This header file can be included with:

    #include "esp_lcd_io_spi.h"
  • This header file is a part of the API provided by the esp_lcd component. To declare that your component depends on esp_lcd, add the following to your CMakeLists.txt:

    REQUIRES esp_lcd


    PRIV_REQUIRES esp_lcd


esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t bus, const esp_lcd_panel_io_spi_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io)

Create LCD panel IO handle, for SPI interface.

  • bus -- [in] SPI bus handle

  • io_config -- [in] IO configuration, for SPI interface

  • ret_io -- [out] Returned IO handle


  • ESP_ERR_INVALID_ARG if parameter is invalid

  • ESP_ERR_NO_MEM if out of memory

  • ESP_OK on success


struct esp_lcd_panel_io_spi_config_t

Panel IO configuration structure, for SPI interface.

Public Members

int cs_gpio_num

GPIO used for CS line

int dc_gpio_num

GPIO used to select the D/C line, set this to -1 if the D/C line is not used

int spi_mode

Traditional SPI mode (0~3)

unsigned int pclk_hz

Frequency of pixel clock

size_t trans_queue_depth

Size of internal transaction queue

esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done

Callback invoked when color data transfer has finished

void *user_ctx

User private data, passed directly to on_color_trans_done's user_ctx

int lcd_cmd_bits

Bit-width of LCD command

int lcd_param_bits

Bit-width of LCD parameter

unsigned int dc_high_on_cmd

If enabled, DC level = 1 indicates command transfer

unsigned int dc_low_on_data

If enabled, DC level = 0 indicates color data transfer

unsigned int dc_low_on_param

If enabled, DC level = 0 indicates parameter transfer

unsigned int octal_mode

transmit with octal mode (8 data lines), this mode is used to simulate Intel 8080 timing

unsigned int quad_mode

transmit with quad mode (4 data lines), this mode is useful when transmitting LCD parameters (Only use one line for command)

unsigned int sio_mode

Read and write through a single data line (MOSI)

unsigned int lsb_first

transmit LSB bit first

unsigned int cs_high_active

CS line is high active

struct esp_lcd_panel_io_spi_config_t::[anonymous] flags

Extra flags to fine-tune the SPI device

Type Definitions

typedef int esp_lcd_spi_bus_handle_t

Type of LCD SPI bus handle