使用 LVGL
LVGL 是一个面向嵌入式设备的开源图形库。它提供了现成的 UI 组件，例如标签、面板、进度条和布局工具，因此你可以在 C/C++ 中构建结构化界面，而无需手动绘制每一个像素。
本指南将使用 PlatformIO 创建一个简单的 LVGL 电子纸状态面板。示例默认以 reTerminal E1001 为目标，并为 reTerminal E1002、E1003 和 E1004 分别保留独立的 PlatformIO 环境。
该项目会渲染一个静态仪表盘，包含：
- 一个标题，
- 一个设备状态卡片，
- 一个网络状态卡片，
- 一个演示用电池卡片。
对于电子纸显示屏，这种静态 UI 工作流是一个很好的起点，因为只有在显示信息发生变化时，屏幕才需要刷新。
如果你想在搭建开发环境之前，快速预览项目效果或体验基础演示固件，请打开 reTerminal E-Series Firmware Hub。你可以选择受支持的 reTerminal E 系列设备，并直接通过浏览器烧录演示固件。
兼容硬件
准备以下 reTerminal E 系列设备之一。本指南中的 PlatformIO 项目默认使用 reTerminal E1001 作为环境。
| reTerminal E1003 | reTerminal E1004 |
|---|---|
 |  |
| 10.3" 黑白电子纸 1872 x 1404 | 13.3" Spectra 6 色电子纸 1200 x 1600 |
项目工作原理
本示例主要包含两个部分：
- LVGL 创建 UI 对象，例如标签、卡片和进度条。
- Seeed_GFX 初始化电子纸显示屏，接收渲染后的像素，并刷新物理面板。
项目将这两部分放在不同的文件中：
| 文件 | 用途 |
|---|---|
platformio.ini | 定义 PlatformIO 开发板、库、编译标志和硬件环境。 |
include/driver.h | 为当前激活的硬件目标选择正确的 Seeed_GFX 驱动文件。 |
include/driver_e1001.h 到 include/driver_e1004.h | 为每个 reTerminal E 系列型号存储 Seeed_GFX 的板卡与屏幕组合配置。 |
include/lv_conf.h | 配置 LVGL 功能、色深和字体。 |
src/main.cpp | 初始化 Arduino、Seeed_GFX、LVGL、显示缓冲区以及电子纸刷新流程。 |
src/ui_status_panel.cpp | 创建 LVGL 状态面板布局。 |
步骤 1：安装 PlatformIO
本指南使用 PlatformIO 作为项目工作流。PlatformIO 会将开发板配置、库和源文件集中在一个文件夹中，使 LVGL 项目更易于构建和维护。
如果尚未安装 PlatformIO，请按照 使用 PlatformIO 中的步骤进行设置，然后再回到本指南。
安装完成后，打开 Visual Studio Code。你应该能在左侧活动栏中看到 PlatformIO 图标。
步骤 2：下载示例项目
LVGL 电子纸状态面板示例位于官方 reTerminal E 系列仓库中：
将该仓库下载到你的电脑，然后打开以下文件夹：
OSHW-reTerminal-Series-E-D/examples/official/LVGLePaperStatusPanel
示例项目包含以下主要文件：
| 文件 | 功能说明 |
|---|---|
platformio.ini | 为 E1001、E1002、E1003 和 E1004 定义 PlatformIO 环境。 |
include/driver.h | 为当前构建环境选择正确的电子纸驱动配置。 |
include/lv_conf.h | 配置本演示所使用的 LVGL 功能和字体。 |
src/main.cpp | 初始化显示屏、LVGL、渲染缓冲区以及电子纸刷新流程。 |
src/ui_status_panel.cpp | 创建显示在电子纸上的状态面板 UI。 |
步骤 3：在 PlatformIO 中打开项目
步骤 1. 打开 Visual Studio Code。
步骤 2. 点击左侧活动栏中的 PlatformIO 图标。
步骤 3. 点击 PIO Home > Open。
步骤 4. 点击 Open Project。
步骤 5. 选择 LVGLePaperStatusPanel 文件夹。
步骤 6. 等待 PlatformIO 加载项目并安装所需库。
步骤 4：选择硬件环境
在项目根目录中打开 platformio.ini。默认环境为 reterminal_e1001。
[platformio]
default_envs = reterminal_e1001
对于 E1001，你可以保留默认设置。对于其他设备，将 default_envs 修改为对应的环境：
| 设备 | PlatformIO 环境 |
|---|---|
| reTerminal E1001 | reterminal_e1001 |
| reTerminal E1002 | reterminal_e1002 |
| reTerminal E1003 | reterminal_e1003 |
| reTerminal E1004 | reterminal_e1004 |
你也可以在不修改 default_envs 的情况下，通过 PlatformIO 终端构建特定环境。
步骤 5：构建并上传演示程序
使用 USB 线将 reTerminal E 系列设备连接到电脑。
要构建默认的 E1001 固件，请运行：
pio run
要构建特定目标，请添加 -e 和环境名称。例如：
pio run -e reterminal_e1001
要将固件上传到设备，请运行：
pio run -e reterminal_e1001 --target upload
上传完成后，打开串口监视器：
pio device monitor -b 115200
当示例程序正确启动时，串口监视器会显示：
Seeed ePaper LVGL status panel starting.
LVGL status panel rendered.
ePaper 显示屏会刷新一次，并显示 LVGL 状态面板。
步骤 6：自定义并从 LVGL UI 中学习
在示例程序成功运行后，你可以开始将其作为一个小型 LVGL 学习项目进行修改。两个最重要的文件是：
| File | Start Here When You Want To |
|---|---|
src/main.cpp | 更改传入 UI 的数值，例如设备状态、网络状态和电池百分比。 |
src/ui_status_panel.cpp | 更改屏幕标题、卡片布局、字体、颜色、标签和 LVGL 组件。 |
更改显示的数值
打开 src/main.cpp，在 setup() 中找到这一行：
ui_status_panel_set_status("Ready", "Wi-Fi Standby", 76);
此函数会更新屏幕上的三个动态数值：
| Parameter | Meaning | Example |
|---|---|---|
status | 显示在 Device 卡片中的设备状态文本。 | "Ready" |
network | 显示在 Network 卡片中的网络状态文本。 | "Wi-Fi Standby" |
battery_percent | 电池条的数值。该函数会将其限制在 0 到 100 之间。 | 76 |
例如，将其更改为：
ui_status_panel_set_status("Online", "Wi-Fi Connected", 95);
然后再次构建并上传项目：
pio run -e reterminal_e1001 --target upload
更改标题和卡片名称
打开 src/ui_status_panel.cpp。主标题在 ui_status_panel_create() 中创建：
lv_label_set_text(title, "Seeed ePaper LVGL Panel");
你可以更改标题文本：
lv_label_set_text(title, "My First LVGL Dashboard");
每个卡片是通过 create_card() 创建的。例如：
lv_obj_t *status_card = create_card(screen, "Device", status_x, status_y, status_w, status_h, lv_palette_main(LV_PALETTE_RED));
lv_obj_t *network_card = create_card(screen, "Network", network_x, network_y, network_w, network_h, lv_palette_main(LV_PALETTE_BLUE));
lv_obj_t *battery_card = create_card(screen, "Battery Demo", battery_x, battery_y, battery_w, battery_h, lv_palette_main(LV_PALETTE_GREEN));
第二个参数是卡片标题。你可以将 "Device"、"Network" 和 "Battery Demo" 更改为与你自己的应用相匹配的名称。
更改颜色
该示例使用 LVGL 调色板颜色：
lv_palette_main(LV_PALETTE_RED)
lv_palette_main(LV_PALETTE_BLUE)
lv_palette_main(LV_PALETTE_GREEN)
对于 reTerminal E1002 和 reTerminal E1004 等彩色 ePaper 型号，src/main.cpp 会将 LVGL 颜色映射到 ePaper 调色板。示例调色板包括白色、黑色、红色、黄色、绿色和蓝色。
对于 reTerminal E1001 和 reTerminal E1003 等黑白 ePaper 型号，相同的 UI 会根据亮度转换为黑白。较暗的颜色变为黑色，较亮的颜色变为白色。
这意味着你可以在四款设备上使用相同的 LVGL UI 代码，而显示驱动会为所选硬件转换最终像素。
更改布局
该示例使用 platformio.ini 中的 EPAPER_LVGL_HOR_RES 和 EPAPER_LVGL_VER_RES 来确定屏幕尺寸。在 src/ui_status_panel.cpp 中，这些数值在此处被使用：
const int32_t screen_width = EPAPER_LVGL_HOR_RES;
const int32_t screen_height = EPAPER_LVGL_VER_RES;
const bool is_landscape = screen_width >= screen_height;
然后布局会为更宽的屏幕选择横向布局，为更高的屏幕选择纵向布局。这就是为什么同一个示例可以在 800 x 480 设备和更大的 ePaper 面板上运行。
作为一个简单的首次修改，可以调整间距数值：
const int32_t margin = max_i32(32, screen_width / 20);
const int32_t gap = max_i32(20, screen_width / 40);
增大 margin 会在屏幕边缘留出更多空白。增大 gap 会在卡片之间留出更多空间。
添加你自己的数据
本示例中的电池数值是示例 UI 数据，因此屏幕会将其显示为演示数值。要连接真实的应用数据，请保留 UI 函数，并将你自己的数值传入其中：
int battery_percent = 88;
ui_status_panel_set_status("Running", "Wi-Fi Connected", battery_percent);
对于 ePaper 项目，一个实用的工作流程是：
步骤 1. 在你的应用中读取或计算最新数据。
步骤 2. 将新数值传入 ui_status_panel_set_status()。
步骤 3. 当内容需要更改时刷新 ePaper 显示屏。
该示例在 setup() 中渲染一次，因为屏幕内容是静态的。对于传感器仪表盘、日历或状态监视器等应用，你可以在显示数据发生变化时更新数值并刷新面板。
资源
- [Docs] LVGL 文档
- [GitHub] LVGL
- [GitHub] Seeed_GFX 库
- [GitHub] LVGL ePaper 状态面板示例
- [Tool] reTerminal E-Series 固件中心
- [Wiki] 使用 PlatformIO 工作
技术支持与产品讨论
感谢你选择我们的产品！我们将为你提供多种支持，以确保你在使用我们产品时的体验尽可能顺畅。我们提供多种沟通渠道，以满足不同的偏好和需求。