wangbeihong/BotanicalBuddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 添加 LCD 显示组件 lvgl_st7735s_use，集成 SPI 显示与 LVGL 界面支持

Browse Source
This commit is contained in:
Wang Beihong
2026-03-05 14:40:22 +08:00
parent 3cf8f5c628
commit c2c49cc672
9 changed files with 483 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@@ -1,6 +1,9 @@
# BotanicalBuddy
基于 ESP-IDF 的植物助手项目，当前已集成 **Wi-Fi 配网组件（wifi-connect）**，支持手机连接设备热点后通过网页完成路由器配置。
基于 ESP-IDF 的植物助手项目，当前已集成：
- **Wi-Fi 配网组件（wifi-connect）**：手机连接设备热点后通过网页完成路由器配置
- **LCD 显示组件（lvgl_st7735s_use）**：基于 LVGL 驱动 ST77xx SPI 屏并显示界面
## 功能特性
@@ -9,6 +12,8 @@
- 手机访问 `http://192.168.4.1` 完成 Wi-Fi 配置
- 支持清除已保存 Wi-Fi 参数并重新配网
- 串口中文状态日志，便于调试和现场维护
- 支持 ST77xx SPI LCD 显示（LVGL）
- 支持方向/偏移参数化配置，便于后续适配不同屏幕
## 目录结构
@@ -18,6 +23,8 @@
- `USER_GUIDE.md`：用户操作手册
- `QUICK_POSTER.md`：张贴版快速指引
- `BLOG.md`：博客草稿
- `components/lvgl_st7735s_use/`：LCD 显示组件（LVGL + ST77xx）
- `README.md`：组件说明与调参指南
## 开发环境
@@ -32,7 +39,10 @@
- `idf.py build`
2. 烧录并查看日志
- `idf.py -p /dev/ttyUSB0 flash monitor`
3. 配网
3. 显示初始化
- 在 `app_main` 中调用：`ESP_ERROR_CHECK(start_lvgl_demo());`
- 可选：`ESP_ERROR_CHECK(lvgl_st7735s_set_center_text("BotanicalBuddy"));`
4. 配网
- 长按设备按键进入配网模式
- 手机连接 `ESP32-xxxxxx`
- 打开 `http://192.168.4.1`
@@ -45,4 +55,9 @@
- 路由连接
- 状态显示
- 清除配置
- 中文日志与文档
- 中文日志与文档
并完成 LCD 显示链路：
- SPI 屏初始化
- LVGL 显示注册
- 方向/偏移可配置

4
components/lvgl_st7735s_use/CMakeLists.txt Normal file
View File

@@ -0,0 +1,4 @@
idf_component_register(SRCS "lvgl_st7735s_use.c"
INCLUDE_DIRS "include"
REQUIRES driver esp_lcd esp_lvgl_port
)

105
components/lvgl_st7735s_use/README.md Normal file
View File

@@ -0,0 +1,105 @@
# lvgl_st7735s_use 组件说明
`lvgl_st7735s_use` 是项目中的 LCD 显示组件，基于 `esp_lcd + esp_lvgl_port`，用于快速驱动 ST77xx 系列 SPI 屏并显示 LVGL 界面。
---
## 功能概览
- 初始化 SPI LCD（含背光、面板、显示偏移）
- 初始化 LVGL 端口并注册显示设备
- 默认创建一个居中标签用于快速验证显示链路
- 提供运行时更新中心文本接口
- 支持可配置方向、镜像与偏移
- 支持可选三色测试图（调试用）
---
## 对外 API
头文件：`include/lvgl_st7735s_use.h`
- `esp_err_t start_lvgl_demo(void);`
- 完成 LCD + LVGL 初始化并创建默认界面
- `esp_err_t lvgl_st7735s_set_center_text(const char *text);`
- 运行时更新中心标签文字（线程安全，内部已加锁）
---
## 关键配置项（可直接改宏）
在 `include/lvgl_st7735s_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`
建议：首次点亮优先用较低时钟（如 `10MHz`），稳定后再升频。
### 2) 方向与偏移（重点）
- `EXAMPLE_LCD_GAP_X`
- `EXAMPLE_LCD_GAP_Y`
- `EXAMPLE_LCD_ROT_SWAP_XY`
- `EXAMPLE_LCD_ROT_MIRROR_X`
- `EXAMPLE_LCD_ROT_MIRROR_Y`
说明：
- 当前项目已验证一组可用参数（顺时针 90° + 26 偏移）。
- 若出现“文字偏移/边缘花屏/方向反了”，优先微调上述宏，不要同时在多层重复旋转。
### 3) 调试项
- `EXAMPLE_LCD_ENABLE_COLOR_TEST`
- `1`：上电先画 RGB 三色测试图（便于确认硬件链路）
- `0`：跳过测试，直接进入 LVGL
---
## 在主程序中调用
```c
#include "esp_check.h"
#include "lvgl_st7735s_use.h"
void app_main(void)
{
ESP_ERROR_CHECK(start_lvgl_demo());
ESP_ERROR_CHECK(lvgl_st7735s_set_center_text("BotanicalBuddy"));
}
```
---
## 常见问题
### 1) 背光亮但没有内容
优先排查：
- 面板型号与驱动是否匹配（ST7735S / 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`

56
components/lvgl_st7735s_use/include/lvgl_st7735s_use.h Normal file
View File

@@ -0,0 +1,56 @@
// SPDX-License-Identifier: MIT
#pragma once
#include "esp_err.h"
#ifdef __cplusplus
extern "C" {
#endif
/* LCD size */
#define EXAMPLE_LCD_H_RES (160)
#define EXAMPLE_LCD_V_RES (80)
/* LCD SPI总线配置 */
#define EXAMPLE_LCD_SPI_NUM (SPI2_HOST) // 使用SPI2主机接口进行通信
/* LCD显示参数配置 */
#define EXAMPLE_LCD_PIXEL_CLK_HZ (10 * 1000 * 1000) // 先用10MHz提高兼容性，点亮后再逐步升频
/* LCD命令和参数配置 */
#define EXAMPLE_LCD_CMD_BITS (8) // 命令位数为8位，用于发送LCD控制命令
#define EXAMPLE_LCD_PARAM_BITS (8) // 参数位数为8位，用于发送命令参数
/* LCD颜色和缓冲区配置 */
#define EXAMPLE_LCD_BITS_PER_PIXEL (16) // 每个像素使用16位颜色(RGB565格式)
#define EXAMPLE_LCD_DRAW_BUFF_DOUBLE (1) // 启用双缓冲模式，提高显示流畅度
#define EXAMPLE_LCD_DRAW_BUFF_HEIGHT (50) // 绘图缓冲区高度为50行，影响刷新性能
/* LCD背光配置 */
#define EXAMPLE_LCD_BL_ON_LEVEL (1) // 背光开启电平为高电平(1)
/* LCD方向/偏移配置（当前为顺时针90°，并保留26偏移） */
#define EXAMPLE_LCD_GAP_X (1)
#define EXAMPLE_LCD_GAP_Y (26)
#define EXAMPLE_LCD_ROT_SWAP_XY (1)
#define EXAMPLE_LCD_ROT_MIRROR_X (1)
#define EXAMPLE_LCD_ROT_MIRROR_Y (0)
/* 调试项：上电后是否先显示三色测试图 */
#define EXAMPLE_LCD_ENABLE_COLOR_TEST (0)
/* LCD pins */
#define EXAMPLE_LCD_GPIO_SCLK (GPIO_NUM_2)
#define EXAMPLE_LCD_GPIO_MOSI (GPIO_NUM_3)
#define EXAMPLE_LCD_GPIO_RST (GPIO_NUM_9)
#define EXAMPLE_LCD_GPIO_DC (GPIO_NUM_8)
#define EXAMPLE_LCD_GPIO_CS (GPIO_NUM_7)
#define EXAMPLE_LCD_GPIO_BL (GPIO_NUM_6)
esp_err_t start_lvgl_demo(void);
esp_err_t lvgl_st7735s_set_center_text(const char *text);
#ifdef __cplusplus
}
#endif

239
components/lvgl_st7735s_use/lvgl_st7735s_use.c Normal file
View File

@@ -0,0 +1,239 @@
#include <stdio.h>
#include <stdlib.h>
#include "lvgl_st7735s_use.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#include "driver/spi_master.h"
#include "esp_err.h"
#include "esp_log.h"
#include "esp_check.h"
#include "esp_lcd_panel_io.h"
#include "esp_lcd_panel_vendor.h"
#include "esp_lcd_panel_ops.h"
#include "esp_lvgl_port.h"
static const char *TAG = "lvgl_st7735s_use";
static esp_lcd_panel_io_handle_t lcd_io = NULL;
static esp_lcd_panel_handle_t lcd_panel = NULL;
static lv_display_t *lvgl_disp = NULL;
static lv_obj_t *s_center_label = NULL;
static esp_err_t app_lcd_color_test(void)
{
const size_t pixels = EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES;
uint16_t *frame = calloc(pixels, sizeof(uint16_t));
ESP_RETURN_ON_FALSE(frame != NULL, ESP_ERR_NO_MEM, TAG, "分配测试帧缓冲失败");
for (int y = 0; y < EXAMPLE_LCD_V_RES; y++) {
for (int x = 0; x < EXAMPLE_LCD_H_RES; x++) {
uint16_t color;
if (x < EXAMPLE_LCD_H_RES / 3) {
color = 0xF800; // 红
} else if (x < (EXAMPLE_LCD_H_RES * 2) / 3) {
color = 0x07E0; // 绿
} else {
color = 0x001F; // 蓝
}
frame[y * EXAMPLE_LCD_H_RES + x] = color;
}
}
esp_err_t err = esp_lcd_panel_draw_bitmap(lcd_panel, 0, 0, EXAMPLE_LCD_H_RES, EXAMPLE_LCD_V_RES, frame);
free(frame);
ESP_RETURN_ON_ERROR(err, TAG, "三色测试绘制失败");
ESP_LOGI(TAG, "LCD三色测试图已发送");
return ESP_OK;
}
/**
* @brief 初始化LCD硬件和SPI接口
*
* 该函数负责初始化LCD所需的GPIO、SPI总线，并配置LCD面板
* 包括背光控制、SPI总线配置、面板IO配置和面板驱动安装
*
* @return esp_err_t 初始化结果，ESP_OK表示成功
*/
static esp_err_t app_lcd_init(void)
{
esp_err_t ret = ESP_OK;
gpio_config_t bk_gpio_config = {
.mode = GPIO_MODE_OUTPUT,
.pin_bit_mask = 1ULL << EXAMPLE_LCD_GPIO_BL
};
ESP_ERROR_CHECK(gpio_config(&bk_gpio_config));
ESP_LOGI(TAG, "初始化SPI总线");
const spi_bus_config_t buscfg = {
.sclk_io_num = EXAMPLE_LCD_GPIO_SCLK,
.mosi_io_num = EXAMPLE_LCD_GPIO_MOSI,
.miso_io_num = GPIO_NUM_NC,
.quadwp_io_num = GPIO_NUM_NC,
.quadhd_io_num = GPIO_NUM_NC,
.max_transfer_sz = EXAMPLE_LCD_H_RES * EXAMPLE_LCD_DRAW_BUFF_HEIGHT * sizeof(uint16_t),
};
ESP_RETURN_ON_ERROR(spi_bus_initialize(EXAMPLE_LCD_SPI_NUM, &buscfg, SPI_DMA_CH_AUTO), TAG, "SPI初始化失败");
ESP_LOGI(TAG, "安装面板IO");
const esp_lcd_panel_io_spi_config_t io_config = {
.dc_gpio_num = EXAMPLE_LCD_GPIO_DC,
.cs_gpio_num = EXAMPLE_LCD_GPIO_CS,
.pclk_hz = EXAMPLE_LCD_PIXEL_CLK_HZ,
.lcd_cmd_bits = EXAMPLE_LCD_CMD_BITS,
.lcd_param_bits = EXAMPLE_LCD_PARAM_BITS,
.spi_mode = 0,
.trans_queue_depth = 10,
};
ESP_GOTO_ON_ERROR(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)EXAMPLE_LCD_SPI_NUM, &io_config, &lcd_io), err, TAG, "创建面板IO失败");
ESP_LOGI(TAG, "安装LCD驱动");
const esp_lcd_panel_dev_config_t panel_config = {
.reset_gpio_num = EXAMPLE_LCD_GPIO_RST,
#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(6, 0, 0)
.rgb_endian = LCD_RGB_ENDIAN_RGB,
#else
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_BGR,
#endif
.bits_per_pixel = EXAMPLE_LCD_BITS_PER_PIXEL,
};
ESP_GOTO_ON_ERROR(esp_lcd_new_panel_st7789(lcd_io, &panel_config, &lcd_panel), err, TAG, "创建面板失败");
ESP_GOTO_ON_ERROR(esp_lcd_panel_reset(lcd_panel), err, TAG, "面板复位失败");
ESP_GOTO_ON_ERROR(esp_lcd_panel_init(lcd_panel), err, TAG, "面板初始化失败");
ESP_GOTO_ON_ERROR(esp_lcd_panel_swap_xy(lcd_panel, false), err, TAG, "设置面板swap_xy失败");
ESP_GOTO_ON_ERROR(esp_lcd_panel_mirror(lcd_panel, false, false), err, TAG, "设置面板镜像失败");
ESP_GOTO_ON_ERROR(esp_lcd_panel_set_gap(lcd_panel, EXAMPLE_LCD_GAP_X, EXAMPLE_LCD_GAP_Y), err, TAG, "设置显示偏移失败");
ESP_LOGI(TAG, "面板基准参数已应用: gap=(%d,%d)", EXAMPLE_LCD_GAP_X, EXAMPLE_LCD_GAP_Y);
ESP_GOTO_ON_ERROR(esp_lcd_panel_invert_color(lcd_panel, true), err, TAG, "设置反色失败");
ESP_GOTO_ON_ERROR(esp_lcd_panel_disp_on_off(lcd_panel, true), err, TAG, "打开显示失败");
ESP_RETURN_ON_ERROR(gpio_set_level(EXAMPLE_LCD_GPIO_BL, EXAMPLE_LCD_BL_ON_LEVEL), TAG, "背光引脚置位失败");
ESP_LOGI(TAG, "背光已打开，电平=%d", EXAMPLE_LCD_BL_ON_LEVEL);
return ret;
// 错误处理标签，用于清理资源
err:
if (lcd_panel) {
esp_lcd_panel_del(lcd_panel);
lcd_panel = NULL;
}
if (lcd_io) {
esp_lcd_panel_io_del(lcd_io);
lcd_io = NULL;
}
spi_bus_free(EXAMPLE_LCD_SPI_NUM);
return ret;
}
/**
* @brief 初始化LVGL图形库
*
* 该函数负责初始化LVGL库，并配置显示设备
* 包括LVGL任务配置、显示缓冲区配置和旋转设置
*
* @return esp_err_t 初始化结果，ESP_OK表示成功
*/
static esp_err_t app_lvgl_init(void)
{
const lvgl_port_cfg_t lvgl_cfg = {
.task_priority = 4,
.task_stack = 4096,
.task_affinity = -1,
.task_max_sleep_ms = 500,
.timer_period_ms = 5
};
ESP_RETURN_ON_ERROR(lvgl_port_init(&lvgl_cfg), TAG, "LVGL端口初始化失败");
ESP_LOGI(TAG, "添加LCD屏幕");
const lvgl_port_display_cfg_t disp_cfg = {
.io_handle = lcd_io,
.panel_handle = lcd_panel,
.buffer_size = EXAMPLE_LCD_H_RES * EXAMPLE_LCD_DRAW_BUFF_HEIGHT,
.double_buffer = EXAMPLE_LCD_DRAW_BUFF_DOUBLE,
.hres = EXAMPLE_LCD_H_RES,
.vres = EXAMPLE_LCD_V_RES,
.monochrome = false,
#if LVGL_VERSION_MAJOR >= 9
.color_format = LV_COLOR_FORMAT_RGB565,
#endif
.rotation = {
.swap_xy = EXAMPLE_LCD_ROT_SWAP_XY,
.mirror_x = EXAMPLE_LCD_ROT_MIRROR_X,
.mirror_y = EXAMPLE_LCD_ROT_MIRROR_Y,
},
.flags = {
.buff_dma = true,
#if LVGL_VERSION_MAJOR >= 9
.swap_bytes = false,
#endif
}};
lvgl_disp = lvgl_port_add_disp(&disp_cfg);
ESP_RETURN_ON_FALSE(lvgl_disp != NULL, ESP_FAIL, TAG, "添加LVGL显示设备失败");
ESP_LOGI(TAG, "LVGL旋转已应用: swap_xy=%d mirror_x=%d mirror_y=%d",
EXAMPLE_LCD_ROT_SWAP_XY, EXAMPLE_LCD_ROT_MIRROR_X, EXAMPLE_LCD_ROT_MIRROR_Y);
return ESP_OK;
}
/**
* @brief 创建并显示LVGL主界面
*
* 该函数负责创建LVGL的用户界面元素，包括图像、标签和按钮
* 并设置它们的位置和属性
*/
static void app_main_display(void)
{
lv_obj_t *scr = lv_scr_act();
lvgl_port_lock(0);
lv_obj_set_style_bg_color(scr, lv_color_white(), 0);
lv_obj_set_style_bg_opa(scr, LV_OPA_COVER, 0);
s_center_label = lv_label_create(scr);
lv_label_set_text(s_center_label, "ESP32C3-LVGL1");
lv_obj_set_style_text_color(s_center_label, lv_color_black(), 0);
lv_obj_set_style_text_font(s_center_label, &lv_font_unscii_8, 0);
lv_obj_align(s_center_label, LV_ALIGN_CENTER, 0, 0);
lvgl_port_unlock();
}
/**
* @brief 启动LVGL演示程序
*
* 该函数是程序的入口点，负责初始化LCD硬件、LVGL库，并显示主界面
*/
esp_err_t lvgl_st7735s_set_center_text(const char *text)
{
ESP_RETURN_ON_FALSE(text != NULL, ESP_ERR_INVALID_ARG, TAG, "text is null");
ESP_RETURN_ON_FALSE(s_center_label != NULL, ESP_ERR_INVALID_STATE, TAG, "label not ready");
lvgl_port_lock(0);
lv_label_set_text(s_center_label, text);
lv_obj_align(s_center_label, LV_ALIGN_CENTER, 0, 0);
lvgl_port_unlock();
return ESP_OK;
}
esp_err_t start_lvgl_demo(void)
{
ESP_RETURN_ON_ERROR(app_lcd_init(), TAG, "LCD初始化失败");
#if EXAMPLE_LCD_ENABLE_COLOR_TEST
ESP_RETURN_ON_ERROR(app_lcd_color_test(), TAG, "LCD测试图绘制失败");
vTaskDelay(pdMS_TO_TICKS(300));
#endif
ESP_RETURN_ON_ERROR(app_lvgl_init(), TAG, "LVGL初始化失败");
app_main_display();
return ESP_OK;
}

32
dependencies.lock Normal file
View File

@@ -0,0 +1,32 @@
dependencies:
espressif/esp_lvgl_port:
component_hash: b6360960f47b6776462e7092861b3ea66477ffb762a01baa0aecbb3d74cd50f4
dependencies:
- name: idf
require: private
version: '>=5.1'
- name: lvgl/lvgl
registry_url: https://components.espressif.com
require: public
version: '>=8,<10'
source:
registry_url: https://components.espressif.com/
type: service
version: 2.7.2
idf:
source:
type: idf
version: 5.5.2
lvgl/lvgl:
component_hash: 184e532558c1c45fefed631f3e235423d22582aafb4630f3e8885c35281a49ae
dependencies: []
source:
registry_url: https://components.espressif.com
type: service
version: 9.5.0
direct_dependencies:
- espressif/esp_lvgl_port
- idf
manifest_hash: fa314ee0d60a34ffe2dea85313c7369c0c4b16079167ed05ad45e0cadad2199d
target: esp32c3
version: 2.0.0

3
main/CMakeLists.txt
View File

@@ -1,3 +1,4 @@
idf_component_register(SRCS "main.c"
INCLUDE_DIRS "."
REQUIRES wifi-connect)
REQUIRES wifi-connect esp_lvgl_port lvgl_st7735s_use
)

17
main/idf_component.yml Normal file
View File

@@ -0,0 +1,17 @@
## IDF Component Manager Manifest File
dependencies:
## Required IDF version
idf:
version: '>=4.1.0'
# # Put list of dependencies here
# # For components maintained by Espressif:
# component: "~1.0.0"
# # For 3rd party components:
# username/component: ">=1.0.0,<2.0.0"
# username2/component2:
# version: "~1.0.0"
# # For transient dependencies `public` flag can be set.
# # `public` flag doesn't have an effect dependencies of the `main` component.
# # All dependencies of `main` are public by default.
# public: true
espressif/esp_lvgl_port: ^2.7.2

13
main/main.c
View File

@@ -2,13 +2,20 @@
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_check.h"
#include "wifi-connect.h"
#include "lvgl_st7735s_use.h"
void app_main(void)
{
// 初始化 Wi-Fi 配网组件，支持长按按键进入配网
//初始化 Wi-Fi 配网组件，支持长按按键进入配网
ESP_ERROR_CHECK(wifi_connect_init());
printf("设备启动完成：长按按键进入配网模式，手机连接 ESP32-* 后访问 http://192.168.4.1\n");
// 启动 LVGL 演示程序，显示简单的界面
ESP_ERROR_CHECK(start_lvgl_demo());
for (;;)
{
vTaskDelay(pdMS_TO_TICKS(1000));
}
}