开始前适用开发板：ESP32-P4 + ESP32-C5 · 开发框架：ESP-IDF
适用开发板：P4C5 · 工程
03.development.lvgl_esp_adapter· targetesp32p4
前置：MIPI 屏触摸
内容：官方esp_lvgl_adapter+ BSP 跑lv_demo_benchmark
学习时长：约 20 分钟 · 难度：★★☆☆☆
学习目标
完成本节后，你将能够：
- 理解
esp_lvgl_adapter的作用和内部机制 - 区分「手写 MIPI port」和「BSP + adapter」两种方案
- 阅读 LVGL benchmark 结果并进行性能对比
- 掌握 P4C5 后续所有 LVGL 工程的基础架构
1. 这个例子在干嘛
用 esp_lvgl_adapter + ksdiy_p4c5_bsp 的标准化方式初始化整个显示系统，然后跑 LVGL 官方 lv_demo_benchmark 测试图形性能。
与 mipi_lcd_touch 的关系：
| 对比项 | mipi_lcd_touch（上一节） | 本例（lvgl_esp_adapter） |
|---|---|---|
| MIPI 初始化 | 手写 AXP + MIPI + Touch | BSP 一键完成 |
| LVGL 移植 | 手写 flush/tick/handler | adapter 自动处理 |
| Demo | Meter 仪表盘 | benchmark 性能测试 |
| 学习价值 | 理解底层 | 后续工程的标准架构 |
类比：mipi_lcd_touch 是「从零组装电脑」，lvgl_esp_adapter 是「品牌整机开箱即用」。
2. 软件架构
┌─────────────────────────────────────┐
│ lv_demo_benchmark() │ 应用层
├─────────────────────────────────────┤
│ LVGL 9 核心 │
├───────────────┬─────────────────────┤
│ Display Port │ Input Device Port │
├───────────────┴─────────────────────┤
│ esp_lvgl_adapter │ ← 自动桥接
│ · flush 回调 → MIPI 写屏 │
│ · 多缓冲管理 │
│ · 旋转处理 │
│ · 防撕裂（TE 信号） │
├─────────────────────────────────────┤
│ ksdiy_p4c5_bsp │ ← 板级支持包
│ · AXP2101 PMIC 初始化 │
│ · MIPI DSI ST7102 配置 │
│ · ST7123 触摸初始化 │
│ · 背光 PWM │
└─────────────────────────────────────┘
adapter 具体做了什么？
| 功能 | 说明 |
|---|---|
| Display 注册 | 自动创建 lv_display_t，注册 flush 回调 |
| Tick 提供 | esp_timer 驱动 lv_tick_inc() |
| 任务创建 | 独立 FreeRTOS 任务运行 lv_timer_handler() |
| 多缓冲 | 支持双缓冲/三缓冲，减少撕裂 |
| 旋转 | 统一的旋转 API，触摸坐标自动跟随 |
| 线程安全 | 内置互斥锁管理 |
3. 编译烧录
cd P4_C5_4.3_Firmware\03.development.lvgl_esp_adapter
idf.py set-target esp32p4
idf.py build flash monitor
无需 Wi-Fi。首次建议先跑通 mipi_lcd_touch 确认硬件。
4. 运行现象
| 阶段 | 屏幕表现 | 串口输出 |
|---|---|---|
| 启动 | BSP 初始化 → 短暂黑屏 | AXP/MIPI/Touch 日志 |
| Benchmark 运行 | 自动循环多个测试场景 | 各场景 FPS |
| 完成 | 显示汇总分数或停在最后场景 | 最终 Weighted FPS |
Benchmark 场景说明
| 场景 | 测试内容 | 性能关注点 |
|---|---|---|
| 矩形填充 | 纯色矩形渲染 | GPU/DMA 带宽 |
| 边框 | 矩形边框渲染 | 线条绘制效率 |
| 文字 | 字体渲染 | 字体缓存命中率 |
| 图片 | 图像贴图 | 内存带宽 |
| 阴影 | 阴影效果 | CPU 计算量 |
| 渐变 | 颜色渐变 | 像素级计算 |
| 旋转图片 | 旋转贴图 | 矩阵运算 |
P4C5 MIPI 参考 FPS：4060+ fps（优于 Korvo SPI 的 2040 fps）。
5. 关键文件与代码解析
| 文件 | 作用 | 重点关注 |
|---|---|---|
main/app_main.c | BSP 初始化 + adapter + demo | 代码极简 |
components/ksdiy_p4c5_bsp | 板级硬件初始化 | 黑盒调用即可 |
managed_components/esp_lvgl_adapter | LVGL 适配层 | 自动下载 |
典型 app_main（极简）
void app_main(void) {
bsp_display_start(); // BSP 初始化一切 + LVGL
bsp_display_lock(0); // 获取 LVGL 互斥锁
lv_demo_benchmark(); // 启动 benchmark
bsp_display_unlock(); // 释放锁
}
重点：只需 4 行代码 就完成了从 PMIC → MIPI → Touch → LVGL → Demo 的全部初始化。后续 MP3、相册、小智等工程的显示部分都是这个模式。
6. 性能优化指南
| 优化项 | 方法 | 效果 |
|---|---|---|
| PSRAM 带宽 | 配置为 QPI 200MHz | 帧缓冲读写更快 |
| 多缓冲 | 开启双缓冲/三缓冲 | 流水线化，减少等待 |
| CPU 频率 | 配置为最高（以芯片支持为准） | 加速 LVGL 渲染计算 |
| LVGL 内存 | 增大 CONFIG_LV_MEM_SIZE | 减少内存分配失败 |
| PPA 加速 | P4 专有像素处理加速器 | 硬件加速缩放/旋转 |
7. 常见问题与排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 不亮屏 | AXP/MIPI 硬件问题 | 先跑 board_test |
| FPS 偏低 | PSRAM 带宽配置低 | menuconfig → PSRAM → QPI 200MHz |
| FPS 偏低 | 单缓冲 | 检查 sdkconfig 缓冲配置 |
| 画面撕裂 | 未开 TE（Tearing Effect）信号 | 确认 adapter 配置中 TE 使能 |
| 触摸偏移 | 旋转角不匹配 | 检查 adapter 和 BSP 的旋转设置一致 |
| 编译缺组件 | 网络问题 | idf.py reconfigure 重试 |
8. 动手改造建议
- 换 Demo：
lv_demo_benchmark()→lv_demo_widgets()体验全部控件 - 对比旋转：跑
lvgl_esp_adapter_rotate工程，测试四向旋转性能 - 性能对比：修改
CONFIG_LV_MEM_SIZE和缓冲大小，记录 FPS 变化 - 自定义 UI：在 benchmark 之后添加自己的 LVGL 页面
- 与 Korvo 对比：跑 Korvo lvgl_esp_adapter，对比 SPI 与 MIPI 性能差距
9. 知识延伸
- ESP-IDF 显示生态：
esp_lcd+esp_lvgl_adapter+BSP三层架构是乐鑫推荐的标准显示方案 - LVGL 9 的变化：从 LVGL 8 升级到 9，API 变化显著（
lv_disp_drv_t→lv_display_t），不能照搬旧教程 - BSP 的价值：换板（如从 P4C5 换到其他 MIPI 屏板）只需换 BSP 组件，应用代码零修改
10. 下一步
| 方向 | 推荐例程 | 说明 |
|---|---|---|
| MP3 播放器 | MP3 | LVGL + 音频 |
| 电子相册 | esp-album | LVGL + 图片展示 |
| 小智 AI | xiaozhi | LVGL + AI 对话 |
酷世DIY · Kevincoooool