128×160彩屏LVGL移植全攻略：从ST7735初始化到流畅刷新

简介：一套适用于 STM32 开发者的 LVGL 移植代码工程，目标是把中景园 1.8 寸 128×160 彩屏接入 LVGL，解决显示驱动适配、分辨率配置与界面初始化等问题。压缩包共 412 个文件，大小约 3.86MB，以 204 个 C 源文件与 183 个头文件为主体，另含 Makefile、Keil 工程文件、链接脚本与字体资源；目录按 USER、HARDWARE、Middlewares、STM32F10x_FWLib 划分，便于区分用户代码、底层硬件驱动、中间件和标准外设库。开发者可直接用 Keil MDK 打开参考工程，查看 LCD 驱动、LVGL 显示配置和 STM32F10x 外设调用方式，并借助 lv_font_simsun_16_cjk 等中文字体文件快速生成带中文菜单的界面。目前已有 811 人浏览学习，适合需要在小尺寸彩屏上做嵌入式 GUI，或希望系统掌握 LVGL 移植流程的开发者。

1. 移植前的清醒认知：128×160 跑 LVGL，到底在移植什么

把商家例程改成 LVGL 界面，中间隔着的不只是把 lvgl 源码文件夹拖进工程这一步。很多人手里都有那块 1.8 寸 128×160 SPI 彩屏，控制器是 ST7735，屏驱初始化做完、lv_conf.h 打开、flush 回调写完，按下复位键却只见半屏乱码或者干脆白屏。下面的内容按踩坑顺序拆开：引脚定义、lv_conf.h 关键开关、ST7735 初始化序列、flush 回调与 DMA 刷新、tick 心跳和 UI 验证，最后附上五条高频排查记录和一套改完就能落地的优化思路。适合手上有屏、想尽快跑通 LVGL 8.3 的 MCU 开发者，读完能把商家例程那层黑匣子剥开，知道哪一行改错了该往哪看。

2. 屏与库的对接：ST7735 引脚规划、LVGL 版本选型和工程骨架

2.1 这块屏的硬件底细

一块 1.8 寸 128×160 的 SPI 彩屏，引脚顺序各家略有不同，但丝印基本一致：VCC、GND、CS、RESET、DC、SDA、SCK、BLK，部分批次会把 DC 标成 RS，把 BLK 标成 LED。它走的是四线 SPI 加三根控制脚，数据线只有一根 MOSI，不需要 MISO。识别方法很简单：看控制器丝印，十几块钱的 1.8 寸模块十有八九是 ST7735 或 ST7735S，个别卖家会混用，所以下面的初始化序列严格来说只对 ST7735 家族有效。

典型接线表（以某 M3 内核主控的 SPI1 为例）：

我一般不会把 CS 绑到硬件 NSS 上，而是用普通 GPIO 手动拉，原因见后面 flush 的实现：每次传输前要同时保证 DC、CS 电平正确，硬件 NSS 在这种半双工写操作里反而是个累赘。供电上，不确定模块是否带稳压就先接 3.3V，背光引脚单独控制，别和逻辑电源共用一个 GPIO 硬怼，不然会出现一种玄学：白屏时背光还亮着，你以为是代码没跑，其实是屏没初始化成功。

2.2 LVGL 版本：8.3 还是 9.x

LVGL 当前主推 9.x，渲染架构重构过，但网上的移植例程、商家改好的驱动、各种组件包，绝大多数还是按 8.3 写的。8.3 的显示驱动注册方式是lv_disp_drv_t结构体加lv_disp_drv_register，flush 回调签名固定，踩坑记录一搜一大堆；9.x 改成lv_display_create和lv_display_set_flush_cb，回调参数类型也换了，直接把 8.3 的代码拷过去是编不过的。

第一次移植我建议直接锁定 8.3，比如 8.3.0 这个发布版。它不是功能最新，而是资料密度最大的版本，等这一块跑的顺了再升 9.x，否则你分不清是自己驱动没写好还是新 API 不熟。另外 8.3 对 C99 编译器和开源编译链都友好，MDK 工程、CMake 工程都能直接塞进去。

2.3 目录结构：把 lvgl 源码放进工程的三种姿势

推荐的做法是保持 lvgl 仓库结构不动，整包放进工程，编译时按需裁剪。项目结构大致长这样：

Project/ ├─ lvgl/ │ ├─ src/ │ ├─ demos/ # 不需要的话整体排除，省 Flash │ ├─ examples/ # 组件用法示例，可以保留 │ └─ lv_conf_template.h ├─ lv_conf.h # 从 template 拷出来改名，放工程根目录 ├─ Core/ │ ├─ Inc/ │ └─ Src/ │ ├─ main.c │ ├─ st7735.c # 屏驱：初始化 + set_window + 数据发送 │ └─ lvgl_port.c # LVGL 对接：draw_buf、disp_drv、tick └─ Drivers/

编译时把 lvgl/src 下所有 .c 加进工程，src根目录下的模板文件 lv_templ.c 可以排除；demos 默认不编译，examples 里只有你真正用到的组件才建议保留，否则 Flash 会多出几十 KB。.c文件的 include 路径要能同时找到 lvgl 根目录和 lv_conf.h 所在目录。

lv_conf.h 的查找机制是 8.3 里最容易卡住新手的地方：lvgl 内部靠LV_CONF_INCLUDE_SIMPLE这个编译宏决定用"lv_conf.h"这种相对 include 还是走绝对路径。我习惯在编译器预定义里加LV_CONF_INCLUDE_SIMPLE=1，然后把 lv_conf.h 放在工程根目录，这样最省事，也不会出现两个 lv_conf.h 互相打架的情况。

3. 核心移植实战：lv_conf.h 开关、初始化序列与 flush 回调

3.1 lv_conf.h：四个直接影响画面的开关

移植成败一半在这几个宏上。打开 lv_conf.h，先把下面四个改掉：

#define LV_COLOR_DEPTH 16 #define LV_COLOR_16_SWAP 0 #define LV_HOR_RES_MAX 128 #define LV_VER_RES_MAX 160 #define LV_MEM_SIZE (8 * 1024)

LV_COLOR_DEPTH 是像素格式，ST7735 原生就是 RGB565，所以必须设为 16。有人习惯照抄 32 位色的工程，结果在 1.8 寸屏上要么颜色发暗要么渲染特别慢，因为内部渲染器要多做一次颜色转换。

LV_COLOR_16_SWAP 控制的是小端主控上 RGB565 两个字节的存放顺序。先保持 0，等点亮后颜色不对再改成 1，这是排查偏色的第一级开关，比改 MADCTL 里的 BGR 位更直观。

LV_HOR_RES_MAX 和 LV_VER_RES_MAX 是编译期的尺寸上限，不是实际分辨率。实际分辨率在运行时通过disp_drv.hor_res和disp_drv.ver_res告诉 LVGL，这两个值只是让内部数组和宏展开有个定数可用。

LV_MEM_SIZE 是 LVGL 自己的内存池，所有对象、样式、动画都从这里分配。在只有 20KB RAM 的 M3 主控上，我给 8KB 内存池加 2.5KB 显示缓冲，再留出约 9KB 给系统栈和驱动；如果主控是 ESP32 这种内存宽裕的，直接给到 32KB 也不心疼。

3.2 ST7735 初始化序列：魔数背后是什么

商家例程里那一串初始化命令，核心就五条。抽出来看：

static void st7735_write_cmd(uint8_t cmd) { LCD_CS_LOW(); LCD_DC_LOW(); /* 命令模式：DC = 0 */ spi_write(&cmd, 1); LCD_CS_HIGH(); } static void st7735_write_data(uint8_t *buf, uint16_t len) { LCD_CS_LOW(); LCD_DC_HIGH(); /* 数据模式：DC = 1 */ spi_write(buf, len); LCD_CS_HIGH(); } void st7735_init(void) { LCD_RST_LOW(); delay_ms(20); LCD_RST_HIGH(); delay_ms(120); st7735_write_cmd(0x01); delay_ms(120); /* SWRESET 软件复位 */ st7735_write_cmd(0x11); delay_ms(120); /* SLPOUT 退出睡眠 */ uint8_t p; st7735_write_cmd(0x3A); p = 0x05; st7735_write_data(&p, 1); /* COLMOD: RGB565 */ st7735_write_cmd(0x36); p = 0x08; st7735_write_data(&p, 1); /* MADCTL: 竖屏 RGB 序 */ st7735_write_cmd(0x29); /* DISPON 开显示 */ }

RST 引脚必须先拉低再拉高，低电平保持至少 20ms，拉高后要等 120ms 让片上逻辑稳定，这两处延时不能省。0x3A 设成 0x05 表示 16 位色彩，和 LVGL 的 LV_COLOR_DEPTH 16 对应。0x36 是 MADCTL，bit7 是上下镜像 MY，bit6 是左右镜像 MX，bit5 是行列交换 MV，bit3 是 BGR 颜色顺序位。0x08 这个值对大多数 1.8 寸批次有效，如果发现颜色偏色，在 0x00、0x08、0xC8 三组里试，会有一组颜色正常。

这段初始化在竖直方向上省掉了 CASET/RASET，因为 flush 回调里每帧都会重新设窗口，初始化时保持一致即可。要注意的是，如果你要做横屏 160×128，MADCTL 要加 MV 位并且 LVGL 的分辨率要交换，否则内容会被旋转出屏。

3.3 flush 回调与区域寻址

这是整个移植里最关键的一段。LVGL 每次刷新会先把无效区域渲染到一个内存缓冲里，然后调用你注册的 flush 回调，把这块区域的数据倒给屏幕。ST7735 通过 CASET（0x2A）、RASET（0x2B）、RAMWR（0x2C）三步完成区域写入：

static void st7735_set_window(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { uint8_t d[4]; st7735_write_cmd(0x2A); d[0] = x0 >> 8; d[1] = x0 & 0xFF; d[2] = x1 >> 8; d[3] = x1 & 0xFF; st7735_write_data(d, 4); st7735_write_cmd(0x2B); d[0] = y0 >> 8; d[1] = y0 & 0xFF; d[2] = y1 >> 8; d[3] = y1 & 0xFF; st7735_write_data(d, 4); st7735_write_cmd(0x2C); /* RAMWR 开始写显存 */ } static void lvgl_flush_cb(lv_disp_drv_t *drv, const lv_area_t *area, lv_color_t *color_p) { int32_t w = area->x2 - area->x1 + 1; int32_t h = area->y2 - area->y1 + 1; st7735_set_window(area->x1, area->y1, area->x2, area->y2); /* color_p 是当前区域紧密排列的像素，行宽就是 w，没有跨行空隙 */ for (int32_t y = 0; y < h; y++) { st7735_write_data((uint8_t *)color_p, w * 2); /* 每像素 2 字节 */ color_p += w; } lv_disp_flush_ready(drv); }

这里最容易被绕进去的点：color_p 指向的是 area 这个脏区的像素数据，不是整屏数据。如果你的 flush 函数自作聪明地把 CASET/RASET 固定写成 0,0 到 127,159，那 LVGL 传进来的小区域数据就会被整体错位贴到屏上，表现出来就是半屏花、内容被切块。只有严格按 area 的坐标去 set_window，才和 LVGL 的渲染方式对得上。

lv_disp_flush_ready(drv)一定要在所有数据发送完之后调用。如果你用阻塞 SPI，在 spi_write 返回后调用；如果用 DMA，就得在传输完成中断里调用。不调用它，LVGL 会认为屏幕还在忙，后续所有渲染全部排队，整个界面像死了一样。

注册部分同样在 lvgl_port.c 里：

static lv_color_t buf[128 * 10]; static lv_disp_draw_buf_t draw_buf; static lv_disp_drv_t disp_drv; void lvgl_display_init(void) { st7735_init(); lv_disp_draw_buf_init(&draw_buf, buf, NULL, 128 * 10); lv_disp_drv_init(&disp_drv); disp_drv.draw_buf = &draw_buf; disp_drv.hor_res = 128; disp_drv.ver_res = 160; disp_drv.flush_cb = lvgl_flush_cb; lv_disp_drv_register(&disp_drv); }

缓冲数组开的是 128×10 像素，也就是 2560 字节。10 行是 F103 这种小内存主控的合理折中：太高占内存，太低每帧刷屏次数变多、速度肉眼可见地下降。内存宽裕的板子可以把第二块缓冲交给lv_disp_draw_buf_init的第三个参数，做成双缓冲，性能还能再往上顶一截。

3.4 set_px_cb：什么时候才需要

8.3 的移植模板里经常出现 set_px_cb，很多人照着抄完发现根本没被调用，就开始怀疑自己。实际上 set_px_cb 是逐点写入的兜底回调，ST7735 支持区域寻址，走 flush_cb 整块发送已经是最优路径，完全不需要注册它。只有当你用的显示控制器不支持 CASET/RASET 这种区域写入，或者显存缓冲小到极致、想用逐点绘制省 RAM 时，才会用到 set_px_cb。看到模板里有它就照抄，属于典型的画蛇添足，反而可能拖慢渲染。

4. 让界面动起来：tick 心跳、任务调度与验证页面

4.1 喂 tick：LVGL 的时间基准

LVGL 的动画、长按、超时全部依赖内部时钟，这个时钟不会自己走，必须由你在某处定时调用lv_tick_inc。最简单的做法是挂在系统滴答中断里：

void SysTick_Handler(void) { lv_tick_inc(1); /* 每 1ms 喂一次 */ }

不喂 tick 的典型症状不是白屏，而是界面能显示、但进度条不动，动画每隔很久才跳一下，整个 UI 像被卡住。这就是典型的“黑匣子”问题：看起来代码都执行了，其实是时间基准断了。tick 的间隔不需要精确到 1ms，你甚至可以每 5ms 调lv_tick_inc(5)，只要累计值和真实时间一致，动画速度就不会漂。

4.2 lv_timer_handler：主循环里的大管家

时间基准之外，LVGL 还需要一个周期性调度的入口。裸机工程里放在主循环：

while (1) { lv_timer_handler(); delay_ms(5); }

lv_timer_handler会检查内部计时，到点才执行刷新，默认刷新周期是 30ms，换算过来大概 33FPS。它不是调得越频繁越好，主循环里如果夹杂了长时的 SPI 阻塞传输，刷新周期会被拉长，表现出来就是滑动列表一卡一卡。

如果工程跑的是 FreeRTOS，就把这个循环搬进一个独立任务：

void lvgl_task(void *arg) { while (1) { lv_timer_handler(); vTaskDelay(pdMS_TO_TICKS(5)); } }

多任务下注意一点：别在多个任务里同时调 LVGL 的控件 API，需要在别的任务改界面时加一把互斥锁，或者统一发给这个任务处理。

4.3 验证移植的三个界面元素

移植完成后别急着做业务界面，先跑一个“自测页面”，能一次性确认文字渲染、动画节奏、刷新周期三个维度：

static void ui_demo(void) { lv_obj_t *scr = lv_scr_act(); lv_obj_t *label = lv_label_create(scr); lv_label_set_text(label, "LVGL 128x160"); lv_obj_align(label, LV_ALIGN_TOP_MID, 0, 10); lv_obj_t *bar = lv_bar_create(scr); lv_obj_set_size(bar, 110, 10); lv_obj_align(bar, LV_ALIGN_CENTER, 0, 10); lv_bar_set_range(bar, 0, 100); lv_anim_t a; lv_anim_init(&a); lv_anim_set_var(&a, bar); lv_anim_set_values(&a, 0, 100); lv_anim_set_time(&a, 2000); lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t)lv_bar_set_value); lv_anim_start(&a); }

label 能验证字体渲染、文字坐标对齐；进度条的动画能验证 tick 有没有喂、刷新周期是不是稳定。如果进度条不是平滑前进而是一顿一顿，先查 tick，再查主循环里有没有长阻塞。另外在 lv_conf.h 里把LV_USE_PERF_MONITOR和LV_USE_MEM_MONITOR都打开，屏幕右上角会显示实时 FPS 和内存占用，后面调缓冲高度、调刷新周期都靠这两个数字说话，比肉眼靠谱得多。

5. 避坑手册：五个高频翻车点的现象、原因与解决

5.1 满屏花屏、彩色噪点

现象：上电后满屏随机彩色噪点，或者刷出内容但像素明显错位。

原因：一是 SPI 速率设得太高，信号线上时序被拉坏；二是 RGB565 字节序反了，高低字节对调。

解决：先把 SPI 分频调到 4MHz 级别验证，确认没问题再逐步提频。偏色类问题优先翻LV_COLOR_16_SWAP，从 0 改 1，重新编译看效果。这两个变量互不干扰，可以分开排。

5.2 只显示半屏或内容整体错位

现象：只有上半屏有东西，下半屏黑，或者一个控件横跨两个区域被切成两半。

原因：flush 回调里 set_window 的坐标写得不对，最常见的是把 CASET/RASET 写死成整屏 (0,0)-(127,159)，LVGL 传进来的却是窗口区域 (x1,y1)-(x2,y2)，数据被整体错位贴图。

解决：flush 里必须把 area 的四个坐标原样传给 set_window。如果区域寻址是对的，还出现整体偏移几个像素，说明这个批次的 GRAM 坐标起点不是 0，在 set_window 里统一加偏移即可，别去改 init 序列。

5.3 画面撕裂、刷新时能看到两帧分界线

现象：滑动列表或动画刷新时，屏幕中间出现一条水平分界线，上下内容不是同一帧。

原因：显示缓冲只有一份，SPI 发送还没结束，主循环又触发了下一轮渲染，写显存和刷屏互相抢时间。另一个常见根因是lv_disp_flush_ready调用得太早，数据还没发完就告诉 LVGL 可以继续了。

解决：用两块 draw buffer，让 LVGL 渲染下一块缓冲和 SPI 发送当前缓冲重叠起来；如果不想动双缓冲，至少把 flush_ready 的调用时机放到 SPI 发送真正完成之后，阻塞模式下就是 spi_write 返回之后再调。

5.4 白屏或按复位才亮

现象：上电白屏，看起来程序没跑，手按一下复位键就正常了。

原因：RST 引脚没有显式控制，或者初始化里 RST 低电平保持时间太短，片上逻辑还没复位完。也有可能是 SLPOUT 之后等待时间不足就开显示了。

解决：RST 用 GPIO 显式控制，初始化时拉低 20ms 再拉高，并等待 120ms。0x11 退出睡眠后也要等 120ms，再发 0x29 开显示。背光 BLK 单独拉高，避免背光状态干扰你判断屏是否真的初始化成功。

5.5 颜色发暗、白色偏黄或红色偏紫

现象：整体颜色不对，白色不白，红色明显偏紫。

原因：LV_COLOR_DEPTH 设成了 32 位，或者 MADCTL 的 BGR 位和实际面板不匹配，也可能 LV_COLOR_16_SWAP 状态反了。

解决：先确认 LV_COLOR_DEPTH 是 16，再把 MADCTL 在 0x00、0x08、0xC8 三组里逐一试，最后才动 LV_COLOR_16_SWAP。按这个顺序排查，每改一处就刷一个纯色页面验证，不要一把全改然后再回头找原因。

6. 二次开发：从“能显示”到“能出货”的四个改动

DMA 接管 SPI 发送。阻塞 SPI 在空闲时还可以，做动画就露馅了。把 flush 里的发送换成 DMA，flush_ready 挪到 DMA 完成中断里调：

void HAL_SPI_TxCpltCallback(SPI_HandleTypeDef *hspi) { if (hspi->Instance == SPI1) { lv_disp_flush_ready(&disp_drv); } }

单缓冲下 LVGL 本来就会等 ready 再渲染下一块，所以不会踩缓冲区，发送期间主循环彻底解放，帧率能明显提一截。

双缓冲叠加 DMA。lv_disp_draw_buf_init(&draw_buf, buf1, buf2, 128 * 10)同时给两块缓冲，LVGL 渲染下一块的同时 DMA 在发送当前块，刷新率和 CPU 占用都能改善，代价是 2.5KB 额外 RAM。

按键接入。1.8 寸配电阻触摸意义不大，直接用 GPIO 按键注册一个LV_INDEV_TYPE_BUTTON输入设备，回调里返回按下状态即可，十分钟能接完。

内存精算表。这是最后的平衡点：

把那以后我每次换屏第一件事不再是抄例程，而是先写一个 20px 色块在屏上横竖移动的自测页面，确认坐标寻址和字节序没问题，再碰业务界面。这套流程救过我不少次，在换了三块不同批次的屏之后，我现在连接线都强迫自己对着丝印核对一遍才上电。希望上面的记录能帮你少走几步弯路。

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