TobudOS 集成 LittlevGL(LVGL v6)嵌入式 GUI:能力特性、移植流程与代码示例实战指南

原创2026-10-09 16:22:031,681 阅读

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 进一步给出了三种缓冲配置的完整范例,值得对照阅读:

  1. 单缓冲(若干行):LittlevGL 在缓冲中绘制内容并整块写入显示屏,最简单;
  2. 双缓冲(若干行):配合 DMA 使用,让“绘制下一块区域”与“发送当前缓冲”并行,提升渲染吞吐;
  3. 双全屏缓冲:两块屏幕大小的缓冲,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 逐项裁剪与调优,最终在资源受限的物联网终端上获得流畅、美观的图形交互体验。

登录后查看全文
TobudOS