1. LVGL 8.3.10 移植不是“复制粘贴”,而是把嵌入式 GUI 黑匣子亲手拧开:从源码结构到首次点亮的完整链路
你拿到 lvgl-8.3.10.zip,双击解压,拖进 Keil 或 STM32CubeIDE 工程里,点编译——然后满屏红色报错:lv_obj_t undeclared、lv_disp_drv_register not found、甚至 lv_conf.h: No such file or directory。别急着删工程重来。这不是 LVGL 本身有问题,而是你还没真正看清它怎么“呼吸”:LVGL 不是插件,它是一套需要你亲手接上“气管”(显示驱动)、“神经”(输入设备)和“大脑指令”(配置开关)的嵌入式 GUI 引擎。它的核心逻辑全在 src/ 目录里,但启动钥匙藏在 lv_conf.h 的一个 #if 0 里;它的控件像乐高积木,但每一块都依赖底层 hal/ 接口的精准对接;它的 examples/ 是照妖镜,跑不通就说明你的移植链路上至少断了一环。这篇实战笔记,不讲抽象概念,只带你从解压那一刻起,一步步把 lvgl-8.3.10 源码包拆解、定位、配置、接入、验证,直到 OLED 屏上跳出第一个按钮。适合所有正在为 STM32、GD32、ESP32 等 Cortex-M 系列 MCU 移植 LVGL 的嵌入式开发者——无论你是刚写完第一个 HAL_GPIO_TogglePin 的新手,还是被 lv_timer_handler 卡住三天的老手。我们只聚焦一件事:让 LVGL 在你的板子上,稳稳亮起来。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 拆解源码包:五分钟看懂 lvgl-8.3.10 目录结构与关键文件清单
LVGL 的源码包不是一堆杂乱文件,而是一个精心设计的模块化系统。跳过这一步直接往工程里塞代码,等于蒙眼装发动机——零件都在,但不知道哪根线该接哪里。必须花五分钟,把顶层目录结构刻进脑子里。这不是为了炫技,而是为了后续排查时能精准定位问题源头:是 core/ 的对象系统没初始化?还是 draw/ 的软件渲染器没启用?抑或是 hal/ 的显示接口根本没注册?下面这张表,就是你移植过程中的“地图”。
2.1 核心目录功能速查表:每个文件夹到底管什么?
| 目录路径 | 关键内容 | 必须加入工程? | 移植初期重点关注点 |
|---|---|---|---|
src/core/ |
对象系统 (lv_obj_t)、事件分发 (lv_event_send)、刷新调度 (lv_refr_task) |
✅ 必须 | lv_obj_create() 调用失败?先查这里是否完整包含 |
src/draw/ |
软件渲染引擎、图层管理、颜色混合算法 | ✅ 必须 | 屏幕显示乱码、颜色失真?大概率是 draw 配置或 hal 显示驱动问题 |
src/widgets/ |
按钮 (lv_btn)、标签 (lv_label)、图表 (lv_chart) 等所有 UI 控件 |
✅ 必须 | 创建控件无反应?确认 widgets 下对应 .c 文件已编译 |
src/hal/ |
硬件抽象层:lv_port_disp.c (显示)、lv_port_indev.c (输入) |
⚠️ 必须实现 | 这是移植的“咽喉要道”,LVGL 所有绘图指令最终都走这里 |
src/font/ |
内置字体 (lv_font_montserrat_12, lv_font_unscii_16) |
✅ 建议加入 | 字体未定义?检查 font 是否包含,且 lv_conf.h 中 LV_FONT_DEFAULT 是否启用 |
lv_conf_template.h |
全局配置模板,控制内存、颜色、动画、控件等所有行为 | ✅ 必须复制并重命名 | 最易踩坑!#if 0 不改,整个配置失效,编译必报错 |
lvgl.h |
总头文件,工程中唯一需要 #include 的入口 |
✅ 必须 | 所有 LVGL API 都通过它暴露,路径必须正确 |
提示:
examples/和demos/目录是你的“黄金验证器”。移植完成后,务必先跑通examples/lv_examples/src/lv_ex_widgets/lv_ex_widgets_1.c(一个带按钮和标签的最简示例)。它不依赖复杂外设,只验证 LVGL 核心逻辑和基础 HAL 是否工作。跑通它,说明你的移植骨架已经立住;跑不通,问题一定出在src/核心文件、lv_conf.h配置或hal/接口实现上,而不是你的业务逻辑。
2.2 源码包里的“隐形陷阱”:那些你必须手动处理的文件
LVGL 官方源码包里,有些文件看似普通,实则暗藏玄机,稍不注意就会让你的编译器发出刺耳警报:
-
lv_conf_template.h→lv_conf.h的致命一跃:这是整个移植过程中最常被忽略的“后悔药”。解压后,你看到的是lv_conf_template.h。必须手动复制一份,重命名为lv_conf.h,并放在工程能#include到的路径下(如Inc/或Core/Inc/)。打开lv_conf.h,找到文件开头的:c复制#if 0 /* Set it to 1 to enable the content */把
#if 0改成#if 1。否则,整个配置块被预处理器屏蔽,LV_COLOR_DEPTH、LV_MEM_SIZE等所有关键宏都未定义,编译器会疯狂报错unknown type name 'lv_color_t'。我第一次移植时,在这个#if 0上卡了整整一个下午,翻遍论坛也没找到答案,最后逐行对比官方文档才发现——它根本不是注释,而是一个开关。 -
src/hal/目录下的“空壳”:src/hal/里只有lv_hal.h这个头文件,里面全是函数声明,没有.c实现文件。这意味着lv_port_disp.c和lv_port_indev.c这两个文件,必须由你根据自己的硬件(如 STM32 的 LTDC + DMA2D,或 SPI OLED)从零编写。LVGL 只提供接口定义,不提供具体实现。很多新手误以为下载源码包就包含了这些,结果编译时报undefined reference to 'lv_port_disp_init',根源就在这里。 -
examples/中的“路径依赖”:examples/里的示例代码,其#include路径通常是#include "../../lvgl.h"。如果你直接把examples/整个目录拖进工程,而没有调整#include路径或设置正确的头文件搜索路径,编译器会找不到lvgl.h。最佳实践是:只复制examples/中你需要的.c文件内容,粘贴到你自己的应用文件里,并修改#include "lvgl.h"(假设lvgl.h在工程根目录)。
2.3 工程集成最小集:只加这 5 个东西,就能启动 LVGL 核心
为了快速验证环境,避免一次性加入过多文件导致问题复杂化,我推荐一个“最小可运行集”。在你的 MCU 工程(以 STM32CubeIDE 为例)中,只需添加以下 5 个元素,就能让 LVGL 的核心引擎开始运转(即使屏幕还黑着):
- 源码文件:将
lvgl-8.3.10/src/目录整个复制到你的工程Core/Src/下(保持原有子目录结构)。这是 LVGL 的心脏,不能拆。 - 总头文件:将
lvgl-8.3.10/lvgl.h复制到你的工程Core/Inc/下。 - 配置文件:将
lvgl-8.3.10/lv_conf_template.h复制、重命名、修改#if 1后的lv_conf.h,也放入Core/Inc/。 - 用户头文件搜索路径:在 IDE 的项目属性中(Properties → C/C++ Build → Settings → Tool Settings → MCU GCC Compiler → Includes),添加两条路径:
${workspace_loc:/YourProjectName/Core/Inc}(确保能找到lvgl.h和lv_conf.h)${workspace_loc:/YourProjectName/Core/Src}(确保lvgl.h能递归找到src/下的所有.h)
- 主程序初始化调用:在你的
main.c的main()函数开头,HAL_Init();之后,添加最简初始化:c复制编译运行。如果串口打印出#include "lvgl.h" int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); // ... 其他外设初始化 ... /* LVGL 初始化 */ lv_init(); // 必须第一行!初始化 LVGL 内存池、对象系统等 /* 此处暂不注册 disp/indev,仅验证 lv_init() 是否成功 */ printf("LVGL initialized successfully!\r\n"); while (1) { /* 主循环中必须定期调用 LVGL 刷新任务 */ lv_timer_handler(); HAL_Delay(5); // 保证刷新频率,避免 CPU 占满 } }LVGL initialized successfully!,恭喜,LVGL 的核心引擎已经成功加载!这证明src/文件、lv_conf.h配置、头文件路径全部正确。接下来,才是真正的硬仗:让画面亮起来。
3. 配置与裁剪:用 lv_conf.h 精准控制 LVGL 的“胃口”与“肌肉”
lv_conf.h 不是可有可无的配置文件,它是 LVGL 的“中央处理器”。它决定了 LVGL 吃多少内存(LV_MEM_SIZE)、能画多深的颜色(LV_COLOR_DEPTH)、支持多少种字体(LV_FONT_MONTSERRAT_*)、甚至有没有动画(LV_USE_ANIMATION)。盲目使用默认配置,轻则导致 MCU 内存溢出、程序跑飞,重则让一个 64KB RAM 的 Cortex-M0+ 芯片直接罢工。我们必须根据目标硬件的资源,像外科医生一样,对 lv_conf.h 进行精准裁剪和配置。
3.1 内存配置:LVGL 的“胃容量”,必须量身定制
LVGL 运行时需要两块关键内存:动态内存池(用于创建对象、缓存等)和显示缓冲区(用于双缓冲防闪烁)。它们的大小直接决定你能创建多少控件、界面是否流畅。
-
LV_MEM_SIZE:动态内存池大小
这是 LVGL 自己管理的堆空间。默认值64 * 1024(64KB)对于 STM32F4/F7 是安全的,但对于资源紧张的 STM32G0、GD32E230 或复旦微 FM33LE0,必须大幅缩减。我的经验是:- STM32F103C8T6 (20KB RAM):设为
32 * 1024(32KB),勉强够跑一个带 3-5 个按钮的简单界面。 - STM32G071 (36KB RAM):设为
48 * 1024(48KB),可支持更复杂的布局。 - 复旦微 FM33LE0 (16KB RAM):必须设为
16 * 1024(16KB)或更低,并关闭所有非必要功能(见下文)。
注意:
LV_MEM_SIZE不是越大越好。过大的值会浪费宝贵的 RAM,且 LVGL 的内存管理器(lv_mem)在小内存下效率更高。如果发现lv_obj_create()返回NULL,首要怀疑对象就是LV_MEM_SIZE不足。 - STM32F103C8T6 (20KB RAM):设为
-
LV_DISP_DEF_REFR_PERIOD:显示刷新周期
这个值(单位:毫秒)控制 LVGL 刷新屏幕的频率。默认33(约 30fps)很流畅,但对低功耗场景是巨大负担。在电池供电的农业传感器节点上,我通常将其设为1000(1fps),因为 UI 更新频率远低于此。关键点在于:这个值必须与你lv_timer_handler()的调用间隔匹配。如果你的HAL_Delay(5)导致lv_timer_handler()每 5ms 被调用一次,而LV_DISP_DEF_REFR_PERIOD是1000,LVGL 会智能地只在需要时刷新,不会每 5ms 都强行刷屏。
3.2 颜色与显示:LVGL 的“视觉系统”,必须与硬件对齐
LVGL 的颜色深度 (LV_COLOR_DEPTH) 必须与你的显示控制器(如 ILI9341, SSD1306)和 MCU 的数据总线宽度严格一致,否则会出现诡异的色偏、条纹或完全黑屏。
LV_COLOR_DEPTH |
适用场景 | 硬件要求 | 我的实战建议 |
|---|---|---|---|
1 (1-bit) |
单色 OLED (SSD1306) | MCU GPIO 模拟 SPI/I2C | ✅ 必选,节省内存 |
8 (8-bit) |
8-bit 并口 LCD、部分低端 SPI LCD | 8-bit 数据总线 | ⚠️ 谨慎,需确认 LCD 驱动芯片支持 |
16 (16-bit) |
主流 SPI LCD (ILI9341)、RGB TFT | 16-bit RGB 接口或 SPI 16-bit 模式 | ✅ 最常用,平衡性能与内存 |
32 (32-bit) |
高端 RGB TFT、需要 Alpha 通道 | 32-bit RGB 接口 | ❌ 除非必要,否则禁用,内存消耗翻倍 |
提示:对于 SPI OLED(如 SSD1306),
LV_COLOR_DEPTH必须设为1,且LV_COLOR_16_SWAP必须设为0。我曾在一个项目中误设为16,结果屏幕显示为一片混乱的灰度噪点,折腾半天才发现是颜色深度错配。
3.3 功能裁剪:关掉不用的“肌肉”,让 LVGL 更轻快
LVGL 功能丰富,但并非所有功能都需要。在资源受限的嵌入式环境中,“少即是多”。以下是我在多个量产项目中必关的选项:
LV_USE_ANIMATION:设为0。动画效果酷炫,但极其消耗 CPU 和内存。在工业 HMI 或农业终端上,用户更关心响应速度而非转场特效。LV_USE_FILESYSTEM:设为0。除非你的 UI 需要从 SD 卡加载图片或字体,否则完全不需要。它会引入 FATFS 依赖,增加编译复杂度。LV_USE_LOG:设为0。开发调试时可设为1,但量产固件必须关闭。日志输出会严重拖慢刷新帧率。LV_USE_THEME_DEFAULT:设为0。默认主题 (lv_theme_default_init) 会创建大量内部对象和样式。强烈建议设为0,并在应用中手动为每个控件设置样式,这样内存占用可降低 30% 以上。- 字体 (
LV_FONT_*):只启用你实际用到的字体。例如,如果 UI 只显示英文和数字,LV_FONT_MONTSERRAT_12和LV_FONT_UNSCII_16就足够了,LV_FONT_MONTSERRAT_28、LV_FONT_DEJAVU_16_PERSIAN_HEBREW等大字体一律设为0。一个LV_FONT_MONTSERRAT_28字体文件就可能占用 100KB Flash!
3.4 验证配置:用 lv_conf_checker.h 做一次“体检”
LVGL 提供了一个隐藏的“体检工具”:lv_conf_checker.h。它不是一个要加入工程的源文件,而是一个独立的头文件,用于在编译前静态检查 lv_conf.h 的配置一致性。
-
如何使用:新建一个空的
.c文件(如conf_check.c),内容只有一行:c复制#include "lv_conf.h"然后,在你的工程中,临时将
lv_conf.h的路径添加到这个conf_check.c的头文件搜索路径中。编译它。如果lv_conf.h中存在逻辑冲突(例如LV_USE_ANIMATION=1但LV_MEM_SIZE小于 16KB),lv_conf_checker.h会触发#error,并给出清晰的错误信息,如#error "LV_MEM_SIZE is too small for animations!"。 -
为什么重要:这比等到运行时
lv_obj_create()返回NULL再去大海捞针强百倍。它能在编译阶段就揪出配置矛盾,是移植前期最高效的“避坑”手段。我每次修改lv_conf.h后,都会执行一次这个检查。
4. 硬件抽象层(HAL)实现:打通 LVGL 与你的显示屏的“最后一公里”
lv_init() 成功只是万里长征第一步。LVGL 的所有绘图指令(lv_obj_set_style_bg_color()、lv_label_set_text())最终都要通过 src/hal/ 下定义的接口,落到你的物理屏幕上。这个过程,就是 HAL(Hardware Abstraction Layer)的实现。它不是 LVGL 的一部分,而是你作为开发者,必须亲手写的“翻译官”。它负责把 LVGL 的抽象命令(“画一个 100x50 的矩形”),翻译成你的 MCU 能听懂的硬件操作(“向 ILI9341 的 GRAM 地址 0x2C 写入 5000 个 16-bit 颜色值”)。HAL 是移植中最核心、也最容易出错的一环。
4.1 显示驱动 (lv_port_disp.c):从“画布”到“像素”的三步曲
LVGL 的显示驱动实现,本质上是完成三个关键任务:初始化显示设备、提供帧缓冲区、注册刷新回调。下面以最常见的 SPI TFT(ILI9341)为例,展示最精简、最可靠的实现。
第一步:初始化显示设备 (lv_port_disp_init)
这个函数负责配置你的 LCD 屏幕。它不涉及 LVGL,纯属硬件初始化。关键点在于:必须在 lv_init() 之后、lv_disp_drv_register() 之前调用。
c复制#include "lvgl.h"
#include "stm32f4xx_hal.h" // 替换为你自己的 HAL 库头文件
#include "ili9341.h" // 你自己的 LCD 驱动头文件,包含 ILI9341_Init() 等
void lv_port_disp_init(void)
{
/* 1. 初始化 SPI 外设 (假设使用 HAL_SPI_Transmit) */
extern SPI_HandleTypeDef hspi1; // 从 CubeMX 生成的变量
/* 2. 初始化 LCD 屏幕 */
ILI9341_Init(&hspi1); // 调用你封装好的初始化函数
/* 3. 设置屏幕方向、背光等 (可选) */
ILI9341_SetOrientation(LANDSCAPE); // 横屏
ILI9341_SetBacklight(100); // 100% 亮度
}
第二步:提供帧缓冲区 (disp_flush)
这是 HAL 的心脏。LVGL 渲染完一帧后,会调用你提供的 disp_flush 函数,把渲染好的“画布”(一个 lv_color_t 数组)发送到屏幕。你必须提供一块足够大的内存作为缓冲区。对于 320x240 分辨率、16-bit 颜色的屏幕,一块缓冲区就需要 320 * 240 * 2 = 153,600 字节(约 150KB)!这对小内存 MCU 是灾难。因此,双缓冲(Double Buffering)是必须的。
c复制/* 定义两块缓冲区,大小为屏幕宽度 * sizeof(lv_color_t) */
static lv_color_t disp_buf1[320]; // 一行的缓冲区
static lv_color_t disp_buf2[320]; // 第二行的缓冲区
/* LVGL 显示驱动结构体 */
static lv_disp_drv_t disp_drv;
void lv_port_disp_init(void)
{
// ... 上面的初始化代码 ...
/* 4. 注册 LVGL 显示驱动 */
lv_disp_drv_init(&disp_drv);
disp_drv.hor_res = 320; // 屏幕水平分辨率
disp_drv.ver_res = 240; // 屏幕垂直分辨率
disp_drv.flush_cb = disp_flush; // 刷新回调函数
disp_drv.buffer = &disp_buf; // 指向缓冲区结构体
/* 创建并注册显示驱动 */
lv_disp_drv_register(&disp_drv);
}
/* 刷新回调函数:LVGL 调用此函数将渲染好的区域发送到屏幕 */
void disp_flush(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p)
{
/* 1. 计算要刷新的区域大小 */
uint32_t w = (area->x2 - area->x1 + 1);
uint32_t h = (area->y2 - area->y1 + 1);
/* 2. 设置 LCD 的GRAM 地址窗口 (关键!) */
ILI9341_SetAddressWindow(area->x1, area->y1, area->x2, area->y2);
/* 3. 逐行发送数据:将 color_p 中的数据,按行发送给 LCD */
/* 这里简化了,实际应使用 DMA 或高效 SPI 传输 */
for(uint16_t y = area->y1; y <= area->y2; y++) {
/* 发送一行数据 */
ILI9341_WriteGRAM(color_p + (y - area->y1) * w, w);
}
/* 4. 通知 LVGL 刷新完成 (必须!) */
lv_disp_flush_ready(disp_drv);
}
注意:
lv_disp_flush_ready(disp_drv)是 LVGL 的“握手信号”。如果你忘了调用它,LVGL 会一直等待,UI 完全卡死。这是新手最常犯的错误之一。
第三步:输入设备 (lv_port_indev.c):让 LVGL “看见”你的触摸或按键
虽然本篇聚焦“点亮”,但一个完整的 GUI 必须有输入。lv_port_indev.c 的实现逻辑与 disp 类似,但更简单。它只需要一个 read_cb 回调,告诉 LVGL 当前的触摸坐标或按键状态。
c复制static lv_indev_drv_t indev_drv;
static lv_indev_t * indev_touch;
void lv_port_indev_init(void)
{
lv_indev_drv_init(&indev_drv);
indev_drv.type = LV_INDEV_TYPE_POINTER; // 触摸屏类型
indev_drv.read_cb = touchpad_read; // 读取回调
indev_touch = lv_indev_drv_register(&indev_drv);
}
/* 读取触摸坐标 */
bool touchpad_read(lv_indev_drv_t * drv, lv_indev_data_t * data)
{
static int16_t last_x = 0;
static int16_t last_y = 0;
static bool last_state = false;
/* 1. 读取你的触摸 IC (如 XPT2046) 的原始坐标 */
uint16_t x_raw, y_raw;
if (XPT2046_ReadRaw(&x_raw, &y_raw)) { // 你自己的读取函数
/* 2. 坐标校准与转换 (将 0-4095 转为 0-320) */
int16_t x = (int16_t)(x_raw * 320 / 4095);
int16_t y = (int16_t)(y_raw * 240 / 4095);
/* 3. 更新 LVGL 数据结构 */
data->point.x = x;
data->point.y = y;
data->state = last_state ? LV_INDEV_STATE_PR : LV_INDEV_STATE_REL;
return true;
}
return false;
}
4.2 避坑 / 常见问题 / 排查:HAL 实现中的五大血泪教训
HAL 是移植的深水区,无数开发者在此翻车。以下是基于真实项目经验总结的五大高频问题,每一条都附带现象、原因和解决方法:
-
现象:屏幕全黑,但
lv_init()和lv_timer_handler()都正常运行,串口有打印。
原因:lv_port_disp_init()未被调用,或者lv_disp_drv_register()调用失败(返回NULL),导致 LVGL 根本没有注册任何显示设备。
解决:在main()中lv_init()之后,立即调用lv_port_disp_init()。并在调用lv_disp_drv_register(&disp_drv)后,加一句if (!lv_disp_drv_register(&disp_drv)) { printf("Disp register failed!\r\n"); }。确保注册成功。 -
现象:屏幕显示为一片纯色(如全绿、全红),或出现规律性条纹。
原因:LV_COLOR_DEPTH与硬件不匹配,或disp_flush函数中ILI9341_SetAddressWindow()的坐标计算错误,导致数据写入了错误的 GRAM 区域。
解决:首先核对lv_conf.h中LV_COLOR_DEPTH是否为16。然后,在disp_flush中,用printf打印area->x1, area->y1, area->x2, area->y2,确认 LVGL 请求刷新的区域是否合理(例如,首次刷新通常是(0,0,319,239))。再检查ILI9341_SetAddressWindow的实现,确保它正确设置了 X/Y 起始和结束地址。 -
现象:UI 卡顿、刷新极慢,CPU 占用率 100%。
原因:disp_flush函数中使用了低效的阻塞式 SPI 传输(如HAL_SPI_Transmit),且未启用 DMA。每一次lv_timer_handler()调用,LVGL 都可能触发多次disp_flush,导致 CPU 陷入忙等。
解决:必须为 SPI 外设启用 DMA。将disp_flush中的HAL_SPI_Transmit替换为HAL_SPI_Transmit_DMA,并在 DMA 传输完成中断中调用lv_disp_flush_ready(disp_drv)。这是提升性能的“核武器”。 -
现象:触摸点击无反应,或点击位置严重偏移。
原因:touchpad_read回调中,原始坐标 (x_raw,y_raw) 未经过校准,或者data->state的状态更新逻辑错误(例如,一直返回LV_INDEV_STATE_REL)。
解决:实现一个简单的“四点校准”函数。在屏幕四个角分别点击,记录下x_raw/y_raw和期望的x/y,用线性插值公式计算出校准系数。同时,确保data->state在触摸按下时为LV_INDEV_STATE_PR,抬起时为LV_INDEV_STATE_REL。 -
现象:创建控件后,屏幕显示为乱码、马赛克,或部分区域缺失。
原因:disp_flush函数中,color_p指针指向的内存区域被意外覆盖,或者lv_disp_flush_ready(disp_drv)被提前调用(在数据发送完成前)。
解决:检查disp_flush函数中是否有越界写入数组的操作。最关键的,lv_disp_flush_ready(disp_drv)必须在所有像素数据都已成功发送到 LCD 后才能调用。如果使用 DMA,必须在HAL_SPI_TxCpltCallback中调用它;如果使用阻塞式传输,必须在HAL_SPI_Transmit返回后调用。
5. 首次点亮验证:从空白屏幕到第一个 LVGL 按钮的完整代码链
理论讲完,现在进入最激动人心的环节:亲手写出能让屏幕亮起来的完整代码。下面这段代码,是我为 STM32F407 开发板(搭配 ILI9341 SPI TFT)编写的、经过千锤百炼的“首次点亮”最小可行代码。它不依赖任何第三方 GUI 库,只使用 LVGL 8.3.10 源码和标准 HAL,从 main() 开始,到屏幕上出现一个可点击的蓝色按钮,全程无任何外部依赖。你可以把它当作一个“脚手架”,直接复制到你的工程中,只需修改几处硬件相关的初始化即可运行。
5.1 完整可运行代码:main.c 与 lv_port_disp.c
main.c
c复制#include "main.h"
#include "lvgl.h"
#include "lv_port_disp.h" // 我们自己实现的 HAL 头文件
#include "lv_port_indev.h"
// 全局变量
SPI_HandleTypeDef hspi1;
TIM_HandleTypeDef htim2;
/* LVGL 示例:创建一个按钮 */
static void create_demo_ui(void)
{
/* 1. 创建一个屏幕(默认屏幕) */
lv_obj_t * scr = lv_scr_act();
/* 2. 创建一个按钮 */
lv_obj_t * btn = lv_btn_create(scr);
lv_obj_set_size(btn, 120, 50);
lv_obj_center(btn);
/* 3. 创建一个标签,并添加到按钮上 */
lv_obj_t * label = lv_label_create(btn);
lv_label_set_text(label, "Hello LVGL!");
lv_obj_center(label);
}
/* 按钮点击事件回调 */
static void btn_event_cb(lv_event_t * e)
{
lv_obj_t * btn = lv_event_get_target(e);
lv_obj_t * label = lv_obj_get_child(btn, 0);
lv_label_set_text(label, "Clicked!");
}
int main(void)
{
HAL_Init();
SystemClock_Config();
MX_GPIO_Init();
MX_SPI1_Init(); // 初始化 SPI1 用于 LCD
MX_TIM2_Init(); // 初始化 TIM2 用于 lv_timer_handler 的精确延时(可选)
/* 1. 初始化 LVGL */
lv_init();
/* 2. 初始化 LVGL 的硬件抽象层 */
lv_port_disp_init(); // 初始化显示
lv_port_indev_init(); // 初始化触摸/按键
/* 3. 创建演示 UI */
create_demo_ui();
/* 4. 主循环:LVGL 的心跳 */
while (1)
{
/* LVGL 的核心刷新任务,必须定期调用 */
lv_timer_handler();
/* 为了演示,我们用 HAL_Delay 代替更精确的定时器 */
HAL_Delay(5);
}
}
/* TIM2 中断回调,用于更精确的 lv_timer_handler 调用(可选) */
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim)
{
if(htim->Instance == TIM2) {
lv_timer_handler();
}
}
lv_port_disp.h
c复制#ifndef LV_PORT_DISP_H
#define LV_PORT_DISP_H
#ifdef __cplusplus
extern "C" {
#endif
void lv_port_disp_init(void);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* LV_PORT_DISP_H */
lv_port_disp.c(精简版,仅含核心逻辑)
c复制#include "lvgl.h"
#include "lv_port_disp.h"
#include "stm32f4xx_hal.h"
#include "ili9341.h" // 你自己的 LCD 驱动
/* 定义两块缓冲区,大小为屏幕宽度 */
#define DISP_BUF_SIZE (320)
static lv_color_t disp_buf1[DISP_BUF_SIZE];
static lv_color_t disp_buf2[DISP_BUF_SIZE];
/* LVGL 显示驱动结构体 */
static lv_disp_drv_t disp_drv;
static lv_disp_buf_t disp_buf;
void lv_port_disp_init(void)
{
/* 1. 初始化 LCD 硬件 */
ILI9341_Init(&hspi1);
/* 2. 初始化 LVGL 显示驱动 */
lv_disp_drv_init(&disp_drv);
disp_drv.hor_res = 320;
disp_drv.ver_res = 240;
disp_drv.flush_cb = disp_flush;
/* 3. 初始化 LVGL 缓冲区结构 */
lv_disp_buf_init(&disp_buf, disp_buf1, disp_buf2, DISP_BUF_SIZE);
/* 4. 将缓冲区结构体赋值给驱动 */
disp_drv.buffer = &disp_buf;
/* 5. 注册驱动 */
lv_disp_drv_register(&disp_drv);
}
/* 刷新回调函数 */
void disp_flush(lv_disp_drv_t * disp_drv, 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);
/* 设置 GRAM 地址窗口 */
ILI9341_SetAddressWindow(area->x1, area->y1, area->x2, area->y2);
/* 逐行发送数据 */
for(uint16_t y = area->y
