基于 RT-Thread 的 Raspberry Pi Pico 运行 LVGL 图形界面：ST7789 SPI 屏移植全指南

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS

本篇技术指南以 RT-Thread 仓库中bsp/raspberry-pico/RP2040/applications/lvgl目录下的官方文档与配套源码为骨架，系统讲解如何在 Raspberry Pi Pico 上通过 RT-Thread Studio 使能并移植 LVGL 图形库，驱动 ST7789 SPI 接口 TFT-LCD 屏幕。读完本文，你将掌握完整的操作路径：在 RT-Thread Settings 中开启 LVGL、配置屏幕分辨率与方向、对接 LVGL 显示刷新接口与按键输入设备，并最终在 240×240 屏幕上运行 LVGL 官方音乐播放器演示。

一、硬件准备：Pico 主板与 ST7789 屏幕

1.1 Raspberry Pi Pico 核心参数

本项目基于 Raspberry Pi Pico（RP2040 芯片），其关键硬件参数如下：

• 双核 Arm Cortex-M0+，主频 133MHz
• 芯片内置 264KB SRAM 与 2MB 板载闪存
• 通过专用 QSPI 总线支持最高 16MB 片外闪存
• 内置 DMA 控制器
• 30 个 GPIO 引脚，其中 4 个可用作模拟输入
• 2 个 UART、2 个 SPI 控制器、2 个 I2C 控制器
• 16 个 PWM 通道

这些资源为 LVGL 运行提供了基础：264KB SRAM 足以承载 LVGL 的绘制缓冲区与对象树，双核 Cortex-M0+ 保证界面渲染与 RT-Thread 调度互不阻塞。

1.2 ST7789 SPI 屏幕规格

本文使用的拓展屏为ST7789 SPI 接口 TFT-LCD，这是一颗单芯片 TFT-LCD 控制器/驱动器，核心规格如下：

• 显示分辨率：240 × RGB (H) × 320 (V)
• 帧内存（Frame Memory）大小：240 × 320 × 18-bit = 1,382,400 bits
• LCD 驱动输出电路：
  • Source 输出：240 RGB 通道
  • Gate 输出：320 通道
  • 公共电极输出（Common Electrode Output）

ST7789 支持 SPI 串行接口，仅需 4~5 根信号线即可驱动，非常适合 Pico 这类引脚资源有限的开发板。

1.3 引脚接线对照表

从仓库中的 drv_lcd.h 可以提取出本工程实际的接线定义，接线时请对照此表：

同时，drv_lcd.h 中还定义了屏幕尺寸与显示方向宏：

#define LCD_HEIGHT 240 #define LCD_WIDTH 240 #define HORIZONTAL 0 #define VERTICAL 1

注意：虽然 ST7789 原生分辨率为 240×320，但本项目使用的屏幕模组实际可视区域为240×240（驱动代码中以LCD_WIDTH/LCD_HEIGHT均为 240 配置），这也是后续 LVGL 分辨率设置为 240×240 的原因。

二、软件环境搭建

运行本示例需要以下软件组件：

• RT-Thread IoT OS：本仓库即是 RT-Thread 官方内核源码，Pico BSP 位于 bsp/raspberry-pico 目录；
• RT-Thread Studio IDE（免费版）：用于工程创建、配置与编译烧录；
• LVGL：开源的嵌入式图形库，本工程通过 RT-Thread 软件包管理集成（示例中为 LVGL v8.x 版本，源码位于packages/LVGL-v8.1.0软件包目录）。

在 RT-Thread Studio 中导入本 BSP 工程后，即可开始以下配置流程。

三、使能 LVGL for LCD

在 RT-Thread Studio 中打开工程的RT-Thread Settings配置页，在「硬件」分类下的配置树中，展开Hardware Drivers Config → Onboard Peripheral Drivers，找到Enable LVGL for LCD配置项并将其勾选：

该配置项对应的源码依赖关系体现在 lvgl/SConscript 中：

group = group + DefineGroup('LVGL-port', src, depend = ['BSP_USING_LVGL'], CPPPATH = CPPPATH)

即只有定义了BSP_USING_LVGL（由上述配置项生成）时，lv_conf.h、lv_port_disp.c、lv_port_indev.c等 LVGL 移植文件才会被编译进工程。同时该目录还会递归加载demo/子目录下的演示源码。

四、配置屏幕参数

使能 LVGL 后，需要根据实际屏幕规格配置分辨率与显示方向。本教程使用 ST7789，屏幕实际尺寸为 240×240。

在 drv_lcd.h 中，通过LCD_HEIGHT、LCD_WIDTH两个宏定义选择屏幕尺寸，通过HORIZONTAL/VERTICAL选择显示方向：

与屏幕物理参数相对应，LVGL 侧的配置位于 lv_conf.h：

#define LV_COLOR_DEPTH 16 /* 16 位色深 RGB565 */ #define LV_COLOR_16_SWAP 1 /* 高低字节交换，匹配 ST7789 RGB565 时序 */ #define LV_HOR_RES_MAX 240 /* 水平最大分辨率 */ #define LV_VER_RES_MAX 240 /* 垂直最大分辨率 */ #define LV_USE_PERF_MONITOR 1 /* 启用性能监视器，可在屏幕角落显示 FPS */

这里需要解释两个关键配置的作用：

• LV_COLOR_DEPTH 16：LVGL 以 16 位 RGB565 格式绘制，与 ST7789 的 16 位 SPI 像素数据格式一一对应，一次spi_write_blocking即可写入一个像素；
• LV_COLOR_16_SWAP 1：开启字节序交换，因为 SPI 总线按大端先发高字节，而内存中 RGB565 通常按小端存储，此开关保证颜色显示正确；
• LV_HOR_RES_MAX/LV_VER_RES_MAX均为 240：与 drv_lcd.h 中LCD_WIDTH/LCD_HEIGHT保持严格一致，这两组宏在显示驱动注册时会被交叉引用（见下一节），务必同步修改。

五、LVGL 显示接口对接

LVGL 本身不直接操作硬件，需要通过显示驱动（Display Driver）与绘制缓冲（Draw Buffer）完成对接。本工程的核心移植文件是 lv_port_disp.c。

5.1 显示刷新回调：lcd_fb_flush

LVGL 绘制完成后，会通过注册的flush_cb回调把缓冲区内容送到屏幕。本工程的实现如下：

static void lcd_fb_flush(lv_disp_drv_t *disp_drv, const lv_area_t *area, lv_color_t *color_p) { LCD_DisplayWindows(area->x1, area->y1, area->x2, area->y2, (uint16_t*) color_p); lv_disp_flush_ready(disp_drv); }

• LCD_DisplayWindows(x1, y1, x2, y2, color_p)：只刷新脏矩形区域（area指定的窗口），底层通过 ST7789 的0x2A/0x2B命令设置窗口坐标后批量写入像素，实现局部刷新，减少 SPI 传输量；
• lv_disp_flush_ready(disp_drv)：通知 LVGL 本次刷新完成，可继续绘制下一帧。

LCD_DisplayWindows的实现位于 drv_lcd.c，其底层使用spi_write_blocking(SPI_PORT, ...)发送数据，SPI 控制器选择spi1，初始化时钟为 80MHz（spi_init(SPI_PORT, 80000 * 1000)）。同时该文件还封装了 DMA 通道（initDMA/pushPixelsDMA/dmaWait），为后续大块像素搬运提供 DMA 加速能力。

5.2 绘制缓冲与驱动注册：lv_port_disp_init

显示驱动的初始化入口为lv_port_disp_init，完整流程如下：

void lv_port_disp_init(void) { SPI_Init(); LCD_Init(HORIZONTAL); lv_disp_draw_buf_init(&disp_buf, lv_disp_buf1, RT_NULL, DISP_BUF_SIZE); lv_disp_drv_init(&disp_drv); disp_drv.hor_res = LV_VER_RES_MAX; disp_drv.ver_res = LV_HOR_RES_MAX; disp_drv.draw_buf = &disp_buf; disp_drv.flush_cb = lcd_fb_flush; lv_disp_drv_register(&disp_drv); g_disp_drv = disp_drv; }

关键点说明：

1. 硬件初始化：SPI_Init()与LCD_Init(HORIZONTAL)完成 SPI 外设、GPIO、PWM 背光与 ST7789 寄存器初始化（drv_lcd.c 中的LCD_InitReg包含了 Gamma、电源、帧率等完整寄存器序列）；
2. 缓冲区绑定：lv_disp_draw_buf_init将静态数组lv_disp_buf1[DISP_BUF_SIZE]绑定为 LVGL 绘制缓冲，DISP_BUF_SIZE定义为LV_HOR_RES_MAX * LV_VER_RES_MAX，即完整的 240×240 全屏缓冲；
3. 分辨率交叉映射：disp_drv.hor_res = LV_VER_RES_MAX、disp_drv.ver_res = LV_HOR_RES_MAX，这是源码中一个值得注意的细节——由于显示方向为横向（HORIZONTAL），物理屏的宽高被交换映射到 LVGL 的逻辑分辨率上；
4. 注册驱动：lv_disp_drv_register将配置好的驱动注册进 LVGL 全局驱动表，此后 LVGL 的绘制与刷新即与该屏幕绑定。

5.3 初始化调用链

从 LVGL 软件包侧的lv_rt_thread_port.c可以看出调用关系：lv_port_init()中先执行lv_init()初始化 LVGL 核心，随后在#ifndef PKG_USING_LVGL_DISP_DEVICE分支内调用lv_port_disp_init()完成显示接口初始化（如果启用了 RT-Thread 显示设备框架PKG_USING_LVGL_DISP_DEVICE，则改走设备框架路径）。本 BSP 的示例采用直接对接方式，即上文所述流程。

六、输入设备对接（按键扩展）

除了显示输出，本工程还提供了按键输入设备移植，文件为 lv_port_indev.c，将 Pico 板载按键映射为 LVGL 按钮输入设备（LV_INDEV_TYPE_BUTTON）：

#define BUTTON0_PIN 2 #define BUTTON1_PIN 18 #define BUTTON2_PIN 16 #define BUTTON_WKUP_PIN 20

实现要点：

• lv_port_indev_init()中通过rt_pin_mode(...)将四个按键引脚配置为输入模式，并初始化lv_indev_drv_t，指定类型为LV_INDEV_TYPE_BUTTON、读取回调为button_read；
• button_read调用button_get_pressed_id轮询四个按键（按下时引脚为低电平PIN_LOW），将按下的按键 ID 与LV_INDEV_STATE_PRESSED/RELEASED状态写入lv_indev_data_t，交由 LVGL 处理；
• 最终通过lv_indev_drv_register注册输入设备。

这为 LVGL 界面提供了交互能力，可用于菜单选择、翻页等操作，而无需额外的触摸屏硬件。

七、运行 LVGL 演示程序

7.1 演示入口

完成上述配置并编译烧录后，工程会运行 LVGL 官方提供的音乐播放器演示。入口代码位于 demo/lv_demo.c：

void lv_user_gui_init(void) { /* display demo; you may replace with your LVGL application at here */ extern void lv_demo_music(void); lv_demo_music(); }

这里就是替换为你自己的 LVGL 应用的地方：只需在lv_user_gui_init中调用你自定义的界面初始化函数即可。

7.2 使能音乐演示

音乐演示依赖 LVGL 软件包中的 demo 组件，在 lv_conf.h 中通过PKG_USING_LV_MUSIC_DEMO条件编译开关控制：

#ifdef PKG_USING_LV_MUSIC_DEMO #define LV_USE_DEMO_RTT_MUSIC 1 #define LV_DEMO_RTT_MUSIC_AUTO_PLAY 1 #define LV_FONT_MONTSERRAT_12 1 #define LV_FONT_MONTSERRAT_16 1 #define LV_COLOR_SCREEN_TRANSP 1 #endif

即在 RT-Thread 软件包配置中启用LV_MUSIC_DEMO后，会同时开启音乐演示、自动播放、所需字体与屏幕透明色支持。

7.3 板载外设辅助验证

BSP 默认的 main.c 还提供了板载 LED（GPIO 25）的闪烁程序与Hello, RT-Thread!串口打印，可用于烧录后先验证 RT-Thread 系统本身运行正常，再接入 LVGL 界面调试。

八、工程结构与二次开发指引

本示例的完整工程结构如下：

bsp/raspberry-pico/RP2040/ ├── applications/ │ ├── lvgl/ │ │ ├── lv_conf.h # LVGL 核心配置（色深、分辨率、demo 开关） │ │ ├── lv_port_disp.c # 显示驱动移植（刷新回调 + 缓冲 + 注册） │ │ ├── lv_port_indev.c # 按键输入设备移植 │ │ ├── demo/lv_demo.c # 用户 GUI 入口（演示/自定义应用） │ │ └── SConscript # BSP_USING_LVGL 条件编译 │ └── main.c # 板载 LED 示例 └── board/ports/lcd/ ├── drv_lcd.c # ST7789 底层驱动（SPI/PWM/DMA） └── drv_lcd.h # 引脚与屏幕尺寸宏定义

对开发者而言，二次开发通常只需两步：

1. 在demo/lv_demo.c的lv_user_gui_init中替换为你自己的界面初始化代码；
2. 如需更换屏幕尺寸或型号，同步修改 drv_lcd.h 的LCD_WIDTH/LCD_HEIGHT与 lv_conf.h 的LV_HOR_RES_MAX/LV_VER_RES_MAX，并调整lv_port_disp.c中的分辨率映射即可。

九、小结

本文完整复现了官方文档的四个核心步骤——使能 LVGL for LCD → 配置屏幕参数 → 对接显示接口 → 运行演示，并结合 lv_conf.h、lv_port_disp.c、drv_lcd.c 等源码，深入剖析了色深/字节序、脏矩形刷新、绘制缓冲、DMA 搬运与按键输入等关键实现。按照上述步骤操作，即可在 Pico + ST7789 的组合上跑通完整的 LVGL 图形界面，并以此为模板快速扩展出自定义的嵌入式 GUI 应用。

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS