飞书文档https://x509p6c8to.feishu.cn/wiki/Ly6ywvphqi6HZlk38vHcz2OgnXg
LVGL是一个开源的显示框架,使用它可以加速我们开发带显示屏交互的应用。
IDF对于LVGL的支持一直有更新的,我们可以很方便在组件库中搜索到对应版本的LVGL,并把它添加到工程中
idf.py add-dependency "lvgl/lvgl^9.2.0"
关于LVGL的使用,在IDF的例程中也是有提供的esp-idf/examples/peripherals/lcd/spi_lcd_touch,我们可以借鉴此工程,实现对应屏幕的LVGL移植,其实LVGL部分都是一样的,根据不同屏幕修改屏幕外设初始化部分即可。
课程板卡使用的屏幕是SPI接口的,分辨率是172*320,驱动芯片是st7789,然后对应的IO可以回到上节课了解
#define EXAMPLE_LCD_BK_LIGHT_ON_LEVEL 0
#define EXAMPLE_LCD_BK_LIGHT_OFF_LEVEL !EXAMPLE_LCD_BK_LIGHT_ON_LEVEL
#define EXAMPLE_PIN_NUM_SCLK GPIO_NUM_16
#define EXAMPLE_PIN_NUM_MOSI GPIO_NUM_17
#define EXAMPLE_PIN_NUM_MISO GPIO_NUM_NC
#define EXAMPLE_PIN_NUM_LCD_DC GPIO_NUM_21
#define EXAMPLE_PIN_NUM_LCD_RST GPIO_NUM_18
#define EXAMPLE_PIN_NUM_LCD_CS GPIO_NUM_15
#define EXAMPLE_PIN_NUM_BK_LIGHT GPIO_NUM_2
// The pixel number in horizontal and vertical
#define EXAMPLE_LCD_H_RES 172
#define EXAMPLE_LCD_V_RES 320
// Bit number used to represent command and parameter
#define EXAMPLE_LCD_CMD_BITS 8
#define EXAMPLE_LCD_PARAM_BITS 8
参考上节课的LDC控制器部分,在屏幕初始化完成起来后,我们就可以进行LVGL的适配。关键步骤如下
- 初始化 LVGL 库:设置 LVGL 的内部数据结构。
- 创建显示对象:使用屏幕分辨率创建显示对象。
- 分配绘图缓冲区:分配足够的内存用于绘图缓冲区。
- 初始化缓冲区:设置缓冲区和渲染模式。
- 关联面板句柄:将面板句柄与显示对象关联。
- 设置颜色格式:配置颜色格式为 RGB565。
- 设置刷新回调:注册刷新回调函数。
- 安装 tick 定时器:创建和启动定时器用于 LVGL 的 tick 接口。
- 注册事件回调:注册事件回调函数用于刷新完成通知。
- 设置旋转角度:根据需要设置显示旋转角度。
- 创建 LVGL 任务:创建任务处理 LVGL 的事件循环。
- 显示 UI:创建并显示 LVGL 的示例 UI。
初始化 LVGL 库
首先,需要初始化 LVGL 库,设置必要的内部数据结构。
// 初始化 LVGL 库
ESP_LOGI(TAG, "Initialize LVGL library");
lv_init();
创建 LVGL 显示对象
创建一个 LVGL 显示对象,并使用屏幕的分辨率作为参数。
// 创建一个 LVGL 显示对象
lv_display_t *display = lv_display_create(EXAMPLE_LCD_H_RES, EXAMPLE_LCD_V_RES);
分配绘图缓冲区
分配 LVGL 使用的绘图缓冲区。推荐选择的缓冲区大小至少为屏幕大小的 1/10。
// 分配 LVGL 使用的绘图缓冲区
size_t draw_buffer_sz = EXAMPLE_LCD_H_RES * EXAMPLE_LVGL_DRAW_BUF_LINES * sizeof(lv_color16_t);
void *buf1 = spi_bus_dma_memory_alloc(LCD_HOST, draw_buffer_sz, 0);
assert(buf1); // 确保内存分配成功
void *buf2 = spi_bus_dma_memory_alloc(LCD_HOST, draw_buffer_sz, 0);
assert(buf2); // 确保内存分配成功
初始化绘图缓冲区
初始化 LVGL 绘图缓冲区,并设置两个缓冲区和渲染模式。
// 初始化 LVGL 绘图缓冲区
lv_display_set_buffers(display, buf1, buf2, draw_buffer_sz, LV_DISPLAY_RENDER_MODE_PARTIAL);
关联面板句柄
将 LCD面板句柄关联到显示对象。
// 将面板句柄关联到显示对象
lv_display_set_user_data(display, panel_handle);
设置颜色格式
设置颜色格式为 RGB565。
// 设置颜色格式为 RGB565
lv_display_set_color_format(display, LV_COLOR_FORMAT_RGB565);
设置刷新回调函数
设置回调函数,用于将渲染后的图像复制到显示区域。
// 设置回调函数,用于将渲染后的图像复制到显示区域
lv_display_set_flush_cb(display, example_lvgl_flush_cb);
安装 LVGL 的 tick 定时器
安装 LVGL 的 tick 定时器,用于 LVGL 的 tick 接口。使用 esp_timer 创建一个 2ms 周期的定时器。
// 安装 LVGL 的 tick 定时器
ESP_LOGI(TAG, "Install LVGL tick timer");
const esp_timer_create_args_t lvgl_tick_timer_args = {
.callback = &example_increase_lvgl_tick, // 定时器回调函数
.name = "lvgl_tick" // 定时器名称
};
esp_timer_handle_t lvgl_tick_timer = NULL;
ESP_ERROR_CHECK(esp_timer_create(&lvgl_tick_timer_args, &lvgl_tick_timer)); // 创建定时器
ESP_ERROR_CHECK(esp_timer_start_periodic(lvgl_tick_timer, EXAMPLE_LVGL_TICK_PERIOD_MS * 1000)); // 启动定时器
注册 IO 面板事件回调
注册 IO 面板事件回调,用于 LVGL 刷新完成通知。
// 注册 IO 面板事件回调,用于 LVGL 刷新完成通知
ESP_LOGI(TAG, "Register io panel event callback for LVGL flush ready notification");
const esp_lcd_panel_io_callbacks_t cbs = {
.on_color_trans_done = example_notify_lvgl_flush_ready, // 颜色传输完成回调函数
};
/* 注册回调函数 */
ESP_ERROR_CHECK(esp_lcd_panel_io_register_event_callbacks(io_handle, &cbs, display));
设置显示旋转角度(可选)
设置显示旋转角度,根据需要进行配置。
// 设置显示旋转角度(可选)
// lv_disp_set_rotation(display, LV_DISPLAY_ROTATION_0);
创建 LVGL 任务
创建 LVGL 任务,用于处理 LVGL 的事件循环。
// 创建 LVGL 任务
ESP_LOGI(TAG, "Create LVGL task");
xTaskCreate(example_lvgl_port_task, "LVGL", EXAMPLE_LVGL_TASK_STACK_SIZE, NULL, EXAMPLE_LVGL_TASK_PRIORITY, NULL);
显示 LVGL Meter Widget
显示 LVGL Meter Widget。锁定互斥锁,因为 LVGL API 不是线程安全的。
// 显示 LVGL Meter Widget
ESP_LOGI(TAG, "Display LVGL Meter Widget");
_lock_acquire(&lvgl_api_lock); // 锁定互斥锁
example_lvgl_demo_ui(display); // 创建并显示 LVGL 的示例 UI
_lock_release(&lvgl_api_lock); // 释放互斥锁
最终参考源码如下:
#include <stdio.h>
#include <unistd.h>
#include <sys/lock.h>
#include <sys/param.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_lcd_panel_io.h"
#include "esp_lcd_panel_vendor.h"
#include "esp_lcd_panel_ops.h"
#include "driver/gpio.h"
#include "driver/spi_master.h"
#include "esp_timer.h"
#include "esp_err.h"
#include "esp_log.h"
#include "lvgl.h"
static const char *TAG = "example";
// Using SPI2 in the example
#define LCD_HOST SPI2_HOST
Please update the following configuration according to your LCD spec //
#define EXAMPLE_LCD_PIXEL_CLOCK_HZ (20 * 1000 * 1000)
#define EXAMPLE_LCD_BK_LIGHT_ON_LEVEL 0
#define EXAMPLE_LCD_BK_LIGHT_OFF_LEVEL !EXAMPLE_LCD_BK_LIGHT_ON_LEVEL
#define EXAMPLE_PIN_NUM_SCLK GPIO_NUM_16
#define EXAMPLE_PIN_NUM_MOSI GPIO_NUM_17
#define EXAMPLE_PIN_NUM_MISO GPIO_NUM_NC
#define EXAMPLE_PIN_NUM_LCD_DC GPIO_NUM_21
#define EXAMPLE_PIN_NUM_LCD_RST GPIO_NUM_18
#define EXAMPLE_PIN_NUM_LCD_CS GPIO_NUM_15
#define EXAMPLE_PIN_NUM_BK_LIGHT GPIO_NUM_2
// The pixel number in horizontal and vertical
#define EXAMPLE_LCD_H_RES 172
// Bit number used to represent command and parameter
#define EXAMPLE_LCD_V_RES 320
#define EXAMPLE_LCD_CMD_BITS 8
#define EXAMPLE_LCD_PARAM_BITS 8
// 列地址偏移示例(假设X起始偏移为0,Y起始偏移为40)
#define X_OFFSET 34
#define Y_OFFSET 0
esp_lcd_panel_handle_t panel_handle = NULL;
typedef struct {
int cmd; /*<! The specific LCD command */
const void *data; /*<! Buffer that holds the command specific data */
size_t data_bytes; /*<! Size of `data` in memory, in bytes */
unsigned int delay_ms; /*<! Delay in milliseconds after this command */
} st7789_lcd_init_cmd_t;
typedef struct {
const st7789_lcd_init_cmd_t *init_cmds;
uint16_t init_cmds_size; /*<! Number of commands in above array */
struct {
unsigned int use_qspi_interface: 1; /*<! Set to 1 if use QSPI interface, default is SPI interface */
} flags;
} st7789_vendor_config_t;
static const st7789_lcd_init_cmd_t lcd_init_cmds [] ={
/* {cmd, { data }, data_size, delay_ms} "*/
{0x11, (uint8_t []){0x00}, 0, 0},
{0x36, (uint8_t []){0x00}, 1, 0},
{0x3A, (uint8_t []){0x05}, 1, 0},
{0xB2, (uint8_t []){0x0C, 0x0C, 0x00, 0x33, 0x33}, 5, 0},
{0xB7, (uint8_t []){0x35}, 1, 0},
{0xBB, (uint8_t []){0x35}, 1, 0},
{0xC0, (uint8_t []){0x2C}, 1, 0},
{0xC2, (uint8_t []){0x01}, 1, 0},
{0xC3, (uint8_t []){0x13}, 1, 0},
{0xC4, (uint8_t []){0x20}, 1, 0},
{0xC6, (uint8_t []){0x0F}, 1, 0},
{0xD0, (uint8_t []){0xA4, 0xA1}, 2, 0},
{0xD6, (uint8_t []){0xA1}, 1, 0},
{0xE0, (uint8_t []){0xF0, 0x00, 0x04, 0x04, 0x04, 0x05, 0x29, 0x33, 0x3e, 0x38, 0x12, 0x12, 0x28, 0x30}, 14, 0},
{0xE1, (uint8_t []){0xF0, 0x07, 0x0A, 0x0D, 0x0b, 0x07, 0x28, 0x33, 0x3e, 0x36, 0x14, 0x14, 0x29, 0x32}, 14, 0},
{0x21, (uint8_t []){0x00}, 0, 0},
{0x11, (uint8_t []){0x00}, 0, 120},
{0x29, (uint8_t []){0x00}, 0, 0},
};
#define EXAMPLE_LVGL_DRAW_BUF_LINES 20 // number of display lines in each draw buffer
#define EXAMPLE_LVGL_TICK_PERIOD_MS 2
#define EXAMPLE_LVGL_TASK_MAX_DELAY_MS 500
#define EXAMPLE_LVGL_TASK_MIN_DELAY_MS 1
#define EXAMPLE_LVGL_TASK_STACK_SIZE (4 * 1024)
#define EXAMPLE_LVGL_TASK_PRIORITY 2
// LVGL library is not thread-safe, this example will call LVGL APIs from different tasks, so use a mutex to protect it
static _lock_t lvgl_api_lock;
/* Rotate display and touch, when rotated screen in LVGL. Called when driver parameters are updated. */
static void example_lvgl_port_update_callback(lv_display_t *disp)
{
esp_lcd_panel_handle_t panel_handle = lv_display_get_user_data(disp);
lv_display_rotation_t rotation = lv_display_get_rotation(disp);
switch (rotation) {
case LV_DISPLAY_ROTATION_0:
// Rotate LCD display
esp_lcd_panel_swap_xy(panel_handle, false);
esp_lcd_panel_mirror(panel_handle, true, false);
break;
case LV_DISPLAY_ROTATION_90:
// Rotate LCD display
esp_lcd_panel_swap_xy(panel_handle, true);
esp_lcd_panel_mirror(panel_handle, true, true);
break;
case LV_DISPLAY_ROTATION_180:
// Rotate LCD display
esp_lcd_panel_swap_xy(panel_handle, false);
esp_lcd_panel_mirror(panel_handle, false, true);
break;
case LV_DISPLAY_ROTATION_270:
// Rotate LCD display
esp_lcd_panel_swap_xy(panel_handle, true);
esp_lcd_panel_mirror(panel_handle, false, false);
break;
}
}
static void example_lvgl_flush_cb(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map)
{
example_lvgl_port_update_callback(disp);
esp_lcd_panel_handle_t panel_handle = lv_display_get_user_data(disp);
int offsetx1 = area->x1;
int offsetx2 = area->x2;
int offsety1 = area->y1;
int offsety2 = area->y2;
// because SPI LCD is big-endian, we need to swap the RGB bytes order
lv_draw_sw_rgb565_swap(px_map, (offsetx2 + 1 - offsetx1) * (offsety2 + 1 - offsety1));
// copy a buffer's content to a specific area of the display
esp_lcd_panel_draw_bitmap(panel_handle, offsetx1, offsety1, offsetx2 + 1, offsety2 + 1, px_map);
}
static bool example_notify_lvgl_flush_ready(esp_lcd_panel_io_handle_t panel_io, esp_lcd_panel_io_event_data_t *edata, void *user_ctx)
{
lv_display_t *disp = (lv_display_t *)user_ctx;
lv_display_flush_ready(disp);
return false;
}
static void example_increase_lvgl_tick(void *arg)
{
/* Tell LVGL how many milliseconds has elapsed */
lv_tick_inc(EXAMPLE_LVGL_TICK_PERIOD_MS);
}
static void example_lvgl_port_task(void *arg)
{
ESP_LOGI(TAG, "Starting LVGL task");
uint32_t time_till_next_ms = 0;
uint32_t time_threshold_ms = 1000 / CONFIG_FREERTOS_HZ;
while (1) {
_lock_acquire(&lvgl_api_lock);
time_till_next_ms = lv_timer_handler();
_lock_release(&lvgl_api_lock);
// in case of triggering a task watch dog time out
time_till_next_ms = MAX(time_till_next_ms, time_threshold_ms);
time_till_next_ms = 10;
usleep(1000 * time_till_next_ms);
}
}
static void set_angle(void * obj, int32_t v)
{
lv_arc_set_value(obj, v);
}
void example_lvgl_demo_ui(lv_display_t *disp)
{
lv_obj_t *scr = lv_display_get_screen_active(disp);
/*Create an Arc*/
lv_obj_t * arc = lv_arc_create(scr);
lv_arc_set_rotation(arc, 270);
lv_arc_set_bg_angles(arc, 0, 360);
lv_obj_remove_style(arc, NULL, LV_PART_KNOB); /*Be sure the knob is not displayed*/
lv_obj_remove_flag(arc, LV_OBJ_FLAG_CLICKABLE); /*To not allow adjusting by click*/
lv_obj_center(arc);
lv_obj_set_style_bg_color(arc, lv_color_hex(0x00ff00), LV_PART_MAIN);
lv_anim_t a;
lv_anim_init(&a);
lv_anim_set_var(&a, arc);
lv_anim_set_exec_cb(&a, set_angle);
lv_anim_set_duration(&a, 1000);
lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE); /*Just for the demo*/
lv_anim_set_repeat_delay(&a, 500);
lv_anim_set_values(&a, 0, 100);
lv_anim_start(&a);
}
void app_main(void)
{
// 关闭LCD背光
ESP_LOGI(TAG, "Turn off LCD backlight");
gpio_config_t bk_gpio_config = {
.mode = GPIO_MODE_OUTPUT, // 设置GPIO模式为输出
.pin_bit_mask = 1ULL << EXAMPLE_PIN_NUM_BK_LIGHT // 设置背光控制引脚
};
ESP_ERROR_CHECK(gpio_config(&bk_gpio_config)); // 配置GPIO
// 初始化SPI总线
ESP_LOGI(TAG, "Initialize SPI bus");
spi_bus_config_t buscfg = {
.sclk_io_num = EXAMPLE_PIN_NUM_SCLK, // SCLK引脚编号
.mosi_io_num = EXAMPLE_PIN_NUM_MOSI, // MOSI引脚编号
.miso_io_num = GPIO_NUM_NC, // MISO引脚编号
.quadwp_io_num = GPIO_NUM_NC, // QUADWP引脚编号(未使用)
.quadhd_io_num = GPIO_NUM_NC, // QUADHD引脚编号(未使用)
.max_transfer_sz = EXAMPLE_LCD_H_RES * EXAMPLE_LCD_V_RES * sizeof(uint16_t), // 最大传输大小
};
ESP_ERROR_CHECK(spi_bus_initialize(LCD_HOST, &buscfg, SPI_DMA_CH_AUTO)); // 初始化SPI总线
// 安装面板IO
ESP_LOGI(TAG, "Install panel IO");
esp_lcd_panel_io_handle_t io_handle = NULL;
esp_lcd_panel_io_spi_config_t io_config = {
.dc_gpio_num = EXAMPLE_PIN_NUM_LCD_DC, // 数据/命令控制引脚编号
.cs_gpio_num = EXAMPLE_PIN_NUM_LCD_CS, // 片选引脚编号
.pclk_hz = EXAMPLE_LCD_PIXEL_CLOCK_HZ, // 像素时钟频率
.lcd_cmd_bits = EXAMPLE_LCD_CMD_BITS, // 命令位数
.lcd_param_bits = EXAMPLE_LCD_PARAM_BITS, // 参数位数
.spi_mode = 3, // SPI模式
.trans_queue_depth = 10, // 传输队列深度
};
// 将LCD连接到SPI总线
ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)LCD_HOST, &io_config, &io_handle));
st7789_vendor_config_t vendor_config = { // 用于替换驱动组件中的初始化命令及参数
.init_cmds = lcd_init_cmds,
.init_cmds_size = sizeof(lcd_init_cmds) / sizeof(st7789_lcd_init_cmd_t),
};
esp_lcd_panel_dev_config_t panel_config = {
.reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST, // 复位引脚编号
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, // RGB元素顺序
.bits_per_pixel = 16, // 每像素位数
.data_endian = LCD_RGB_DATA_ENDIAN_BIG, // MSB
.vendor_config = &vendor_config, // 用于替换驱动组件中的初始化命令及参数
};
ESP_LOGI(TAG, "Install ST7789 panel driver");
ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));
// 复位和初始化面板
ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle)); // 复位面板
ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle)); // 初始化面板
ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_handle, true)); // 反转颜色
ESP_ERROR_CHECK(esp_lcd_panel_mirror(panel_handle, false, false)); // 镜像显示(水平镜像)
// 用户可以在点亮屏幕或背光之前刷新预定义的图案到屏幕上
ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true)); // 打开屏幕显示
// 打开LCD背光
ESP_LOGI(TAG, "Turn on LCD backlight");
gpio_set_level(EXAMPLE_PIN_NUM_BK_LIGHT, EXAMPLE_LCD_BK_LIGHT_ON_LEVEL); // 设置背光引脚电平
ESP_LOGI(TAG, "Initialize LVGL library");
lv_init();
// create a lvgl display
lv_display_t *display = lv_display_create(EXAMPLE_LCD_H_RES, EXAMPLE_LCD_V_RES);
lv_display_set_offset(display, X_OFFSET, Y_OFFSET);
// alloc draw buffers used by LVGL
// it's recommended to choose the size of the draw buffer(s) to be at least 1/10 screen sized
size_t draw_buffer_sz = EXAMPLE_LCD_H_RES * EXAMPLE_LVGL_DRAW_BUF_LINES * sizeof(lv_color16_t);
void *buf1 = spi_bus_dma_memory_alloc(LCD_HOST, draw_buffer_sz, 0);
assert(buf1);
void *buf2 = spi_bus_dma_memory_alloc(LCD_HOST, draw_buffer_sz, 0);
assert(buf2);
// initialize LVGL draw buffers
lv_display_set_buffers(display, buf1, buf2, draw_buffer_sz, LV_DISPLAY_RENDER_MODE_PARTIAL);
// associate the mipi panel handle to the display
lv_display_set_user_data(display, panel_handle);
// set color depth
lv_display_set_color_format(display, LV_COLOR_FORMAT_RGB565);
// set the callback which can copy the rendered image to an area of the display
lv_display_set_flush_cb(display, example_lvgl_flush_cb);
ESP_LOGI(TAG, "Install LVGL tick timer");
// Tick interface for LVGL (using esp_timer to generate 2ms periodic event)
const esp_timer_create_args_t lvgl_tick_timer_args = {
.callback = &example_increase_lvgl_tick,
.name = "lvgl_tick"
};
esp_timer_handle_t lvgl_tick_timer = NULL;
ESP_ERROR_CHECK(esp_timer_create(&lvgl_tick_timer_args, &lvgl_tick_timer));
ESP_ERROR_CHECK(esp_timer_start_periodic(lvgl_tick_timer, EXAMPLE_LVGL_TICK_PERIOD_MS * 1000));
ESP_LOGI(TAG, "Register io panel event callback for LVGL flush ready notification");
const esp_lcd_panel_io_callbacks_t cbs = {
.on_color_trans_done = example_notify_lvgl_flush_ready,
};
/* Register done callback */
ESP_ERROR_CHECK(esp_lcd_panel_io_register_event_callbacks(io_handle, &cbs, display));
lv_disp_set_rotation(display, LV_DISPLAY_ROTATION_0);
ESP_LOGI(TAG, "Create LVGL task");
xTaskCreate(example_lvgl_port_task, "LVGL", EXAMPLE_LVGL_TASK_STACK_SIZE, NULL, EXAMPLE_LVGL_TASK_PRIORITY, NULL);
ESP_LOGI(TAG, "Display LVGL Meter Widget");
// Lock the mutex due to the LVGL APIs are not thread-safe
_lock_acquire(&lvgl_api_lock);
example_lvgl_demo_ui(display);
_lock_release(&lvgl_api_lock);
while(1){
vTaskDelay(3000 / portTICK_PERIOD_MS);
}
}