简介一套适用于 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 为例屏幕丝印作用接到主控VCC电源3.3VGND地GNDCS片选低有效PA4GPIO 输出RESET复位低有效PA2GPIO 输出DC / RS数据命令选择高为数据PA3GPIO 输出SDASPI 数据PA7SPI1_MOSISCKSPI 时钟PA5SPI1_SCKBLK / LED背光高有效PA1GPIO 输出我一般不会把 CS 绑到硬件 NSS 上而是用普通 GPIO 手动拉原因见后面 flush 的实现每次传输前要同时保证 DC、CS 电平正确硬件 NSS 在这种半双工写操作里反而是个累赘。供电上不确定模块是否带稳压就先接 3.3V背光引脚单独控制别和逻辑电源共用一个 GPIO 硬怼不然会出现一种玄学白屏时背光还亮着你以为是代码没跑其实是屏没初始化成功。2.2 LVGL 版本8.3 还是 9.xLVGL 当前主推 9.x渲染架构重构过但网上的移植例程、商家改好的驱动、各种组件包绝大多数还是按 8.3 写的。8.3 的显示驱动注册方式是lv_disp_drv_t结构体加lv_disp_drv_registerflush 回调签名固定踩坑记录一搜一大堆9.x 改成lv_display_create和lv_display_set_flush_cb回调参数类型也换了直接把 8.3 的代码拷过去是编不过的。对比项8.39.x显示驱动注册lv_disp_drv_t lv_disp_drv_registerlv_display_create lv_display_set_flush_cbflush 回调参数lv_disp_drv_t / lv_area_t / lv_color_tlv_display_t / lv_area_t / uint8_tset_px_cb存在逐点回调已移除网上例程数量非常多较少第一次移植我建议直接锁定 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_SIMPLE1然后把 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 是 MADCTLbit7 是上下镜像 MYbit6 是左右镜像 MXbit5 是行列交换 MVbit3 是 BGR 颜色顺序位。0x08 这个值对大多数 1.8 寸批次有效如果发现颜色偏色在 0x00、0x08、0xC8 三组里试会有一组颜色正常。这段初始化在竖直方向上省掉了 CASET/RASET因为 flush 回调里每帧都会重新设窗口初始化时保持一致即可。要注意的是如果你要做横屏 160×128MADCTL 要加 MV 位并且 LVGL 的分辨率要交换否则内容会被旋转出屏。3.3 flush 回调与区域寻址这是整个移植里最关键的一段。LVGL 每次刷新会先把无效区域渲染到一个内存缓冲里然后调用你注册的 flush 回调把这块区域的数据倒给屏幕。ST7735 通过 CASET0x2A、RASET0x2B、RAMWR0x2C三步完成区域写入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 喂 tickLVGL 的时间基准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 里的发送换成 DMAflush_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输入设备回调里返回按下状态即可十分钟能接完。内存精算表。这是最后的平衡点项目小 RAM 主控大 RAM 主控LV_MEM_SIZE8KB32KB显示缓冲2.5KB 单缓冲双缓冲各 10 行系统栈剩余约 9KB充足把那以后我每次换屏第一件事不再是抄例程而是先写一个 20px 色块在屏上横竖移动的自测页面确认坐标寻址和字节序没问题再碰业务界面。这套流程救过我不少次在换了三块不同批次的屏之后我现在连接线都强迫自己对着丝印核对一遍才上电。希望上面的记录能帮你少走几步弯路。本文还有配套的精品资源点击获取