1. 衡山派开发板驱动1.47寸ST7789V3彩屏实战：基于RT-Thread的SPI/QSPI移植与图形显示

衡山派开发板驱动1.47寸ST7789V3彩屏实战基于RT-Thread的SPI/QSPI移植与图形显示最近在衡山派开发板上做项目需要用到一块小尺寸的彩色LCD屏幕来显示信息。很多朋友问我怎么在RT-Thread系统下驱动这种SPI接口的彩屏今天我就把完整的移植过程分享出来从硬件连接到软件配置再到图形显示手把手教你点亮这块1.47寸的ST7789V3屏幕。这篇文章适合正在使用衡山派开发板想要实现图形界面显示的嵌入式开发者。跟着步骤走你就能在自己的开发板上看到彩色的文字、图形甚至显示图片。1. 屏幕模块介绍与硬件连接咱们先来认识一下要驱动的这块屏幕。这是一块1.47英寸的彩色LCD分辨率是172×320像素驱动芯片是ST7789V3通过SPI接口与主控通信。1.1 屏幕基本参数参数项规格说明工作电压3.3V工作电流90mA模块尺寸30mm × 37mm显示分辨率172(H) × 320(V) RGB驱动芯片ST7789V3通信协议SPI管脚数量8 Pin2.54mm间距排针1.2 引脚定义与连接屏幕模块有8个引脚我们需要把它们正确连接到衡山派开发板上。下面是引脚连接表屏幕引脚功能说明衡山派开发板引脚VCC电源正极3.3V3.3V电源GND电源地GNDSCLSPI时钟线SCKSPI时钟引脚SDASPI数据输出线MOSISPI数据输出引脚RES复位引脚PC.7DC数据/命令选择PE.16CS片选引脚PC.9BLK背光控制PE.14注意如果你的MCU GPIO引脚不够用有两个变通方法将RES引脚接到MCU的复位引脚这样MCU复位时屏幕也跟着复位可以将BLK直接接到3.3V或悬空代价是无法控制背光亮度连接时一定要仔细核对特别是电源不要接错3.3V的屏幕接到5V上可能会损坏。2. 驱动代码移植步骤驱动代码我已经为大家准备好了完整的包咱们只需要按照步骤把它集成到自己的工程中就行。2.1 获取驱动代码首先需要下载驱动代码文件包。你可以在资料下载中心找到这个屏幕的移植资料包解压后会看到以下几个关键文件1-47-color-screen/ ├── lcd_init.c # LCD初始化与底层通信 ├── lcd_init.h # 引脚定义和函数声明 ├── lcd.c # 图形绘制函数 ├── lcd.h # 图形API头文件 ├── test_1_47_color_screen.c # 测试程序 ├── Kconfig # RT-Thread配置选项 └── SConscript # 编译脚本把这些文件复制到你的工程目录下\luban-lite\application\rt-thread\helloworld\user-bsp\提示如果找不到user-bsp这个文件夹说明你还没有进行模块移植的前置操作。需要先按照手册完成必要的配置操作。2.2 修改Kconfig配置文件接下来要修改Kconfig文件让RT-Thread的配置系统知道我们添加了新的模块。用VSCode或其他编辑器打开文件application\rt-thread\helloworld\Kconfig在这个文件的#endif前面添加以下内容# 1.47寸彩屏 source application/rt-thread/helloworld/user-bsp/1-47-color-screen/Kconfig这样就告诉系统我们有一个新的模块需要配置。2.3 使用menuconfig配置工程现在进入RT-Thread的配置界面启用我们的屏幕驱动。打开env工具双击luban-lite文件夹下的win_env.bat脚本列出可用配置输入以下命令查看所有默认配置scons --list-def选择衡山派默认配置找到d13x_JLC_rt-thread_helloworld这个配置这是衡山派开发板的默认配置输入scons --apply-def7或者scons --apply-defd13x_JLC_rt-thread_helloworld_defconfig进入配置菜单输入命令打开配置界面scons --menuconfig启用LCKFB模块在配置界面中找到并选中Porting code using the LCKFB module按Y键启用。进入LCKFB子菜单回车进入Porting code using the LCKFB module菜单。启用1.47寸彩屏找到Use 1.47 inch color screen选项按Y键启用。你会看到前面出现一个*号表示已选中。保存并退出按左右方向键选择Save保存配置然后一路回车退出。2.4 编译工程配置完成后就可以开始编译了。在env工具中输入scons或者使用多核编译加快速度我的电脑是16核所以用-j16scons -j16提示-j参数用来选择编译使用的核心数核心越多编译越快。如果你写的数字高于电脑本身的核心数会自动按照最高可用核心数来编译。编译完成后会在\luban-lite\output\d13x_JLC_rt-thread_helloworld\images文件夹下生成一个d13x_JLC_v1.0.0.img镜像文件。2.5 烧录镜像最后一步就是把编译好的镜像烧录到开发板上。具体的烧录教程可以参考衡山派官方文档中的镜像烧录部分。烧录完成后就可以进行下一步的移植验证了。3. 驱动代码解析现在咱们来看看驱动代码的具体实现理解每一部分的作用这样以后自己修改或者调试时心里就有底了。3.1 引脚定义与初始化lcd_init.h头文件里定义了屏幕用到的所有引脚和基本参数// 屏幕方向设置0或1为竖屏2或3为横屏 #define USE_HORIZONTAL 2 // 根据方向设置屏幕宽高 #if USE_HORIZONTAL0||USE_HORIZONTAL1 #define LCD_W 172 #define LCD_H 320 #else #define LCD_W 320 #define LCD_H 172 #endif // 引脚定义 - 这里对应衡山派开发板的实际引脚 #define LCD_RES rt_pin_get(PC.7) // 复位引脚 #define LCD_DC rt_pin_get(PE.16) // 数据/命令选择 #define LCD_BLK rt_pin_get(PE.14) // 背光控制 #define LCD_CS rt_pin_get(PC.9) // 片选引脚 // 引脚操作宏定义 #define LCD_RES_Clr() rt_pin_write(LCD_RES, 0) // RES置低 #define LCD_RES_Set() rt_pin_write(LCD_RES, 1) // RES置高 // ... 其他引脚类似这里有个重要的配置项USE_HORIZONTAL用来设置屏幕的显示方向。0和1是竖屏2和3是横屏。根据这个设置LCD_W和LCD_H会自动调整为正确的宽高值。3.2 SPI/QSPI通信底层lcd_init.c这是驱动最核心的部分负责与屏幕芯片进行通信。GPIO初始化void LCD_GPIO_Init(void) { // 查找并获取QSPI设备句柄 lcd_dev (struct rt_qspi_device *)rt_device_find(LCD_DEVICE_NAME); if (!lcd_dev) { LOG_E(Qspi sample run failed! cant find %s device!\n, LCD_DEVICE_NAME); return; } // 配置所有控制引脚为输出模式 rt_pin_mode(LCD_RES, PIN_MODE_OUTPUT); rt_pin_mode(LCD_DC, PIN_MODE_OUTPUT); rt_pin_mode(LCD_BLK, PIN_MODE_OUTPUT); rt_pin_mode(LCD_CS, PIN_MODE_OUTPUT); // 初始化引脚状态 LCD_RES_Set(); LCD_DC_Set(); LCD_BLK_Set(); LCD_CS_Set(); }数据写入函数void LCD_Writ_Bus(u8 dat) { struct rt_qspi_message msg; rt_memset(msg, 0, sizeof(msg)); // 配置QSPI消息结构 msg.instruction.content 0; // 指令内容 msg.instruction.qspi_lines 0; // 指令模式单线模式 msg.qspi_data_lines 1; // QSPI总线位宽1位 // 传输一条消息开始发送数据时片选选中函数返回时释放片选 msg.parent.send_buf dat; // 发送缓冲区指针 msg.parent.length 1; // 发送/接收数据字节数 msg.parent.cs_take 1; // 片选选中 msg.parent.cs_release 1; // 释放片选 rt_spi_take_bus((struct rt_spi_device *)lcd_dev); LCD_CS_Clr(); int ret rt_qspi_transfer_message(lcd_dev, msg); if(ret ! 1) { LOG_E(rt_qspi_transfer_message failed!!); } LCD_CS_Set(); rt_spi_release_bus((struct rt_spi_device *)lcd_dev); }这个函数是通信的基础所有的命令和数据都是通过它发送给屏幕的。注意msg.parent.cs_take和msg.parent.cs_release这两个参数它们控制着片选信号确保每次通信时CS引脚的正确时序。命令和数据写入函数// 写入命令 void LCD_WR_REG(u8 dat) { LCD_DC_Clr(); // DC置低表示接下来发送的是命令 LCD_Writ_Bus(dat); LCD_DC_Set(); // DC置高之后发送的都是数据 } // 写入8位数据 void LCD_WR_DATA8(u8 dat) { LCD_Writ_Bus(dat); } // 写入16位数据RGB565颜色数据 void LCD_WR_DATA(u16 dat) { LCD_Writ_Bus(dat8); // 先发高字节 LCD_Writ_Bus(dat); // 再发低字节 }这里有个关键点LCD_DC引脚用来区分命令和数据。当DC为低电平时发送的是命令寄存器地址当DC为高电平时发送的是数据。这是ST7789芯片的通信协议要求。设置显示区域函数void LCD_Address_Set(u16 x1, u16 y1, u16 x2, u16 y2) { if(USE_HORIZONTAL0) { LCD_WR_REG(0x2a); // 列地址设置 LCD_WR_DATA(x134); LCD_WR_DATA(x234); LCD_WR_REG(0x2b); // 行地址设置 LCD_WR_DATA(y1); LCD_WR_DATA(y2); LCD_WR_REG(0x2c); // 存储器写 } // ... 其他方向类似 }这个函数用来设置接下来要操作的显示区域。ST7789芯片内部有一个显存我们通过设置行列地址来告诉芯片我们要在哪个区域写入像素数据。注意那个34的偏移这是因为这块屏幕的实际显示区域在显存中有偏移需要根据数据手册调整。3.3 屏幕初始化序列lcd_init.c屏幕初始化是一系列命令的集合用来配置芯片的各种参数void LCD_Init(void) { LCD_GPIO_Init(); // 初始化GPIO // 复位序列 LCD_RES_Clr(); // 复位引脚拉低 delay_ms(30); // 保持30ms LCD_RES_Set(); // 复位引脚拉高 delay_ms(100); // 等待100ms LCD_BLK_Set(); // 打开背光 delay_ms(100); // 发送初始化命令序列 LCD_WR_REG(0x11); // 退出睡眠模式 delay_ms(120); // 设置屏幕方向 LCD_WR_REG(0x36); if(USE_HORIZONTAL0) LCD_WR_DATA8(0x00); else if(USE_HORIZONTAL1) LCD_WR_DATA8(0xC0); else if(USE_HORIZONTAL2) LCD_WR_DATA8(0x70); else LCD_WR_DATA8(0xA0); // 设置像素格式RGB565 LCD_WR_REG(0x3A); LCD_WR_DATA8(0x05); // 更多初始化命令... // ...省略部分命令 LCD_WR_REG(0x29); // 打开显示 }初始化序列看起来有点复杂但其实都是按照ST7789数据手册的要求来配置的。每个命令都有特定的作用比如设置颜色格式、伽马校正、电源控制等。如果你要修改屏幕参数比如颜色深度、刷新率等就需要修改这里的命令。3.4 图形绘制函数lcd.c驱动层之上是图形绘制层提供了各种绘图API画点函数- 所有图形的基础void LCD_DrawPoint(u16 x, u16 y, u16 color) { LCD_Address_Set(x, y, x, y); // 设置光标位置 LCD_WR_DATA(color); // 写入颜色数据 }画点是最基本的操作先设置要画的坐标位置然后写入颜色值。颜色是RGB565格式16位高5位是红色中间6位是绿色低5位是蓝色。画线函数- 使用Bresenham算法void LCD_DrawLine(u16 x1, u16 y1, u16 x2, u16 y2, u16 color) { // 计算坐标增量 int delta_x x2 - x1; int delta_y y2 - y1; // 判断步进方向 int incx (delta_x 0) ? 1 : ((delta_x 0) ? 0 : -1); int incy (delta_y 0) ? 1 : ((delta_y 0) ? 0 : -1); // 选择基本增量轴 int distance (delta_x delta_y) ? delta_x : delta_y; // 逐点绘制 for(int t 0; t distance; t) { LCD_DrawPoint(x1, y1, color); // ... 误差累积计算 } }Bresenham算法是计算机图形学中经典的画线算法只用整数运算就能画出平滑的直线效率很高。显示字符函数void LCD_ShowChar(u16 x, u16 y, u8 num, u16 fc, u16 bc, u8 sizey, u8 mode) { u8 temp, sizex, t, m 0; u16 i, TypefaceNum; u16 x0 x; sizex sizey / 2; // 字符宽度是高度的一半 TypefaceNum (sizex / 8 ((sizex % 8) ? 1 : 0)) * sizey; num num - ; // 得到偏移后的值字库从空格开始 LCD_Address_Set(x, y, x sizex - 1, y sizey - 1); for(i 0; i TypefaceNum; i) { // 根据字号选择不同的字库 if(sizey 12) temp ascii_1206[num][i]; else if(sizey 16) temp ascii_1608[num][i]; else if(sizey 24) temp ascii_2412[num][i]; else if(sizey 32) temp ascii_3216[num][i]; else return; // 逐位判断是否点亮该像素 for(t 0; t 8; t) { if(!mode) { // 非叠加模式 if(temp (0x01 t)) LCD_WR_DATA(fc); else LCD_WR_DATA(bc); } else { // 叠加模式 if(temp (0x01 t)) LCD_DrawPoint(x, y, fc); x; if((x - x0) sizex) { x x0; y; break; } } } } }字符显示的原理是使用点阵字库。每个字符对应一个位图位图中的每个bit表示一个像素是否点亮。函数根据字符的ASCII码在字库中找到对应的位图数据然后逐位判断并绘制。颜色定义// 常用颜色定义RGB565格式 #define WHITE 0xFFFF // 白色R31, G63, B31 #define BLACK 0x0000 // 黑色R0, G0, B0 #define RED 0xF800 // 红色R31, G0, B0 #define GREEN 0x07E0 // 绿色R0, G63, B0 #define BLUE 0x001F // 蓝色R0, G0, B31 #define YELLOW 0xFFE0 // 黄色R31, G63, B0 // ... 更多颜色RGB565格式的颜色值可以这样理解一个16位的数从高位到低位分别是5位红色、6位绿色、5位蓝色。比如红色0xF800就是二进制的11111 000000 00000。3.5 测试程序test_1_47_color_screen.c最后来看测试程序它创建了一个线程来测试屏幕的各种功能// 线程入口函数 static void lcd_thread_entry(void *param) { float t 0; LCD_Init(); // 屏幕初始化 rt_kprintf([ LCD_Init ] succeed.\r\n); LCD_Fill(0, 0, LCD_W, LCD_H, WHITE); // 清屏为白色 rt_kprintf([ LCD_Fill ] succeed.\r\n); while(1) { if(t 99.88) t 0; // 显示中文 LCD_ShowChinese(40, 0, (uint8_t *)中电港, RED, WHITE, 32, 0); // 显示屏幕尺寸 LCD_ShowString(10, 33, (uint8_t *)LCD_W:, RED, WHITE, 32, 0); LCD_ShowIntNum(106, 33, LCD_W, 3, RED, WHITE, 32); LCD_ShowString(10, 66, (uint8_t *)LCD_H:, RED, WHITE, 32, 0); LCD_ShowIntNum(106, 66, LCD_H, 3, RED, WHITE, 32); // 显示动态浮点数 LCD_ShowFloatNum1(10, 99, t, 4, RED, WHITE, 32); t 0.11; // 显示图片如果有图片数据 // LCD_ShowPicture(160, 95, 40, 40, gImage_1); rt_thread_mdelay(500); // 延时500ms } }这个测试程序做了几件事初始化屏幕清屏为白色在循环中显示中文、屏幕尺寸、动态变化的数字每500ms更新一次4. 移植验证与调试代码都准备好后咱们来实际测试一下。4.1 连接串口调试首先需要用USB转TTL模块连接到衡山派开发板的串口上具体连接方法参考官方文档。串口波特率默认是115200。4.2 运行测试程序在串口终端中输入以下命令来运行测试程序test_lckfb_1_47_color_screen提示输入时可以按TAB键进行命令补全避免输错。如果一切正常你应该能在串口看到类似这样的输出malloc the qspi succeed. [ lcd_qspi_attach ] succeed. [ lcd_qspi_init ] succeed. [ LCD_Init ] succeed. [ LCD_Fill ] succeed.同时在1.47寸屏幕上看到顶部显示红色的中电港三个字中间显示屏幕的宽度和高度LCD_W: 320, LCD_H: 172底部有一个从0开始递增的浮点数每0.5秒增加0.114.3 常见问题排查如果屏幕没有显示可以按照以下步骤排查检查硬件连接确认电源3.3V和GND连接正确检查SPI四根线SCK、MOSI、CS、DC是否接对确认复位和背光引脚连接正确检查软件配置确认menuconfig中正确启用了Use 1.47 inch color screen检查引脚定义是否与你的实际连接一致确认编译没有错误使用逻辑分析仪或示波器检查SPI时钟是否有信号检查CS片选信号是否正常查看数据线上是否有数据传输修改调试信息在LCD_Init()函数中添加更多的rt_kprintf输出检查每个初始化步骤是否成功执行5. 进阶使用与优化基本的显示功能实现后你还可以进一步优化和扩展5.1 提高刷新速度当前的SPI时钟是20MHz如果你需要更快的刷新速度可以尝试提高SPI时钟频率// 在lcd_qspi_init函数中修改 qspi_cfg.parent.max_hz 40 * 1000 * 1000; // 提高到40MHz使用DMA传输对于大量数据的传输如图片显示可以使用DMA来减轻CPU负担。优化绘制算法对于区域填充等操作可以一次性发送整个区域的数据而不是逐个像素发送。5.2 添加双缓冲如果显示有闪烁现象可以考虑实现双缓冲在内存中开辟两块显示缓冲区所有的绘图操作先在后台缓冲区进行完成一帧绘制后一次性将后台缓冲区数据复制到屏幕5.3 集成GUI框架如果你需要更复杂的图形界面可以考虑集成现有的GUI框架LittlevGL轻量级、开源、功能丰富UGUI更轻量适合资源受限的系统RT-Thread的PersimmonRT-Thread自带的GUI组件5.4 显示图片代码中已经预留了显示图片的函数LCD_ShowPicture你需要将图片转换为RGB565格式的数组将数组放在pic.h头文件中调用显示函数可以使用Image2Lcd等工具进行图片转换。6. 实际项目中的经验分享在实际项目中用这块屏幕时我遇到过几个坑这里分享给大家坑点1屏幕初始化时序ST7789对复位时序比较敏感如果复位时间不够可能导致初始化失败。如果遇到屏幕不亮的情况可以适当增加复位延时。坑点2SPI模式ST7789通常使用SPI模式3CPOL1, CPHA1代码中已经正确配置。如果换成其他型号的屏幕可能需要调整SPI模式。坑点3内存占用320×172的分辨率RGB565格式下需要320×172×2 110KB的显存。如果使用双缓冲就需要220KB。要确保开发板有足够的内存。坑点4刷新率SPI接口的屏幕刷新率受限于总线速度。20MHz的SPI时钟下全屏刷新一帧大约需要 (320×172×16 bits) / 20MHz ≈ 44ms也就是约22fps。 如果需要更高的刷新率要么提高SPI时钟要么减少每次刷新的数据量。优化建议局部刷新对于动态显示不要每次都刷新整个屏幕。只刷新变化的部分可以显著提高效率。比如显示一个变化的数字只刷新数字所在的区域即可。按照上面的步骤你应该已经成功点亮了1.47寸彩屏。这套驱动代码我在好几个项目里都用过比较稳定。如果遇到问题可以重点检查硬件连接和SPI配置这两个是最容易出问题的地方。