ESP32-S3驱动CST328与ST7789，LVGL触摸屏实战指南

简介：面向嵌入式软件开发者的完整示例工程，基于乐鑫 ESP32-S3 微控制器，驱动 CST328 触摸控制芯片与 ST7789 彩色显示屏，配合官方 ESP-IDF 开发框架和 LVGL 开源图形库，实现从屏幕点亮、触摸响应到复杂界面展示的完整流程。适合正在学习嵌入式图形界面开发、需要快速完成显示方案验证的开发者。压缩包内共有 1342 个文件，主要包括 C 语言源文件、C 头文件、Python 辅助脚本、Markdown 说明文档、PNG 与 GIF 图片素材、字体资源、配置文件等，压缩后大小约 26.45MB，目录组织清楚，便于按模块查阅。目前该资源已有 1465 人学习下载。例程具体展示了 SPI 外设初始化、LVGL 环境配置、触摸驱动适配、控件布局与事件处理等关键环节，并附带多组演示画面和可复用素材，能够帮助用户理解嵌入式 GUI 底层工作原理，快速迁移至智能仪器仪表、自助终端、智能家居面板等实际项目，有效降低重复移植成本。

1. ESP32-S3 驱动 CST328 与 ST7789：LVGL 从模拟器到真机的第一道坎

用 ESP32-S3 驱动 CST328 触摸和 ST7789 屏幕，再把 LVGL 跑起来，这组合看着简单，真上手全是坑。lvgl esp32 在模拟器里零成本，到了真机，SPI 时序、I2C 寄存器、缓冲策略全变成拦路虎，黑屏、坐标乱跳、刷新撕裂会轮着教你做人。

这套 ESP32S3 驱动 CST328、ST7789 的例程，解决的就是「模拟器能跑、真机点不亮」的断层：ST7789 走 SPI 出画面，CST328 走 I2C 回触摸坐标，再用 LVGL 的 flush 和 read 两个回调合成完整的触摸 UI。适合手里有一块 240x240 或 240x320 屏、想用 ESP-IDF 正经做界面的开发者，也适合刚焊好第一块屏的人照着抄。

2. 硬件与工程结构：CST328 的 I2C、ST7789 的 SPI 与 ESP-IDF 组件骨架

2.1 接口速览：一块触摸屏模组里的两条总线

先别急着写代码，把模组拆开看总线关系。市面上常见的带触摸的 ST7789 模组，内部是两颗独立的 die：一颗 ST7789 驱动 TFT 面板，一颗 CST328 负责电容触摸，两者共用供电，但对外引出的是完全独立的两组总线。显示走 SPI，触摸走 I2C，互不干扰，这在电路设计上是好事，两路可以各自调试，显示挂了不影响触摸自检。

为什么显示不走并口？8080 并口要占十几根 GPIO，ESP32-S3 引脚虽然不算少，但一块产品板的 GPIO 往往还要挂传感器、按键、串口调试，SPI 四根线是最经济的方案。触摸用 I2C 同理，两根线搞定，而且 CST328 这类触摸 IC 对 I2C 的支持非常成熟，寄存器简单、时序宽容度也好。

CST328 默认 7 位 I2C 地址常见为 0x15，具体以模组原理图为准，有些屏厂会通过外部引脚电平把地址改成 0x2A。它支持多点触摸，但 LVGL 是单指针 UI 框架，绝大多数例程只取第一点，读一次 7 个字节就能拿到坐标和按压状态。寄存器布局各家手册措辞不同，但核心套路一致：0x00 是状态字节，低 4 位是触点数量，后面跟着第一点的 X/Y 坐标。

还有一个细节：CST328 带了手势寄存器，能上报上滑、下滑之类的方向事件，LVGL 用不上，因为 LVGL 自带手势识别。我的建议是别让 LVGL 和触摸 IC 两边同时做手势判断，否则一个滑动会触发两次响应，例程里只读坐标，不做手势层的重复劳动。

ST7789 是 240x320 的 TFT 驱动 IC，这套例程用到的分辨率是 240x240 或 240x320 中的一个区域。它支持 3 线/4 线 SPI，4 线就是标准的 CS、SCLK、MOSI 加一根 DC 数据/命令切换线，外加复位和背光。颜色深度用 16 位 RGB565 时，一帧数据是宽乘高乘 2 字节，240x240 全屏要 115200 字节，这个量直接决定了后续缓冲区怎么安排。

供电要留意：两颗 IC 都是 3.3V 逻辑，但不少模组的背光走独立引脚，有高电平点亮也有低电平点亮，接反不烧东西，只是背光不亮，容易被误判成屏幕坏了。触摸的 SDA/SCL 还必须有上拉电阻，很多模组内部没做，不补上拉就等着间歇性失灵。

2.2 工程骨架：ESP-IDF 5.x 的组件目录与板级配置文件

这套例程基于 ESP-IDF 5.x，工程结构长这样：

project/ ├── CMakeLists.txt ├── sdkconfig ├── main/ │ ├── CMakeLists.txt │ ├── idf_component.yml │ ├── board_cfg.h # 引脚和分辨率定义，改板子只动这一处 │ ├── st7789_lcd.c # 显示初始化与 LVGL flush │ ├── cst328_touch.c # 触摸读取与 LVGL read │ └── main.c # 应用入口

关键在idf_component.yml，用 ESP-IDF 的组件管理器拉 LVGL，不需要手动往工程里塞源码：

dependencies: lvgl/lvgl: "^8.3.0"

版本决策要提前做：LVGL 8 和 9 的 API 差得很大，flush 回调签名、draw_buf 初始化方式都变了。例程按 8.3 写，因为 8.x 资料最多、踩坑案例最全，屏厂发布的参考驱动基本围着 8.x 做。如果你新开项目想用 9.x，回调这块大概率要重写，不建议边学边迁移。

LVGL 作为托管组件装好后，色深、内存池大小等配置项会出现在menuconfig里，不用手改lv_conf.h。默认内存池对复杂界面偏小，我一般调到 16KB 以上，不然控件一多就开始拒绝分配内存，现象是 UI 画到一半缺块，串口报lv_mem相关错误。

板级配置单独放头文件的好处，是换屏时只改一处：

#define PANEL_WIDTH 240 #define PANEL_HEIGHT 240 #define PANEL_SWAP_XY true #define CST328_I2C_ADDR 0x15 #define PIN_LCD_SCLK 12 #define PIN_LCD_MOSI 11 #define PIN_LCD_CS 10 #define PIN_LCD_DC 9 #define PIN_LCD_RST 8 #define PIN_LCD_BL 7 #define PIN_TOUCH_SDA 4 #define PIN_TOUCH_SCL 5 #define PIN_TOUCH_INT 6

建议在board_cfg.h里加一个编译期检查：分辨率超过屏幕物理尺寸直接报错，防止换屏时只改了宽高、忘了改触摸变换公式，这种隐性 bug 排查起来特别费时。

2.3 驱动路线怎么选：esp_lcd 官方组件 vs 裸寄存器驱动

在 ESP-IDF 5.x 下驱动 ST7789，有两条路。

第一条用官方esp_lcd组件。它内置esp_lcd_new_panel_st7789()，初始化、交换坐标、镜像翻转都是现成接口，LVGL 官方移植组件esp_lvgl_port也基于它封装，代码量最少，排错容易。缺点是把 ST7789 的命令序列封了一层，屏厂魔改过的初始化代码不好塞进去，个别冷门屏会不兼容。

第二条是自己写 SPI 初始化序列，照着手册把 Power_On、SLPOUT、COLMOD、DISPON 一条条发出去，再直接对接 LVGL 的 flush 回调。优点是完全可控，任何屏都能救回来；缺点是要处理 DMA、字节序、同步，工作量比第一条大一个量级。

我的建议很直接：除非手里是一块大厂魔改初始化时序的特殊屏，否则一律走 esp_lcd 路线。CST328 没有官方驱动，触摸部分两边工作量差不多，触摸读取必须自己写，但没必要为了证明技术能力把显示也裸写一遍。esp_lvgl_port组件内部把 SPI 异步传输和 LVGL 缓冲回收做了同步封装，相当于把后面要讲的时序竞争提前处理好了，不想操心 flush 细节就用它。

3. 动手实现：SPI 初始化、CST328 读取与 LVGL 双回调对接

3.1 初始化 SPI 总线和 ST7789：pclk、位宽与扫描方向

显示链路第一步是初始化 SPI 总线。SPI 总线上可能同时挂 SD 卡或其他外设，这里单独给 LCD 分配一个 host，避免 DMA 队列互相干扰：

#include "driver/spi_master.h" #include "esp_lcd_panel_io.h" #include "esp_lcd_panel_ops.h" #include "esp_lcd_panel_vendor.h" #include "board_cfg.h" // 1. 初始化 SPI 总线，自动分配 DMA 通道 spi_bus_config_t bus_cfg = { .sclk_io_num = PIN_LCD_SCLK, .mosi_io_num = PIN_LCD_MOSI, .miso_io_num = -1, // ST7789 不回数据 .quadwp_io_num = -1, .quadhd_io_num = -1, .max_transfer_sz = PANEL_WIDTH * PANEL_HEIGHT * 2 + 8, }; spi_bus_initialize(LCD_SPI_HOST, &bus_cfg, SPI_DMA_CH_AUTO); // 2. 挂载 SPI 面板 IO，pclk 决定刷新上限 esp_lcd_panel_io_spi_config_t io_cfg = { .dc_gpio_num = PIN_LCD_DC, .cs_gpio_num = PIN_LCD_CS, .pclk_hz = 40 * 1000 * 1000, .lcd_cmd_bits = 8, .lcd_param_bits = 8, .spi_mode = 0, .trans_queue_depth = 20, }; esp_lcd_panel_io_handle_t io_handle = NULL; esp_lcd_new_panel_io_spi(LCD_SPI_HOST, &io_cfg, &io_handle);

.max_transfer_sz必须大于一次最大帧传输的长度，否则 DMA 描述符会拒绝超过 4KB 的传输，报错信息还特别隐晦。.pclk_hz就是 SPI 时钟频率，40MHz 是起步值，跑顺了可以往上加到 60 甚至 80MHz，前提是排线别太长，杜邦线就别想了，排线或 PCB 走线才有戏。.spi_mode = 0对应 ST7789 手册的 CPOL=0、CPHA=0，绝大多数模组都吃这个模式，反应慢就卡在这里。.trans_queue_depth决定能排队多少笔 SPI 事务，深度 20 对 LVGL 整块刷屏够用，太小会频繁返回 BUSY，然后 flush 回调里全是超时日志。

接着创建 ST7789 面板并执行初始化：

esp_lcd_panel_dev_config_t panel_cfg = { .reset_gpio_num = PIN_LCD_RST, .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, .bits_per_pixel = 16, // RGB565 }; esp_lcd_panel_handle_t panel = NULL; esp_lcd_new_panel_st7789(io_handle, &panel_cfg, &panel); // 3. 复位后等 120ms，有些屏对这条时序特别敏感 esp_lcd_panel_reset(panel); vTaskDelay(pdMS_TO_TICKS(120)); // 4. 初始化后处理颜色方向和显示开关 esp_lcd_panel_init(panel); esp_lcd_panel_invert_color(panel, true); // RGB565 屏基本都要开 esp_lcd_panel_disp_on_off(panel, true); // 显式开显示，别省

.bits_per_pixel = 16必须跟 LVGL 的色深严格一致，否则颜色整体错位。.rgb_ele_order选 RGB 还是 BGR 取决于屏厂，接反了红蓝互换，一眼能看出来就翻回来。invert_color是 ST7789 家族著名的坑：很多模组的 TFT 面板像素极性和驱动 IC 默认相反，不开反色时白变黑、红变青，而且不同批次的模组差异都可能有。ESP-IDF 里先设true，颜色不对就改false，二选一必中。

3.2 读取 CST328 触摸数据：寄存器地址、坐标字节序与按下判定

触摸侧用 ESP-IDF 5.2 之后的i2c_master驱动，API 比老的driver/i2c.h干净，错误处理更细：

#include "driver/i2c_master.h" static i2c_master_dev_handle_t touch_dev; void cst328_init(void) { i2c_master_bus_config_t bus_cfg = { .i2c_port = I2C_NUM_0, .sda_io_num = PIN_TOUCH_SDA, .scl_io_num = PIN_TOUCH_SCL, .clk_source = I2C_CLK_SRC_DEFAULT, .glitch_ignore_cnt = 7, .flags.enable_internal_pullup = true, }; i2c_master_bus_handle_t bus_handle = NULL; i2c_new_master_bus(&bus_cfg, &bus_handle); i2c_device_config_t dev_cfg = { .dev_addr_length = I2C_ADDR_BIT_LEN_7, .device_address = CST328_I2C_ADDR, // 0x15，以模块原理图为准 .scl_speed_hz = 400 * 1000, }; i2c_master_bus_add_device(bus_handle, &dev_cfg, &touch_dev); }

.scl_speed_hz = 400 * 1000是 I2C 快速模式，CST328 手册一般都支持，别用 100kHz 低速模式，触摸采样是轮询的，总线越快延迟越低。.glitch_ignore_cnt = 7是毛刺过滤，调试阶段波形一团糟可以先调大，确认问题之后再把值收回来。地址这块如果 0x15 读不到 ACK，用逻辑分析仪抓 SDA 在地址阶段的波形，能直接看到七位地址是多少，比盲猜省时间。

读坐标的函数要处理两件事：I2C 传输失败和坐标越界。写成返回 bool，让上层决定要不要沿用旧坐标：

bool cst328_read_point(uint16_t *x, uint16_t *y, bool *pressed) { uint8_t reg = 0x00; // 状态寄存器，坐标数据跟随其后 uint8_t buf[7] = {0}; esp_err_t err = i2c_master_transmit_receive(touch_dev, &reg, 1, buf, 7, 100); if (err != ESP_OK) { return false; // 上层沿用上一次坐标，避免 UI 抖动 } uint8_t touch_count = buf[0] & 0x0F; // 低 4 位是触点数量 *pressed = (touch_count > 0); if (*pressed) { *x = ((uint16_t)buf[1] << 8) | buf[2]; *y = ((uint16_t)buf[3] << 8) | buf[4]; // 坐标高位偶尔会混入状态位，按分辨率钳位 if (*x >= PANEL_WIDTH) *x = PANEL_WIDTH - 1; if (*y >= PANEL_HEIGHT) *y = PANEL_HEIGHT - 1; } return true; }

CST328 的坐标系原点默认在触摸传感器左上角，X 向右、Y 向下，和屏幕扫描方向一致，大多数情况不用镜像。但有些屏厂把触摸排线换了个方向焊，原点就跑到右下角去了，这种情况不要改驱动，在 LVGL 的 read 回调里做映射就行。

坐标高字节是重灾区：有些手册定义 X 是 12 位，高 4 位另有含义，直接把buf[1]全当坐标高位，读出来的数会跳上千，钳位逻辑能兜底但治标不治本，正确做法是先把位域确认清楚。

3.3 注册 LVGL 回调：flush_cb 和 read_cb 的对接细节

LVGL 对接的核心是两个回调，外加一颗心跳。LVGL 跟裸跑了几年 HAL 库的人最大的认知差就是：它需要你定期喂 tick，否则动画、长按、双击判定全部失灵，现象是界面画出来了按键也能点，但滑动起来一顿一顿。

先初始化 LVGL 本体、喂 tick、注册回调：

#include "lvgl.h" static lv_disp_draw_buf_t draw_buf; static lv_color_t buf_part1[PANEL_WIDTH * 40]; static lv_color_t buf_part2[PANEL_WIDTH * 40]; // 双缓冲 static void lvgl_tick_task(void *arg) { while (1) { lv_tick_inc(10); // 每 10ms 喂一次心跳 vTaskDelay(pdMS_TO_TICKS(10)); } } void lvgl_port_init(void) { lv_init(); xTaskCreate(lvgl_tick_task, "lv_tick", 2048, NULL, 5, NULL); lv_disp_draw_buf_init(&draw_buf, buf_part1, buf_part2, PANEL_WIDTH * 40); lv_disp_drv_t disp_drv; lv_disp_drv_init(&disp_drv); disp_drv.hor_res = PANEL_WIDTH; disp_drv.ver_res = PANEL_HEIGHT; disp_drv.flush_cb = lvgl_flush_cb; disp_drv.draw_buf = &draw_buf; lv_disp_drv_register(&disp_drv); lv_indev_drv_t indev_drv; lv_indev_drv_init(&indev_drv); indev_drv.type = LV_INDEV_TYPE_POINTER; indev_drv.read_cb = lvgl_touch_cb; lv_indev_drv_register(&indev_drv); }

缓冲大小 240x40 算下来每块 19200 字节，两块不到 40KB，ESP32-S3 内部 SRAM 放得下。缓冲高度越大，一帧分块次数越少、CPU 开销越低，但 SRAM 占用越高。40 行是性价比不错的起步，想更顺就提到 80，看编译后的内存余量决定。

主循环里还得让 LVGL 干活：

void app_main(void) { // ... SPI 和 I2C 初始化 ... lvgl_port_init(); while (1) { lv_timer_handler(); // 处理动画和重绘 vTaskDelay(pdMS_TO_TICKS(5)); } }

lv_timer_handler()调用间隔太大会让动画掉帧，5ms 是比较通用的值；不调它，UI 基本就是一幅静态图。

flush 回调做三件事：把区域送到屏幕、处理好边界、通知 LVGL 缓冲可回收：

static void lvgl_flush_cb(lv_disp_drv_t *drv, const lv_area_t *area, lv_color_t *color_p) { // esp_lcd 的坐标是排他性的右边界，LVGL 给的是包含性的，x2/y2 必须 +1 esp_lcd_panel_draw_bitmap(panel, area->x1, area->y1, area->x2 + 1, area->y2 + 1, (void *)color_p); lv_disp_flush_ready(drv); }

x2 + 1这个细节漏了，屏幕右边缘和下边缘会丢一行像素，怎么查都像是屏幕坏了。lv_disp_flush_ready是告诉 LVGL「这块缓冲我用完了」，叫得越早 LVGL 越早画下一块。但注意：esp_lcd_panel_draw_bitmap是异步的，DMA 可能还没读完缓冲。简单例程里直接用上面的即时版本，双缓冲给了 DMA 足够时间追上一帧的绘制；如果看到偶发花屏或条纹，把 flush 改成等 SPI 完成信号量再flush_ready，这是esp_lvgl_port的内部做法。

read 回调把触摸数据填进lv_indev_data_t，每次被 LVGL 输入定时器调用：

static void lvgl_touch_cb(lv_indev_drv_t *drv, lv_indev_data_t *data) { static uint16_t last_x = 0, last_y = 0; static bool last_pressed = false; uint16_t x = last_x, y = last_y; bool pressed = last_pressed; if (cst328_read_point(&x, &y, &pressed)) { last_x = x; last_y = y; last_pressed = pressed; } >esp_lcd_panel_swap_xy(panel, PANEL_SWAP_XY); // 交换 X/Y 扫描方向 esp_lcd_panel_mirror(panel, false, false); // 按需镜像 esp_lcd_panel_set_gap(panel, 0, 0); // 裁边用，320 屏显示 240 区域才需要

swap_xy交换的是屏幕扫描方向，mirror的两个布尔分别控制 X 轴和 Y 轴镜像。这几个开关一点亮，显示侧就转了，但触摸 IC 的坐标是硬件层面的，它不知道你转了屏，于是出现「画面横过来了，触摸还按竖的算」的错位。解决办法是在 read 回调里做数学变换，逻辑和屏幕变换保持一致：

// 假设屏幕做了 swap_xy 且没有镜像 if (PANEL_SWAP_XY) { uint16_t tmp = x; x = y; y = PANEL_WIDTH - 1 - tmp; // 用旋转后的宽度算 }

这行变换是我实测时最常调的地方。调试顺序必须固定：先把原始坐标直接打印到串口，手指点四角，确认触摸 IC 的原始坐标系方向；再打开显示旋转，对照四角出现的位置，决定 Y 要不要镜像、X 要不要镜像；最后才把变换写死进 read 回调。顺序反了会绕晕，因为屏幕和触摸的错误会互相叠加，你改了一个方向，另一个方向又错位了。

4. 避坑与排查：黑屏、坐标错乱、卡顿与触摸失灵的 5 个实战记录

4.1 黑屏但背光亮：先查复位时序和 DISPON

现象：上电后背光正常亮，屏幕全黑，串口日志显示 LVGL 任务在跑，但屏幕上什么都画不出来。

原因：八成是 ST7789 没真正完成初始化。常见三类：reset_gpio_num没配对或复用了其他功能引脚；复位后延时太短，IC 没就绪就接着发命令；esp_lcd_panel_init()内部发了 SLPOUT 但没等够手册要求的 120ms，DISPON 自然没生效。还有一部分模组需要显式调用esp_lcd_panel_disp_on_off(panel, true)，默认可能是关的。

解决：先核对reset_gpio_num，别拿复用引脚顶上。第二步在esp_lcd_panel_reset()后加vTaskDelay(120ms)，把复位到初始化的间隔拉到最稳妥区间。第三步把disp_on_off(panel, true)加上，放在invert_color之后。还黑就用逻辑分析仪抓 CS、SCLK、DC 三条线，确认命令确实发出去、极性对。记住：背光亮不等于屏幕活着，它只说明背光 LED 供电正常。

4.2 触摸坐标错乱：先打印原始坐标再谈对齐

现象：点屏幕左上角，UI 响应在右下角；或者点一下坐标数值疯狂跳变，甚至出现几万的大数。

原因：数值跳变，多半是寄存器位域取错了。CST328 的高字节里混了状态位或触点编号，没做掩码直接当坐标高位，就会出现几千上万的坐标。UI 视觉位置和触摸位置整体错位，则九成是屏幕做了swap_xy/mirror之后，触摸变换没同步更新。

解决：临时把读到的x、y、pressed直接ESP_LOGI打印，去掉所有钳位和变换，纯裸数据。手指点四个角，对照打印值与物理位置，确认原始坐标系，然后再定变换公式。四角对上了再开 UI。最高优先级原则：裸数据是基准，一切变换都从裸数据出发，别上来就猜公式。

4.3 刷新卡顿与撕裂：pclk、缓冲区和 DMA 三方拉扯

现象：滑动列表时一顿一顿，快速滚动时屏幕中间有水平分割线，像是两帧拼在一起。

原因：卡顿核心是单缓冲区——LVGL 画完一块区域前不能画下一块，SPI 传输期间 CPU 有大段空转。撕裂是 flush 回调里lv_disp_flush_ready叫得太早，LVGL 已经把新内容写进 DMA 还没读走的缓冲。另一点是 pclk 只有 20MHz 时，240x240x2 字节的整帧传输要十几毫秒，流畅度必然受影响。

解决：先上双缓冲，改动最小收益最直接。再把pclk_hz从 40MHz 试到 60MHz，画面没噪点就继续上，有噪点就退一档——这跟走线质量和屏的极限有关，实测出来才算数。撕裂就改 flush 等待 SPI 完成信号量，把.trans_queue_depth设成 1 让传输严格串行，牺牲一点吞吐换画面完整。最后是压缩 LVGL 脏矩形面积，局部刷新永远比全屏快，UI 上少用大面积的重绘调用。

4.4 触摸偶尔失灵：I2C 上拉电阻、INT 引脚和传输失败处理

现象：刚上电触摸一切正常，跑几分钟后突然没反应；或者按一个按钮要按好几次才触发；还有的伴随坐标偶尔跳变。

原因：I2C 总线没有外部上拉或上拉电阻太大，电平建立时间不够，随着温升或走线耦合，传输开始偶发失败。另一个常见原因是模块的 INT 引脚悬空，CST328 靠它做触摸唤醒和事件同步，悬空时 IC 行为不一定可预期。再一个是驱动里没处理 I2C 的 NACK 和超时返回值，一次失败后总线状态残留，后续所有传输都失败。

解决：PCB 上给 SDA/SCL 各加一颗 4.7kΩ 上拉到 3.3V，这是最靠谱的做法，别只依赖 ESP32-S3 的内部弱上拉。INT 引脚接到任意 GPIO，哪怕代码暂时用不上，也得给它一个确定电平。读取函数严格检查每次i2c_master_transmit_receive返回值，失败时先把总线句柄复位再继续，别让总线死在半途。最后可以在触摸 IC 供电上加一个断 10ms 再上电的软件复位流程，作为最后的后悔药。

4.5 花屏与颜色翻车：INVON、COLMOD 和 LVGL 色深的三角关系

现象：屏幕能点亮，但颜色完全不对——白色变黑色、红色变青色，或者整屏出现不太规则的彩色噪点。

原因：颜色反相基本是 ST7789 的 INVON 没开或开错，不同屏厂 TFT 面板极性相反，这个开关二选一总能调对。彩色噪点和错位是像素格式不匹配：屏的 COLMOD 设成了 18 位，但 LVGL 打包的是 16 位 RGB565，两边数据宽度对不上，画面就花。

解决：先确认esp_lcd_panel_invert_color(panel, true)已调用，颜色不对就改成false，这是排查第一优先。再检查esp_lcd_panel_dev_config_t里bits_per_pixel = 16，同时确认 LVGL 配置里色深为 16 位，在menuconfig里搜LV_COLOR_DEPTH就能改。最后对照屏厂的初始化序列，看有没有自定义像素格式命令，有就以屏厂手册为准覆写。

5. 验证与进阶：帧率测量、缓冲布局与低功耗收尾

5.1 帧率怎么测：perf 监视器和串口时间戳双管齐下

LVGL 自带帧率测量：menuconfig里打开LV_USE_PERF_MONITOR，屏幕角落会常驻一个显示 FPS 和 CPU 占用的小角标，这是最直观的验证手段。但这个数字是 LVGL 画图帧率，不是屏幕实际刷新率。要核实屏侧吞吐，我在 flush 回调里用esp_timer_get_time()掐耗时：

static int64_t flush_ms_sum; static uint32_t flush_count; static int64_t last_report_ms; static void lvgl_flush_cb(lv_disp_drv_t *drv, const lv_area_t *area, lv_color_t *color_p) { int64_t t0 = esp_timer_get_time(); esp_lcd_panel_draw_bitmap(panel, area->x1, area->y1, area->x2 + 1, area->y2 + 1, (void *)color_p); flush_ms_sum += (esp_timer_get_time() - t0) / 1000; flush_count++; if (esp_timer_get_time() - last_report_ms > 1000000) { ESP_LOGI("LCD", "avg flush %lld us, count %lu", (long long)(flush_ms_sum * 1000UL / flush_count), (unsigned long)flush_count); flush_ms_sum = 0; flush_count = 0; last_report_ms = esp_timer_get_time(); } lv_disp_flush_ready(drv); }

两边的数字对不上时，问题多半在 DMA 队列或 pclk 上，回到 4.3 的思路去查。

5.2 缓冲布局：SRAM、PSRAM 与分块高度怎么选

240x240 全屏缓冲需要 115KB，ESP32-S3 内部 SRAM 能挤出来，但大屏就得考虑 PSRAM。三种方案的取舍：

分块高度从 40 起步，UI 复杂就提到 60，超过 80 收益递减。缓冲放 PSRAM 时注意地址对齐和缓存一致性，读到异常闪烁就先把 DMA 缓存关掉再看。

5.3 背光 PWM 与触摸唤醒：低功耗的最后一道工序

背光用 LEDC 输出 PWM，把静态常亮改成可调亮度，省下的电流比任何软件优化都实在。配合 INT 引脚做触摸唤醒：屏幕超时后关背光，把 CST328 的 INT 配成唤醒源，手指点屏幕就能拉起。整套组合能把功耗压到待机毫安级，前提是触摸 IC 的待机模式配置正确，不同型号差异大，以手里那颗的寄存器手册为准。

我自己的习惯是：每次拿到新屏，先花半天把「复位 → ST7789 纯色显示 → CST328 裸坐标打印 → LVGL 最小触摸 Demo」这条最短链路走通，再谈 UI 优化。跳过任何一步，后面的排查成本都会翻倍。这套例程把整条链路打包好了，你照着跑通再改业务，能少走我当年绕的那些弯路。希望帮到你。

本文还有配套的精品资源，点击获取