ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

LVGL 8.3.10 源码移植与 STM32 嵌入式GUI开发实战

LVGL 8.3.10 源码移植与 STM32 嵌入式GUI开发实战

简介:面向STM32等资源受限嵌入式平台的GUI开发源码包,版本为lvgl-8.3.10,适合单片机界面开发、嵌入式GUI入门学习、课程实践与项目移植参考。包内共1183个文件,以C源码和头文件为主体,辅以Python脚本、Markdown与RST文档、PNG/GIF图片、字体资源及多种构建配置,压缩包约24.51MB,覆盖图形库实现、演示素材、说明文档和跨平台工程样例。该版本提供按钮、图表、列表、滑动条、图片等模块化组件,并支持动画、抗锯齿、透明度、平滑滚动与图层混合等效果,可搭配触摸屏、键盘、编码器、按键等输入设备,且不依赖特定硬件平台。已有1824人学习下载,读者可据此梳理组件组织方式、移植配置流程、主题与字体资源管理,以及示例工程的结构关系,为嵌入式界面开发和效果验证提供较完整的参考,也便于在资源受限设备上评估界面方案与交互效果。

1. 一块 240×320 的屏先把话说清:lvgl-8.3.10 源码包到底解决什么问题

上个月在实验室帮人看一块 2.8 寸 240×320 的 SPI 屏,对方用裸机逐点画汉字的方案已经写到第三版,字模塞进 Flash 吃掉大半空间,改一次布局要重算一遍坐标。这类活我一般直接劝人换 GUI 库,lvgl-8.3.10 这个源码包就是我会递过去的那一份:它本身不是成品界面,也不带任何行业模板,而是一套面向嵌入式设计、按对象树组织的界面框架,按钮、标签、列表、图表、动画、样式、事件这些基础件都在里面,源码全给,STM32 这类单片机挂一块屏就能跑起来。适合三类人:正在给单片机选界面方案、手里有现成 STM32 工程要接屏、以及打算把 LVGL 当成自家产品 UI 底座做长期二次开发的人。它省掉的不是设计能力,而是从零写一套控件库、渲染器和事件分发的那几个月。

2. 解压之后先翻哪几页:lvgl-8.3.10 的目录结构与刷新链路

拿到源码包别急着往工程里塞。先把目录过一遍,知道哪几个文件是必须动的、哪几个目录是可以整块忽略的,后面接显示和触摸时心里才有地图。8.3.10 这一版的结构比较规整,src 下按职责切得很细,移植相关的东西集中在 hal 和 examples/porting 两处。

2.1 目录树里真正要动的只有三处

解压出来的顶层长这样,我给每个目录补了一句人话注释:

lvgl-8.3.10/ ├── src/ │ ├── core/ # 对象树、事件、样式、定时器、动画,整个框架的地基 │ ├── draw/ # 软件渲染、脏区计算、位图绘制、GPU 接口 │ ├── font/ # 内置字模 + 字体解析(含 binfont) │ ├── hal/ # 显示、输入、文件系统、时间等抽象接口 │ ├── misc/ # 双向链表、内存池、数学工具、printf │ ├── widgets/ # btn/label/slider/chart/table/textarea 等控件 │ └── extra/ # flex、grid 布局、主题、第三方库封装 ├── examples/ │ └── porting/ # lv_port_disp_template.c / lv_port_indev_template.c ├── demos/ # 官方演示,用来验证移植是否成功 ├── docs/ # 离线文档 ├── lv_conf_template.h # 配置模板,复制成 lv_conf.h 再改 ├── lvgl.h # 唯一对外头文件 ├── CMakeLists.txt ├── Kconfig └── env_support/ # cmake / make / rt-thread 等构建脚本

真正需要你动手的只有三处:把lv_conf_template.h复制成lv_conf.h并放到能被 include 到的路径;从examples/porting里把显示和输入的模板文件拷出来改;把src目录整体加入编译。剩下的 examples、demos、docs 都可以先不参与构建,等界面跑通了再挑一个 demo 丢进去做压力测试。

2.2 一次界面刷新在内部走了哪几步

LVGL 的心跳模型是「主循环里轮询 + 脏区重绘」,理解这条链路,后面白屏、花屏、卡顿的排查全靠它。

应用层调用lv_obj_set_pos()、lv_label_set_text()这类接口修改对象属性时,框架并不会立刻画屏,而是把该对象所在的区域标记为脏区(invalid area)。随后主循环里调用的lv_timer_handler()会检查刷新的时间片是否到期,到期后把脏区合并、裁剪,逐块调用绘制函数把像素写进你提供的 draw buffer,最后回调你实现的flush_cb,由你把这块像素搬进 LCD 显存。搬完之后必须调用lv_disp_flush_ready(),否则框架会一直认为 DMA 没传完,界面就停在那不动了。

这条链路上有三个隐含约定。第一,flush_cb必须在像素真正送出去之后(或 DMA 传输完成中断里)才能调 ready,早调会花屏,晚调会掉帧。第二,脏区是以对象为粒度的,一个全屏背景对象被改一下,脏区就是整屏,所以背景尽量用静态图或样式,别在定时器里反复改。第三,渲染和刷屏是两个线程视角的东西,如果你在中断里改对象属性,一定记得加lv_timer_handler的临界保护,不然会出现链表被踩的玄学崩溃。

2.3 lv_conf.h 里先改的四个宏

配置项有上百个,第一次移植先只盯这几个,其余的等跑起来再说:

宏典型取值作用与后果
LV_COLOR_DEPTH16必须和你的 LCD 像素格式一致,写错就是花屏
LV_COLOR_16_SWAP0 或 1决定 RGB565 的高低字节序,SPI 屏常见要开 1
LV_MEM_SIZE32~64 KB对象和样式全从这块静态堆里分配,给小了会创建失败
LV_DISP_DEF_REFR_PERIOD30 ms刷新周期,帧率上限由它和刷屏耗时共同决定
LV_USE_LOG1(调试期)断言和错误日志走LV_LOG_USER,排查期很有用

LV_COLOR_DEPTH和LV_COLOR_16_SWAP是最容易翻车的两个,它们不匹配时不会报错,只是屏上出现颜色错乱的条纹。我的习惯是先在配置里把这两个值写死,再写一个纯色矩形铺满全屏,颜色对了再往下做界面。

2.4 和 emWin、TouchGFX、裸机画点比一比

选型这事不用绕弯子,把几个常见方案的边界摆出来就清楚了:

方案授权上手成本适用场景
裸机画点 + 字模无低,但功能全靠自己写只做几行参数显示的小设备
emWin商业授权,随芯片附带中已有授权、团队熟悉其 API
TouchGFX绑定特定平台生态中高,需要设计工具链产品外观要求高、有 UI 设计师
LVGL 8.3.10开源,源码全给中,文档和示例齐全中小团队快速做出可维护的嵌入式界面

LVGL 的优势不在性能极限,而在「源码可见 + 控件齐全 + 社区示例多」。出了问题能顺着src/core往下读,这在嵌入式项目里比什么都值钱。它的劣势也要说清楚:默认软件渲染,对 MCU 主频和内存有基本要求,低端 8 位机上跑不动,至少得是一颗几十兆主频、带几十 KB RAM 的 Cortex-M 核。

3. 挪到 STM32 上跑通:显示、触摸、心跳三条线一次接通

移植这件事拆开看就是三条线:显示线负责把像素送出去,触摸线负责把坐标读回来,心跳线负责给框架提供时间基准和调度入口。三条线任何一条没接上,表现都是「屏是黑的」或者「点了没反应」,所以建议一条一条单独验证,别一次性全接完再调。

3.1 把源码包并进工程:三种常见构建方式

工程组织上我一般把 LVGL 放在工程根目录的Middlewares/LVGL下,源码目录整块加入编译,配置头文件放上一层,保证lvgl.h里能 include 到它。

YourProject/ ├── Core/ ├── Drivers/ ├── Middlewares/ │ └── LVGL/ │ ├── lvgl/ # 源码包原样放这 │ └── lv_conf.h # 从模板复制,改完放这 ├── App/ │ ├── ui/ │ └── port/ │ ├── lv_port_disp.c │ └── lv_port_indev.c └── MDK-ARM/ 或 build/

Keil 下就是新建一个 Group,把src下除src/extra里用不到的部分全部 Add 进去,头文件路径加上lvgl和lv_conf.h所在目录;GCC/CMake 下直接把env_support/cmake里的脚本 include 进来就行。注意lv_conf.h只要一份,不要出现源码包里自带的模板和工程里改过的版本同时被搜到,那种情况下编译器会莫名其妙地用了默认配置,你会对着「我明明改了内存大小」怀疑人生。

第一次编译的目标不是跑界面,而是编译通过、链接不报未定义符号。常见缺失是lv_tick_get相关的实现,如果你开了LV_TICK_CUSTOM就必须提供对应的宏,否则乖乖用lv_tick_inc()。

3.2 lv_conf.h 的落地配置

以下是我在 STM32 + 16 位 SPI 屏上常用的一段配置,注释里写清了为什么这么取值:

/* lv_conf.h:只列出移植阶段最关键的几项 */ #define LV_COLOR_DEPTH 16 /* 与 LCD 的 RGB565 对齐 */ #define LV_COLOR_16_SWAP 1 /* SPI 屏按字节发送,需交换高低字节 */ #define LV_MEM_CUSTOM 0 /* 用 LVGL 自带的静态内存池,省去对接 malloc */ #define LV_MEM_SIZE (48U * 1024U) /* 界面越复杂越大,先给 48K 观察余量 */ #define LV_MEM_ADR 0 /* 0 表示由链接器分配,也可指向外部 SDRAM 地址 */ #define LV_DISP_DEF_REFR_PERIOD 30 /* 刷新周期 30ms,约 33fps 上限 */ #define LV_INDEV_DEF_READ_PERIOD 30 /* 触摸采样周期 */ #define LV_USE_LOG 1 /* 调试期打开,正式版关掉省空间 */ #define LV_USE_ASSERT_NULL 1 /* 空指针断言,排查野指针很有用 */ #define LV_USE_PERF_MONITOR 1 /* 屏角显示 CPU 占用和帧率,调优阶段必开 */ #define LV_FONT_MONTSERRAT_14 1 /* 默认字体,界面基础字号 */ #define LV_USE_FLEX 1 #define LV_USE_GRID 1

几点补充说明。LV_MEM_SIZE的估算方法是:每个对象大约几十字节,每个样式几十字节,一张 240×320 的全屏位图如果是 16 位色就要 150KB,所以大图千万别按全屏缓存,要么压缩成二进制文件按需解码,要么直接用外部存储。LV_USE_PERF_MONITOR打开后屏幕上会飘一个小角标,显示当前帧率和 CPU 占用,压测时非常直观,正式发布前记得关。

3.3 显示驱动:flush_cb 加上双缓冲

显示移植的核心是三个动作:初始化 draw buffer、填 flush 回调、注册显示设备。

/* lv_port_disp.c:显示驱动骨架 */ static lv_disp_draw_buf_t draw_buf; static lv_color_t buf_1[MY_DISP_HOR_RES * 20]; /* 20 行大小的局部缓冲 */ static lv_color_t buf_2[MY_DISP_HOR_RES * 20]; /* 第二块,交给 DMA 后台搬运 */ static void disp_flush(lv_disp_drv_t *drv, const lv_area_t *area, lv_color_t *color_p) { uint32_t w = lv_area_get_width(area); uint32_t h = lv_area_get_height(area); uint32_t px = w * h; LCD_SetWindow(area->x1, area->y1, area->x2, area->y2); /* 设定显示窗口 */ LCD_WritePixels_DMA((uint16_t *)color_p, px); /* 异步发像素 */ /* 关键:DMA 传完之前不能调 ready,否则框架会覆盖这块缓冲 */ lv_disp_flush_ready(drv); } void lv_port_disp_init(void) { lv_disp_draw_buf_init(&draw_buf, buf_1, buf_2, MY_DISP_HOR_RES * 20); static lv_disp_drv_t disp_drv; lv_disp_drv_init(&disp_drv); disp_drv.hor_res = MY_DISP_HOR_RES; /* 240 */ disp_drv.ver_res = MY_DISP_VER_RES; /* 320 */ disp_drv.flush_cb = disp_flush; disp_drv.draw_buf = &draw_buf; lv_disp_drv_register(&disp_drv); }

lv_disp_draw_buf_init的第四个参数是缓冲区的像素个数,不是字节数。缓冲区越大,一次刷新的行数越多,SPI 传输的连续段越长,帧率越稳;但双缓冲会占用两倍 RAM,像上面 240 宽 × 20 行 × 2 字节 × 2 块大约是 19KB,对 64KB RAM 的片子勉强可以。如果 RAM 紧张,可以只传buf_1、buf_2传NULL,退化成单缓冲,代价是刷屏期间 CPU 不能同时写缓冲,大范围重绘会看到明显的撕裂感。

提示:如果你的屏用了 DMA 并且不想阻塞 CPU,就把lv_disp_flush_ready()挪到 DMA 传输完成中断里调用,flush_cb 里只负责启动传输。这样 LVGL 渲染和刷屏能并行,帧率提升很明显,但中断和主循环共享缓冲区的临界区必须处理好。

3.4 触摸驱动:read_cb 与坐标标定

输入驱动的回调返回的是「当前这一刻的坐标和按下状态」,LVGL 会自己在内部做按压去抖和手势判断。

/* lv_port_indev.c:触摸读取回调 */ static void touch_read(lv_indev_drv_t *drv, lv_indev_data_t *data) { static lv_coord_t last_x = 0, last_y = 0; uint16_t raw_x, raw_y; if (TP_IsPressed()) { TP_GetRawXY(&raw_x, &raw_y); last_x = map_axis(raw_x, TP_X_MIN, TP_X_MAX, 0, MY_DISP_HOR_RES - 1); last_y = map_axis(raw_y, TP_Y_MIN, TP_Y_MAX, 0, MY_DISP_VER_RES - 1); >/* 1ms 定时器中断里喂时间 */ void SysTick_Handler(void) { HAL_IncTick(); lv_tick_inc(1); /* 少调一次,动画就会变慢;多调一次,动画就会飞速 */ } /* 主循环:按框架返回的下次到期时间决定睡多久 */ int main(void) { HAL_Init(); SystemClock_Config(); LCD_Init(); TP_Init(); lv_init(); lv_port_disp_init(); lv_port_indev_init(); ui_init(); /* 建界面 */ while (1) { uint32_t idle = lv_timer_handler(); /* 返回值是距离下次任务的毫秒数 */ if (idle > 0) { HAL_Delay(idle > 5 ? 5 : idle); /* 上限 5ms,保证外设任务也能跑到 */ } App_Poll(); /* 业务轮询,别写阻塞操作 */ } }

lv_timer_handler()的返回值是「距离下一个定时任务还有多少毫秒」,合理利用它可以让 CPU 在不必要的时候进低功耗。但注意不要真的睡满它返回的时长,因为你的串口收包、按键扫描也在主循环里,我一般封顶 5ms,兼顾响应和功耗。如果用了 RTOS,就把这一段放进一个独立任务,优先级设成中等,栈给到 2KB 以上,因为lv_timer_handler的调用链不算浅。

4. 界面代码怎么落笔:对象树、样式、事件与动画的写法

移植通了之后,接下来写的才是业务代码。LVGL 的编程模型和前端框架很像:一切都是对象,对象挂在父对象下面形成树,样式负责外观,事件负责交互,定时器和动画负责动态变化。这个模型不难,但有几个坑点在写法上绕不开。

4.1 对象树:从 lv_scr_act 开始搭第一个卡片

每个显示设备默认有一块活动屏幕,用lv_scr_act()拿到,所有界面元素都挂在它下面,或者挂在它的子对象下面。父子关系不只是布局上的从属,还决定了坐标、可见性和事件冒泡:父对象移动,子对象跟着走;父对象删除,子对象一起销毁。

static lv_obj_t *g_card; static lv_obj_t *g_title; static lv_obj_t *g_value; void ui_init(void) { lv_obj_t *scr = lv_scr_act(); lv_obj_set_style_bg_color(scr, lv_color_hex(0x0F172A), 0); /* 卡片:父对象是屏幕 */ g_card = lv_obj_create(scr); lv_obj_set_size(g_card, 200, 120); lv_obj_center(g_card); /* 相对父对象居中 */ /* 标题:父对象是卡片,坐标相对卡片左上角 */ g_title = lv_label_create(g_card); lv_label_set_text(g_title, "TEMP"); lv_obj_align(g_title, LV_ALIGN_TOP_LEFT, 12, 10); g_value = lv_label_create(g_card); lv_label_set_text(g_value, "--.- C"); lv_obj_align(g_value, LV_ALIGN_CENTER, 0, 10); }

lv_obj_create()默认创建的是基础容器,带圆角、边框和背景,很多人第一次写界面发现「怎么多了一圈灰边」,就是没意识到默认样式。lv_obj_set_size在 8.x 里其实是宽度和高度的组合封装,如果只想改一个维度,用lv_obj_set_width和lv_obj_set_height更清楚。坐标 API 里的LV_ALIGN_*是相对父对象的对齐点,加偏移量就能微调,这比手算绝对坐标可维护得多。

4.2 布局:flex 和 grid 什么时候比 set_pos 省事

界面上一行按钮、一列参数的时候,别再一个个算坐标。8.3 里的 flex 布局和 CSS 的 flex 思路一致,写起来很省。

/* 让容器里的子对象横向排列,间距 8,内容居中 */ lv_obj_set_layout(g_card, LV_LAYOUT_FLEX); lv_obj_set_flex_flow(g_card, LV_FLEX_FLOW_ROW); lv_obj_set_flex_align(g_card, LV_FLEX_ALIGN_SPACE_EVENLY, /* 主轴分布 */ LV_FLEX_ALIGN_CENTER, /* 交叉轴对齐 */ LV_FLEX_ALIGN_CENTER); /* 轨道对齐 */ lv_obj_set_style_pad_all(g_card, 12, 0); lv_obj_set_style_pad_column(g_card, 8, 0); /* 子对象之间的列间距 */

flex 的好处是增删子对象时不用重新排坐标,删掉一个按钮后面的自动补位。grid 更适合做仪表盘那种九宫格布局,用lv_obj_set_grid_dsc_array()定义行高列宽,再给每个子对象指定lv_obj_set_grid_cell()的起止行列。我的经验是:一排或一列用 flex,二维矩阵用 grid,绝对定位只留给背景图和装饰元素。

一个容易踩的坑是 flex 容器里的子对象还带着默认的LV_SIZE_CONTENT尺寸行为,某些控件不设宽高会被压扁。真遇到布局结果和预期不一致,先把容器的pad、子对象的min_width打出来看,多数是尺寸约束在打架。

4.3 样式系统:把颜色、圆角、边框收进一个 lv_style_t

直接在对象上调用lv_obj_set_style_*写得多了会非常散,改一个主题色要翻半天。正确姿势是定义独立的lv_style_t,一次性 add 到需要的对象上。

static lv_style_t style_card; static lv_style_t style_card_pressed; void ui_style_init(void) { lv_style_init(&style_card); lv_style_set_bg_color(&style_card, lv_color_hex(0x1E293B)); lv_style_set_bg_opa(&style_card, LV_OPA_COVER); lv_style_set_radius(&style_card, 10); lv_style_set_border_width(&style_card, 0); lv_style_set_text_color(&style_card, lv_color_hex(0xE2E8F0)); /* 按下态:只覆盖和默认态不一样的部分 */ lv_style_init(&style_card_pressed); lv_style_set_bg_color(&style_card_pressed, lv_color_hex(0x334155)); lv_obj_add_style(g_card, &style_card, LV_STATE_DEFAULT); lv_obj_add_style(g_card, &style_card_pressed, LV_STATE_PRESSED); }

样式是按状态叠加的,LV_STATE_PRESSED只写和默认态不同的属性,其余自动继承,这比在每个回调里改颜色干净得多。样式对象要放在静态区或全局区,因为 LVGL 只保存指针不拷贝内容,声明成局部变量会在函数返回后失效,表现是界面随机变色或崩溃,这个坑挺多人踩。

主题方面,lv_theme_default_init()可以统一设定主色、次色和深色模式,自定义样式会覆盖主题值,所以顺序是先初始化主题,再 add 自定义样式。想要整体换肤,把颜色抽成几个宏或一个颜色表,比散落在各处的十六进制值强太多。

4.4 事件回调:lv_event_get_target 与 user_data

交互全靠事件回调。注册时把处理函数和一个用户数据指针挂上去,回调里通过 API 取回来。

typedef struct { uint8_t ch; uint16_t value; } btn_ctx_t; static void btn_event_cb(lv_event_t *e) { lv_event_code_t code = lv_event_get_code(e); lv_obj_t *target = lv_event_get_target(e); btn_ctx_t *ctx = (btn_ctx_t *)lv_event_get_user_data(e); switch (code) { case LV_EVENT_CLICKED: app_on_button(ctx->ch, ctx->value); /* 交给业务层,不在 UI 层写逻辑 */ break; case LV_EVENT_LONG_PRESSED: app_on_long_press(ctx->ch); break; default: break; } } void ui_bind_button(lv_obj_t *btn, btn_ctx_t *ctx) { lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_CLICKED, ctx); lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_LONG_PRESSED, ctx); }

lv_event_get_target返回触发事件的对象,如果事件是冒泡上来的,用lv_event_get_current_target拿到当前处理者。用户数据指针的生命周期要长于控件,我一般把上下文结构体挂成静态数组,按控件索引取,避免动态分配和野指针。事件回调里千万不要做耗时操作,比如写 Flash、发长报文,回调执行期间界面是卡住的,这些活丢到定时器或业务任务里去。

4.5 定时器与动画:状态刷新和过渡效果

LVGL 的定时器不是硬件定时器,而是挂在心跳上的软件定时器,由lv_timer_handler统一驱动,所以回调里不能长时间阻塞。

/* 每 500ms 刷新一次数值显示 */ static void refresh_timer_cb(lv_timer_t *t) { lv_obj_t *label = (lv_obj_t *)t->user_data; int32_t v = app_get_temperature_x10(); lv_label_set_text_fmt(label, "%d.%d C", v / 10, (v % 10 + 10) % 10); } void ui_start_refresh(void) { lv_timer_create(refresh_timer_cb, 500, g_value); /* 第三个参数是 user_data */ }

数值变化要做过渡效果时用动画系统,它同样跑在心跳上,按缓动曲线在指定时长内反复调用设值函数:

lv_anim_t a; lv_anim_init(&a); lv_anim_set_var(&a, g_value); /* 动画作用对象 */ lv_anim_set_values(&a, 0, 100); /* 起止值 */ lv_anim_set_time(&a, 800); /* 时长 ms */ lv_anim_set_path_cb(&a, lv_anim_path_ease_out); /* 缓动曲线 */ lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t)lv_bar_set_value); lv_anim_start(&a);

动画结束没有额外通知的话,用lv_anim_set_ready_cb挂个回调做收尾。注意动画对象被删除时要先lv_anim_del(obj, NULL),否则动画回调会访问已经释放的内存,现象是偶发死机,定位起来非常费劲。

4.6 中文字体与图片资源怎么塞进去

内置字体只有 ASCII,中文要自己转换。官方提供的字体转换工具可以按需生成指定字号、指定字符集的 C 文件,只把你界面上真正用到的汉字打进去,体积能控制在几十 KB。

/* 转换出来的字体文件里通常已声明 lv_font_t my_font_16,这里显式引用 */ LV_FONT_DECLARE(my_font_16); void ui_use_cn_font(lv_obj_t *label) { lv_obj_set_style_text_font(label, &my_font_16, 0); }

LV_FONT_DECLARE是声明宏,必须和字体文件里的符号名一致。字符集建议直接用界面文案文本文件喂给转换工具,避免漏字;字体选思源黑体这类开源字体,注意授权条款。

图片资源用转换工具转成 C 数组后整形成lv_img_dsc_t,注意数组前四个字节是 LVGL 的头信息(宽、高、色彩格式),转换工具会一起生成,不要手动截断。位图大就用外部存储 + 文件系统,按需读取解码,别一次性全加载到 RAM。

5. 调试台前的常见问题:白屏、花屏、死机、中文方框的五次翻车记录

下面这几条是我在移植和调试阶段真实遇到过的,按「现象 → 原因 → 解决」的顺序写,遇到类似症状可以按图索骥。

5.1 上电白屏,什么也不显示

现象:程序能跑,串口有日志,屏背光亮但全白,或者全黑无内容。

原因:最常见是lv_timer_handler()没被调用,或者flush_cb里忘了调lv_disp_flush_ready()。另一个高频原因是显示设备的hor_res和ver_res填反了,脏区计算直接越界。还有一种是 draw buffer 声明成局部变量,lv_port_disp_init返回后缓冲区失效。

解决:先确认主循环里确实调用了lv_timer_handler,可以在这行打个断点看会不会停住;再检查 flush 回调是否被触发,最简单的办法是在disp_flush里翻转一个 GPIO,用示波器看有没有脉冲。缓冲区必须是静态或全局的,并且大小传的是像素个数。最后核对分辨率和 LCD 实际扫描方向,两者不一致时画面会出现只刷了一部分的现象。

5.2 界面出来了,但颜色是花的

现象:控件位置和形状都对,颜色却像负片或红蓝互换。

原因:LV_COLOR_DEPTH和 LCD 的像素格式不匹配,或者LV_COLOR_16_SWAP没有按屏幕要求设置。SPI 屏按字节发送,高位字节在前还是低位字节在前,取决于屏的控制器,配错就是颜色错乱。还有一种情况是 flush 里强制转成uint16_t *,但实际缓冲区类型不是 16 位色。

解决:先铺一个纯红矩形,看图上是红还是蓝,来判断是通道顺序问题还是字节序问题。红蓝互换一般是 RGB 和 BGR 的顺序差异,在初始化 LCD 控制器时调换即可;颜色整体发暗或发紫,基本就是字节序反了,把LV_COLOR_16_SWAP取反再试。改完记得全量重编译,这个宏会影响很多头文件的展开,增量编译有时不生效。

5.3 触摸能点,但坐标偏得离谱

现象:点击按钮左侧十像素,实际触发的是右侧的控件;或者纵向坐标整个反向。

原因:触摸控制器的原始坐标范围没有做映射,或者映射的min/max标定值不对。电阻屏还存在 X 轴反向的情况,以及屏幕旋转后触摸没有同步旋转。

解决:写一个临时界面,在read_cb里把原始坐标通过串口打出来,手动点四角记录极值,修正映射函数的参数。旋转屏幕时,触摸坐标也要跟着做一次变换,横屏和竖屏的互换是x' = 屏高 - y这类公式,别只转了显示忘了转输入。最后确认lv_indev_drv_t.type是LV_INDEV_TYPE_POINTER,类型填错时点击行为会很怪。

5.4 跑几分钟后卡死或重启

现象:界面正常跑一段时间后僵住,或者直接进 HardFault。

原因:内存池耗尽导致对象创建失败,或者栈溢出。前者表现为界面某次刷新后不再变化,lv_mem_monitor能看到 used 接近 total;后者多见于事件回调里定义了很大的局部数组,或者lv_timer_handler的调用链超过任务栈。还有一种隐蔽情况是中断里操作了 LVGL 对象,链表被并发改写。

解决:把LV_USE_PERF_MONITOR和LV_USE_MEM_MONITOR打开,运行一段时间看内存曲线是否持续上涨,涨了就是有对象没删除。栈的问题用调试器看 MSP 水位,或者把主任务栈临时加大一倍验证。中断里只置标志位,所有 UI 操作回到主循环执行,这条规矩最好写进代码规范里。

5.5 中文显示成方框或问号

现象:英文数字正常,汉字显示成方块。

原因:字体没换,或者转换字体时没有把对应汉字打进字符集,也可能LV_FONT_DECLARE声明的符号名和实际生成的不一致导致链接到了默认字体。

解决:先用lv_obj_set_style_text_font显式指定自定义字体,确认链接的是自己的字体文件;再在字体转换时把界面上所有文案统一收集成一个文本文件作为字符集输入。如果只有个别字是方块,那就是字符集漏了;如果整段都是方块,说明字体根本没生效。

5.6 编译报一堆未定义符号或空间不够

现象:链接阶段提示某个lv_*函数找不到,或者代码段超出 Flash。

原因:源码目录没加全,或者lv_conf.h里关掉了某个功能宏却在代码里用了对应控件。空间不够多半是字体和图片资源太大,或者把 demos 也编进去了。

解决:先确认lvgl/src下所有.c都进了工程,缺哪个补哪个;再检查LV_USE_*系列宏和代码里用到的控件是否对应。空间紧张时优先砍字体字号和图片数量,把不用的控件宏关掉,效果很明显。

6. 二次开发怎么不返工:把界面层和业务层切开的改造路径

接手别人写的 LVGL 代码,最难受的不是控件用得不熟,而是界面和业务缠在一起:按钮回调里直接读传感器、写 Flash、发串口,改一个界面要通读整个工程。想把这份源码包用成自家产品的 UI 底座,第一件事是把层次切开。

我的做法是分三层:port层只放显示、触摸、心跳这些和硬件强相关的文件,换屏时只改这一层;ui层只负责创建控件、绑定事件、暴露刷新接口,不包含任何业务判断;app层处理数据、状态机和通信。ui对外只暴露两类函数,一类是ui_init()、ui_set_value()这样的入口,另一类是事件回调里转调的业务函数,中间用函数指针或弱符号解耦,这样界面可以在 PC 模拟器上单独跑起来调试,不用每次都烧板子。

/* ui/ui_port.h:业务层实现,UI 层只声明 */ typedef struct { void (*on_btn_click)(uint8_t id); void (*on_value_req)(uint8_t id, int32_t *out); } ui_app_if_t; void ui_set_app_if(const ui_app_if_t *iface); void ui_set_value(uint8_t id, int32_t value);

改造时第二个值得做的是把屏幕参数抽成配置。分辨率、色深、旋转方向、触摸标定值集中到一个头文件里,换硬件只改这一处。再往上一层,把控件创建过程封装成ui_create_card()、ui_create_list_row()这类工厂函数,界面结构调整时不用逐处修改。

验证方法上,我一般分三步走:先在 PC 上编译一份模拟器版本,把界面逻辑跑通,这一步能挡掉绝大部分样式和布局问题;再烧到板子上做压力测试,用定时器每 100ms 刷新一次数值,连续跑几个小时,同时打开性能监视器看内存和帧率曲线是否平稳;最后做异常场景验证,拔掉传感器、快速连点、断电重启,观察界面是否会因为数据异常崩溃。这套流程跑下来,后面换屏、换 MCU、加页面时踩的坑会少很多。

从那以后我每次接手新的界面需求,都会先花半小时把port、ui、app三个目录建好,再动手写第一个控件——这个习惯帮我省掉的返工时间,远大于它本身花的时间。希望帮到你。

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

返回列表