ESP32+1.3寸屏保姆级教程：用PlatformIO搞定TFT_eSPI和LVGL驱动（附完整代码）
ESP32与1.3寸TFT屏幕的终极开发指南：从PlatformIO到LVGL的完美实践
在创客和嵌入式开发领域，ESP32凭借其强大的性能和丰富的功能接口，成为了物联网和交互式项目的首选微控制器。而1.3寸TFT屏幕则是小型项目中显示交互界面的理想选择，尺寸适中且价格亲民。本文将带你从零开始，在VSCode+PlatformIO环境下，一步步完成ESP32与1.3寸TFT屏幕的驱动配置，并实现LVGL图形库的完美运行。
1. 硬件准备与平台搭建
1.1 硬件清单与连接
首先确保你手头有以下硬件组件：
- ESP32开发板（如ESP-WROOM-32）
- 1.3寸TFT屏幕（240×240分辨率，ST7789驱动）
- 杜邦线若干
- Micro USB数据线
对于1.3寸TFT屏幕的接线，参考以下配置：
| 屏幕引脚 | ESP32引脚 | 功能说明 |
|---|---|---|
| GND | GND | 接地 |
| VCC | 3.3V | 电源 |
| SCL | D18 | SPI时钟 |
| SDA | D23 | SPI数据 |
| RES | D19 | 复位 |
| DC | D5 | 数据/命令选择 |
| BLK | D21 | 背光控制（可选） |
提示：不同厂商的屏幕引脚定义可能略有差异，务必参考你的屏幕规格书确认引脚功能。
1.2 开发环境配置
- 安装VSCode（Visual Studio Code）
- 在VSCode扩展商店中搜索并安装PlatformIO IDE
- 安装完成后，通过PlatformIO主页创建新项目：
- 选择"ESP32 Dev Module"作为开发板
- 选择Arduino作为框架
- 指定项目保存路径
; platformio.ini 基础配置示例 [env:esp32dev] platform = espressif32 board = esp32dev framework = arduino monitor_speed = 1152002. TFT_eSPI库的配置与优化
2.1 安装与基础配置
在PlatformIO项目中添加TFT_eSPI库：
- 打开PlatformIO主页
- 选择"Libraries"标签
- 搜索"TFT_eSPI"并安装最新版本
安装完成后，需要修改库的用户配置文件：
- 导航到项目目录下的
.pio/libdeps/esp32dev/TFT_eSPI文件夹 - 打开
User_Setup.h文件进行编辑
// User_Setup.h 关键配置示例 #define ST7789_DRIVER // 指定使用ST7789驱动 #define TFT_WIDTH 240 // 屏幕宽度 #define TFT_HEIGHT 240 // 屏幕高度 // 引脚定义 #define TFT_MOSI 23 // SPI数据线 #define TFT_SCLK 18 // SPI时钟线 #define TFT_CS -1 // 未使用片选 #define TFT_DC 5 // 数据/命令选择 #define TFT_RST 19 // 复位引脚 #define TFT_BL 21 // 背光控制 #define SPI_FREQUENCY 40000000 // SPI通信频率(40MHz)2.2 常见问题解决
在配置过程中，你可能会遇到以下问题：
SPI库引用错误： 在
platformio.ini中添加以下配置解决：lib_ldf_mode = deep+屏幕显示异常：
- 检查SPI频率是否设置过高
- 确认所有引脚连接正确
- 尝试调整屏幕旋转方向：
tft.setRotation(1); // 参数0-3对应不同旋转方向
背光不亮： 确保BLK引脚已连接并正确配置，或尝试直接连接3.3V
3. LVGL图形库的集成与配置
3.1 LVGL库的安装与初始化
- 通过PlatformIO安装LVGL库（建议选择8.x稳定版本）
- 在项目目录中创建
lvgl_conf.h文件：- 复制
lvgl/lvgl_conf_template.h并重命名 - 启用基本配置：
- 复制
// lvgl_conf.h 关键配置 #define LV_COLOR_DEPTH 16 // 颜色深度(16bit) #define LV_HOR_RES_MAX 240 // 水平分辨率 #define LV_VER_RES_MAX 240 // 垂直分辨率 #define LV_USE_LOG 1 // 启用日志 #define LV_USE_USER_DATA 1 // 启用用户数据3.2 LVGL与TFT_eSPI的对接
在main.cpp中实现显示驱动接口：
#include <lvgl.h> #include <TFT_eSPI.h> static TFT_eSPI tft; static lv_disp_draw_buf_t draw_buf; static lv_color_t buf[TFT_WIDTH * 10]; // 显示缓冲区 // 显示刷新回调函数 void my_disp_flush(lv_disp_drv_t *disp, const lv_area_t *area, lv_color_t *color_p) { uint32_t w = area->x2 - area->x1 + 1; uint32_t h = area->y2 - area->y1 + 1; tft.startWrite(); tft.setAddrWindow(area->x1, area->y1, w, h); tft.pushColors((uint16_t *)&color_p->full, w * h, true); tft.endWrite(); lv_disp_flush_ready(disp); } void setup() { // 初始化TFT屏幕 tft.init(); tft.setRotation(0); tft.fillScreen(TFT_BLACK); // 初始化LVGL lv_init(); lv_disp_draw_buf_init(&draw_buf, buf, NULL, TFT_WIDTH * 10); // 配置显示驱动 static lv_disp_drv_t disp_drv; lv_disp_drv_init(&disp_drv); disp_drv.hor_res = TFT_WIDTH; disp_drv.ver_res = TFT_HEIGHT; disp_drv.flush_cb = my_disp_flush; disp_drv.draw_buf = &draw_buf; lv_disp_drv_register(&disp_drv); // 创建测试界面 lv_obj_t *label = lv_label_create(lv_scr_act()); lv_label_set_text(label, "Hello LVGL!"); lv_obj_align(label, LV_ALIGN_CENTER, 0, 0); } void loop() { lv_timer_handler(); // 处理LVGL任务 delay(5); }4. 高级优化与性能提升
4.1 双缓冲与内存优化
为了提升显示流畅度，可以实现双缓冲机制：
// 定义两个缓冲区 static lv_color_t buf1[TFT_WIDTH * 20]; static lv_color_t buf2[TFT_WIDTH * 20]; // 初始化时使用双缓冲 lv_disp_draw_buf_init(&draw_buf, buf1, buf2, TFT_WIDTH * 20);4.2 触摸输入支持
如果你的屏幕支持触摸功能，可以添加触摸驱动：
#include <XPT2046_Touchscreen.h> #define TOUCH_CS 16 // 触摸芯片片选引脚 XPT2046_Touchscreen touch(TOUCH_CS); // 触摸读取函数 void my_touchpad_read(lv_indev_drv_t *indev, lv_indev_data_t *data) { if (touch.touched()) { TS_Point p = touch.getPoint(); >// 背光控制函数 void setBacklight(bool state) { digitalWrite(TFT_BL, state ? HIGH : LOW); } // 在需要时关闭背光节省电量 setBacklight(false);5. 实战项目：构建简易天气站界面
结合LVGL的丰富组件，我们可以创建一个美观的天气显示界面：
void createWeatherUI() { // 创建主样式 static lv_style_t main_style; lv_style_init(&main_style); lv_style_set_bg_color(&main_style, lv_color_hex(0x000000)); // 应用主样式 lv_obj_t *scr = lv_scr_act(); lv_obj_add_style(scr, &main_style, 0); // 添加温度显示 lv_obj_t *temp_label = lv_label_create(scr); lv_label_set_text(temp_label, "25°C"); lv_obj_set_style_text_color(temp_label, lv_color_hex(0xFFFFFF), 0); lv_obj_set_style_text_font(temp_label, &lv_font_montserrat_48, 0); lv_obj_align(temp_label, LV_ALIGN_TOP_LEFT, 20, 20); // 添加天气图标 LV_IMG_DECLARE(icon_cloudy); lv_obj_t *icon = lv_img_create(scr); lv_img_set_src(icon, &icon_cloudy); lv_obj_align(icon, LV_ALIGN_TOP_RIGHT, -20, 20); // 添加日期时间 lv_obj_t *date_label = lv_label_create(scr); lv_label_set_text(date_label, "2023-07-15 14:30"); lv_obj_set_style_text_color(date_label, lv_color_hex(0xCCCCCC), 0); lv_obj_align(date_label, LV_ALIGN_BOTTOM_MID, 0, -20); }注意：实际项目中，你需要准备天气图标并添加到LVGL资源文件中。