990abc210c
新增资源文件：添加了字体、图像和屏幕相关的头文件与源文件。 定义数据结构：创建了用于描述字体和图像的数据结构。 实现主屏逻辑：实现了主屏幕的创建函数以及周期性刷新（tick）函数。 集成 LVGL 管理：集成了 LVGL 主题初始化及屏幕管理功能。 添加 UI 初始化：新增 UI 初始化及刷新函数，用于管理界面更新。 重构主入口：重构主应用程序入口，以支持 UI 任务及 FreeRTOS 多任务调度。 更新构建配置：更新了 CMakeLists 及组件配置，以包含新的依赖项。
115 lines
2.6 KiB
Markdown
115 lines
2.6 KiB
Markdown
# lvgl_st7789_use 组件说明
|
||
|
||
`lvgl_st7789_use` 是项目中的 LCD 显示组件，基于 `esp_lcd + esp_lvgl_port`，用于快速驱动 ST7789 SPI 屏并显示 LVGL 界面。
|
||
|
||
---
|
||
|
||
## 功能概览
|
||
|
||
- 初始化 SPI LCD（含背光、面板、显示偏移）
|
||
- 初始化 LVGL 端口并注册显示设备
|
||
- 默认创建一个居中标签用于快速验证显示链路
|
||
- 提供运行时更新中心文本接口
|
||
- 支持可配置方向、镜像与偏移
|
||
- 支持可选三色测试图（调试用）
|
||
|
||
---
|
||
|
||
## 对外 API
|
||
|
||
头文件：`include/lvgl_st7789_use.h`
|
||
|
||
- `esp_err_t start_lvgl_demo(void);`
|
||
- 完成 LCD + LVGL 初始化并创建默认界面
|
||
|
||
- `esp_err_t lvgl_st7789_set_center_text(const char *text);`
|
||
- 运行时更新中心标签文字（线程安全，内部已加锁）
|
||
|
||
---
|
||
|
||
## 关键配置项（可直接改宏）
|
||
|
||
在 `include/lvgl_st7789_use.h` 中：
|
||
|
||
### 1) 屏幕与 SPI
|
||
|
||
- `EXAMPLE_LCD_H_RES` / `EXAMPLE_LCD_V_RES`
|
||
- `EXAMPLE_LCD_PIXEL_CLK_HZ`
|
||
- `EXAMPLE_LCD_SPI_NUM`
|
||
- `EXAMPLE_LCD_CMD_BITS` / `EXAMPLE_LCD_PARAM_BITS`
|
||
|
||
建议：ST7789 默认可先用 `20MHz`，如出现花屏或不稳定再降到 `10MHz` 复测。
|
||
|
||
### 2) 颜色校准（重点）
|
||
|
||
- `EXAMPLE_LCD_COLOR_ORDER_BGR`
|
||
- `EXAMPLE_LCD_INVERT_COLOR`
|
||
- `EXAMPLE_LCD_SWAP_BYTES`
|
||
|
||
说明：
|
||
- 出现“黑色发灰、红绿蓝偏紫/互串”时，优先调整这三项。
|
||
- 建议从 `RGB + 不反色 + 不交换字节` 起步，再逐项切换。
|
||
|
||
### 3) 方向与偏移（重点）
|
||
|
||
- `EXAMPLE_LCD_GAP_X`
|
||
- `EXAMPLE_LCD_GAP_Y`
|
||
- `EXAMPLE_LCD_ROT_SWAP_XY`
|
||
- `EXAMPLE_LCD_ROT_MIRROR_X`
|
||
- `EXAMPLE_LCD_ROT_MIRROR_Y`
|
||
|
||
说明：
|
||
- 若出现“文字偏移/边缘花屏/方向反了”，优先微调上述宏，不要同时在多层重复旋转。
|
||
|
||
### 4) 调试项
|
||
|
||
- `EXAMPLE_LCD_ENABLE_COLOR_TEST`
|
||
- `1`：上电先画 RGB 三色测试图（便于确认硬件链路）
|
||
- `0`：跳过测试，直接进入 LVGL
|
||
|
||
---
|
||
|
||
## 在主程序中调用
|
||
|
||
```c
|
||
#include "esp_check.h"
|
||
#include "lvgl_st7789_use.h"
|
||
|
||
void app_main(void)
|
||
{
|
||
ESP_ERROR_CHECK(start_lvgl_demo());
|
||
ESP_ERROR_CHECK(lvgl_st7789_set_center_text("BotanicalBuddy"));
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 1) 背光亮但没有内容
|
||
|
||
优先排查：
|
||
- 面板型号与驱动是否匹配（当前应为 ST7789）
|
||
- SPI 模式、时钟是否过高
|
||
- 方向/偏移参数是否正确
|
||
|
||
### 2) 文字方向反了或显示偏移
|
||
|
||
优先调整：
|
||
- `EXAMPLE_LCD_ROT_*`
|
||
- `EXAMPLE_LCD_GAP_X / EXAMPLE_LCD_GAP_Y`
|
||
|
||
### 3) 想快速确认硬件链路是否通
|
||
|
||
把 `EXAMPLE_LCD_ENABLE_COLOR_TEST` 设为 `1`，观察是否能显示三色图。
|
||
|
||
---
|
||
|
||
## 依赖
|
||
|
||
由组件 `CMakeLists.txt` 声明：
|
||
|
||
- `driver`
|
||
- `esp_lcd`
|
||
- `esp_lvgl_port`
|