硬件名称

规格参数

核心用途

ESP32S3开发板

双核Xtensa LX7，内置WiFi/蓝牙，PSRAM可选

主控核心，运行LVGL与机器人控制逻辑

LCD显示屏+FT5x06触摸屏

分辨率推荐480320/800480，16bit色彩深度，I2C触摸接口

人机交互界面显示与触摸输入

USB数据线

Type-C，支持数据传输与供电

程序烧录、串口调试与供电

配套外设

3.7V锂电池、HC-SR04超声波模块、直流电机驱动、ADC电压采集电路

机器人功能拓展，实现传感器数据可视化

YAML

dependencies:

  lvgl/lvgl: ^9.4.0

  espressif/esp_lvgl_port: ^2.6.3

  espressif/esp_lcd_touch_ft5x06: ^1.0.6

Bash

idf.py add-dependency "lvgl/lvgl^9.4.0"

idf.py add-dependency "espressif/esp_lvgl_port^2.6.3"

idf.py add-dependency "espressif/esp_lcd_touch_ft5x06^1.0.6"

C

#include "esp_lcd_touch_ft5x06.h"

#include "esp_lvgl_port.h"

// 触摸屏句柄

static esp_lcd_touch_handle_t tp;

// LVGL显示设备句柄（指向液晶屏）

static lv_disp_t *disp;

// LVGL输入设备句柄（指向触摸屏）

static lv_indev_t *disp_indev = NULL;

// LVGL绘制缓存高度，平衡内存占用与界面流畅度，推荐20-50

#define BSP_LCD_DRAW_BUF_HEIGHT    (20)

// 液晶屏水平/垂直分辨率，需与实际屏幕参数匹配

#define BSP_LCD_H_RES    480

#define BSP_LCD_V_RES    320

// I2C总线编号，需与底层驱动一致

#define BSP_I2C_NUM      0

// 液晶屏初始化+添加LVGL接口

static lv_disp_t *bsp_display_lcd_init(void)

{

    /* 液晶屏底层初始化，需复用工程中已验证的LCD驱动 */

    bsp_display_new();

    lcd_set_color(0xffff); // 整屏背景置白，验证屏幕是否正常点亮

    esp_lcd_panel_disp_on_off(panel_handle, true); // 开启屏幕显示

    /* 配置LVGL显示参数，绑定液晶屏接口 */

    const lvgl_port_display_cfg_t disp_cfg = {

        .io_handle = io_handle,

        .panel_handle = panel_handle,

        .buffer_size = BSP_LCD_H_RES * BSP_LCD_DRAW_BUF_HEIGHT,

        .double_buffer = false, // 双缓存可提升流畅度，需根据硬件内存开启

        .hres = BSP_LCD_H_RES,

        .vres = BSP_LCD_V_RES,

        .monochrome = false,

        /* 旋转/镜像配置，必须与液晶屏底层驱动参数完全一致 */

        .rotation = {

            .swap_xy = true,

            .mirror_x = true,

            .mirror_y = false,

        },

        .flags = {

            .buff_dma = true,  // 开启DMA加速，提升绘制速度

            .buff_spiram = false, // 与DMA互斥，不可同时为true

            .swap_bytes = true,

        }

    };

    return lvgl_port_add_disp(&disp_cfg);

}

// FT5x06触摸屏底层初始化

esp_err_t bsp_touch_new(esp_lcd_touch_handle_t *ret_touch)

{

    esp_lcd_touch_config_t tp_cfg = {

        .x_max = BSP_LCD_V_RES,

        .y_max = BSP_LCD_H_RES,

        .rst_gpio_num = GPIO_NUM_NC, // 与LCD复位引脚共用

        .int_gpio_num = GPIO_NUM_NC,

        .levels = {

            .reset = 0,

            .interrupt = 0,

        },

        /* 触摸坐标配置，必须与液晶屏旋转配置一致，避免触摸偏移 */

        .flags = {

            .swap_xy = 1,

            .mirror_x = 1,

            .mirror_y = 0,

        },

    };

    esp_lcd_panel_io_handle_t tp_io_handle = NULL;

    // 适配FT5x06的I2C配置

    esp_lcd_panel_io_i2c_config_t tp_io_config = ESP_LCD_TOUCH_IO_I2C_FT5X06_CONFIG();

    // 初始化I2C通信接口

    ESP_RETURN_ON_ERROR(esp_lcd_new_panel_io_i2c((esp_lcd_i2c_bus_handle_t)BSP_I2C_NUM, &tp_io_config, &tp_io_handle), TAG, "Touch I2C init failed");

    // 初始化FT5x06触摸屏

    ESP_ERROR_CHECK(esp_lcd_touch_new_i2c_ft5x06(tp_io_handle, &tp_cfg, ret_touch));

    return ESP_OK;

}

// 触摸屏初始化+添加LVGL输入设备接口

static lv_indev_t *bsp_display_indev_init(lv_disp_t *disp)

{

    /* 初始化触摸屏底层 */

    ESP_ERROR_CHECK(bsp_touch_new(&tp));

    assert(tp);

    /* 配置LVGL触摸输入参数，绑定触摸屏接口 */

    const lvgl_port_touch_cfg_t touch_cfg = {

        .disp = disp,

        .handle = tp,

    };

    return lvgl_port_add_touch(&touch_cfg);

}

C

// LVGL+显示+触摸总初始化函数

void bsp_lvgl_start(void)

{

    /* 初始化LVGL核心运行环境 */

    lvgl_port_cfg_t lvgl_cfg = ESP_LVGL_PORT_INIT_CONFIG();

    lvgl_port_init(&lvgl_cfg);

    /* 初始化液晶屏并注册到LVGL */

    disp = bsp_display_lcd_init();

    /* 初始化触摸屏并注册到LVGL */

    disp_indev = bsp_display_indev_init(disp);

    /* 开启液晶屏背光 */

    bsp_display_backlight_on();

}

C

#ifndef _LCD_H_

#define _LCD_H_

#include "driver/gpio.h"

#include "driver/i2c.h"

#include "esp_lcd_touch_ft5x06.h"

#include "esp_lvgl_port.h"

// LVGL总初始化函数声明

void bsp_lvgl_start(void);

#endif

CMake

idf_component_register(SRCS "LCD.c"

                    INCLUDE_DIRS "include"

                    REQUIRES driver esp_lcd esp_lcd_touch_ft5x06 esp_lvgl_port)

C

#include <stdio.h>

#include "freertos/FreeRTOS.h"

#include "freertos/task.h"

#include "LCD.h"

// 引入LVGL Demo头文件

#include "demos/lv_demos.h"

void app_main(void)

{

    // 工程底层外设初始化

    bsp_i2c_init();

    pca9557_init();

    // LVGL核心初始化（移植的核心函数）

    bsp_lvgl_start();

    // 启动LVGL基准测试Demo，验证移植是否成功

    lv_demo_benchmark();

    // LVGL主循环，必须保持运行，处理界面刷新与事件

    while(1){

        vTaskDelay(pdMS_TO_TICKS(10));

    }

}

CMake

# 添加头文件包含路径

set(INCLUDES "." "./ui/generated" "./ui/custom" "./ui/generated/guider_customer_fonts")

# 递归查找当前目录及子目录下所有.c源文件

file(GLOB_RECURSE SOURCES ./*.c)

# 注册组件，将GUI代码加入工程编译

idf_component_register(SRCS ${SOURCES}

                    INCLUDE_DIRS ${INCLUDES})

C

#include <stdio.h>

#include "freertos/FreeRTOS.h"

#include "freertos/task.h"

#include "LCD.h"

// 引入GUI Guider生成的头文件

#include "gui_guider.h"

#include "custom.h"

// GUI全局结构体

lv_ui guider_ui;

void app_main(void)

{

    // 工程底层外设初始化

    bsp_i2c_init();

    pca9557_init();

    // LVGL核心初始化

    bsp_lvgl_start();

    // GUI Guider界面初始化

    setup_ui(&guider_ui);

    // 自定义代码初始化（事件回调、业务逻辑）

    custom_init(&guider_ui);

    // LVGL主循环，处理界面刷新与触摸事件

    while(1){

        lv_timer_handler(); // LVGL事件处理函数，必须持续调用

        vTaskDelay(pdMS_TO_TICKS(5));

    }

}

C

#include "gui_guider.h"

#include "lvgl.h"

// 电池电量Bar组件更新函数

void robot_battery_update(lv_ui *ui, int32_t battery_percent)

{

    // 限制电量数值在0-100范围内

    battery_percent = lv_clamp(battery_percent, 0, 100);

    // 更新Bar组件数值，开启动画效果

    lv_bar_set_value(ui->screen_bar_battery, battery_percent, LV_ANIM_ON);

    // 更新电量百分比标签

    char buf[16];

    sprintf(buf, "电量：%d%%", battery_percent);

    lv_label_set_text(ui->screen_label_battery, buf);

    // 低电量报警：电量低于20%时，Bar组件变为红色

    if(battery_percent < 20){

        lv_obj_set_style_bg_color(ui->screen_bar_battery, lv_color_hex(0xFF0000), LV_PART_INDICATOR);

    }else{

        lv_obj_set_style_bg_color(ui->screen_bar_battery, lv_color_hex(0x00FF00), LV_PART_INDICATOR);

    }

}

C

#include "esp_timer.h"

#include "FRTask.h"

// 定时器全局结构体

typedef struct {

    uint32_t time_sec;

    uint8_t hour;

    uint8_t minute;

    uint8_t second;

    int32_t battery_val;

    int32_t distance_val;

} TIMER_Type;

TIMER_Type One_timer = {0};

// 定时器回调函数，1秒触发一次

void ESP_Timer_Callback(void *arg)

{

    // 系统运行时间累计

    One_timer.time_sec++;

    One_timer.hour = One_timer.time_sec / 60 / 60 % 24;

    One_timer.minute = One_timer.time_sec / 60 % 60;

    One_timer.second = One_timer.time_sec % 60;

    // 此处添加传感器数据采集：ADC采集电池电压、超声波采集距离

    // One_timer.battery_val =  adc_get_battery_percent();

    // One_timer.distance_val = hc_sr04_get_distance();

}

// 定时器初始化函数

void ESP_Timer_Init(void)

{

    esp_timer_create_args_t timer_args = {

        .callback = &ESP_Timer_Callback,

        .name = "robot_timer",

        .arg = NULL,

        .dispatch_method = ESP_TIMER_TASK,

    };

    esp_timer_handle_t timer_handle;

    // 创建定时器

    esp_timer_create(&timer_args, &timer_handle);

    // 启动周期定时器，1000000us = 1s，可根据需求调整刷新周期

    esp_timer_start_periodic(timer_handle, 1000000);

}

C

void app_main(void)

{

    // 底层初始化

    bsp_i2c_init();

    pca9557_init();

    bsp_lvgl_start();

    // 定时器初始化

    ESP_Timer_Init();

    // GUI界面初始化

    setup_ui(&guider_ui);

    custom_init(&guider_ui);

    uint32_t last_sec = 0;

    char time_str[16] = {0};

    while(1){

        // 仅当时间更新时，刷新界面

        if(last_sec != One_timer.time_sec){

            last_sec = One_timer.time_sec;

            // 更新系统运行时间

            sprintf(time_str, "%02d:%02d:%02d", One_timer.hour, One_timer.minute, One_timer.second);

            lv_label_set_text(guider_ui.screen_label_time, time_str);

            // 更新电池电量显示

            robot_battery_update(&guider_ui, One_timer.battery_val);

        }

        lv_timer_handler();

        vTaskDelay(pdMS_TO_TICKS(5));

    }

}

C

// 按钮点击事件回调函数

void btn_robot_move_event_cb(lv_event_t *e)

{

    lv_event_code_t code = lv_event_get_code(e);

    // 获取点击的按钮对象

    lv_obj_t *btn = lv_event_get_target(e);

    // 获取用户自定义数据

    lv_ui *ui = lv_event_get_user_data(e);

    // 处理点击事件

    if(code == LV_EVENT_CLICKED){

        if(btn == ui->screen_btn_forward){

            // 前进按钮点击：调用电机前进函数

            // robot_motor_forward(50);

            lv_label_set_text(ui->screen_label_status, "运行状态：前进");

        }

        else if(btn == ui->screen_btn_back){

            // 后退按钮点击：调用电机后退函数

            // robot_motor_back(50);

            lv_label_set_text(ui->screen_label_status, "运行状态：后退");

        }

        else if(btn == ui->screen_btn_stop){

            // 停止按钮点击：调用电机停止函数

            // robot_motor_stop();

            lv_label_set_text(ui->screen_label_status, "运行状态：停止");

        }

    }

}

// 在custom_init中绑定按钮事件

void custom_init(lv_ui *ui)

{

    // 为前进、后退、停止按钮绑定点击事件

    lv_obj_add_event_cb(ui->screen_btn_forward, btn_robot_move_event_cb, LV_EVENT_CLICKED, ui);

    lv_obj_add_event_cb(ui->screen_btn_back, btn_robot_move_event_cb, LV_EVENT_CLICKED, ui);

    lv_obj_add_event_cb(ui->screen_btn_stop, btn_robot_move_event_cb, LV_EVENT_CLICKED, ui);

}

问题现象

核心原因

标准化解决方法

LCD屏显示花屏、画面颠倒

1. LVGL旋转配置与液晶屏底层驱动不一致；2. 绘制缓存设置过小

1. 统一液晶屏与LVGL的swap_xy/mirror_x/mirror_y配置；2. 适当增大BSP_LCD_DRAW_BUF_HEIGHT至20-50

触摸屏无响应/触摸坐标偏移

1. 触摸屏I2C初始化失败；2. 触摸坐标旋转配置与液晶屏不匹配

1. 检查I2C总线与引脚配置，验证触摸屏底层驱动是否正常；2. 保证触摸屏与液晶屏的swap_xy/mirror配置完全一致

GUI Guider界面不显示/组件丢失

1. LVGL定时器未在主循环持续调用；2. 组件父对象设置错误；3. CMake配置未包含GUI代码

1. 确保主循环中持续调用lv_timer_handler()；2. 组件必须挂载到屏幕根对象；3. 检查CMakeLists.txt的头文件路径与源文件递归配置

中文显示乱码/方框

1. 字体未正确导入；2. 组件未选择中文字体；3. 工程编码非UTF-8

1. 按教程重新导入中文字体，确保编译无报错；2. 中文组件必须选择已导入的中文字体；3. 工程文件编码统一设置为UTF-8

编译报错：undefined reference to xxx

1. 源文件未加入编译；2. 头文件路径未配置；3. 组件依赖缺失

1. 检查CMakeLists.txt的file(GLOB_RECURSE)配置是否覆盖所有.c文件；2. 补全头文件包含路径；3. 重新拉取LVGL相关组件

界面卡顿、刷新延迟

1. 主循环中vTaskDelay延时过长；2. 未开启DMA加速；3. 定时器中执行耗时操作

1. 主循环延时设置为5-10ms；2. 开启LVGL的DMA缓存加速；3. 耗时操作放入独立FreeRTOS任务，不要在定时器/事件回调中执行