SOC-ESP32S3部分：31-ESP-LCD控制器库

小智学长 | 嵌入式2025-06-07 8:49

飞书文档https://x509p6c8to.feishu.cn/wiki/Syy3wsqHLiIiQJkC6PucEJ7Snib

ESP 系列芯片可以支持市场上常见的 LCD（如 SPI LCD、I2C LCD、并行 LCD (Intel 8080)、RGB/SRGB LCD、MIPI DSI LCD 等）所需的各种时序。esp_lcd 控制器为上述各类 LCD 提供了一个统一的抽象驱动框架。

更多支持的接口例程可以查看：esp-idf/examples/peripherals/lcd

在开发LCD类应用时，我们可以优先选择IDF自带了部分驱动，例如NT35510 SSD1306 ST7789，这部分驱动位于esp-idf/components/esp_lcd中，或者，我们也可以在组件库中查找，例如gc9a01

复制代码 
https://components.espressif.com/components?q=esp_lcd_gc9a01

这些驱动都是适配了esp_lcd控制器的，使用起来非常方便。

如果以上两个方法都找不到对应驱动呢？这时候就需要我们自己写了，有两种办法，

第一种是比较传统的，是把厂家提供的驱动文件，修改为ESP32的接口，例如SPI、IO相关的函数，这部分可以参考我们SPI课程中，使用SPI适配的ST7789屏幕驱动。

第二种是推荐大家用的，把驱动按esp_lcd框架的方式封装，找接近的芯片，更改部分参数即可，例如找不到ST7789的，我们可以找ST77916的，一般同一个厂家一系列的芯片，差异点只在初始化参数的不同。

复制代码 
https://components.espressif.com/components?q=esp_lcd_st

最终参考esp-idf/examples/peripherals/lcd/spi_lcd_touch实现的驱动：

步骤如下

  1. 初始化背光IO
  2. 初始化LCD的SPI配置
  3. 初始化其它显示IO
  4. 初始化ST7789驱动
  5. 设置屏幕显示方向颜色，打开背光
  6. 使用绘制函数绘制图像esp_lcd_panel_draw_bitmap

初始化背光IO

复制代码 
   gpio_config_t bk_gpio_config = {
       .mode = GPIO_MODE_OUTPUT, // 设置GPIO模式为输出
       .pin_bit_mask = 1ULL << EXAMPLE_PIN_NUM_BK_LIGHT // 设置背光控制引脚
   };
   ESP_ERROR_CHECK(gpio_config(&bk_gpio_config)); // 配置GPIO

初始化LCD的SPI配置

复制代码 
   spi_bus_config_t buscfg = {
       .sclk_io_num = EXAMPLE_PIN_NUM_SCLK, // SCLK引脚编号
       .mosi_io_num = EXAMPLE_PIN_NUM_MOSI, // MOSI引脚编号
       .miso_io_num = GPIO_NUM_NC,          // MISO引脚编号
       .quadwp_io_num = GPIO_NUM_NC,        // QUADWP引脚编号（未使用）
       .quadhd_io_num = GPIO_NUM_NC,        // QUADHD引脚编号（未使用）
       .max_transfer_sz = EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES * sizeof(uint16_t), // 最大传输大小
   };
   ESP_ERROR_CHECK(spi_bus_initialize(LCD_HOST, &buscfg, SPI_DMA_CH_AUTO)); // 初始化SPI总线

初始化其它显示IO

复制代码 
   ESP_LOGI(TAG, "Install panel 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 = 3, // SPI模式
       .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));

初始化ST7789驱动

复制代码 
   // 安装st7789面板驱动
   esp_lcd_panel_handle_t panel_handle = NULL;
   esp_lcd_panel_dev_config_t panel_config = {
       .reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST,  // 复位引脚编号
       .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, // RGB元素顺序
       .bits_per_pixel = 16,                       // 每像素位数
       .data_endian = LCD_RGB_DATA_ENDIAN_BIG,     // MSB
   };
   ESP_LOGI(TAG, "Install st7789 panel driver");
   ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));

设置屏幕显示方向颜色，打开背光

复制代码 
   // 复位和初始化面板
   ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle)); // 复位面板
   ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle)); // 初始化面板
   ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true)); // 反转颜色
   ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, true, false)); // 镜像显示（水平镜像）

   // 用户可以在点亮屏幕或背光之前刷新预定义的图案到屏幕上
   ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true)); // 打开屏幕显示
  
   // 打开LCD背光
   ESP_LOGI(TAG, "Turn on LCD backlight");
   gpio_set_level(EXAMPLE_PIN_NUM_BK_LIGHT, EXAMPLE_LCD_BK_LIGHT_ON_LEVEL); // 设置背光引脚电平

使用绘制函数绘制图像esp_lcd_panel_draw_bitmap

复制代码 
// 设置液晶屏颜色
void lcd_set_color(uint16_t color)
{
   // 分配内存 这里分配了液晶屏一行数据需要的大小
    uint16_t *buffer = (uint16_t *)heap_caps_malloc(EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES * sizeof(uint16_t), MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL);

    if (NULL == buffer)
    {
        ESP_LOGE(TAG, "Memory for bitmap is not enough");
    }
    else
    {
        for (size_t i = 0; i < EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES; i++) // 给缓存中放入颜色数据
        {
            buffer[i] = color;
        }
        esp_lcd_panel_draw_bitmap(panel_handle, 0 + X_OFFSET, 0, EXAMPLE_LCD_H_RES + X_OFFSET, EXAMPLE_LCD_V_RES, buffer);
        free(buffer); // 释放内存
    }
}

SPI屏幕

SPI屏幕使用的驱动芯片是ST7789，这个驱动芯片支持的分辨率是240*320，据厂家手册说明可知，由于是异形屏幕，屏幕的分辨率是172*320，所以驱动芯片左右两边分别有34列((240-172)/2) = 34是没有接到屏幕的，所以我们设置显示地址是，要偏移34列，屏幕接线部分如下：

|----------------------------------------------------------------------------|----------------------------------------------------------------------------|
| | |

从原理图可知：

复制代码 
SPI SCLK为GPIO_NUM_16
SPI MOSI为GPIO_NUM_17
SPI MISO不需要
LCD_DC为GPIO_NUM_21
LCD_RST为GPIO_NUM_18
LCD_CS为GPIO_NUM_15
背光IO为GPIO_NUM_2，背光有效电平为低电平

具体代码如下

复制代码 
#include <stdio.h>
#include <unistd.h>
#include <sys/lock.h>
#include <sys/param.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_lcd_panel_io.h"
#include "esp_lcd_panel_vendor.h"
#include "esp_lcd_panel_ops.h"
#include "driver/gpio.h"
#include "driver/spi_master.h"
#include "esp_err.h"
#include "esp_log.h"

static const char *TAG = "example";

// Using SPI2 in the example
#define LCD_HOST  SPI2_HOST


 Please update the following configuration according to your LCD spec //

#define EXAMPLE_LCD_PIXEL_CLOCK_HZ     (20 * 1000 * 1000)
#define EXAMPLE_LCD_BK_LIGHT_ON_LEVEL  0
#define EXAMPLE_LCD_BK_LIGHT_OFF_LEVEL !EXAMPLE_LCD_BK_LIGHT_ON_LEVEL

#define EXAMPLE_PIN_NUM_SCLK           GPIO_NUM_16
#define EXAMPLE_PIN_NUM_MOSI           GPIO_NUM_17
#define EXAMPLE_PIN_NUM_MISO           GPIO_NUM_NC
#define EXAMPLE_PIN_NUM_LCD_DC         GPIO_NUM_21
#define EXAMPLE_PIN_NUM_LCD_RST        GPIO_NUM_18
#define EXAMPLE_PIN_NUM_LCD_CS         GPIO_NUM_15
#define EXAMPLE_PIN_NUM_BK_LIGHT       GPIO_NUM_2

// The pixel number in horizontal and vertical
#define EXAMPLE_LCD_H_RES              172
// Bit number used to represent command and parameter
#define EXAMPLE_LCD_V_RES              320
#define EXAMPLE_LCD_CMD_BITS           8
#define EXAMPLE_LCD_PARAM_BITS         8

// 列地址偏移示例（假设X起始偏移为0，Y起始偏移为40）
#define X_OFFSET 34
#define Y_OFFSET 0
#define Y_OFFSET_NUM 0

esp_lcd_panel_handle_t panel_handle = NULL;

typedef struct {
    int cmd;                /*<! The specific LCD command */
    const void *data;       /*<! Buffer that holds the command specific data */
    size_t data_bytes;      /*<! Size of `data` in memory, in bytes */
    unsigned int delay_ms;  /*<! Delay in milliseconds after this command */
} st7789_lcd_init_cmd_t;

typedef struct {
    const st7789_lcd_init_cmd_t *init_cmds;   
    uint16_t init_cmds_size;    /*<! Number of commands in above array */
    struct {
        unsigned int use_qspi_interface: 1;     /*<! Set to 1 if use QSPI interface, default is SPI interface */
    } flags;
} st7789_vendor_config_t;

static const st7789_lcd_init_cmd_t lcd_init_cmds [] ={
    /* {cmd, { data }, data_size, delay_ms} "*/
    // {0x2A, (uint8_t []){0x00, X_OFFSET, 0x00, 0xEF - X_OFFSET}, 4, 0}, // 列地址 0~171 (0xAB = 171)
    // {0x2B, (uint8_t []){0x00, Y_OFFSET, 0x01, 0x3F - Y_OFFSET}, 4, 0}, // 行地址 0~319
    {0x11, (uint8_t []){0x00}, 0, 0},
    {0x36, (uint8_t []){0x00}, 1, 0},
    {0x3A, (uint8_t []){0x05}, 1, 0},
    {0xB2, (uint8_t []){0x0C, 0x0C, 0x00, 0x33, 0x33}, 5, 0},
    {0xB7, (uint8_t []){0x35}, 1, 0},
    {0xBB, (uint8_t []){0x35}, 1, 0},
    {0xC0, (uint8_t []){0x2C}, 1, 0},
    {0xC2, (uint8_t []){0x01}, 1, 0},
    {0xC3, (uint8_t []){0x13}, 1, 0},
    {0xC4, (uint8_t []){0x20}, 1, 0},
    {0xC6, (uint8_t []){0x0F}, 1, 0},
    {0xD0, (uint8_t []){0xA4, 0xA1}, 2, 0},
    {0xD6, (uint8_t []){0xA1}, 1, 0},
    {0xE0, (uint8_t []){0xF0, 0x00, 0x04, 0x04, 0x04, 0x05, 0x29, 0x33, 0x3e, 0x38, 0x12, 0x12, 0x28, 0x30}, 14, 0},
    {0xE1, (uint8_t []){0xF0, 0x07, 0x0A, 0x0D, 0x0b, 0x07, 0x28, 0x33, 0x3e, 0x36, 0x14, 0x14, 0x29, 0x32}, 14, 0},
    {0x21, (uint8_t []){0x00}, 0, 0},
    {0x11, (uint8_t []){0x00}, 0, 120},
    {0x29, (uint8_t []){0x00}, 0, 0},
};

// 设置液晶屏颜色
void lcd_set_color(uint16_t color)
{
   // 分配内存 这里分配了液晶屏一行数据需要的大小
    uint16_t *buffer = (uint16_t *)heap_caps_malloc(EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES * sizeof(uint16_t), MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL);

    if (NULL == buffer)
    {
        ESP_LOGE(TAG, "Memory for bitmap is not enough");
    }
    else
    {
        for (size_t i = 0; i < EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES; i++) // 给缓存中放入颜色数据
        {
            buffer[i] = color;
        }
        esp_lcd_panel_draw_bitmap(panel_handle, 0 + X_OFFSET, 0, EXAMPLE_LCD_H_RES + X_OFFSET, EXAMPLE_LCD_V_RES, buffer);
        free(buffer); // 释放内存
    }
}

void app_main(void)
{

   // 关闭LCD背光
   ESP_LOGI(TAG, "Turn off LCD backlight");
   gpio_config_t bk_gpio_config = {
       .mode = GPIO_MODE_OUTPUT, // 设置GPIO模式为输出
       .pin_bit_mask = 1ULL << EXAMPLE_PIN_NUM_BK_LIGHT // 设置背光控制引脚
   };
   ESP_ERROR_CHECK(gpio_config(&bk_gpio_config)); // 配置GPIO

   // 初始化SPI总线
   ESP_LOGI(TAG, "Initialize SPI bus");
   spi_bus_config_t buscfg = {
       .sclk_io_num = EXAMPLE_PIN_NUM_SCLK, // SCLK引脚编号
       .mosi_io_num = EXAMPLE_PIN_NUM_MOSI, // MOSI引脚编号
       .miso_io_num = GPIO_NUM_NC,          // MISO引脚编号
       .quadwp_io_num = GPIO_NUM_NC,        // QUADWP引脚编号（未使用）
       .quadhd_io_num = GPIO_NUM_NC,        // QUADHD引脚编号（未使用）
       .max_transfer_sz = EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES * sizeof(uint16_t), // 最大传输大小
   };
   ESP_ERROR_CHECK(spi_bus_initialize(LCD_HOST, &buscfg, SPI_DMA_CH_AUTO)); // 初始化SPI总线

   // 安装面板IO
   ESP_LOGI(TAG, "Install panel 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 = 3, // SPI模式
       .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));

   st7789_vendor_config_t vendor_config = {  // 用于替换驱动组件中的初始化命令及参数
    .init_cmds = lcd_init_cmds,
    .init_cmds_size = sizeof(lcd_init_cmds) / sizeof(st7789_lcd_init_cmd_t),
    };

   esp_lcd_panel_dev_config_t panel_config = {
       .reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST,  // 复位引脚编号
       .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, // RGB元素顺序
       .bits_per_pixel = 16,                       // 每像素位数
       .data_endian = LCD_RGB_DATA_ENDIAN_BIG,     // MSB
       .vendor_config = &vendor_config,           // 用于替换驱动组件中的初始化命令及参数
   };
   ESP_LOGI(TAG, "Install ST7789 panel driver");
   ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));
   // 复位和初始化面板
   ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle)); // 复位面板
   ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle)); // 初始化面板
   ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true)); // 反转颜色
   ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, false, false)); // 镜像显示（水平镜像）

   // 用户可以在点亮屏幕或背光之前刷新预定义的图案到屏幕上
   ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true)); // 打开屏幕显示

   // 打开LCD背光
   ESP_LOGI(TAG, "Turn on LCD backlight");
   gpio_set_level(EXAMPLE_PIN_NUM_BK_LIGHT, EXAMPLE_LCD_BK_LIGHT_ON_LEVEL); // 设置背光引脚电平

   while(1){
    lcd_set_color(0xFFFF);
    vTaskDelay(1000 / portTICK_PERIOD_MS);
    ESP_LOGI(TAG, "lcd_set_color switch");
    lcd_set_color(0x001F);
    vTaskDelay(1000 / portTICK_PERIOD_MS);
    ESP_LOGI(TAG, "lcd_set_color switch");
   }
}

如果编译报错fatal error: esp_lcd_panel_io.h: No such file or directory

需要在main/CMakeLists.txt中添加esp_lcd组件

复制代码 
idf_component_register(SRCS "main.c"
                    PRIV_REQUIRES esp_lcd
                    INCLUDE_DIRS "")
相关推荐
想搞嵌入式的小白33 分钟前
STM32外设问题总结
单片机·嵌入式硬件
木子单片机2 小时前
基于STM32语音识别柔光台灯
stm32·单片机·嵌入式硬件·proteus·语音识别·keil
广药门徒2 小时前
澄清 STM32 NVIC 中断优先级
单片机·嵌入式硬件
远创智控研发五部3 小时前
边缘计算网关提升水产养殖尾水处理的远程运维效率
物联网·远程监控·工业自动化·边缘计算网关·无线数传模块
小禾苗_3 小时前
32单片机——窗口看门狗
单片机·嵌入式硬件
小灰灰搞电子3 小时前
单片机0-10V电压输出电路分享
单片机·嵌入式硬件
Moonnnn.5 小时前
【单片机期末】串行口循环缓冲区发送
笔记·单片机·嵌入式硬件·学习
Despacito0o8 小时前
MQTT入门实战宝典：从零起步掌握物联网核心通信协议
物联网·struts·servlet
大河qu10 小时前
IoT/HCIP实验-3/LiteOS操作系统内核实验(任务、内存、信号量、CMSIS..)
ide·物联网·liteos·liteos studio·cmsis接口
小智学长 | 嵌入式10 小时前
SOC-ESP32S3部分：26-物联网MQTT连云
单片机·物联网·esp32
热门推荐
01基于STM32的智能电池管理系统02KGG转MP3工具|非KGM文件|解密音频03YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】04【无人机】无人机通信模块，无人机图数传模块的介绍，数传，图传，图传数传一体电台，05从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑06【SpeedAI科研小助手】2分钟极速解决知网维普重复率、AIGC率过高，一键全文降！文件格式不变，公式都保留的！07VMware虚拟机安装Win7专业版保姆级教程（附镜像包）08DeepSeek各版本说明与优缺点分析09组基轨迹建模 GBTM的介绍与实现（Stata 或 R）10海康Visionmaster-常见问题排查方法-启动阶段