简介这份资源面向使用ESP32-S3开发嵌入式图形界面的工程师与爱好者聚焦在LVGL图形库下驱动1.69寸电容触摸屏的完整实现解决显示与触摸两大模块的适配问题。屏幕显示采用ST7789控制器通过SPI接口传输图像数据触摸部分由CST816芯片负责支持多点触控需经I2C或SPI读取触点坐标并转换为LVGL可识别的输入事件。资源包共971个文件以C语言源码与头文件为主体辅以Python脚本、Markdown说明文档、PNG/GIF图片素材及字体文件压缩包约17.39MB目录结构便于按显示驱动、触摸驱动与LVGL配置模块检索。已有6177人学习下载读者可从中获取ST7789与CST816的初始化代码、LVGL自定义触摸驱动示例、事件回调注册方式及整合调试思路适合需要快速搭建交互式UI原型的物联网项目开发者参考。1. 一块 1.69 寸电容屏为什么值得用 ESP32-S3 单独跑一遍 LVGL手头拿到一块 1.69 寸电容触摸屏分辨率 240×280驱动芯片常见是 ST7789V2 配 CST816 触摸很多人第一反应是“这么小的屏随便点个灯就行”。但真把它接到 ESP32-S3 上跑 LVGL你会发现事情没那么简单SPI 时钟拉高了花屏触摸中断抖动导致误触LVGL 的缓冲区给少了刷屏像幻灯片。这块屏的价值恰恰在于它小、它便宜、它接口简单适合把 LVGL 的移植流程完整走一遍把 ESP-IDF 的 SPI 配置、触摸中断、任务调度这些环节全部摸清楚。适合已经点过灯、跑过串口但还没独立驱动过一块带触摸的彩屏的嵌入式开发者。下面按我实际拆解的步骤从硬件连线一路写到触摸校准和性能调优。2. 硬件连线与 ESP-IDF 工程搭建先把 SPI 和 I2C 分清楚2.1 屏幕与触摸的引脚分配逻辑1.69 寸电容屏模块通常引出 8 个引脚VCC、GND、SCL、SDA、RES、DC、CS、BLK。其中 SCL/SDA 是 I2C接电容触摸芯片 CST816SPI 的 SCK、MOSI 加上 RES、DC、CS 接 ST7789V2。ESP32-S3 的 GPIO 矩阵很灵活但有几个坑GPIO 0~3 是 strapping 引脚上电电平会影响启动模式尽量别用来接屏GPIO 19/20 是 USB D-/D如果要用 USB 串口调试就避开。我一般把 SPI 放在 GPIO 10~13 这组I2C 放在 GPIO 8/9背光 BLK 接 GPIO 4 用 LEDC 调光。屏幕引脚ESP32-S3 GPIO功能说明SCLGPIO 9I2C 时钟接 CST816SDAGPIO 8I2C 数据接 CST816SCKGPIO 12SPI 时钟MOSIGPIO 11SPI 数据RESGPIO 13屏幕复位低电平有效DCGPIO 10数据/命令选择CSGPIO 14片选低电平有效BLKGPIO 4背光PWM 调光注意不同厂家的模块引脚顺序可能不同上电前一定用万用表确认 VCC 和 GND接反会直接烧屏。2.2 创建工程与组件依赖用 ESP-IDF v5.x 创建工程LVGL 通过组件管理器引入。我习惯用idf.py create-project建一个空工程然后在idf_component.yml里声明依赖# idf_component.yml dependencies: idf: 5.0 lvgl/lvgl: ^8.3.0 espressif/esp_lcd_st7789: ^1.0.0 espressif/esp_lcd_touch_cst816s: ^1.0.0这里选 LVGL 8.3 而不是 9.x原因是 8.3 的 API 稳定社区示例多ESP-IDF 的esp_lvgl_port组件对 8.x 支持最成熟。esp_lcd_st7789和esp_lcd_touch_cst816s是乐鑫官方维护的驱动省去自己写初始化序列的麻烦。执行idf.py reconfigure后组件会自动下载到managed_components目录。2.3 SPI 总线初始化与屏幕驱动挂载SPI 总线配置是第一个容易翻车的地方。ST7789V2 在 240×280 分辨率下SPI 时钟建议先跑 40MHz稳定后再往上试。下面是我常用的初始化代码// spi_init.c #include driver/spi_master.h #include esp_lcd_panel_io.h #include esp_lcd_panel_vendor.h #include esp_lcd_panel_ops.h #define LCD_HOST SPI2_HOST #define PIN_SCK 12 #define PIN_MOSI 11 #define PIN_CS 14 #define PIN_DC 10 #define PIN_RST 13 spi_bus_config_t buscfg { .sclk_io_num PIN_SCK, .mosi_io_num PIN_MOSI, .miso_io_num -1, // 屏幕只写不读MISO 不接 .quadwp_io_num -1, .quadhd_io_num -1, .max_transfer_sz 240 * 80 * sizeof(uint16_t), // 单次最大传输 }; ESP_ERROR_CHECK(spi_bus_initialize(LCD_HOST, buscfg, SPI_DMA_CH_AUTO)); esp_lcd_panel_io_spi_config_t io_config { .dc_gpio_num PIN_DC, .cs_gpio_num PIN_CS, .pclk_hz 40 * 1000 * 1000, // 40MHz .lcd_cmd_bits 8, .lcd_param_bits 8, .spi_mode 0, .trans_queue_depth 10, }; esp_lcd_panel_io_handle_t io_handle NULL; ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)LCD_HOST, io_config, io_handle));max_transfer_sz设成 240×80×2 字节是因为 LVGL 刷屏时按行分块传输这个值要大于单次刷新的最大数据量否则 DMA 会报错。pclk_hz先给 40MHz如果花屏就降到 20MHz 排查是时序问题还是接线问题。trans_queue_depth给 10 是留出异步传输的缓冲太小会导致刷屏卡顿。3. LVGL 移植与触摸接入缓冲区、任务和中断一个都不能少3.1 LVGL 初始化的三个关键参数LVGL 移植的核心是lv_init()之后的显示缓冲区和输入设备注册。缓冲区大小直接决定刷屏流畅度ESP32-S3 有 512KB SRAM我一般给 LVGL 分配 240×40 像素的双缓冲区约 19KB// lvgl_port.c #define BUF_LINES 40 static lv_disp_draw_buf_t draw_buf; static lv_color_t *buf1; static lv_color_t *buf2; void lvgl_init(void) { lv_init(); buf1 heap_caps_malloc(240 * BUF_LINES * sizeof(lv_color_t), MALLOC_CAP_DMA); buf2 heap_caps_malloc(240 * BUF_LINES * sizeof(lv_color_t), MALLOC_CAP_DMA); lv_disp_draw_buf_init(draw_buf, buf1, buf2, 240 * BUF_LINES); static lv_disp_drv_t disp_drv; lv_disp_drv_init(disp_drv); disp_drv.hor_res 240; disp_drv.ver_res 280; disp_drv.flush_cb lcd_flush_cb; // 刷屏回调 disp_drv.draw_buf draw_buf; lv_disp_drv_register(disp_drv); }MALLOC_CAP_DMA必须加否则 SPI DMA 传输会失败。双缓冲区的好处是 LVGL 在渲染下一帧时DMA 还在传上一帧减少撕裂感。如果内存紧张可以只用一个缓冲区但刷屏会有明显闪烁。3.2 触摸驱动注册与坐标映射CST816 通过 I2C 上报触摸坐标注册到 LVGL 的输入设备// touch_init.c static void touch_read_cb(lv_indev_drv_t *drv, lv_indev_data_t *data) { esp_lcd_touch_point_data_t point; uint8_t point_cnt 0; esp_lcd_touch_read_data(touch_handle); esp_lcd_touch_get_data(touch_handle, point, point_cnt, 1); if (point_cnt 0) { >// lvgl_task.c void lvgl_task(void *arg) { while (1) { uint32_t time_till_next lv_timer_handler(); vTaskDelay(pdMS_TO_TICKS(time_till_next 10 ? 10 : time_till_next)); } } void app_main(void) { spi_init(); lcd_init(); i2c_init(); touch_init(); lvgl_init(); xTaskCreate(lvgl_task, lvgl, 4096, NULL, 5, NULL); }lv_timer_handler返回下一次需要调用的毫秒数但为了触摸响应及时我一般限制最大延时 10ms。任务栈给 4096 字节优先级 5低于 WiFi 任务但高于空闲任务。如果发现刷屏卡顿先看这个任务的栈是否溢出用uxTaskGetStackHighWaterMark查。4. 避坑排查花屏、误触、刷屏慢的五个血泪经验4.1 花屏或颜色错乱现象屏幕点亮后显示雪花点或者颜色红蓝颠倒。原因通常是 SPI 时钟太快导致时序不满足或者颜色格式配置错误。解决先把pclk_hz降到 10MHz如果正常了再逐步往上加颜色颠倒则检查esp_lcd_panel_set_color_space是否设为 RGBST7789V2 默认是 BGR需要在初始化时调用esp_lcd_panel_invert_color或设置color_space为 RGB。4.2 触摸坐标偏移或反向现象点击屏幕左侧光标出现在右侧。原因CST816 的坐标原点和屏幕原点不一致或者mirror_x配置反了。解决在esp_lcd_touch_config_t里调整mirror_x和mirror_y如果偏移是线性的还需要在touch_read_cb里做比例缩放比如>// perf_test.c static void anim_cb(lv_anim_t *a, int32_t v) { lv_obj_set_x(rect, v); } void perf_test(void) { lv_obj_t *rect lv_obj_create(lv_scr_act()); lv_obj_set_size(rect, 50, 50); lv_obj_set_style_bg_color(rect, lv_color_hex(0xFF0000), 0); lv_anim_t a; lv_anim_init(a); lv_anim_set_var(a, rect); lv_anim_set_exec_cb(a, anim_cb); lv_anim_set_values(a, 0, 190); lv_anim_set_time(a, 1000); lv_anim_set_repeat_count(a, LV_ANIM_REPEAT_INFINITE); lv_anim_start(a); // 用 GPIO 翻转测帧率接示波器看周期 gpio_set_direction(GPIO_NUM_6, GPIO_MODE_OUTPUT); while (1) { gpio_set_level(GPIO_NUM_6, 1); lv_timer_handler(); gpio_set_level(GPIO_NUM_6, 0); vTaskDelay(pdMS_TO_TICKS(1)); } }把 GPIO 6 接示波器高电平时间就是lv_timer_handler的执行时间。240×280 全屏刷新40MHz SPI 下理想值在 15ms 左右如果超过 30ms 就要查缓冲区大小和 DMA 配置。这个办法比看串口打印靠谱因为串口输出本身会干扰时序。另一个技巧是开 LVGL 的性能监控在lv_conf.h里把LV_USE_PERF_MONITOR设为 1屏幕右下角会显示 CPU 占用和帧率。如果 CPU 占用长期高于 70%说明有对象在频繁重绘检查是不是用了lv_obj_invalidate刷了整个屏幕。从那以后我每次移植新屏都强制先跑一遍这个 GPIO 翻转测试确认帧率达标再写业务逻辑。希望帮到你。本文还有配套的精品资源点击获取