衡山派Luban-Lite系统LVGL示例程序配置与自定义APP开发实战
衡山派Luban-Lite系统LVGL示例程序配置与自定义APP开发实战
最近在用衡山派的开发板做项目，需要做一个带界面的产品。官方SDK里已经集成了LVGL这个强大的嵌入式图形库，还提供了几个现成的Demo。但很多朋友拿到手后，不知道该怎么配置这些Demo，更不清楚如何把自己的界面程序加进去。今天我就以实际项目经验，手把手带你走一遍从配置官方Demo到创建自定义APP的全过程，帮你避开我当初踩过的那些坑。
1. 运行官方LVGL Demo：从配置到显示
咱们先来看看怎么让官方提供的LVGL Demo跑起来。这就像是拿到一个新玩具，先看看它自带的几个演示效果，了解下它的能力。
1.1 进入系统配置菜单
衡山派的Luban-Lite系统基于RT-Thread，所有的功能模块都是通过一个叫menuconfig的图形化界面来配置的。打开它很简单，在SDK的根目录下执行：
me这个命令会打开一个基于终端的配置界面，用上下键和空格键就能操作。咱们要配置的东西都在这里面。
1.2 关键配置项详解
进入me界面后，找到Application options这个主菜单，按回车进入。这里面的配置项比较多，我挑几个和LVGL Demo直接相关的重点讲。
第一步：启用并配置文件系统LVGL的界面通常需要显示图片、字体等资源，这些资源文件需要放在一个文件系统里（比如FATFS）供程序读取。所以首先要确保文件系统镜像被启用。
在Application options菜单下，找到*** Filesystem related ***部分：
- 确保
[*] Using File System Image 0被选中（按空格键，出现[*]表示选中）。 - 进入
--- Using File System Image 0子菜单。 Select File System Type保持默认的(FATFS)即可。Data Directory这个路径非常关键！它告诉系统去哪里找Demo所需的图片、字体等资源文件。路径必须和你选择的Demo匹配，否则程序找不到资源，屏幕就是一片白。Image Name可以保持默认的app.fatfs。- 建议勾选
[*] auto calcuate image size，让系统自动计算文件系统镜像的大小。
第二步：选择并配置LVGL Demo还是在Application options菜单下，找到*** lvgl demo select related ***部分：
- 确保
[*] ArtInChip lvgl demo被选中。这个是衡山派（ArtInChip）提供的LVGL演示程序集。 - 进入
--- ArtInChip lvgl demo子菜单。 - 重点来了：
select lvgl demo这个选项让你选择具体运行哪个Demo。用左右键切换：(X) lvgl demo with basic function: 基础功能演示，包含按钮、滑块、图表等基础控件。( ) lvgl demo of meter: 仪表盘演示，一个很炫酷的汽车仪表盘界面。
- 下面的
LVGL color depth和LVGL image cached number通常用默认值（16位色深，8张图片缓存）就行，初次使用不建议修改。 LVGL Resource Directory是LVGL库内部寻找资源的路径，一般保持默认的/rodata/lvgl_data。
注意：路径匹配的坑！这是我第一次配置时栽跟头的地方。
Using File System Image 0里的Data Directory路径，必须和上面select lvgl demo选择的Demo对应上。
- 如果你选了
lvgl demo with basic function，那么Data Directory应该填：(packages/artinchip/lvgl-ui/aic_demo/base_demo/lvgl_src/)- 如果你选了
lvgl demo of meter，那么Data Directory应该填：(packages/artinchip/lvgl-ui/aic_demo/meter_demo/lvgl_src/)填错了路径，编译出来的固件里就没有对应Demo的图片资源，上电后LVGL线程跑起来，但界面是白的，调试起来很头疼。
配置完成后，按ESC键退出，记得保存配置。然后编译、下载固件到开发板，上电后就能看到对应的LVGL演示界面了。
2. 创建你自己的LVGL应用（test_demo）
官方Demo跑通了，但咱们的项目肯定需要自己的界面。接下来，我以添加一个名为test_demo的自定义应用为例，把整个流程拆解清楚。
2.1 第一步：在配置菜单中添加选项
首先，得让系统知道有test_demo这个应用存在，并且可以在me配置界面里选择它。这个配置信息写在application/Kconfig文件里。
用文本编辑器打开这个文件，找到类似下面这样定义其他Demo的地方（比如AIC_LVGL_METER_DEMO）：
config AIC_LVGL_METER_DEMO bool "LVGL demo of meter"咱们就在它附近，仿照着添加我们自己的配置项：
config AIC_LVGL_TEST_DEMO # 这个宏名很重要，后面代码里要用到 bool "LVGL demo of test"config AIC_LVGL_TEST_DEMO：这定义了一个配置选项的标识符（宏），在C代码中可以通过#ifdef AIC_LVGL_TEST_DEMO来判断是否选中了我们的Demo。bool：表示这是一个布尔类型的选项（要么选中，要么不选）。"LVGL demo of test"：这是在me配置界面里显示给用户看的描述文字。
保存Kconfig文件后，下次执行me命令，就能在菜单里看到我们的新选项了。
2.2 第二步：在配置界面中选择你的APP
现在，再次运行me命令，进入配置界面。
- 导航到
Application options ---> [*] ArtInChip LVGL demo --->。 - 你会看到
select LVGL demo这个选项，按回车进入。 - 在出现的列表中，用方向键移动，按空格键选中我们刚刚添加的
(X) LVGL demo of test。 - 保存并退出配置。
2.3 第三步：配置自定义APP的资源路径
和运行官方Demo一样，我们的test_demo如果有图片、字体等资源，也需要告诉文件系统去哪里找。假设我们的资源文件放在packages/artinchip/lvgl-ui/aic_demo/test_demo/lvgl_src/目录下。
在me配置界面中：
- 进入
Application options ---> [*] Using File System Image 0 --->。 - 将
Data Directory的路径修改为：(packages/artinchip/lvgl-ui/aic_demo/test_demo/lvgl_src/)提示：这个路径是以你的SDK根目录为起点的，请根据你实际存放资源的目录进行调整。即使资源目录里只有一个空的
readme.txt文件，也需要正确配置，否则文件系统镜像可能不会包含该目录。
2.4 第四步：准备源码并编写构建脚本
现在来准备我们test_demo的源代码。按照SDK的惯例，我们在packages/artinchip/lvgl-ui/aic_demo/目录下创建一个名为test_demo的文件夹，并组织好文件结构：
test_demo/ ├── lvgl_src/ # 存放图片、字体等资源文件 │ └── readme.txt # 用于验证资源打包，可以是空文件 ├── SConscript # 构建脚本，最重要！ ├── thread/ # 应用线程相关代码 │ ├── test_thread.c │ └── test_thread.h └── ui/ # 界面绘制相关代码 ├── test_ui.c └── test_ui.h其中，SConscript文件是告诉编译系统如何编译我们这个Demo的关键。内容如下，我已经加了详细注释：
from building import * import os cwd = GetCurrentDir() # 获取当前目录（即test_demo目录） group = [] # 1. 指定需要编译的源文件 src = Glob('*.c') # 编译test_demo根目录下的.c文件 src += Glob('./ui/*.c') # 编译ui子目录下的.c文件 src += Glob('./thread/*.c') # 编译thread子目录下的.c文件 # 2. 指定头文件搜索路径 CPPPATH = [cwd] # 当前目录 CPPPATH.append(cwd + '/ui') # ui子目录 CPPPATH.append(cwd + '/thread') # thread子目录 # 3. 检查并递归处理子目录（如果你的demo还有更深层目录，这部分会用到） list = os.listdir(cwd) for d in list: path = os.path.join(cwd, d) if os.path.isfile(os.path.join(path, 'SConscript')): group = group + SConscript(os.path.join(d, 'SConscript')) # 4. 定义编译组，关键依赖项是 AIC_LVGL_TEST_DEMO # 只有当在me中选中了我们的demo，这部分代码才会被编译进固件 group = group + DefineGroup('LVGL-port', src, depend = ['AIC_LVGL_TEST_DEMO'], CPPPATH = CPPPATH) Return('group')关键点：depend = [‘AIC_LVGL_TEST_DEMO’]这一行，必须和我们在application/Kconfig里定义的config名字完全一致。这样，编译系统就能根据me中的选择，决定是否编译test_demo的代码。
2.5 第五步：将APP接入系统入口
代码和资源都准备好了，最后一步是告诉系统：“当用户选择了我的test_demo时，请调用我写的初始化函数。”
我们需要修改系统LVGL的入口文件。找到packages/artinchip/lvgl-ui/aic_ui.c中的aic_ui_init()函数。这个函数就像是LVGL应用的总调度中心。
在函数内部，你会看到很多#ifdef ... #endif的代码块，每个官方Demo都在这里有一个“挂号”的地方。咱们就在最后，仿照着添加自己Demo的入口：
void aic_ui_init() { // ... 其他demo的初始化代码 ... #ifdef AIC_LVGL_TEST_DEMO // 如果配置中选中了我们的test_demo // 包含头文件（如果函数声明在头文件里） #include "test_ui.h" // 或者使用 extern 声明（如果头文件已在别处包含） extern void test_thread(); extern void test_ui_init(); // 调用我们应用的初始化函数 test_thread(); // 启动应用线程 test_ui_init(); // 初始化UI界面 #endif return; }这里调用的test_thread()和test_ui_init()就是你写在test_thread.c和test_ui.c里的函数。通过这样的方式，你的自定义应用就被完美地集成到衡山派的LVGL框架里了。
3. 实战心得与避坑指南
走完上面这套流程，你的test_demo应该就能成功编译并运行了。最后分享几个我实战中的心得：
- Bringup阶段别折腾：第一次拿到板子，或者更换硬件平台后，强烈建议先运行官方默认的Demo（比如基础功能演示）。这能最快验证硬件（屏幕、触摸、内存）和基础软件驱动是否工作正常。等默认Demo稳定了，再动手改自己的应用。
- 路径检查要仔细：
Data Directory配错是导致“白屏”的最常见原因。每次在me里切换Demo后，都务必检查这个路径是否对应上了。 - 宏定义要一致：
Kconfig里的config名、SConscript里的depend、C代码里的#ifdef，这三个地方的宏名称必须一字不差，大小写敏感。 - 从模仿开始：如果你不确定
test_ui.c和test_thread.c该怎么写，最好的方法是去参考base_demo或meter_demo里对应的源码。看看官方Demo是如何创建界面、处理事件的，依葫芦画瓢能帮你快速上手。
整个过程看似步骤不少，但理顺了就是“配置菜单声明 -> 选择启用 -> 设置资源路径 -> 组织源码 -> 接入主框架”这条线。自己动手走一遍，下次再给衡山派开发板添加任何新的LVGL应用，你都能轻松搞定。