在基于 ESP32-S3 做 HMI 项目时屏幕尺寸往往是最让人纠结的地方。常见的 1.3 寸、1.8 寸、2.4 寸 SPI 屏适合做卡片式界面但一遇到复杂仪表盘、多列表设置页或多行图表就显得拥挤。最近我在调试一块 3.97 寸 480x800 分辨率的 AXS15260 屏幕并把它接入 LVGL 9踩了不少坑也整理出了一套可以复用的驱动与移植流程。本文会完整拆解 ESP32-S3 与 AXS15260 的接线、SPI 初始化、LCM 驱动代码、LVGL 9 的缓冲与刷新机制并给出可复制的 Arduino 示例。最后还会列出高频报错与优化建议供做产品落地时参考。1. 背景与核心概念1.1 为什么选择 3.97 寸 480x800 屏幕在很多嵌入式 GUI 项目中屏幕尺寸和分辨率决定界面表达力。信息密度480x800 在 3.97 寸屏幕上能展示完整的一屏状态栏 多行列表 按钮区适合做智能家居控制面板、小型收银终端、桌面摆件、工业设备操作屏。视觉体验1080x2400 手机屏在 MCU 上驱动成本很高而 480x800 在 ESP32-S3 上可以通过 SPI 接口跑起来并且配合 LVGL 9 可以做出接近原生 App 的动效。开发成本不需要复杂的 RGB 接口电路也不需要 MIPI DSI只要 4 根 SPI 信号线加电源线就能驱动。AXS15260 就是这类 3.97 寸 480x800 液晶面板中常见的驱动控制芯片。它把行列驱动、Gamma 校正、显存刷新等功能集成在屏幕模组内部MCU 只需要通过 SPI 发送命令和像素数据即可。相比老旧的 ST7789、ILI9341 等控制器AXS15260 主要面向高分辨率小尺寸屏对 SPI 带宽要求更高也更需要合理的 LVGL 缓冲策略。1.2 LVGL 9 是什么LVGLLight and Versatile Graphics Library是一个面向嵌入式系统的开源图形库提供控件、布局、动画、事件系统、主题等完整 GUI 能力。LVGL 9 是目前较新的版本对比 LVGL 8.x 的变化非常明显显示驱动从lv_disp_drv_t改为lv_display_t。使用lv_display_create()创建显示实例不再使用lv_disp_drv_register()。flush 回调签名发生了变化刷新完成需要调用lv_display_flush_ready()。屏幕对象相关 API 改名例如lv_scr_act()变成了lv_screen_active()。内置渲染器做了重构绘制性能更强软件渲染路径也更有针对性。所以很多以前针对 LVGL 8 编写的屏幕驱动代码直接拿到 LVGL 9 里会编译不过。这也是本文专门基于 LVGL 9 写适配代码的原因。1.3 SPI 接口在驱动大屏时的特殊性AXS15260 这类高分辨率 SPI 屏和普通小屏的最大区别是数据量480x800 RGB565 一帧数据约 768KB。即使 LVGL 只刷新局部区域联动动画时也会持续产生大量 SPI 写入。SPI 时钟频率、DMA 是否启用、缓冲区分块大小直接决定最终帧率。如果照搬 ST7789 小屏驱动把整帧缓冲放在内部 RAM 里ESP32-S3 的 512KB SRAM 会非常紧张而且刷新一帧需要很长时间。所以本文示例采用“部分缓冲 双缓冲 局部刷新”的策略这也是 LVGL 官方推荐的跑法。2. 环境准备与接线说明2.1 推荐硬件清单硬件型号/说明主控板ESP32-S3-DevKitC 或任意 ESP32-S3 开发板建议带 PSRAM显示屏3.97 寸 480x800 TFTAXS15260 驱动芯片SPI 接口杜邦线/排线尽量短SPI 信号线建议控制在 10cm 内稳压/背光电源3.3V 主电源背光电流较大时可独立供电需要注意有些 AXS15260 模组是 QSPI 接口有些是标准 4 线 SPI。本文以标准 4 线 SPI 为例接线前务必确认你的屏幕丝印和数据手册。如果你的开发板丝印与本文引脚不一致请按实际引脚调整代码中的宏定义。2.2 引脚接线表这里给出一个比较常用的 ESP32-S3 接法作为示例屏幕引脚ESP32-S3 引脚说明VCC / VDD3V3屏幕逻辑电源GNDGND电源地SCL / SCKGPIO 12SPI 时钟SDA / MOSIGPIO 11SPI 主机输出CS / SSGPIO 10片选信号DC / RSGPIO 9数据/命令选择RST / RESGPIO 8复位信号BLK / BLGPIO 7背光控制可 PWM如果你的模块命名不同例如将 SCL 写作 CLK、将 SDA 写作 DIN含义相同。2.3 引脚选择注意事项ESP32-S3 的 SPI 外设比较灵活大多数 GPIO 都能复用为 SPI 信号。但实际接线时要注意尽量避开连接 boot 模式的 GPIO0、GPIO46避免下载和启动异常。如果使用 PSRAM某些 GPIO 已经被 Flash/PSRAM 占用需要查阅开发板原理图。避免与 USB 的 D-/D 冲突否则插线调试时可能影响下载。信号线不要跨过晶振、电源模块等干扰源。在本文示例中我刻意避免使用 GPIO0、GPIO45、GPIO46 等敏感引脚这是一套相对稳妥的组合。2.4 软件环境版本建议不同软件版本差异很大本文示例按以下环境验证软件/工具建议版本Arduino IDE2.xesp32 Arduino 核心2.0.x 或 3.xLVGL 库9.x推荐 9.2 以上显示屏模组AXS15260 480x800 SPI开发板ESP32-S3-DevKitC8MB PSRAM如果你的环境版本不同例如使用 ESP-IDF 或 PlatformIO驱动思路一致只是编译和初始化方式会有差异。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。3. SPI 初始化与 AXS15260 显示驱动3.1 基础流程驱动一块 SPI 屏幕的完整流程可以拆成四步初始化 GPIO设置 DC、CS、RST、BL 的输出状态。初始化 SPI 外设设置时钟、数据位序、SPI 模式。对 AXS15260 发送初始化命令序列。通过 CASET、RASET、RAMWR 命令写入像素。后面所有操作都围绕这四步展开。3.2 引脚与 SPI 初始化代码在 Arduino 环境中先定义引脚#define LCD_SCK 12 #define LCD_MOSI 11 #define LCD_CS 10 #define LCD_DC 9 #define LCD_RST 8 #define LCD_BL 7 #define SPI_FREQ 40000000 // 40MHz可根据模组调整到 80MHz然后初始化void lcd_gpio_init() { pinMode(LCD_CS, OUTPUT); pinMode(LCD_DC, OUTPUT); pinMode(LCD_RST, OUTPUT); pinMode(LCD_BL, OUTPUT); digitalWrite(LCD_CS, HIGH); digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_RST, HIGH); digitalWrite(LCD_BL, HIGH); } void lcd_spi_init() { SPI.begin(LCD_SCK, -1, LCD_MOSI, -1); }SPI 的MISO参数传-1因为这类屏通常只写不读可以省一根信号线。3.3 命令写入与数据写入LCD 工作需要区分命令和数据由 DC 引脚控制DC 为低电平时SPI 上发送的是命令。DC 为高电平时SPI 上发送的是数据。下面封装两个基础函数void lcd_write_cmd(uint8_t cmd) { digitalWrite(LCD_DC, LOW); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.write(cmd); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); } void lcd_write_data(const uint8_t *data, size_t len) { digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.writeBytes(data, len); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); }这里每次都调用beginTransaction/endTransaction是为了避免多线程或中断干扰 SPI 配置。刷新大区域时也可以把事务合并到一次传输中性能会更好。3.4 AXS15260 初始化命令序列AXS15260 与常见 SPI LCD 类似都会用到以下命令0x11Sleep Out唤醒屏幕。0x36MADCTL设置扫描方向和颜色顺序。0x3A像素格式。0x21反色开关。0x29Display ON。下面是一份比较通用的初始化脚本可作为起点。注意不同厂家的 AXS15260 模组可能还会附带专属 Gamma 设置、电源设置等如果屏幕显示异常请优先找模组厂商拿初始化代码。void lcd_reset() { digitalWrite(LCD_RST, LOW); delay(50); digitalWrite(LCD_RST, HIGH); delay(120); } void lcd_panel_init() { lcd_reset(); lcd_write_cmd(0x11); // Sleep Out delay(120); lcd_write_cmd(0x36); // Memory Access Control uint8_t madctl 0x00; // 根据屏幕方向修改 lcd_write_data(madctl, 1); lcd_write_cmd(0x3A); // Pixel Format uint8_t pixfmt 0x55; // RGB565 lcd_write_data(pixfmt, 1); lcd_write_cmd(0x21); // Display Inversion ON delay(20); lcd_write_cmd(0x29); // Display ON delay(100); }如果屏幕显示偏蓝、偏红通常需要调整 MADCTL 的 RGB 顺序。如果颜色完全反相注释掉0x21即可。3.5 设置显示窗口LVGL 每次只刷新需要变化的区域因此驱动需要支持局部窗口设置。AXS15260 与大多数 SPI TFT 一样通过 CASET、RASET 设置窗口void lcd_set_window(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { uint8_t buf[4]; lcd_write_cmd(0x2A); // Column Address Set buf[0] x0 8; buf[1] x0 0xFF; buf[2] x1 8; buf[3] x1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2B); // Row Address Set buf[0] y0 8; buf[1] y0 0xFF; buf[2] y1 8; buf[3] y1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2C); // Memory Write }设置完窗口后立刻发送像素数据即可。数据量等于窗口宽度乘以高度再乘以每像素字节数RGB565 是 2 字节。4. LVGL 9 移植与适配4.1 LVGL 9 的显示驱动注册方式LVGL 9 不再使用lv_disp_drv_t而是用lv_display_t对象。核心流程如下#include lvgl.h static lv_display_t *disp; void lvgl_display_init() { lv_init(); lv_display_create(480, 800); disp lv_display_get_default(); lv_display_set_flush_cb(disp, lvgl_flush_cb); lv_display_set_buffers(disp, buf1, buf2, sizeof(buf1), LV_DISPLAY_RENDER_MODE_PARTIAL); }在 LVGL 9 中lv_display_create()会自动设置为默认 display因此后面可以使用lv_display_get_default()取出。当然也可以在创建时直接保存返回值disp lv_display_create(480, 800);LV_DISPLAY_RENDER_MODE_PARTIAL表示应用部分渲染模式LVGL 会基于传入的缓冲区大小自动拆分刷新区域。4.2 缓冲区的选择LVGL 需要一个内存区域作为绘制缓冲。对于 480x800 屏幕如果画一整帧需要480 * 800 * 2 768000字节约 750KB。如果只使用 1/10 屏幕例如480 * 80需要480 * 80 * 2 76800字节约 75KB。ESP32-S3 的 SRAM 通常 512KB但运行系统、协议栈、LVGL 本身也要占用内存所以整帧缓冲并不现实。更稳妥的方案是在 PSRAM 中申请两个局部缓冲static lv_color_t *buf1; static lv_color_t *buf2; void lvgl_buffer_init() { size_t buf_size 480 * 80 * sizeof(lv_color_t); buf1 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); buf2 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); }使用 PSRAM 缓冲区时SPI 写入仍然会先把小段数据搬运到 DMA 可访问的内存。如果追求更高性能可以结合 DMA 描述符池来做本文不展开工程优化部分会提到方向。4.3 Flush 回调的实现LVGL 9 的 flush 回调原型如下static void lvgl_flush_cb(lv_display_t *display, const lv_area_t *area, uint8_t *px_map)其中area表示需要刷新的区域px_map是 LVGL 渲染好的像素数据。实现思路把区域坐标传给 AXS15260。写入px_map中的全部像素数据。调用lv_display_flush_ready(display)通知 LVGL 刷新完成。代码如下static void lvgl_flush_cb(lv_display_t *display, const lv_area_t *area, uint8_t *px_map) { uint32_t w area-x2 - area-x1 1; uint32_t h area-y2 - area-y1 1; lcd_set_window(area-x1, area-y1, area-x2, area-y2); lcd_write_data(px_map, w * h * sizeof(lv_color_t)); lv_display_flush_ready(display); }这里的lv_color_t默认是uint16_t前提是 LVGL 的LV_COLOR_DEPTH设置为 16。在底板配置中也需要把 AXS15260 的像素格式设置为 RGB565两者必须一致。如果在后续调试中屏幕出现颜色分层、条纹重点检查这个对应关系。4.4 时间基准LVGL 需要知道当前时间用来运行动画和控件刷新。在 Arduino 环境中可以直接把millis()注册为 tick 回调lv_tick_set_cb(millis);也可以使用定时器中断定期调用lv_tick_inc()但示例中使用回调更简洁。4.5 LVGL 8 与 LVGL 9 关键差异对照很多从旧项目迁移的人会卡在这一步。这里列一个常用对照表功能LVGL 8.xLVGL 9.x注册显示驱动lv_disp_drv_tlv_disp_drv_register()lv_display_create()lv_display_set_flush_cb()刷新完成lv_disp_flush_ready()lv_display_flush_ready()获取当前屏幕lv_scr_act()lv_screen_active()设置缓冲区lv_disp_draw_buf_init()lv_display_set_buffers()时间回调lv_tick_inc()lv_tick_set_cb()如果你在编译时看到lv_disp_drv_t未定义说明使用的头文件是 LVGL 9却还在写 LVGL 8 的代码。5. 完整 Arduino 示例5.1 完整 main.cpp下面给出一个可以直接编译运行的 Arduino 示例包含SPI 与 GPIO 初始化AXS15260 面板初始化LVGL 9 显示驱动移植一个简单的文字居中界面#include Arduino.h #include SPI.h #include lvgl.h #define LCD_SCK 12 #define LCD_MOSI 11 #define LCD_CS 10 #define LCD_DC 9 #define LCD_RST 8 #define LCD_BL 7 #define SPI_FREQ 40000000 #define H_RES 480 #define V_RES 800 static lv_color_t *buf1; static lv_color_t *buf2; void lcd_write_cmd(uint8_t cmd) { digitalWrite(LCD_DC, LOW); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.write(cmd); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); } void lcd_write_data(const uint8_t *data, size_t len) { digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.writeBytes(data, len); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); } void lcd_reset() { digitalWrite(LCD_RST, LOW); delay(50); digitalWrite(LCD_RST, HIGH); delay(120); } void lcd_panel_init() { lcd_reset(); lcd_write_cmd(0x11); // Sleep Out delay(120); lcd_write_cmd(0x36); // Memory Access Control uint8_t madctl 0x00; lcd_write_data(madctl, 1); lcd_write_cmd(0x3A); // Pixel Format uint8_t pixfmt 0x55; // RGB565 lcd_write_data(pixfmt, 1); lcd_write_cmd(0x21); // Display Inversion ON delay(20); lcd_write_cmd(0x29); // Display ON delay(100); } void lcd_set_window(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { uint8_t buf[4]; lcd_write_cmd(0x2A); buf[0] x0 8; buf[1] x0 0xFF; buf[2] x1 8; buf[3] x1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2B); buf[0] y0 8; buf[1] y0 0xFF; buf[2] y1 8; buf[3] y1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2C); } static void lvgl_flush_cb(lv_display_t *display, const lv_area_t *area, uint8_t *px_map) { uint32_t w area-x2 - area-x1 1; uint32_t h area-y2 - area-y1 1; lcd_set_window(area-x1, area-y1, area-x2, area-y2); lcd_write_data(px_map, w * h * sizeof(lv_color_t)); lv_display_flush_ready(display); } void setup() { Serial.begin(115200); delay(200); pinMode(LCD_CS, OUTPUT); pinMode(LCD_DC, OUTPUT); pinMode(LCD_RST, OUTPUT); pinMode(LCD_BL, OUTPUT); digitalWrite(LCD_CS, HIGH); digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_RST, HIGH); digitalWrite(LCD_BL, HIGH); SPI.begin(LCD_SCK, -1, LCD_MOSI, -1); lcd_panel_init(); size_t buf_size H_RES * 80 * sizeof(lv_color_t); buf1 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); buf2 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); lv_init(); lv_tick_set_cb(millis); lv_display_t *disp lv_display_create(H_RES, V_RES); lv_display_set_flush_cb(disp, lvgl_flush_cb); lv_display_set_buffers(disp, buf1, buf2, buf_size, LV_DISPLAY_RENDER_MODE_PARTIAL); // 简单界面测试 lv_obj_t *scr lv_screen_active(); lv_obj_set_style_bg_color(scr, lv_color_hex(0x1E1E2E), 0); lv_obj_t *label lv_label_create(scr); lv_label_set_text(label, ESP32-S3\n480x800\nLVGL 9); lv_obj_set_style_text_color(label, lv_color_hex(0xCDD6F4), 0); lv_obj_set_style_text_font(label, lv_font_montserrat_28, 0); lv_obj_center(label); Serial.println(LVGL 9 start); } void loop() { lv_timer_handler(); delay(5); }5.2 运行验证步骤在 Arduino IDE 中选择开发板为 ESP32S3 Dev Module。开启 PSRAM选择 OPI PSRAM 或 QIO Flash具体根据板子型号选择。通过 Arduino 库管理器安装 LVGL版本选择 9.x。编译并上传。打开串口监视器波特率 115200看到LVGL 9 start后屏幕应显示居中的文字。如果屏幕显示白屏先检查 RST、电源、CS、DC 是否接线正确再检查背光是否点亮。如果屏幕有背光但无画面通常是初始化命令序列不匹配或者 SPI 时钟过高。5.3 修改屏幕方向如果你想横屏显示需要同时修改两个地方AXS15260 的 MADCTL 值。LVGL 的显示分辨率参数lv_display_create(800, 480)。常见 MADCTL 值方向MADCTL分辨率竖屏0x00480x800横屏0x60 或 0xA0800x480旋转180°0xC0480x800具体值取决于屏幕模组默认扫描方向和像素排列可以在0x00、0x60、0xC0、0xA0之间试验。6. 常见问题与排查思路6.1 问题速查表问题现象常见原因解决思路白屏无任何显示背光未点亮、RST时序不对、初始化失败先单独点亮背光再检查初始化日志和命令序列背光亮但屏幕无内容SPI 接线错误、CS/DC 接反用万用表确认 GPIO 电平交换测试 CS/DC花屏、彩色条纹像素格式不匹配、SPI 时序不稳定检查0x3A是否设置为0x55降低 SPI 时钟颜色反转反色命令配置不对关闭或开启0x21字体颜色偏紫或偏绿RGB BGR 顺序不对修改 MADCTL 中的 RGB/BGR 位刷新卡顿、动画掉帧缓冲区太小、SPI 时钟太低增大 LVGL 缓冲区和 PSRAM开启 DMA编译报错lv_disp_drv_t未定义使用了 LVGL 8 API把代码改成lv_display_tAPI6.2 白屏排查清单白屏是最常见的问题我这里给出一个固定排查顺序确认 VCC 和 GND 正常使用万用表测量屏幕电源引脚。确认背光引脚有高电平如果背光电流大单独供电。确认 RST 引脚高电平低电平会让屏幕保持在复位状态。用逻辑分析仪抓取 CS、SCK、MOSI确认是否有命令发送。将 SPI 频率降低到 10MHz 测试排除信号质量干扰。逐个替换初始化命令中的 MADCTL、像素格式、反色配置。6.3 flush 永远不完成如果 LVGL 界面停在第一帧或者卡死最常见原因是 flush 回调里没有调用lv_display_flush_ready()。LVGL 会等待显示驱动确认这次刷新完成然后才继续下一次渲染。因此这个 API 是必须调用的不能省。6.4 PSRAM 内存不足如果编译或运行时提示 PSRAM 分配失败先检查menuconfig 是否开启了 PSRAM。开发板型号是否选择了带 PSRAM 的模块。是否使用了过大的缓冲区例如 1/4 屏的双缓冲。建议把缓冲区从 1/10 屏开始测试稳定后再逐步增大。7. 最佳实践与工程优化建议7.1 使用 DMA 和更高的 SPI 速率SPI 写入像素数据是性能瓶颈。ESP32-S3 的 SPI 外设支持 DMA使用 DMA 可以减轻 CPU 负担也能提高连续传输的稳定性。在 Arduino ESP32 中可以使用SPI.beginTransaction配合SPI.writeBytes进行批量传输如果想要进一步优化可以使用esp_lcd接口或者自己封装 SPI DMA 传输。硬件条件较好时可以把SPI_FREQ从 40MHz 提高到 80MHz。但要注意杜邦线过长可能导致时序抖动建议使用短排线或在 PCB 上走线。7.2 合理的 LVGL 缓冲区大小缓冲区越大LVGL 一次能处理的刷新区域越大碎片化重绘越少动画越流畅。缓冲区太大又会挤占内存并可能导致 PSRAM 带宽不足。我的建议是低端场景1/20 屏例如 480x40 双缓冲约 38KB 每个。推荐场景1/10 屏例如 480x80 双缓冲约 76KB 每个。动画要求高1/6 屏到 1/4 屏根据剩余 PSRAM 调整。7.3 避免频繁全屏刷新LVGL 本身已经很智能地只刷新脏区域但某些写法会强制整屏刷新。例如给 screen 反复设置 background 颜色、不断创建和删除大控件都会引起大面积重绘。正确做法是尽量复用对象更新标签文本时使用lv_label_set_text()不要每次重新创建。7.4 背光的处理背光可以一直固定高电平也可以使用 LEDC PWM 做亮度调节。示例中直接digitalWrite(LCD_BL, HIGH)适合快速验证。工程产品里建议把背光控制交给 PWM并且做成可调亮度菜单。7.5 从 Arduino 迁移到 ESP-IDF如果你的目标是量产或复杂系统推荐迁移到 ESP-IDF esp_lcdesp_lvgl_port。ESP-IDF 的esp_lcd组件对 SPI LCD 做了抽象可以简化 DMA 和中断处理而且esp_lvgl_port组件能自动完成 LVGL 9 的显示驱动注册。迁移时主要改动点SPI.begin()换成spi_bus_initialize()和spi_bus_add_device()。底层的SPI.writeBytes()替换为 SPI 事务spi_device_polling_transmit()可选用spi_device_queue_trans()做异步传输。flush 回调中通过lv_display_flush_ready()通知 LVGL这部分逻辑保持不变。使用 PSRAM 时通过heap_caps_malloc(MALLOC_CAP_SPIRAM)分配缓冲区。8. 总结与下一步学习方向到这里你已经完成了一套从零开始驱动 3.97 寸 AXS15260 屏幕并移植 LVGL 9 的流程。整个过程涉及三个核心点通过 SPI 正确初始化 AXS15260 屏幕模组理解命令、数据、DC 引脚之间的关系。使用 LVGL 9 的lv_display_create()、lv_display_set_buffers()、lv_display_flush_ready()完成显示驱动注册。根据屏幕分辨率和内存情况选择合适的缓冲区策略并通过局部刷新保证流畅度。如果你实际接线与本文示例不同只需要修改引脚宏定义如果初始化效果不对优先排查 MADCTL 和像素格式如果动态界面卡顿重点调整 SPI 时钟、DMA 和缓冲区大小。接下来可以继续深入的方向包括为屏幕增加 FT5x06 / CST8xx 等电容触摸驱动并把 LVGL 输入设备注册为触摸屏。学习 LVGL 9 的 Flex 布局和 Grid 布局用来搭建复杂 HMI 页面。把代码迁移到 ESP-IDF结合esp_lcd实现更稳定的批量数据发送。使用 PSRAM 加载更多字体和图片资源提升界面表现力。这套驱动框架不只限于 AXS15260很多基于标准 SPI 命令的 TFT LCD 都可以按照同样的思路适配。实际项目中建议先从一块屏跑通最小系统再逐步叠加业务界面和交互逻辑这样排查问题会更容易。
ESP32-S3驱动AXS15260 480x800屏并移植LVGL 9实战指南
在基于 ESP32-S3 做 HMI 项目时屏幕尺寸往往是最让人纠结的地方。常见的 1.3 寸、1.8 寸、2.4 寸 SPI 屏适合做卡片式界面但一遇到复杂仪表盘、多列表设置页或多行图表就显得拥挤。最近我在调试一块 3.97 寸 480x800 分辨率的 AXS15260 屏幕并把它接入 LVGL 9踩了不少坑也整理出了一套可以复用的驱动与移植流程。本文会完整拆解 ESP32-S3 与 AXS15260 的接线、SPI 初始化、LCM 驱动代码、LVGL 9 的缓冲与刷新机制并给出可复制的 Arduino 示例。最后还会列出高频报错与优化建议供做产品落地时参考。1. 背景与核心概念1.1 为什么选择 3.97 寸 480x800 屏幕在很多嵌入式 GUI 项目中屏幕尺寸和分辨率决定界面表达力。信息密度480x800 在 3.97 寸屏幕上能展示完整的一屏状态栏 多行列表 按钮区适合做智能家居控制面板、小型收银终端、桌面摆件、工业设备操作屏。视觉体验1080x2400 手机屏在 MCU 上驱动成本很高而 480x800 在 ESP32-S3 上可以通过 SPI 接口跑起来并且配合 LVGL 9 可以做出接近原生 App 的动效。开发成本不需要复杂的 RGB 接口电路也不需要 MIPI DSI只要 4 根 SPI 信号线加电源线就能驱动。AXS15260 就是这类 3.97 寸 480x800 液晶面板中常见的驱动控制芯片。它把行列驱动、Gamma 校正、显存刷新等功能集成在屏幕模组内部MCU 只需要通过 SPI 发送命令和像素数据即可。相比老旧的 ST7789、ILI9341 等控制器AXS15260 主要面向高分辨率小尺寸屏对 SPI 带宽要求更高也更需要合理的 LVGL 缓冲策略。1.2 LVGL 9 是什么LVGLLight and Versatile Graphics Library是一个面向嵌入式系统的开源图形库提供控件、布局、动画、事件系统、主题等完整 GUI 能力。LVGL 9 是目前较新的版本对比 LVGL 8.x 的变化非常明显显示驱动从lv_disp_drv_t改为lv_display_t。使用lv_display_create()创建显示实例不再使用lv_disp_drv_register()。flush 回调签名发生了变化刷新完成需要调用lv_display_flush_ready()。屏幕对象相关 API 改名例如lv_scr_act()变成了lv_screen_active()。内置渲染器做了重构绘制性能更强软件渲染路径也更有针对性。所以很多以前针对 LVGL 8 编写的屏幕驱动代码直接拿到 LVGL 9 里会编译不过。这也是本文专门基于 LVGL 9 写适配代码的原因。1.3 SPI 接口在驱动大屏时的特殊性AXS15260 这类高分辨率 SPI 屏和普通小屏的最大区别是数据量480x800 RGB565 一帧数据约 768KB。即使 LVGL 只刷新局部区域联动动画时也会持续产生大量 SPI 写入。SPI 时钟频率、DMA 是否启用、缓冲区分块大小直接决定最终帧率。如果照搬 ST7789 小屏驱动把整帧缓冲放在内部 RAM 里ESP32-S3 的 512KB SRAM 会非常紧张而且刷新一帧需要很长时间。所以本文示例采用“部分缓冲 双缓冲 局部刷新”的策略这也是 LVGL 官方推荐的跑法。2. 环境准备与接线说明2.1 推荐硬件清单硬件型号/说明主控板ESP32-S3-DevKitC 或任意 ESP32-S3 开发板建议带 PSRAM显示屏3.97 寸 480x800 TFTAXS15260 驱动芯片SPI 接口杜邦线/排线尽量短SPI 信号线建议控制在 10cm 内稳压/背光电源3.3V 主电源背光电流较大时可独立供电需要注意有些 AXS15260 模组是 QSPI 接口有些是标准 4 线 SPI。本文以标准 4 线 SPI 为例接线前务必确认你的屏幕丝印和数据手册。如果你的开发板丝印与本文引脚不一致请按实际引脚调整代码中的宏定义。2.2 引脚接线表这里给出一个比较常用的 ESP32-S3 接法作为示例屏幕引脚ESP32-S3 引脚说明VCC / VDD3V3屏幕逻辑电源GNDGND电源地SCL / SCKGPIO 12SPI 时钟SDA / MOSIGPIO 11SPI 主机输出CS / SSGPIO 10片选信号DC / RSGPIO 9数据/命令选择RST / RESGPIO 8复位信号BLK / BLGPIO 7背光控制可 PWM如果你的模块命名不同例如将 SCL 写作 CLK、将 SDA 写作 DIN含义相同。2.3 引脚选择注意事项ESP32-S3 的 SPI 外设比较灵活大多数 GPIO 都能复用为 SPI 信号。但实际接线时要注意尽量避开连接 boot 模式的 GPIO0、GPIO46避免下载和启动异常。如果使用 PSRAM某些 GPIO 已经被 Flash/PSRAM 占用需要查阅开发板原理图。避免与 USB 的 D-/D 冲突否则插线调试时可能影响下载。信号线不要跨过晶振、电源模块等干扰源。在本文示例中我刻意避免使用 GPIO0、GPIO45、GPIO46 等敏感引脚这是一套相对稳妥的组合。2.4 软件环境版本建议不同软件版本差异很大本文示例按以下环境验证软件/工具建议版本Arduino IDE2.xesp32 Arduino 核心2.0.x 或 3.xLVGL 库9.x推荐 9.2 以上显示屏模组AXS15260 480x800 SPI开发板ESP32-S3-DevKitC8MB PSRAM如果你的环境版本不同例如使用 ESP-IDF 或 PlatformIO驱动思路一致只是编译和初始化方式会有差异。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。3. SPI 初始化与 AXS15260 显示驱动3.1 基础流程驱动一块 SPI 屏幕的完整流程可以拆成四步初始化 GPIO设置 DC、CS、RST、BL 的输出状态。初始化 SPI 外设设置时钟、数据位序、SPI 模式。对 AXS15260 发送初始化命令序列。通过 CASET、RASET、RAMWR 命令写入像素。后面所有操作都围绕这四步展开。3.2 引脚与 SPI 初始化代码在 Arduino 环境中先定义引脚#define LCD_SCK 12 #define LCD_MOSI 11 #define LCD_CS 10 #define LCD_DC 9 #define LCD_RST 8 #define LCD_BL 7 #define SPI_FREQ 40000000 // 40MHz可根据模组调整到 80MHz然后初始化void lcd_gpio_init() { pinMode(LCD_CS, OUTPUT); pinMode(LCD_DC, OUTPUT); pinMode(LCD_RST, OUTPUT); pinMode(LCD_BL, OUTPUT); digitalWrite(LCD_CS, HIGH); digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_RST, HIGH); digitalWrite(LCD_BL, HIGH); } void lcd_spi_init() { SPI.begin(LCD_SCK, -1, LCD_MOSI, -1); }SPI 的MISO参数传-1因为这类屏通常只写不读可以省一根信号线。3.3 命令写入与数据写入LCD 工作需要区分命令和数据由 DC 引脚控制DC 为低电平时SPI 上发送的是命令。DC 为高电平时SPI 上发送的是数据。下面封装两个基础函数void lcd_write_cmd(uint8_t cmd) { digitalWrite(LCD_DC, LOW); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.write(cmd); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); } void lcd_write_data(const uint8_t *data, size_t len) { digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.writeBytes(data, len); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); }这里每次都调用beginTransaction/endTransaction是为了避免多线程或中断干扰 SPI 配置。刷新大区域时也可以把事务合并到一次传输中性能会更好。3.4 AXS15260 初始化命令序列AXS15260 与常见 SPI LCD 类似都会用到以下命令0x11Sleep Out唤醒屏幕。0x36MADCTL设置扫描方向和颜色顺序。0x3A像素格式。0x21反色开关。0x29Display ON。下面是一份比较通用的初始化脚本可作为起点。注意不同厂家的 AXS15260 模组可能还会附带专属 Gamma 设置、电源设置等如果屏幕显示异常请优先找模组厂商拿初始化代码。void lcd_reset() { digitalWrite(LCD_RST, LOW); delay(50); digitalWrite(LCD_RST, HIGH); delay(120); } void lcd_panel_init() { lcd_reset(); lcd_write_cmd(0x11); // Sleep Out delay(120); lcd_write_cmd(0x36); // Memory Access Control uint8_t madctl 0x00; // 根据屏幕方向修改 lcd_write_data(madctl, 1); lcd_write_cmd(0x3A); // Pixel Format uint8_t pixfmt 0x55; // RGB565 lcd_write_data(pixfmt, 1); lcd_write_cmd(0x21); // Display Inversion ON delay(20); lcd_write_cmd(0x29); // Display ON delay(100); }如果屏幕显示偏蓝、偏红通常需要调整 MADCTL 的 RGB 顺序。如果颜色完全反相注释掉0x21即可。3.5 设置显示窗口LVGL 每次只刷新需要变化的区域因此驱动需要支持局部窗口设置。AXS15260 与大多数 SPI TFT 一样通过 CASET、RASET 设置窗口void lcd_set_window(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { uint8_t buf[4]; lcd_write_cmd(0x2A); // Column Address Set buf[0] x0 8; buf[1] x0 0xFF; buf[2] x1 8; buf[3] x1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2B); // Row Address Set buf[0] y0 8; buf[1] y0 0xFF; buf[2] y1 8; buf[3] y1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2C); // Memory Write }设置完窗口后立刻发送像素数据即可。数据量等于窗口宽度乘以高度再乘以每像素字节数RGB565 是 2 字节。4. LVGL 9 移植与适配4.1 LVGL 9 的显示驱动注册方式LVGL 9 不再使用lv_disp_drv_t而是用lv_display_t对象。核心流程如下#include lvgl.h static lv_display_t *disp; void lvgl_display_init() { lv_init(); lv_display_create(480, 800); disp lv_display_get_default(); lv_display_set_flush_cb(disp, lvgl_flush_cb); lv_display_set_buffers(disp, buf1, buf2, sizeof(buf1), LV_DISPLAY_RENDER_MODE_PARTIAL); }在 LVGL 9 中lv_display_create()会自动设置为默认 display因此后面可以使用lv_display_get_default()取出。当然也可以在创建时直接保存返回值disp lv_display_create(480, 800);LV_DISPLAY_RENDER_MODE_PARTIAL表示应用部分渲染模式LVGL 会基于传入的缓冲区大小自动拆分刷新区域。4.2 缓冲区的选择LVGL 需要一个内存区域作为绘制缓冲。对于 480x800 屏幕如果画一整帧需要480 * 800 * 2 768000字节约 750KB。如果只使用 1/10 屏幕例如480 * 80需要480 * 80 * 2 76800字节约 75KB。ESP32-S3 的 SRAM 通常 512KB但运行系统、协议栈、LVGL 本身也要占用内存所以整帧缓冲并不现实。更稳妥的方案是在 PSRAM 中申请两个局部缓冲static lv_color_t *buf1; static lv_color_t *buf2; void lvgl_buffer_init() { size_t buf_size 480 * 80 * sizeof(lv_color_t); buf1 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); buf2 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); }使用 PSRAM 缓冲区时SPI 写入仍然会先把小段数据搬运到 DMA 可访问的内存。如果追求更高性能可以结合 DMA 描述符池来做本文不展开工程优化部分会提到方向。4.3 Flush 回调的实现LVGL 9 的 flush 回调原型如下static void lvgl_flush_cb(lv_display_t *display, const lv_area_t *area, uint8_t *px_map)其中area表示需要刷新的区域px_map是 LVGL 渲染好的像素数据。实现思路把区域坐标传给 AXS15260。写入px_map中的全部像素数据。调用lv_display_flush_ready(display)通知 LVGL 刷新完成。代码如下static void lvgl_flush_cb(lv_display_t *display, const lv_area_t *area, uint8_t *px_map) { uint32_t w area-x2 - area-x1 1; uint32_t h area-y2 - area-y1 1; lcd_set_window(area-x1, area-y1, area-x2, area-y2); lcd_write_data(px_map, w * h * sizeof(lv_color_t)); lv_display_flush_ready(display); }这里的lv_color_t默认是uint16_t前提是 LVGL 的LV_COLOR_DEPTH设置为 16。在底板配置中也需要把 AXS15260 的像素格式设置为 RGB565两者必须一致。如果在后续调试中屏幕出现颜色分层、条纹重点检查这个对应关系。4.4 时间基准LVGL 需要知道当前时间用来运行动画和控件刷新。在 Arduino 环境中可以直接把millis()注册为 tick 回调lv_tick_set_cb(millis);也可以使用定时器中断定期调用lv_tick_inc()但示例中使用回调更简洁。4.5 LVGL 8 与 LVGL 9 关键差异对照很多从旧项目迁移的人会卡在这一步。这里列一个常用对照表功能LVGL 8.xLVGL 9.x注册显示驱动lv_disp_drv_tlv_disp_drv_register()lv_display_create()lv_display_set_flush_cb()刷新完成lv_disp_flush_ready()lv_display_flush_ready()获取当前屏幕lv_scr_act()lv_screen_active()设置缓冲区lv_disp_draw_buf_init()lv_display_set_buffers()时间回调lv_tick_inc()lv_tick_set_cb()如果你在编译时看到lv_disp_drv_t未定义说明使用的头文件是 LVGL 9却还在写 LVGL 8 的代码。5. 完整 Arduino 示例5.1 完整 main.cpp下面给出一个可以直接编译运行的 Arduino 示例包含SPI 与 GPIO 初始化AXS15260 面板初始化LVGL 9 显示驱动移植一个简单的文字居中界面#include Arduino.h #include SPI.h #include lvgl.h #define LCD_SCK 12 #define LCD_MOSI 11 #define LCD_CS 10 #define LCD_DC 9 #define LCD_RST 8 #define LCD_BL 7 #define SPI_FREQ 40000000 #define H_RES 480 #define V_RES 800 static lv_color_t *buf1; static lv_color_t *buf2; void lcd_write_cmd(uint8_t cmd) { digitalWrite(LCD_DC, LOW); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.write(cmd); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); } void lcd_write_data(const uint8_t *data, size_t len) { digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_CS, LOW); SPI.beginTransaction(SPISettings(SPI_FREQ, MSBFIRST, SPI_MODE0)); SPI.writeBytes(data, len); SPI.endTransaction(); digitalWrite(LCD_CS, HIGH); } void lcd_reset() { digitalWrite(LCD_RST, LOW); delay(50); digitalWrite(LCD_RST, HIGH); delay(120); } void lcd_panel_init() { lcd_reset(); lcd_write_cmd(0x11); // Sleep Out delay(120); lcd_write_cmd(0x36); // Memory Access Control uint8_t madctl 0x00; lcd_write_data(madctl, 1); lcd_write_cmd(0x3A); // Pixel Format uint8_t pixfmt 0x55; // RGB565 lcd_write_data(pixfmt, 1); lcd_write_cmd(0x21); // Display Inversion ON delay(20); lcd_write_cmd(0x29); // Display ON delay(100); } void lcd_set_window(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { uint8_t buf[4]; lcd_write_cmd(0x2A); buf[0] x0 8; buf[1] x0 0xFF; buf[2] x1 8; buf[3] x1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2B); buf[0] y0 8; buf[1] y0 0xFF; buf[2] y1 8; buf[3] y1 0xFF; lcd_write_data(buf, 4); lcd_write_cmd(0x2C); } static void lvgl_flush_cb(lv_display_t *display, const lv_area_t *area, uint8_t *px_map) { uint32_t w area-x2 - area-x1 1; uint32_t h area-y2 - area-y1 1; lcd_set_window(area-x1, area-y1, area-x2, area-y2); lcd_write_data(px_map, w * h * sizeof(lv_color_t)); lv_display_flush_ready(display); } void setup() { Serial.begin(115200); delay(200); pinMode(LCD_CS, OUTPUT); pinMode(LCD_DC, OUTPUT); pinMode(LCD_RST, OUTPUT); pinMode(LCD_BL, OUTPUT); digitalWrite(LCD_CS, HIGH); digitalWrite(LCD_DC, HIGH); digitalWrite(LCD_RST, HIGH); digitalWrite(LCD_BL, HIGH); SPI.begin(LCD_SCK, -1, LCD_MOSI, -1); lcd_panel_init(); size_t buf_size H_RES * 80 * sizeof(lv_color_t); buf1 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); buf2 (lv_color_t *)heap_caps_malloc(buf_size, MALLOC_CAP_SPIRAM); lv_init(); lv_tick_set_cb(millis); lv_display_t *disp lv_display_create(H_RES, V_RES); lv_display_set_flush_cb(disp, lvgl_flush_cb); lv_display_set_buffers(disp, buf1, buf2, buf_size, LV_DISPLAY_RENDER_MODE_PARTIAL); // 简单界面测试 lv_obj_t *scr lv_screen_active(); lv_obj_set_style_bg_color(scr, lv_color_hex(0x1E1E2E), 0); lv_obj_t *label lv_label_create(scr); lv_label_set_text(label, ESP32-S3\n480x800\nLVGL 9); lv_obj_set_style_text_color(label, lv_color_hex(0xCDD6F4), 0); lv_obj_set_style_text_font(label, lv_font_montserrat_28, 0); lv_obj_center(label); Serial.println(LVGL 9 start); } void loop() { lv_timer_handler(); delay(5); }5.2 运行验证步骤在 Arduino IDE 中选择开发板为 ESP32S3 Dev Module。开启 PSRAM选择 OPI PSRAM 或 QIO Flash具体根据板子型号选择。通过 Arduino 库管理器安装 LVGL版本选择 9.x。编译并上传。打开串口监视器波特率 115200看到LVGL 9 start后屏幕应显示居中的文字。如果屏幕显示白屏先检查 RST、电源、CS、DC 是否接线正确再检查背光是否点亮。如果屏幕有背光但无画面通常是初始化命令序列不匹配或者 SPI 时钟过高。5.3 修改屏幕方向如果你想横屏显示需要同时修改两个地方AXS15260 的 MADCTL 值。LVGL 的显示分辨率参数lv_display_create(800, 480)。常见 MADCTL 值方向MADCTL分辨率竖屏0x00480x800横屏0x60 或 0xA0800x480旋转180°0xC0480x800具体值取决于屏幕模组默认扫描方向和像素排列可以在0x00、0x60、0xC0、0xA0之间试验。6. 常见问题与排查思路6.1 问题速查表问题现象常见原因解决思路白屏无任何显示背光未点亮、RST时序不对、初始化失败先单独点亮背光再检查初始化日志和命令序列背光亮但屏幕无内容SPI 接线错误、CS/DC 接反用万用表确认 GPIO 电平交换测试 CS/DC花屏、彩色条纹像素格式不匹配、SPI 时序不稳定检查0x3A是否设置为0x55降低 SPI 时钟颜色反转反色命令配置不对关闭或开启0x21字体颜色偏紫或偏绿RGB BGR 顺序不对修改 MADCTL 中的 RGB/BGR 位刷新卡顿、动画掉帧缓冲区太小、SPI 时钟太低增大 LVGL 缓冲区和 PSRAM开启 DMA编译报错lv_disp_drv_t未定义使用了 LVGL 8 API把代码改成lv_display_tAPI6.2 白屏排查清单白屏是最常见的问题我这里给出一个固定排查顺序确认 VCC 和 GND 正常使用万用表测量屏幕电源引脚。确认背光引脚有高电平如果背光电流大单独供电。确认 RST 引脚高电平低电平会让屏幕保持在复位状态。用逻辑分析仪抓取 CS、SCK、MOSI确认是否有命令发送。将 SPI 频率降低到 10MHz 测试排除信号质量干扰。逐个替换初始化命令中的 MADCTL、像素格式、反色配置。6.3 flush 永远不完成如果 LVGL 界面停在第一帧或者卡死最常见原因是 flush 回调里没有调用lv_display_flush_ready()。LVGL 会等待显示驱动确认这次刷新完成然后才继续下一次渲染。因此这个 API 是必须调用的不能省。6.4 PSRAM 内存不足如果编译或运行时提示 PSRAM 分配失败先检查menuconfig 是否开启了 PSRAM。开发板型号是否选择了带 PSRAM 的模块。是否使用了过大的缓冲区例如 1/4 屏的双缓冲。建议把缓冲区从 1/10 屏开始测试稳定后再逐步增大。7. 最佳实践与工程优化建议7.1 使用 DMA 和更高的 SPI 速率SPI 写入像素数据是性能瓶颈。ESP32-S3 的 SPI 外设支持 DMA使用 DMA 可以减轻 CPU 负担也能提高连续传输的稳定性。在 Arduino ESP32 中可以使用SPI.beginTransaction配合SPI.writeBytes进行批量传输如果想要进一步优化可以使用esp_lcd接口或者自己封装 SPI DMA 传输。硬件条件较好时可以把SPI_FREQ从 40MHz 提高到 80MHz。但要注意杜邦线过长可能导致时序抖动建议使用短排线或在 PCB 上走线。7.2 合理的 LVGL 缓冲区大小缓冲区越大LVGL 一次能处理的刷新区域越大碎片化重绘越少动画越流畅。缓冲区太大又会挤占内存并可能导致 PSRAM 带宽不足。我的建议是低端场景1/20 屏例如 480x40 双缓冲约 38KB 每个。推荐场景1/10 屏例如 480x80 双缓冲约 76KB 每个。动画要求高1/6 屏到 1/4 屏根据剩余 PSRAM 调整。7.3 避免频繁全屏刷新LVGL 本身已经很智能地只刷新脏区域但某些写法会强制整屏刷新。例如给 screen 反复设置 background 颜色、不断创建和删除大控件都会引起大面积重绘。正确做法是尽量复用对象更新标签文本时使用lv_label_set_text()不要每次重新创建。7.4 背光的处理背光可以一直固定高电平也可以使用 LEDC PWM 做亮度调节。示例中直接digitalWrite(LCD_BL, HIGH)适合快速验证。工程产品里建议把背光控制交给 PWM并且做成可调亮度菜单。7.5 从 Arduino 迁移到 ESP-IDF如果你的目标是量产或复杂系统推荐迁移到 ESP-IDF esp_lcdesp_lvgl_port。ESP-IDF 的esp_lcd组件对 SPI LCD 做了抽象可以简化 DMA 和中断处理而且esp_lvgl_port组件能自动完成 LVGL 9 的显示驱动注册。迁移时主要改动点SPI.begin()换成spi_bus_initialize()和spi_bus_add_device()。底层的SPI.writeBytes()替换为 SPI 事务spi_device_polling_transmit()可选用spi_device_queue_trans()做异步传输。flush 回调中通过lv_display_flush_ready()通知 LVGL这部分逻辑保持不变。使用 PSRAM 时通过heap_caps_malloc(MALLOC_CAP_SPIRAM)分配缓冲区。8. 总结与下一步学习方向到这里你已经完成了一套从零开始驱动 3.97 寸 AXS15260 屏幕并移植 LVGL 9 的流程。整个过程涉及三个核心点通过 SPI 正确初始化 AXS15260 屏幕模组理解命令、数据、DC 引脚之间的关系。使用 LVGL 9 的lv_display_create()、lv_display_set_buffers()、lv_display_flush_ready()完成显示驱动注册。根据屏幕分辨率和内存情况选择合适的缓冲区策略并通过局部刷新保证流畅度。如果你实际接线与本文示例不同只需要修改引脚宏定义如果初始化效果不对优先排查 MADCTL 和像素格式如果动态界面卡顿重点调整 SPI 时钟、DMA 和缓冲区大小。接下来可以继续深入的方向包括为屏幕增加 FT5x06 / CST8xx 等电容触摸驱动并把 LVGL 输入设备注册为触摸屏。学习 LVGL 9 的 Flex 布局和 Grid 布局用来搭建复杂 HMI 页面。把代码迁移到 ESP-IDF结合esp_lcd实现更稳定的批量数据发送。使用 PSRAM 加载更多字体和图片资源提升界面表现力。这套驱动框架不只限于 AXS15260很多基于标准 SPI 命令的 TFT LCD 都可以按照同样的思路适配。实际项目中建议先从一块屏跑通最小系统再逐步叠加业务界面和交互逻辑这样排查问题会更容易。