Smart-granary-code/components/lvgl_st7789_use

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

---

在主程序中调用

#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