TobudOS 集成 LittlevGL(LVGL v6)嵌入式 GUI:能力特性、移植流程与代码示例实战指南
TobudOS 集成 LittlevGL(LVGL v6)嵌入式 GUI:能力特性、移植流程与代码示例实战指南
LittlevGL(后更名为 LVGL)是一款用 C 语言编写、面向嵌入式系统的开源图形库,在 TobudOS 仓库中作为图形界面组件随内核一同维护,可用于为物联网终端设备快速构建按钮、图表、列表、滑块等图形界面。本文以仓库内 LittlevGL 的 README 为骨架,结合 lvgl 源码目录、lv_conf.h 配置 与 lvgl_gui_demo 示例,完整讲解 LittlevGL 的功能特性、硬件资源要求、PC 模拟器快速上手、嵌入式平台六步移植流程及核心代码示例,帮助你掌握在 TobudOS 上落地图形界面的完整链路。
一、LittlevGL 是什么:面向嵌入式系统的开源 GUI 库
LittlevGL 提供在嵌入式系统上创建图形用户界面所需的一切要素,包括易用的图形元素、漂亮的视觉效果和低内存占用。其核心理念是硬件无关:可配合任何微控制器或显示设备使用,且操作系统、外部内存和 GPU 均非必需项,属于可选的加速手段。
仓库中实际捆绑的版本为 v6.0(dev),这一点可由 lv_version.h 中的宏确认:
#define LVGL_VERSION_MAJOR 6
#define LVGL_VERSION_MINOR 0
#define LVGL_VERSION_PATCH 0
#define LVGL_VERSION_INFO "dev"
该头文件同时提供 LV_VERSION_CHECK(x, y, z) 宏,用于在代码中按版本条件编译,例如 LV_VERSION_CHECK(6,0,0) 可判断当前库是否满足 v6.0 及以上要求。
1.1 主要特性一览
- 强大的构建积木:按钮、图表、列表、滑块、图片等现成控件;
- 高级图形效果:支持动画、抗锯齿、透明度、平滑滚动;
- 多种输入设备:触摸板、鼠标、键盘、编码器、物理按键等;
- 多语言支持:基于 UTF-8 编码;
- 完全可定制的图形元素;
- 硬件无关,可用于任意微控制器或显示器;
- 可扩展,可在很少的内存下运行(约 64 kB Flash、10 kB RAM);
- 操作系统、外部内存、GPU 均为可选而非必需;
- 即使在高级图形效果下也支持单帧缓冲运行;
- 纯 C 语言编写,兼容性最大化;
- MicroPython 绑定,可在 MicroPython 中直接调用 LittlevGL API;
- PC 模拟器,无需嵌入式硬件即可在 PC 上开发;
- 提供教程、示例、主题,加速开发。
1.2 资源目录结构
在 TobudOS 仓库中,LittlevGL 位于 components/gui/LittlevGL/3rdparty/lvgl/,其主要组成包括:
| 路径 | 作用 |
|---|---|
| src/ | 核心源码,按 lv_core / lv_draw / lv_font / lv_hal / lv_misc / lv_objx / lv_themes 分层组织 |
| lv_conf_template.h | 配置模板,需复制为 lv_conf.h 后启用 |
| lvgl.h | 总头文件,包含 src/lv_version.h 等全部公开 API |
| lvgl.mk | Makefile 片段,统一纳入各子模块的 .mk 构建规则 |
| porting/ | 显示、输入设备、文件系统的移植模板 |
| docs/ | 配套文档 |
本仓库实际生效的配置位于 components/gui/LittlevGL/3rdparty/lv_conf.h(即 lv_conf_template.h 的实体化版本),编译时通过 components/gui/Makefile 中的 CFGFLAGS += -I$(CUR_DIR)/LittlevGL/3rdparty 将 lv_conf.h 所在目录加入头文件搜索路径。
二、运行条件:支持哪些平台、需要多少资源
README 指出:基本上所有能驱动显示屏的现代控制器都适合运行 LittlevGL。最小硬件要求如下:
- 16、32 或 64 位微控制器或处理器;
- 主频 > 16 MHz;
- 静态数据 > 8 kB RAM,动态数据(图形对象)> 2 kB RAM;
- 程序存储 > 64 kB Flash;
- 可选:约 1/10 屏幕大小的内存用于缓冲绘制(以 240×320、16 位色为例约 15 kB)。
README 中列出的部分平台包括 STM32F1/F3/F4/F7、Microchip dsPIC33/PIC24/PIC32 系列、NXP Kinetis/LPC/iMX、Linux framebuffer(/dev/fb)、树莓派、ESP32、Nordic nRF52 等。在 TobudOS 中,LittlevGL 组件与内核解耦,可配合 arch/ 下任意已移植的 MCU 架构使用。
三、快速上手:在 PC 模拟器中运行
README 建议,最简单的入门方式是在 PC 上借助模拟器运行,无需任何嵌入式硬件。官方提供了多种 IDE 工程选择:
- Eclipse(跨平台,基于 SDL);
- CodeBlocks(原生 Windows);
- Visual Studio(跨平台,基于 SDL);
- PlatformIO(跨平台,基于 SDL);
- Qt Creator(跨平台,基于 SDL)。
模拟器工程通常还附带了 TFT 显示与触摸的模拟实现,可在无硬件的情况下先行验证界面布局与交互逻辑。
四、嵌入式移植六步:把 LittlevGL 跑在真实硬件上
README 给出的移植步骤在“最简单的情形”下只需以下几步。下面按原文档顺序完整展开,并结合仓库中的 lv_port_disp_template.c 等移植模板做补充说明。
第 1 步:复制并配置 lv_conf.h
将 lv_conf_template.h 复制为 lv_conf.h,放在 lvgl 文件夹旁,并把文件开头的 #if 0 改为 #if 1 以启用配置内容。至少需要设置以下三个宏:
/* Maximal horizontal and vertical resolution to support by the library.*/
#define LV_HOR_RES_MAX (480)
#define LV_VER_RES_MAX (320)
/* Color depth:
* - 1: 1 byte per pixel
* - 8: RGB233
* - 16: RGB565
* - 32: ARGB8888
*/
#define LV_COLOR_DEPTH 16
本仓库实际生效的 lv_conf.h 中,LV_HOR_RES_MAX 为 480、LV_VER_RES_MAX 为 320、LV_COLOR_DEPTH 为 16(RGB565),与模板保持一致。其余常用配置项(内存池大小、日志、字体、控件开关等)详见本文第六节。
第 2 步:周期调用 lv_tick_inc() 提供系统时钟
LittlevGL 内部依赖一个毫秒级的系统时钟。需要在定时器或任务中每隔 x 毫秒调用一次 lv_tick_inc(x)(x 建议在 1~10 之间)。其底层实现位于 lv_hal_tick.c:
LV_ATTRIBUTE_TICK_INC void lv_tick_inc(uint32_t tick_period)
{
tick_irq_flag = 0;
sys_time += tick_period;
}
可以看到它把传入的周期累加到内部 sys_time 变量上,随后通过 lv_tick_get() 等接口供动画、长按检测、滚动惯性等内部计时使用。若不想手动喂时钟,也可在配置中开启 LV_TICK_CUSTOM 1,并给出获取系统毫秒时间的表达式(如 millis()),此时无需再调用 lv_tick_inc()。
第 3 步:调用 lv_init()
在完成配置并接入时钟后,调用 lv_init() 完成库的初始化(包括内存管理器、主题、控件系统等内部子系统的初始化)。
第 4 步:创建显示缓冲
LittlevGL 需要一个缓冲区来绘制对象,缓冲区大小必须大于 1 行显示数据。README 给出的最小示例是 10 行缓冲:
static lv_disp_buf_t disp_buf;
static lv_color_t buf[LV_HOR_RES_MAX * 10]; /*Declare a buffer for 10 lines*/
lv_disp_buf_init(&disp_buf, buf, NULL, LV_HOR_RES_MAX * 10); /*Initialize the display buffer*/
仓库的 lv_port_disp_template.c 进一步给出了三种缓冲配置的完整范例,值得对照阅读:
- 单缓冲(若干行):LittlevGL 在缓冲中绘制内容并整块写入显示屏,最简单;
- 双缓冲(若干行):配合 DMA 使用,让“绘制下一块区域”与“发送当前缓冲”并行,提升渲染吞吐;
- 双全屏缓冲:两块屏幕大小的缓冲,LittlevGL 渲染完成后直接把整帧交给显示,仅需切换帧缓冲地址,无需逐像素拷贝。
/* Example for 2) */
static lv_disp_buf_t disp_buf_2;
static lv_color_t buf2_1[LV_HOR_RES_MAX * 10]; /*A buffer for 10 rows*/
static lv_color_t buf2_2[LV_HOR_RES_MAX * 10]; /*An other buffer for 10 rows*/
lv_disp_buf_init(&disp_buf_2, buf2_1, buf2_2, LV_HOR_RES_MAX * 10); /*Initialize the display buffer*/
第 5 步:注册显示驱动与像素拷贝回调
实现一个能把像素数组拷贝到显示屏指定区域的函数,并注册为显示驱动:
lv_disp_drv_t disp_drv; /*Descriptor of a display driver*/
lv_disp_drv_init(&disp_drv); /*Basic initialization*/
disp_drv.hor_res = 480; /*Set the horizontal resolution*/
disp_drv.ver_res = 320; /*Set the vertical resolution*/
disp_drv.flush_cb = my_disp_flush; /*Set your driver function*/
disp_drv.buffer = &disp_buf; /*Assign the buffer to the display*/
lv_disp_drv_register(&disp_drv); /*Finally register the driver*/
void my_disp_flush(lv_disp_t * disp, const lv_area_t * area, lv_color_t * color_p)
{
int32_t x, y;
for(y = area->y1; y <= area->y2; y++) {
for(x = area->x1; x <= area->x2; x++) {
set_pixel(x, y, *color_p); /* Put a pixel to the display.*/
color_p++;
}
}
lv_disp_flush_ready(disp); /* Tell you are ready with the flushing*/
}
移植模板中的 disp_flush() 与此结构完全一致,并且特别强调:lv_disp_flush_ready(disp) 必须在刷新完成后调用,否则 LittlevGL 会一直等待本次刷新完成。若 MCU 带硬件加速(GPU),还可按 lv_port_disp_template.c 中 gpu_blend / gpu_fill 的接口挂接混合与填充加速函数。
第 6 步:注册输入设备驱动
实现一个能读取输入设备的函数并注册。以触摸板为例:
lv_indev_drv_init(&indev_drv); /*Descriptor of a input device driver*/
indev_drv.type = LV_INDEV_TYPE_POINTER; /*Touch pad is a pointer-like device*/
indev_drv.read_cb = my_touchpad_read; /*Set your driver function*/
lv_indev_drv_register(&indev_drv); /*Finally register the driver*/
bool my_touchpad_read(lv_indev_t * indev, lv_indev_data_t * data)
{
static lv_coord_t last_x = 0;
static lv_coord_t last_y = 0;
/*Save the state and save the pressed coordinate*/
data->state = touchpad_is_pressed() ? LV_INDEV_STATE_PR : LV_INDEV_STATE_REL;
if(data->state == LV_INDEV_STATE_PR) touchpad_get_xy(&last_x, &last_y);
/*Set the coordinates (if released use the last pressed coordinates)*/
data->point.x = last_x;
data->point.y = last_y;
return false; /*Return `false` because we are not buffering and no more data to read*/
}
LV_INDEV_TYPE_POINTER 表示指针类设备;data->state 上报按下(LV_INDEV_STATE_PR)或释放(LV_INDEV_STATE_REL)状态,data->point 上报坐标。仓库的 porting/lv_port_indev_template.c 与 porting/lv_port_fs_template.c 分别提供了输入设备与文件系统的移植模板。
第 7 步:周期调用 lv_task_handler()
在主循环 while(1)、定时器中断或操作系统任务中每隔几毫秒调用一次 lv_task_handler(),它负责按需重绘屏幕、处理输入设备事件、推进动画与任务队列。
4.1 在 TobudOS 任务中集成:lvgl_gui_demo 实例
仓库提供了可直接参考的集成示例 lvgl_demo.c:在一个 TobudOS 任务入口函数中完成初始化,然后用 tos_task_delay(5) 让出 CPU,再调用 lv_task_handler(),形成典型的“RTOS 任务 + 周期刷新”模型:
void application_entry(void *arg)
{
uint8_t i;
for (i = 0; i < 8; i++) {
tos_task_delay(50);
}
lv_init();
tft_init();
touchpad_init();
//benchmark_create();
//sysmon_create();
//terminal_create();
//tpcal_create();
//demo_create();
//lv_theme_t *th = lv_theme_alien_init(21, NULL);
//lv_test_theme_1(th);
lv_test_theme_2();
while (1)
{
tos_task_delay(5);
lv_task_handler();
}
}
示例中还展示了主题应用方式:lv_theme_alien_init(21, NULL) 可初始化 Alien 主题,lv_test_theme_2() 直接渲染主题测试界面;被注释的 benchmark_create()、sysmon_create()、terminal_create()、tpcal_create() 分别对应性能基准、系统监控、终端与触摸校准等演示程序,可按需启用。tft_init() 与 touchpad_init() 则是板级显示与触摸硬件初始化,即上述移植步骤中“显示驱动”与“输入驱动”的落地实现。
五、代码示例:控件、样式、特效与 MicroPython
5.1 创建带标签的按钮并绑定点击回调
lv_obj_t * btn = lv_btn_create(lv_scr_act(), NULL); /*Add a button the current screen*/
lv_obj_set_pos(btn, 10, 10); /*Set its position*/
lv_obj_set_size(btn, 100, 50); /*Set its size*/
lv_btn_set_action(btn, LV_BTN_ACTION_CLICK, btn_action);/*Assign a callback to the button*/
lv_obj_t * label = lv_label_create(btn, NULL); /*Add a label to the button*/
lv_label_set_text(label, "Button"); /*Set the labels text*/
lv_res_t btn_action(lv_obj_t * btn)
{
printf("Clicked\n");
return LV_RES_OK;
}
要点:lv_btn_create(lv_scr_act(), NULL) 在当前活动屏幕上创建按钮;lv_label_create(btn, NULL) 以按钮为父对象创建标签;回调函数返回 LV_RES_OK 表示事件已正常处理。
5.2 修改控件样式:按下 / 释放两种状态
static lv_style_t style_btn_rel; /*A variable to store the released style*/
lv_style_copy(&style_btn_rel, &lv_style_plain); /*Initialize from a built-in style*/
style_btn_rel.body.border.color = LV_COLOR_HEX3(0x269);
style_btn_rel.body.border.width = 1;
style_btn_rel.body.main_color = LV_COLOR_HEX3(0xADF);
style_btn_rel.body.grad_color = LV_COLOR_HEX3(0x46B);
style_btn_rel.body.shadow.width = 4;
style_btn_rel.body.shadow.type = LV_SHADOW_BOTTOM;
style_btn_rel.body.radius = LV_RADIUS_CIRCLE;
style_btn_rel.text.color = LV_COLOR_HEX3(0xDEF);
static lv_style_t style_btn_pr; /*A variable to store the pressed style*/
lv_style_copy(&style_btn_pr, &style_btn_rel); /*Initialize from the released style*/
style_btn_pr.body.border.color = LV_COLOR_HEX3(0x46B);
style_btn_pr.body.main_color = LV_COLOR_HEX3(0x8BD);
style_btn_pr.body.grad_color = LV_COLOR_HEX3(0x24A);
style_btn_pr.body.shadow.width = 2;
style_btn_pr.text.color = LV_COLOR_HEX3(0xBCD);
lv_btn_set_style(btn, LV_BTN_STYLE_REL, &style_btn_rel); /*Set the button's released style*/
lv_btn_set_style(btn, LV_BTN_STYLE_PR, &style_btn_pr); /*Set the button's pressed style*/
样式体系包含 body(边框、主色/渐变色、阴影、圆角)与 text(文字颜色)等子结构;LV_COLOR_HEX3() 以 3 位十六进制快速构造颜色;LV_RADIUS_CIRCLE 让按钮呈现圆角/圆形外观。
5.3 启用点击涟漪特效
/*Add some effects when the button is clicked*/
lv_btn_set_ink_in_time(btn, 300);
lv_btn_set_ink_wait_time(btn, 100);
lv_btn_set_ink_out_time(btn, 300);
分别设置点击涟漪的“出现时间 / 停留时间 / 消失时间”(单位毫秒),配合 lv_conf.h 中 LV_BTN_INK_EFFECT 1 与 LV_USE_ANIMATION 1 开启。
5.4 从 MicroPython 使用 LittlevGL
# Create a Button and a Label
scr = lv.obj()
btn = lv.btn(scr)
btn.align(lv.scr_act(), lv.ALIGN.CENTER, 0, 0)
label = lv.label(btn)
label.set_text("Button")
# Load the screen
lv.scr_load(scr)
借助 LittlevGL 的 MicroPython 绑定,可在脚本层以面向对象风格创建对象、对齐控件并加载屏幕。这也与 TobudOS 仓库中的 MicroPython 组件(components/language/micropython)形成呼应——图形界面既可运行在原生 C 应用,也可由脚本驱动。
六、配置项详解:lv_conf.h 核心参数
配置是 LittlevGL 移植中最关键的一环。lv_conf_template.h 按功能分区给出了全部可调项,本仓库的 lv_conf.h 即其启用版本。下面按分区整理核心参数:
6.1 图形与分辨率
| 配置项 | 默认值 | 说明 |
|---|---|---|
LV_HOR_RES_MAX / LV_VER_RES_MAX |
480 / 320 | 库支持的最大水平/垂直分辨率 |
LV_COLOR_DEPTH |
16 | 色深:1(单色)、8(RGB233)、16(RGB565)、32(ARGB8888) |
LV_COLOR_16_SWAP |
0 | 是否交换 RGB565 的两个字节,8 位接口(如 SPI)屏常需置 1 |
LV_COLOR_SCREEN_TRANSP |
0 | 屏幕透明(OSD 等场景),需 LV_COLOR_DEPTH = 32 |
LV_ANTIALIAS |
1 | 抗锯齿(线条与圆角平滑) |
LV_DISP_DEF_REFR_PERIOD |
30 ms | 默认显示刷新周期 |
LV_DPI |
100 px | 每英寸点数,用于初始化默认控件尺寸 |
6.2 内存管理
| 配置项 | 默认值 | 说明 |
|---|---|---|
LV_MEM_CUSTOM |
0 | 1 使用自定义 malloc/free;0 使用内置内存分配器 |
LV_MEM_SIZE |
32 kB | 内置分配器内存池大小(需 ≥ 2 kB) |
LV_MEM_ADR |
0 | 指定内存池地址,可放外部 SRAM |
LV_MEM_AUTO_DEFRAG |
1 | 释放时自动合并相邻空闲块 |
本仓库 lv_conf.h 采用内置分配器,LV_MEM_SIZE 为 32U * 1024U(32 kB),图形对象等动态数据都从该池分配,因此它决定了一个应用最多能创建多少个控件。
6.3 输入设备
| 配置项 | 默认值 | 说明 |
|---|---|---|
LV_INDEV_DEF_READ_PERIOD |
30 ms | 输入设备读取周期 |
LV_INDEV_DEF_DRAG_LIMIT |
10 px | 拖拽判定阈值 |
LV_INDEV_DEF_DRAG_THROW |
20 % | 松手惯性减速速度 |
LV_INDEV_DEF_LONG_PRESS_TIME |
400 ms | 长按触发时间 |
LV_INDEV_DEF_LONG_PRESS_REP_TIME |
100 ms | 长按重复触发周期 |
6.4 特性开关
LV_USE_ANIMATION:动画支持;LV_USE_SHADOW:阴影;LV_USE_GROUP:对象组(键盘/编码器导航);LV_USE_GPU:GPU 接口;LV_USE_FILESYSTEM:文件系统(图片等可能需要);LV_USE_LOG+LV_LOG_LEVEL(TRACE/INFO/WARN/ERROR)+LV_LOG_PRINTF:日志模块,本仓库配置为 WARN 级别且未直接用 printf 输出;LV_TICK_CUSTOM:自定义时钟源,置 1 后通过LV_TICK_CUSTOM_SYS_TIME_EXPR表达式获取毫秒时间,可省去手动调用lv_tick_inc();- 主题开关:
LV_USE_THEME_TEMPL / DEFAULT / ALIEN / NIGHT / MONO / MATERIAL / ZEN / NEMO,其中LV_THEME_LIVE_UPDATE 1允许运行时切换主题(额外占用 8~10 kB RAM,默认关闭); - 字体:
LV_FONT_ROBOTO_12/16/22/28、LV_FONT_UNSCII_8,本仓库启用LV_FONT_ROBOTO_16,LV_FONT_DEFAULT指向&lv_font_roboto_16; - 文本:
LV_TXT_ENC(UTF-8/ASCII)、LV_TXT_BREAK_CHARS(允许换行的字符集合); - 控件开关:
LV_USE_ARC / BAR / BTN / BTNM / CALENDAR / CANVAS / CB / CHART / CONT / DDLIST / GAUGE / IMG / IMGBTN / KB / LABEL / LED / LINE / LIST / LMETER / MBOX / PAGE / PRELOAD / ROLLER / SLIDER / SPINBOX / SW / TA / TABLE / TABVIEW / TILEVIEW / WIN等,逐个置 0 即可裁剪体积,置 1 则启用;各控件还带独立子参数(如LV_BTN_INK_EFFECT、LV_DDLIST_DEF_ANIM_TIME、LV_LABEL_DEF_SCROLL_SPEED等)。
提示:
#include "lvgl/src/lv_conf_checker.h"会在编译期对未定义的配置项给出默认值并做一致性校验,因此即使漏配某些宏,工程仍可编译,但建议按需显式配置。
七、源码结构导读:从 src 到构建
理解 LittlevGL 的源码分层有助于后续二次开发。仓库中 src/ 主要包含:
- lv_core:核心对象系统与事件/任务调度(
lv_obj、lv_task等); - lv_hal:硬件抽象层,包括显示驱动(
lv_hal_disp)、输入设备(lv_hal_indev)与时钟(lv_hal_tick.c),本文移植流程中注册驱动、喂时钟的 API 均出自此层; - lv_draw:绘制引擎(抗锯齿、透明度、阴影等);
- lv_font:字体加载与渲染;
- lv_misc:内存管理、颜色、坐标、字符串等基础工具;
- lv_objx:全部现成控件(按钮、标签、图表、滑块等);
- lv_themes:内置主题。
构建方面,lvgl.mk 通过 include $(LVGL_DIR)/lvgl/src/lv_core/lv_core.mk 等方式把各子目录的 .mk 规则统一纳入编译,TobudOS 的 components/gui/Makefile 则负责把 lv_conf.h 所在目录加入头文件搜索路径并接入组件构建体系。
八、总结
LittlevGL 以“低内存、硬件无关、纯 C、可裁剪”为核心设计取向,是嵌入式 GUI 领域成熟的开源选择。本文围绕仓库内 LittlevGL README 完整还原了从特性认知、硬件资源评估、PC 模拟器验证,到 lv_conf.h 配置、时钟喂入、显示/输入驱动注册、周期刷新的七步移植流程,并给出了按钮、样式、特效与 MicroPython 等可直接复用的代码示例。结合 TobudOS 的 lvgl_gui_demo 与 porting 模板,开发者可以快速在自己的板卡上跑通首帧界面,再依据 lv_conf.h 逐项裁剪与调优,最终在资源受限的物联网终端上获得流畅、美观的图形交互体验。