做嵌入式界面显示时最常用的两个可视化元素就是仪表盘和进度条。一个是展示实时状态一个是展示任务完成度。刚好 LVGL 在 ESP32 上提供了现成的控件支持用起来比想象中简单。本文围绕这两个控件完整拆解 LVGL 的创建流程、属性配置、样式调整和事件更新方式并给出一个设备状态页的实战案例方便直接迁移到自己的项目里。1. LVGL 在 ESP32 上的应用背景1.1 LVGL 是什么LVGLLight and Versatile Graphics Library是一款面向嵌入式设备的开源图形库。它的设计目标是在资源有限的 MCU 上提供接近桌面级 UI 的显示效果。ESP32 内部集成了足够大的 RAM 和 Flash配合 SPI 接口的 TFT 屏幕完全可以流畅运行 LVGL 界面。LVGL 的特点可以概括为以下几点支持控件丰富按钮、标签、图表、仪表盘、进度条、下拉框、列表等都有现成实现。占用资源可控基于帧缓冲方式渲染内存占用可以通过配置调整。自带输入设备驱动抽象支持触摸屏、编码器、物理按键。跨平台可以在 ESP32、STM32、Linux、模拟器等环境运行。在仪表盘和进度条这类数据展示场景中LVGL 的lv_meter和lv_bar两个控件是最常用的选择。1.2 仪表盘与进度条的区别很多刚接触 LVGL 的朋友会把仪表盘和进度条搞混这里先做一个简单区分控件适合展示的数据典型场景lv_meter仪表盘连续变化的物理量强调当前值在区间中的位置温度、电压、速度、转速、油量表lv_bar进度条任务完成比例或过程进度强调“当前值/目标值”下载进度、升级进度、数据采集进度简单说仪表盘适合看“现在是多少”进度条适合看“完成了多少”。两个控件可以配合使用比如监测页面用仪表盘展示温度用进度条展示 Flash 写入进度。1.3 为什么选择 ESP32 运行 LVGLESP32 系列芯片主频通常可达 240MHz拥有 320KB SRAM 和 4MB 以上的 Flash同时内置 Wi-Fi 和蓝牙。这样的硬件条件非常适合运行 LVGL可以驱动分辨率为 320x240 或 480x320 的屏幕。可以通过 Wi-Fi 获取数据再通过 LVGL 界面实时刷新。支持 FreeRTOS可以把 LVGL 的刷新任务与业务逻辑任务分离。如果只是做一个简单的温湿度显示或物联网设备控制面板使用 ESP32 LVGL 是性价比非常高的方案。2. 环境准备与工程结构2.1 硬件准备运行 LVGL 仪表盘和进度条需要以下硬件ESP32 开发板推荐 ESP32-WROOM-32 或 ESP32-S3S3 性能更强SPI 或并行接口的 TFT 屏幕常见为 ILI9341、ST7789、ST7735 驱动芯片可选触摸屏芯片 XPT2046如果界面需要交互连接线若干面包板或 PCB 转接板屏幕分辨率方面320x240 是起步配置480x320 显示仪表盘效果会更细腻。2.2 软件环境LVGL 在 ESP32 上有两条主流开发路线开发方式适合人群说明ESP-IDF LVGL 组件专业嵌入式开发工程可控性强使用 idf.py 管理构建LVGL 通过组件管理器集成Arduino LVGL 库快速原型验证学习入门使用 Arduino IDE 或 PlatformIO集成简单本文重点以 Arduino PlatformIO 或 Arduino IDE 为例因为这种方式代码结构直观适合快速复现。ESP-IDF 用户同样可以参考本文的 LVGL 控件代码核心 API 完全一致。2.3 第三方库安装在 Arduino IDE 的库管理器中搜索并安装以下库LVGLDontell 维护版本TFT_eSPI用于屏幕底层驱动XPT2046_Touchscreen如果使用触摸屏在 PlatformIO 中对应的platformio.ini依赖配置类似[env:esp32dev] platform espressif32 board esp32dev framework arduino monitor_speed 115200 lib_deps lvgl/lvgl^8.3.0 bodmer/TFT_eSPI^2.5.0 paulstoffregen/XPT2046_Touchscreen^1.4.0版本号需要结合当时最新版本调整。LVGL 8.x 和 9.x 在部分 API 上有差异本文示例基于 LVGL 8.3 系列编写使用 9.x 时需要注意函数名的兼容性改动。2.4 TFT_eSPI 屏幕配置TFT_eSPI 库需要根据屏幕引脚修改User_Setup.h文件。以 ILI9341、SPI 接口为例需要配置以下内容#define ILI9341_DRIVER #define TFT_MISO 19 #define TFT_MOSI 23 #define TFT_SCLK 18 #define TFT_CS 5 #define TFT_DC 2 #define TFT_RST 4 #define TFT_BL 15TFT_eSPI 在libraries/TFT_eSPI/User_Setup.h中修改。不同开发板的默认引脚不一样务必对照自己的接线图确认。2.5 LVGL 初始化流程在 Arduino 环境中LVGL 的典型初始化流程如下#include lvgl.h #include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); static lv_disp_draw_buf_t draw_buf; static lv_color_t buf[TFT_WIDTH * 10]; void my_disp_flush(lv_disp_drv_t *disp, 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); tft.startWrite(); tft.setAddrWindow(area-x1, area-y1, w, h); tft.pushColors(color_p-full, w * h, true); tft.endWrite(); lv_disp_flush_ready(disp); } void setup() { Serial.begin(115200); lv_init(); tft.begin(); tft.setRotation(1); lv_disp_draw_buf_init(draw_buf, buf, NULL, TFT_WIDTH * 10); static lv_disp_drv_t disp_drv; lv_disp_drv_init(disp_drv); disp_drv.hor_res TFT_WIDTH; disp_drv.ver_res TFT_HEIGHT; disp_drv.flush_cb my_disp_flush; disp_drv.draw_buf draw_buf; lv_disp_drv_register(disp_drv); }lv_disp_flush_ready(disp)必须在推屏结束后调用否则 LVGL 会认为屏幕还没有准备好接收下一帧数据。3. LVGL 基础概念速览3.1 对象树与父子关系LVGL 采用类似树状结构管理界面元素。每个控件都是一个lv_obj_t对象父对象用来约束子对象的显示区域子对象相对于父对象进行坐标定位。创建子控件的通用写法lv_obj_t *obj lv_obj_create(parent);lv_scr_act()获取当前活动屏幕对象直接创建的控件通常会挂载到屏幕上。3.2 坐标与对齐方式LVGL 支持多种对齐方式常用如LV_ALIGN_CENTER、LV_ALIGN_TOP_MID、LV_ALIGN_BOTTOM_MID。使用对齐方式可以简化坐标计算。示例lv_obj_align(meter, LV_ALIGN_CENTER, 0, 0);对齐后还可以通过偏移量微调位置这种方式在屏幕分辨率变化时不容易错位。3.3 事件回调机制LVGL 使用事件回调机制处理输入和状态变化。在仪表盘和进度条的场景中事件可以用于点击进度条时改变数值或通过定时器周期更新。注册事件回调lv_obj_add_event_cb(obj, event_handler, LV_EVENT_ALL, NULL);回调函数形式static void event_handler(lv_event_t *e) { lv_obj_t *obj lv_event_get_target(e); // 处理逻辑 }4. LVGL 仪表盘控件 lv_meter 详解4.1 创建基础仪表盘lv_meter 的设计逻辑比较特殊先创建表盘再向表盘添加“刻度”scale然后在刻度上添加“指针”indicator。这样设计的好处是可以在同一个仪表盘中叠加多个刻度和多个指针。基础创建代码如下lv_obj_t *meter lv_meter_create(lv_scr_act()); lv_obj_set_size(meter, 220, 220); lv_obj_center(meter);此时屏幕上会出现一个空白表盘区域。如果不添加任何刻度表盘是空的没有任何显示效果。4.2 添加刻度线刻度线分为主刻度线和次刻度线。主刻度线一般较长次刻度线较短两者配合提升可读性。lv_meter_scale_t *scale lv_meter_add_scale(meter); lv_meter_set_scale_ticks(meter, scale, 11, 2, 10, lv_palette_main(LV_PALETTE_BLUE)); lv_meter_set_scale_major_ticks(meter, scale, 2, 4, 15, lv_color_black(), 10); lv_meter_set_scale_range(meter, scale, 0, 100, 270, 90);参数解释第一个lv_meter_set_scale_ticks11 条刻度线宽度 2 像素长度 10 像素颜色蓝色。第二个lv_meter_set_scale_major_ticks每 2 条主刻度显示一个数值宽度 4 像素长度 15 像素文字黑色文字距离刻度末端 10 像素。lv_meter_set_scale_range量程 0 到 100起始角度 270 度结束角度 90 度。这里的角度参数容易理解错。它的含义是“从 270 度开始顺时针覆盖 90 度的范围”也就是说一共 270 度的扇形区域。起点在下方和常见仪表盘视觉一致。4.3 添加指针LVGL 的 lv_meter 支持三种指针直线指针、圆弧指针和刻度标记指针。最常用的是直线指针。lv_meter_indicator_t *indic lv_meter_add_needle_line( meter, scale, 3, lv_palette_main(LV_PALETTE_RED), -10);参数含义scale指针挂载到哪个刻度对象。3指针宽度。颜色红色。-10指针从中心向外偏移 10 像素避免针尖覆盖中心点。设置指针初始值lv_meter_set_indicator_value(meter, indic, 40);对应界面会显示指针指向 40 的位置。这个操作可以随时调用比如通过传感器数据更新仪表盘。4.4 更新仪表盘数据实时更新是仪表盘最常见的用法。可以在定时器回调中修改指针值static void timer_cb(lv_timer_t *timer) { // 模拟获取传感器数据 static int value 0; value 5; if (value 100) value 0; lv_meter_set_indicator_value(meter, indic, value); }创建定时器lv_timer_create(timer_cb, 500, NULL);注意LVGL 定时器的回调函数运行在 LVGL 上下文环境中函数内不要做耗时的阻塞操作否则界面刷新会卡顿。传感器读取、网络请求等任务应该放到其他任务或异步处理。4.5 仪表盘完整示例下面给出一个可在 Arduino LVGL 8.3 环境下直接运行的最小完整示例#include lvgl.h static lv_obj_t *meter; static lv_meter_indicator_t *indic; void update_meter_value(int value) { lv_meter_set_indicator_value(meter, indic, value); } void lv_demo_meter_create(void) { meter lv_meter_create(lv_scr_act()); lv_obj_set_size(meter, 220, 220); lv_obj_center(meter); lv_meter_scale_t *scale lv_meter_add_scale(meter); lv_meter_set_scale_ticks(meter, scale, 11, 2, 10, lv_palette_main(LV_PALETTE_BLUE)); lv_meter_set_scale_major_ticks(meter, scale, 2, 4, 15, lv_color_black(), 10); lv_meter_set_scale_range(meter, scale, 0, 100, 270, 90); indic lv_meter_add_needle_line(meter, scale, 3, lv_palette_main(LV_PALETTE_RED), -10); lv_meter_set_indicator_value(meter, indic, 60); }调用lv_demo_meter_create()后屏幕上会出现一个量程 0 到 100、初始值为 60 的仪表盘。5. LVGL 进度条控件 lv_bar 详解5.1 创建基础进度条lv_bar 的创建比 lv_meter 简单很多只需要创建对象并设置尺寸和范围即可。lv_obj_t *bar lv_bar_create(lv_scr_act()); lv_obj_set_size(bar, 300, 30); lv_obj_center(bar);此时进度条默认范围是 0 到 100。如果数值范围不符合需求可以调用lv_bar_set_range(bar, 0, 100);设置当前进度lv_bar_set_value(bar, 70, LV_ANIM_ON);第三个参数LV_ANIM_ON表示启用动画过渡效果。进度条会从当前值平滑运动到新值非常适合展示进度变化过程。5.2 进度条方向与样式lv_bar 支持水平和垂直两种方向。默认是水平方向。垂直方向需要设置尺寸比例和方向lv_obj_set_size(bar, 30, 200); lv_bar_set_start_value(bar, 0, LV_ANIM_ON);在实际项目中水平进度条更常见垂直进度条常用来表示音量、电量等纵向指标。进度条的核心样式包括背景、指示器已完成部分、圆角。通过 LVGL 样式 API 可以快速美化lv_obj_set_style_bg_color(bar, lv_color_hex(0x333333), LV_STATE_DEFAULT); lv_obj_set_style_bg_opa(bar, LV_OPA_COVER, LV_STATE_DEFAULT); lv_obj_set_style_radius(bar, 15, LV_STATE_DEFAULT); lv_obj_set_style_bg_color(bar, lv_palette_main(LV_PALETTE_GREEN), LV_PART_INDICATOR); lv_obj_set_style_radius(bar, 15, LV_PART_INDICATOR);注意背景色使用LV_STATE_DEFAULT指示器颜色使用LV_PART_INDICATOR。如果不指定LV_PART_INDICATOR指示器会直接使用默认蓝色无法单独定制颜色。5.3 进度条动态更新进度条通常配合业务任务使用。例如下面这段代码模拟任务进度增长static void update_bar_task(lv_timer_t *timer) { static int progress 0; progress 5; if (progress 100) progress 0; lv_bar_set_value(bar, progress, LV_ANIM_ON); }实际项目中这个 progress 值可以来自文件系统写入进度。HTTP 下载进度。传感器采集进度。计算任务处理比例。注意如果进度更新频率非常高建议去掉动画效果使用LV_ANIM_OFF否则动画持续期间多次触发更新会增加 CPU 占用可能导致显示滞后。5.4 进度条样式增强通过 LVGL 风格设置可以让进度条更有层次感。比如增加边框和阴影效果lv_obj_set_style_border_width(bar, 2, LV_STATE_DEFAULT); lv_obj_set_style_border_color(bar, lv_color_hex(0x888888), LV_STATE_DEFAULT); lv_obj_set_style_border_opa(bar, LV_OPA_COVER, LV_STATE_DEFAULT); lv_obj_set_style_shadow_width(bar, 10, LV_STATE_DEFAULT); lv_obj_set_style_shadow_color(bar, lv_color_hex(0x222222), LV_STATE_DEFAULT);此外还可以在进度条上方叠加一个标签用于显示百分比文字lv_obj_t *label lv_label_create(lv_scr_act()); lv_label_set_text(label, 50%); lv_obj_align(label, LV_ALIGN_CENTER, 0, -20);在定时器回调中同步更新文字char buf[16]; sprintf(buf, %d%%, progress); lv_label_set_text(label, buf);6. 实战案例仪表盘与进度条联动6.1 功能需求设计一个简易设备监控页面页面包含一个温度仪表盘量程 0 到 100 摄氏度。一个任务进度条显示数据采集进度。一个标签显示当前进度百分比。模拟逻辑温度值在 20 到 80 之间随机波动进度每 500ms 增加 5%达到 100% 后重新归零。6.2 界面布局借助 LVGL 的对象布局我们可以把仪表盘放在屏幕上方把进度条和标签放在下方。lv_obj_t *screen lv_scr_act(); meter lv_meter_create(screen); lv_obj_set_size(meter, 200, 200); lv_obj_align(meter, LV_ALIGN_TOP_MID, 0, 0); scale lv_meter_add_scale(meter); lv_meter_set_scale_ticks(meter, scale, 11, 2, 10, lv_palette_main(LV_PALETTE_BLUE)); lv_meter_set_scale_major_ticks(meter, scale, 2, 4, 15, lv_color_black(), 10); lv_meter_set_scale_range(meter, scale, 0, 100, 270, 90); indic lv_meter_add_needle_line(meter, scale, 3, lv_palette_main(LV_PALETTE_RED), -10); bar lv_bar_create(screen); lv_obj_set_size(bar, 240, 20); lv_obj_align(bar, LV_ALIGN_BOTTOM_MID, 0, -40); lv_bar_set_range(bar, 0, 100); label lv_label_create(screen); lv_obj_align(label, LV_ALIGN_BOTTOM_MID, 0, -10); lv_label_set_text(label, 0%);6.3 模拟数据更新定时器回调中同时更新仪表盘和进度条static void sim_timer_cb(lv_timer_t *timer) { static int temperature 25; static int progress 0; temperature random(-5, 6); if (temperature 20) temperature 20; if (temperature 80) temperature 80; lv_meter_set_indicator_value(meter, indic, temperature); progress 5; if (progress 100) progress 0; lv_bar_set_value(bar, progress, LV_ANIM_ON); char buf[32]; sprintf(buf, 进度: %d%%, progress); lv_label_set_text(label, buf); }初始化随机数种子randomSeed(analogRead(34));然后把定时器挂到 LVGL 上lv_timer_create(sim_timer_cb, 500, NULL);6.4 主循环集成Arduino 的主循环需要调用lv_timer_handler()来驱动 LVGL 任务处理void loop() { lv_timer_handler(); delay(5); }lv_timer_handler()负责处理 LVGL 内部的事件、刷新和动画任务。如果主循环中没有调用它界面不会刷新。6.5 快速验证步骤将代码编译烧录到 ESP32 后预期效果如下屏幕显示一个 0 到 100 的圆形仪表盘指针在 20 到 80 之间来回摆动。仪表盘下方显示一个水平进度条5%、10%、15% 逐步增长。进度条旁边的文字同步显示当前百分比。进度达到 100% 后自动归零重新开始循环。如果屏幕没有显示优先检查 TFT_eSPI 的引脚配置和 LVGL 初始化顺序。7. 常见问题与排查思路7.1 屏幕白屏或无显示问题现象常见原因解决思路屏幕背光亮但无内容TFT_eSPI 引脚配置错误核对 User_Setup.h 中的 TFT_CS、DC、RST、MOSI、SCLK 引脚屏幕显示花屏SPI 频率过高或接线过长降低 TFT_eSPI 的 SPI 频率使用短杜邦线所有控件都不显示LVGL 初始化顺序问题确认lv_init()在tft.begin()之前执行画面卡死未调用lv_timer_handler()在主循环中周期调用lv_timer_handler()7.2 仪表盘指针不显示如果仪表盘创建了刻度但指针没有出现常见原因有三个没有调用lv_meter_add_needle_line添加指针。指针颜色和背景颜色相同。指针指向的值超出了lv_meter_set_scale_range设置的范围例如量程是 0 到 100但设置值到了 120。排查方式先把指针初始值设为范围正中间例如 50看指针是否出现。如果出现说明值域配置有问题。7.3 进度条动画卡顿进度条动画卡顿通常是由于主循环或定时器中有阻塞操作。比如在loop()中使用delay(1000)或者在 LVGL 定时器回调中执行网络请求。解决方案将耗时的任务放到xTaskCreatePinnedToCore创建的独立 FreeRTOS 任务中。LVGL 定时器回调中只做数值计算和控件更新。主循环中的延时控制在 5ms 到 20ms 之间。7.4 触摸不准使用触摸屏时如果触摸坐标偏差大需要在 LVGL 输入设备驱动中做坐标校准。最简单的方法是使用lv_touchpad_calibrate等校准工具或者根据屏幕旋转方向调整x、y映射逻辑。在没有准确校准前仪表盘和进度条这类界面可以先不接入触摸输入仅做显示降低复杂度。8. 最佳实践与工程建议8.1 显存和帧缓冲优化LVGL 的内存使用主要集中在帧缓冲上。推荐使用部分缓冲partial buffer来降低 RAM 占用。lv_disp_draw_buf_init中的缓冲区大小设置为屏幕宽度的 10 到 20 行即可不需要为整屏分配缓冲。例如 320x240 分辨率缓冲区设置为static lv_color_t buf[320 * 10];如果内存吃紧可以调整到320 * 5但可能会略微影响渲染性能。8.2 控件样式统一管理仪表盘和进度条涉及大量颜色、边框、圆角设置。建议将样式设置统一封装成函数例如static void apply_theme(lv_obj_t *obj) { lv_obj_set_style_bg_color(obj, lv_color_hex(0x222222), LV_STATE_DEFAULT); lv_obj_set_style_border_width(obj, 2, LV_STATE_DEFAULT); }这样可以方便地在多个页面复用主题不需要每个控件重新设置一套样式。8.3 数据更新与界面刷新分离在实际嵌入式项目中传感器采集、网络通信、数据处理和界面显示应该分层设计。建议结构如下采集任务读取传感器数据存放到全局变量或队列。业务任务处理数据生成仪表盘和进度条需要的值。界面任务在 LVGL 定时器中读取最新值并刷新控件。这样做的好处是界面刷新频率与数据变化频率解耦避免传感器偶发波动导致界面频繁重绘。8.4 使用标签显示数值补充仪表盘只有指针用户很难读准确精确数值。建议在仪表盘中心或旁边添加一个标签控件显示数字值lv_obj_t *value_label lv_label_create(meter); lv_label_set_text(value_label, 0); lv_obj_center(value_label);更新时同步调用char temp[8]; sprintf(temp, %d, temperature); lv_label_set_text(value_label, temp);进度条同理推荐在右侧或上方添加百分比标签。8.5 固件升级场景中的注意事项如果进度条用于 OTA 升级进度展示需要注意OTA 写入 Flash 时会占用大量 CPU 和 SPI 资源可能导致界面刷新暂停。建议在 OTA 过程中将 LVGL 刷新频率调低或者使用双核调度让 OTA 任务运行在 Core 0LVGL 刷新运行在 Core 1。进度值应使用原子变量或 volatile 修饰避免任务间读取不一致。8.6 关于 LVGL 8.x 与 9.x 的迁移建议LVGL 9.x 对部分 API 做了调整例如lv_meter的指针创建函数参数顺序可能变化。如果你从 8.3 升级到 9.x编译报错时优先查看官方文档中的 API 变更说明。本文代码在 8.3 系列验证通过9.x 环境下需要适当调整。如果项目和本文一样使用了lv_palette_main系列颜色接口注意该接口在 8.x 中位于lv_color.h在 9.x 中目录结构有改动正确引入头文件即可编译。9. 总结与下一步学习方向到这里LVGL 仪表盘和进度条的核心用法已经完整覆盖。通过本文可以掌握如何初始化 LVGL 并挂载屏幕驱动。如何使用 lv_meter 创建带刻度的圆形仪表盘并更新指针值。如何使用 lv_bar 创建动态进度条并通过 LV_ANIM_ON 实现平滑过渡。如何通过 LVGL 定时器周期性刷新控件。如何排查屏幕无显示、指针不出现、动画卡顿等常见问题。接下来可以继续学习LVGL 的页面切换和容器布局实现多页面控制面板。LVGL 配合蓝牙或 Wi-Fi让仪表盘显示真实传感器数据。LVGL 与 FreeRTOS 任务结合将复杂业务逻辑移出 UI 线程。LVGL 的样式状态机制实现点击、按下、禁用等交互效果。使用 LVGL 模拟器在 PC 上调试界面加快开发效率。仪表盘和进度条看似是两个简单控件但它们是嵌入式人机交互中最常用的可视化形式。把这两个控件的创建、更新、样式和性能细节吃透再延伸到其他 LVGL 控件思路是完全通用的。建议直接拿起一块 ESP32 开发板跟着本文的代码敲一遍遇到报错再回头对照参数表很快就能形成自己的 LVGL 开发节奏。
ESP32上LVGL仪表盘与进度条控件实战详解
做嵌入式界面显示时最常用的两个可视化元素就是仪表盘和进度条。一个是展示实时状态一个是展示任务完成度。刚好 LVGL 在 ESP32 上提供了现成的控件支持用起来比想象中简单。本文围绕这两个控件完整拆解 LVGL 的创建流程、属性配置、样式调整和事件更新方式并给出一个设备状态页的实战案例方便直接迁移到自己的项目里。1. LVGL 在 ESP32 上的应用背景1.1 LVGL 是什么LVGLLight and Versatile Graphics Library是一款面向嵌入式设备的开源图形库。它的设计目标是在资源有限的 MCU 上提供接近桌面级 UI 的显示效果。ESP32 内部集成了足够大的 RAM 和 Flash配合 SPI 接口的 TFT 屏幕完全可以流畅运行 LVGL 界面。LVGL 的特点可以概括为以下几点支持控件丰富按钮、标签、图表、仪表盘、进度条、下拉框、列表等都有现成实现。占用资源可控基于帧缓冲方式渲染内存占用可以通过配置调整。自带输入设备驱动抽象支持触摸屏、编码器、物理按键。跨平台可以在 ESP32、STM32、Linux、模拟器等环境运行。在仪表盘和进度条这类数据展示场景中LVGL 的lv_meter和lv_bar两个控件是最常用的选择。1.2 仪表盘与进度条的区别很多刚接触 LVGL 的朋友会把仪表盘和进度条搞混这里先做一个简单区分控件适合展示的数据典型场景lv_meter仪表盘连续变化的物理量强调当前值在区间中的位置温度、电压、速度、转速、油量表lv_bar进度条任务完成比例或过程进度强调“当前值/目标值”下载进度、升级进度、数据采集进度简单说仪表盘适合看“现在是多少”进度条适合看“完成了多少”。两个控件可以配合使用比如监测页面用仪表盘展示温度用进度条展示 Flash 写入进度。1.3 为什么选择 ESP32 运行 LVGLESP32 系列芯片主频通常可达 240MHz拥有 320KB SRAM 和 4MB 以上的 Flash同时内置 Wi-Fi 和蓝牙。这样的硬件条件非常适合运行 LVGL可以驱动分辨率为 320x240 或 480x320 的屏幕。可以通过 Wi-Fi 获取数据再通过 LVGL 界面实时刷新。支持 FreeRTOS可以把 LVGL 的刷新任务与业务逻辑任务分离。如果只是做一个简单的温湿度显示或物联网设备控制面板使用 ESP32 LVGL 是性价比非常高的方案。2. 环境准备与工程结构2.1 硬件准备运行 LVGL 仪表盘和进度条需要以下硬件ESP32 开发板推荐 ESP32-WROOM-32 或 ESP32-S3S3 性能更强SPI 或并行接口的 TFT 屏幕常见为 ILI9341、ST7789、ST7735 驱动芯片可选触摸屏芯片 XPT2046如果界面需要交互连接线若干面包板或 PCB 转接板屏幕分辨率方面320x240 是起步配置480x320 显示仪表盘效果会更细腻。2.2 软件环境LVGL 在 ESP32 上有两条主流开发路线开发方式适合人群说明ESP-IDF LVGL 组件专业嵌入式开发工程可控性强使用 idf.py 管理构建LVGL 通过组件管理器集成Arduino LVGL 库快速原型验证学习入门使用 Arduino IDE 或 PlatformIO集成简单本文重点以 Arduino PlatformIO 或 Arduino IDE 为例因为这种方式代码结构直观适合快速复现。ESP-IDF 用户同样可以参考本文的 LVGL 控件代码核心 API 完全一致。2.3 第三方库安装在 Arduino IDE 的库管理器中搜索并安装以下库LVGLDontell 维护版本TFT_eSPI用于屏幕底层驱动XPT2046_Touchscreen如果使用触摸屏在 PlatformIO 中对应的platformio.ini依赖配置类似[env:esp32dev] platform espressif32 board esp32dev framework arduino monitor_speed 115200 lib_deps lvgl/lvgl^8.3.0 bodmer/TFT_eSPI^2.5.0 paulstoffregen/XPT2046_Touchscreen^1.4.0版本号需要结合当时最新版本调整。LVGL 8.x 和 9.x 在部分 API 上有差异本文示例基于 LVGL 8.3 系列编写使用 9.x 时需要注意函数名的兼容性改动。2.4 TFT_eSPI 屏幕配置TFT_eSPI 库需要根据屏幕引脚修改User_Setup.h文件。以 ILI9341、SPI 接口为例需要配置以下内容#define ILI9341_DRIVER #define TFT_MISO 19 #define TFT_MOSI 23 #define TFT_SCLK 18 #define TFT_CS 5 #define TFT_DC 2 #define TFT_RST 4 #define TFT_BL 15TFT_eSPI 在libraries/TFT_eSPI/User_Setup.h中修改。不同开发板的默认引脚不一样务必对照自己的接线图确认。2.5 LVGL 初始化流程在 Arduino 环境中LVGL 的典型初始化流程如下#include lvgl.h #include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); static lv_disp_draw_buf_t draw_buf; static lv_color_t buf[TFT_WIDTH * 10]; void my_disp_flush(lv_disp_drv_t *disp, 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); tft.startWrite(); tft.setAddrWindow(area-x1, area-y1, w, h); tft.pushColors(color_p-full, w * h, true); tft.endWrite(); lv_disp_flush_ready(disp); } void setup() { Serial.begin(115200); lv_init(); tft.begin(); tft.setRotation(1); lv_disp_draw_buf_init(draw_buf, buf, NULL, TFT_WIDTH * 10); static lv_disp_drv_t disp_drv; lv_disp_drv_init(disp_drv); disp_drv.hor_res TFT_WIDTH; disp_drv.ver_res TFT_HEIGHT; disp_drv.flush_cb my_disp_flush; disp_drv.draw_buf draw_buf; lv_disp_drv_register(disp_drv); }lv_disp_flush_ready(disp)必须在推屏结束后调用否则 LVGL 会认为屏幕还没有准备好接收下一帧数据。3. LVGL 基础概念速览3.1 对象树与父子关系LVGL 采用类似树状结构管理界面元素。每个控件都是一个lv_obj_t对象父对象用来约束子对象的显示区域子对象相对于父对象进行坐标定位。创建子控件的通用写法lv_obj_t *obj lv_obj_create(parent);lv_scr_act()获取当前活动屏幕对象直接创建的控件通常会挂载到屏幕上。3.2 坐标与对齐方式LVGL 支持多种对齐方式常用如LV_ALIGN_CENTER、LV_ALIGN_TOP_MID、LV_ALIGN_BOTTOM_MID。使用对齐方式可以简化坐标计算。示例lv_obj_align(meter, LV_ALIGN_CENTER, 0, 0);对齐后还可以通过偏移量微调位置这种方式在屏幕分辨率变化时不容易错位。3.3 事件回调机制LVGL 使用事件回调机制处理输入和状态变化。在仪表盘和进度条的场景中事件可以用于点击进度条时改变数值或通过定时器周期更新。注册事件回调lv_obj_add_event_cb(obj, event_handler, LV_EVENT_ALL, NULL);回调函数形式static void event_handler(lv_event_t *e) { lv_obj_t *obj lv_event_get_target(e); // 处理逻辑 }4. LVGL 仪表盘控件 lv_meter 详解4.1 创建基础仪表盘lv_meter 的设计逻辑比较特殊先创建表盘再向表盘添加“刻度”scale然后在刻度上添加“指针”indicator。这样设计的好处是可以在同一个仪表盘中叠加多个刻度和多个指针。基础创建代码如下lv_obj_t *meter lv_meter_create(lv_scr_act()); lv_obj_set_size(meter, 220, 220); lv_obj_center(meter);此时屏幕上会出现一个空白表盘区域。如果不添加任何刻度表盘是空的没有任何显示效果。4.2 添加刻度线刻度线分为主刻度线和次刻度线。主刻度线一般较长次刻度线较短两者配合提升可读性。lv_meter_scale_t *scale lv_meter_add_scale(meter); lv_meter_set_scale_ticks(meter, scale, 11, 2, 10, lv_palette_main(LV_PALETTE_BLUE)); lv_meter_set_scale_major_ticks(meter, scale, 2, 4, 15, lv_color_black(), 10); lv_meter_set_scale_range(meter, scale, 0, 100, 270, 90);参数解释第一个lv_meter_set_scale_ticks11 条刻度线宽度 2 像素长度 10 像素颜色蓝色。第二个lv_meter_set_scale_major_ticks每 2 条主刻度显示一个数值宽度 4 像素长度 15 像素文字黑色文字距离刻度末端 10 像素。lv_meter_set_scale_range量程 0 到 100起始角度 270 度结束角度 90 度。这里的角度参数容易理解错。它的含义是“从 270 度开始顺时针覆盖 90 度的范围”也就是说一共 270 度的扇形区域。起点在下方和常见仪表盘视觉一致。4.3 添加指针LVGL 的 lv_meter 支持三种指针直线指针、圆弧指针和刻度标记指针。最常用的是直线指针。lv_meter_indicator_t *indic lv_meter_add_needle_line( meter, scale, 3, lv_palette_main(LV_PALETTE_RED), -10);参数含义scale指针挂载到哪个刻度对象。3指针宽度。颜色红色。-10指针从中心向外偏移 10 像素避免针尖覆盖中心点。设置指针初始值lv_meter_set_indicator_value(meter, indic, 40);对应界面会显示指针指向 40 的位置。这个操作可以随时调用比如通过传感器数据更新仪表盘。4.4 更新仪表盘数据实时更新是仪表盘最常见的用法。可以在定时器回调中修改指针值static void timer_cb(lv_timer_t *timer) { // 模拟获取传感器数据 static int value 0; value 5; if (value 100) value 0; lv_meter_set_indicator_value(meter, indic, value); }创建定时器lv_timer_create(timer_cb, 500, NULL);注意LVGL 定时器的回调函数运行在 LVGL 上下文环境中函数内不要做耗时的阻塞操作否则界面刷新会卡顿。传感器读取、网络请求等任务应该放到其他任务或异步处理。4.5 仪表盘完整示例下面给出一个可在 Arduino LVGL 8.3 环境下直接运行的最小完整示例#include lvgl.h static lv_obj_t *meter; static lv_meter_indicator_t *indic; void update_meter_value(int value) { lv_meter_set_indicator_value(meter, indic, value); } void lv_demo_meter_create(void) { meter lv_meter_create(lv_scr_act()); lv_obj_set_size(meter, 220, 220); lv_obj_center(meter); lv_meter_scale_t *scale lv_meter_add_scale(meter); lv_meter_set_scale_ticks(meter, scale, 11, 2, 10, lv_palette_main(LV_PALETTE_BLUE)); lv_meter_set_scale_major_ticks(meter, scale, 2, 4, 15, lv_color_black(), 10); lv_meter_set_scale_range(meter, scale, 0, 100, 270, 90); indic lv_meter_add_needle_line(meter, scale, 3, lv_palette_main(LV_PALETTE_RED), -10); lv_meter_set_indicator_value(meter, indic, 60); }调用lv_demo_meter_create()后屏幕上会出现一个量程 0 到 100、初始值为 60 的仪表盘。5. LVGL 进度条控件 lv_bar 详解5.1 创建基础进度条lv_bar 的创建比 lv_meter 简单很多只需要创建对象并设置尺寸和范围即可。lv_obj_t *bar lv_bar_create(lv_scr_act()); lv_obj_set_size(bar, 300, 30); lv_obj_center(bar);此时进度条默认范围是 0 到 100。如果数值范围不符合需求可以调用lv_bar_set_range(bar, 0, 100);设置当前进度lv_bar_set_value(bar, 70, LV_ANIM_ON);第三个参数LV_ANIM_ON表示启用动画过渡效果。进度条会从当前值平滑运动到新值非常适合展示进度变化过程。5.2 进度条方向与样式lv_bar 支持水平和垂直两种方向。默认是水平方向。垂直方向需要设置尺寸比例和方向lv_obj_set_size(bar, 30, 200); lv_bar_set_start_value(bar, 0, LV_ANIM_ON);在实际项目中水平进度条更常见垂直进度条常用来表示音量、电量等纵向指标。进度条的核心样式包括背景、指示器已完成部分、圆角。通过 LVGL 样式 API 可以快速美化lv_obj_set_style_bg_color(bar, lv_color_hex(0x333333), LV_STATE_DEFAULT); lv_obj_set_style_bg_opa(bar, LV_OPA_COVER, LV_STATE_DEFAULT); lv_obj_set_style_radius(bar, 15, LV_STATE_DEFAULT); lv_obj_set_style_bg_color(bar, lv_palette_main(LV_PALETTE_GREEN), LV_PART_INDICATOR); lv_obj_set_style_radius(bar, 15, LV_PART_INDICATOR);注意背景色使用LV_STATE_DEFAULT指示器颜色使用LV_PART_INDICATOR。如果不指定LV_PART_INDICATOR指示器会直接使用默认蓝色无法单独定制颜色。5.3 进度条动态更新进度条通常配合业务任务使用。例如下面这段代码模拟任务进度增长static void update_bar_task(lv_timer_t *timer) { static int progress 0; progress 5; if (progress 100) progress 0; lv_bar_set_value(bar, progress, LV_ANIM_ON); }实际项目中这个 progress 值可以来自文件系统写入进度。HTTP 下载进度。传感器采集进度。计算任务处理比例。注意如果进度更新频率非常高建议去掉动画效果使用LV_ANIM_OFF否则动画持续期间多次触发更新会增加 CPU 占用可能导致显示滞后。5.4 进度条样式增强通过 LVGL 风格设置可以让进度条更有层次感。比如增加边框和阴影效果lv_obj_set_style_border_width(bar, 2, LV_STATE_DEFAULT); lv_obj_set_style_border_color(bar, lv_color_hex(0x888888), LV_STATE_DEFAULT); lv_obj_set_style_border_opa(bar, LV_OPA_COVER, LV_STATE_DEFAULT); lv_obj_set_style_shadow_width(bar, 10, LV_STATE_DEFAULT); lv_obj_set_style_shadow_color(bar, lv_color_hex(0x222222), LV_STATE_DEFAULT);此外还可以在进度条上方叠加一个标签用于显示百分比文字lv_obj_t *label lv_label_create(lv_scr_act()); lv_label_set_text(label, 50%); lv_obj_align(label, LV_ALIGN_CENTER, 0, -20);在定时器回调中同步更新文字char buf[16]; sprintf(buf, %d%%, progress); lv_label_set_text(label, buf);6. 实战案例仪表盘与进度条联动6.1 功能需求设计一个简易设备监控页面页面包含一个温度仪表盘量程 0 到 100 摄氏度。一个任务进度条显示数据采集进度。一个标签显示当前进度百分比。模拟逻辑温度值在 20 到 80 之间随机波动进度每 500ms 增加 5%达到 100% 后重新归零。6.2 界面布局借助 LVGL 的对象布局我们可以把仪表盘放在屏幕上方把进度条和标签放在下方。lv_obj_t *screen lv_scr_act(); meter lv_meter_create(screen); lv_obj_set_size(meter, 200, 200); lv_obj_align(meter, LV_ALIGN_TOP_MID, 0, 0); scale lv_meter_add_scale(meter); lv_meter_set_scale_ticks(meter, scale, 11, 2, 10, lv_palette_main(LV_PALETTE_BLUE)); lv_meter_set_scale_major_ticks(meter, scale, 2, 4, 15, lv_color_black(), 10); lv_meter_set_scale_range(meter, scale, 0, 100, 270, 90); indic lv_meter_add_needle_line(meter, scale, 3, lv_palette_main(LV_PALETTE_RED), -10); bar lv_bar_create(screen); lv_obj_set_size(bar, 240, 20); lv_obj_align(bar, LV_ALIGN_BOTTOM_MID, 0, -40); lv_bar_set_range(bar, 0, 100); label lv_label_create(screen); lv_obj_align(label, LV_ALIGN_BOTTOM_MID, 0, -10); lv_label_set_text(label, 0%);6.3 模拟数据更新定时器回调中同时更新仪表盘和进度条static void sim_timer_cb(lv_timer_t *timer) { static int temperature 25; static int progress 0; temperature random(-5, 6); if (temperature 20) temperature 20; if (temperature 80) temperature 80; lv_meter_set_indicator_value(meter, indic, temperature); progress 5; if (progress 100) progress 0; lv_bar_set_value(bar, progress, LV_ANIM_ON); char buf[32]; sprintf(buf, 进度: %d%%, progress); lv_label_set_text(label, buf); }初始化随机数种子randomSeed(analogRead(34));然后把定时器挂到 LVGL 上lv_timer_create(sim_timer_cb, 500, NULL);6.4 主循环集成Arduino 的主循环需要调用lv_timer_handler()来驱动 LVGL 任务处理void loop() { lv_timer_handler(); delay(5); }lv_timer_handler()负责处理 LVGL 内部的事件、刷新和动画任务。如果主循环中没有调用它界面不会刷新。6.5 快速验证步骤将代码编译烧录到 ESP32 后预期效果如下屏幕显示一个 0 到 100 的圆形仪表盘指针在 20 到 80 之间来回摆动。仪表盘下方显示一个水平进度条5%、10%、15% 逐步增长。进度条旁边的文字同步显示当前百分比。进度达到 100% 后自动归零重新开始循环。如果屏幕没有显示优先检查 TFT_eSPI 的引脚配置和 LVGL 初始化顺序。7. 常见问题与排查思路7.1 屏幕白屏或无显示问题现象常见原因解决思路屏幕背光亮但无内容TFT_eSPI 引脚配置错误核对 User_Setup.h 中的 TFT_CS、DC、RST、MOSI、SCLK 引脚屏幕显示花屏SPI 频率过高或接线过长降低 TFT_eSPI 的 SPI 频率使用短杜邦线所有控件都不显示LVGL 初始化顺序问题确认lv_init()在tft.begin()之前执行画面卡死未调用lv_timer_handler()在主循环中周期调用lv_timer_handler()7.2 仪表盘指针不显示如果仪表盘创建了刻度但指针没有出现常见原因有三个没有调用lv_meter_add_needle_line添加指针。指针颜色和背景颜色相同。指针指向的值超出了lv_meter_set_scale_range设置的范围例如量程是 0 到 100但设置值到了 120。排查方式先把指针初始值设为范围正中间例如 50看指针是否出现。如果出现说明值域配置有问题。7.3 进度条动画卡顿进度条动画卡顿通常是由于主循环或定时器中有阻塞操作。比如在loop()中使用delay(1000)或者在 LVGL 定时器回调中执行网络请求。解决方案将耗时的任务放到xTaskCreatePinnedToCore创建的独立 FreeRTOS 任务中。LVGL 定时器回调中只做数值计算和控件更新。主循环中的延时控制在 5ms 到 20ms 之间。7.4 触摸不准使用触摸屏时如果触摸坐标偏差大需要在 LVGL 输入设备驱动中做坐标校准。最简单的方法是使用lv_touchpad_calibrate等校准工具或者根据屏幕旋转方向调整x、y映射逻辑。在没有准确校准前仪表盘和进度条这类界面可以先不接入触摸输入仅做显示降低复杂度。8. 最佳实践与工程建议8.1 显存和帧缓冲优化LVGL 的内存使用主要集中在帧缓冲上。推荐使用部分缓冲partial buffer来降低 RAM 占用。lv_disp_draw_buf_init中的缓冲区大小设置为屏幕宽度的 10 到 20 行即可不需要为整屏分配缓冲。例如 320x240 分辨率缓冲区设置为static lv_color_t buf[320 * 10];如果内存吃紧可以调整到320 * 5但可能会略微影响渲染性能。8.2 控件样式统一管理仪表盘和进度条涉及大量颜色、边框、圆角设置。建议将样式设置统一封装成函数例如static void apply_theme(lv_obj_t *obj) { lv_obj_set_style_bg_color(obj, lv_color_hex(0x222222), LV_STATE_DEFAULT); lv_obj_set_style_border_width(obj, 2, LV_STATE_DEFAULT); }这样可以方便地在多个页面复用主题不需要每个控件重新设置一套样式。8.3 数据更新与界面刷新分离在实际嵌入式项目中传感器采集、网络通信、数据处理和界面显示应该分层设计。建议结构如下采集任务读取传感器数据存放到全局变量或队列。业务任务处理数据生成仪表盘和进度条需要的值。界面任务在 LVGL 定时器中读取最新值并刷新控件。这样做的好处是界面刷新频率与数据变化频率解耦避免传感器偶发波动导致界面频繁重绘。8.4 使用标签显示数值补充仪表盘只有指针用户很难读准确精确数值。建议在仪表盘中心或旁边添加一个标签控件显示数字值lv_obj_t *value_label lv_label_create(meter); lv_label_set_text(value_label, 0); lv_obj_center(value_label);更新时同步调用char temp[8]; sprintf(temp, %d, temperature); lv_label_set_text(value_label, temp);进度条同理推荐在右侧或上方添加百分比标签。8.5 固件升级场景中的注意事项如果进度条用于 OTA 升级进度展示需要注意OTA 写入 Flash 时会占用大量 CPU 和 SPI 资源可能导致界面刷新暂停。建议在 OTA 过程中将 LVGL 刷新频率调低或者使用双核调度让 OTA 任务运行在 Core 0LVGL 刷新运行在 Core 1。进度值应使用原子变量或 volatile 修饰避免任务间读取不一致。8.6 关于 LVGL 8.x 与 9.x 的迁移建议LVGL 9.x 对部分 API 做了调整例如lv_meter的指针创建函数参数顺序可能变化。如果你从 8.3 升级到 9.x编译报错时优先查看官方文档中的 API 变更说明。本文代码在 8.3 系列验证通过9.x 环境下需要适当调整。如果项目和本文一样使用了lv_palette_main系列颜色接口注意该接口在 8.x 中位于lv_color.h在 9.x 中目录结构有改动正确引入头文件即可编译。9. 总结与下一步学习方向到这里LVGL 仪表盘和进度条的核心用法已经完整覆盖。通过本文可以掌握如何初始化 LVGL 并挂载屏幕驱动。如何使用 lv_meter 创建带刻度的圆形仪表盘并更新指针值。如何使用 lv_bar 创建动态进度条并通过 LV_ANIM_ON 实现平滑过渡。如何通过 LVGL 定时器周期性刷新控件。如何排查屏幕无显示、指针不出现、动画卡顿等常见问题。接下来可以继续学习LVGL 的页面切换和容器布局实现多页面控制面板。LVGL 配合蓝牙或 Wi-Fi让仪表盘显示真实传感器数据。LVGL 与 FreeRTOS 任务结合将复杂业务逻辑移出 UI 线程。LVGL 的样式状态机制实现点击、按下、禁用等交互效果。使用 LVGL 模拟器在 PC 上调试界面加快开发效率。仪表盘和进度条看似是两个简单控件但它们是嵌入式人机交互中最常用的可视化形式。把这两个控件的创建、更新、样式和性能细节吃透再延伸到其他 LVGL 控件思路是完全通用的。建议直接拿起一块 ESP32 开发板跟着本文的代码敲一遍遇到报错再回头对照参数表很快就能形成自己的 LVGL 开发节奏。
