GD32VW553开发板驱动1.3寸SH1106 OLED显示屏实战指南最近在玩GD32VW553这块开发板想给它接个小屏幕显示点信息就选了市面上很常见的1.3寸SH1106 OLED屏。这种屏价格便宜、接口简单SPI显示效果也不错非常适合嵌入式项目做状态显示或者调试信息输出。但网上的驱动代码五花八门移植到GD32VW553上总有点小问题。今天我就把完整的移植过程和踩过的坑分享给大家手把手教你从零开始点亮这块屏。咱们的目标很明确用GD32VW553的SPI接口驱动这块128x64分辨率的单色OLED实现显示字符、汉字、图片等功能。我会把硬件连接、软件配置、关键代码都讲清楚保证你跟着做一遍就能成功。1. 硬件准备与连接1.1 了解你的OLED模块我用的这块1.3寸OLED屏核心驱动芯片是SH1106。先看看它的关键参数参数规格工作电压3.3V ~ 5V工作电流约20mA屏幕尺寸33.5 x 35.4 mm分辨率128 x 64 像素像素间距0.23(H) x 0.23(V) mm像素尺寸0.21(H) x 0.21(V) mm通信协议SPI可通过跳线帽切换为IIC注意SH1106和常见的SSD1306驱动芯片很相似但略有不同。SH1106支持132x64的RAM但实际显示区域是128x64所以初始化指令有些区别这个后面会讲到。模块背面一般有8个引脚我们需要用到其中6个来连接GD32VW553。各引脚功能如下GND电源地VCC电源正极接3.3V或5VD0 (SCL/SCK)SPI时钟线D1 (SDA/MOSI)SPI数据线主出从入RES复位引脚低电平有效DC数据/命令选择引脚高电平为数据低电平为命令CS片选引脚低电平有效BLK背光控制有些模块没有这个引脚1.2 连接开发板根据GD32VW553开发板的引脚资源我选择了以下连接方式。你可以根据自己的项目需求调整只要保证SPI引脚对应正确就行。OLED模块引脚GD32VW553开发板引脚功能说明GNDGND电源地VCC3V33.3V电源D0 (SCL)PA11SPI时钟线SCKD1 (SDA)PA9SPI数据输出MOSIRESPA7复位引脚DCPA4数据/命令选择CSPB11片选引脚提示如果你的项目GPIO资源紧张RES引脚可以不接MCU直接接VCC或通过一个电容接地实现上电复位。但为了可靠控制建议还是接上。连接好硬件后咱们就可以开始软件部分的配置了。2. 工程搭建与驱动移植2.1 获取驱动源码首先需要准备好OLED的驱动代码。我用的这个驱动是从一个成熟的工程里移植过来的功能比较全支持显示字符、汉字、图形等。你可以从提供的资料链接下载完整的工程示例。下载后重点关注oled.h和oled.c这两个文件它们包含了所有的驱动函数。2.2 创建工程并添加文件如果你还没有GD32VW553的工程模板可以参考官方例程创建一个。这里假设你已经有了一个可以编译的基础工程。接下来把下载的oled.h、oled.c以及字库文件oledfont.h复制到你的工程目录下。通常我会在Src和Inc文件夹里分别存放.c和.h文件。然后在你的工程管理软件比如Keil、IAR或者VS CodePlatformIO中添加这些文件将oled.c添加到工程的源文件组将oled.h和oledfont.h的路径添加到头文件包含目录2.3 修改引脚定义这是移植的关键一步。我们需要根据刚才的硬件连接修改oled.h文件中的引脚定义。打开oled.h找到引脚定义的部分修改为以下内容//-----------------OLED端口定义---------------- #define OLED_RCU_ENABLE() rcu_periph_clock_enable(RCU_GPIOA); \ rcu_periph_clock_enable(RCU_GPIOB); \ rcu_periph_clock_enable(RCU_SPI) #define OLED_SCL_PORT GPIOA #define OLED_SCL_PIN GPIO_PIN_11 #define OLED_SCL_AF GPIO_AF_0 #define OLED_SDA_PORT GPIOA #define OLED_SDA_PIN GPIO_PIN_9 #define OLED_SDA_AF GPIO_AF_0 #define OLED_RES_PORT GPIOA #define OLED_RES_PIN GPIO_PIN_7 #define OLED_DC_PORT GPIOA #define OLED_DC_PIN GPIO_PIN_4 #define OLED_CS_PORT GPIOB #define OLED_CS_PIN GPIO_PIN_11 // 背光控制引脚如果模块有 #define OLED_BLK_PORT GPIOB #define OLED_BLK_PIN GPIO_PIN_12 // 引脚电平控制宏定义 #define OLED_RES_Clr() gpio_bit_write(OLED_RES_PORT,OLED_RES_PIN,0) // RES低电平 #define OLED_RES_Set() gpio_bit_write(OLED_RES_PORT,OLED_RES_PIN,1) // RES高电平 #define OLED_DC_Clr() gpio_bit_write(OLED_DC_PORT,OLED_DC_PIN,0) // DC低电平命令 #define OLED_DC_Set() gpio_bit_write(OLED_DC_PORT,OLED_DC_PIN,1) // DC高电平数据 #define OLED_CS_Clr() gpio_bit_write(OLED_CS_PORT,OLED_CS_PIN,0) // CS低电平选中 #define OLED_CS_Set() gpio_bit_write(OLED_CS_PORT,OLED_CS_PIN,1) // CS高电平不选中这里有几个地方需要注意OLED_SCL_AF和OLED_SDA_AF设置为GPIO_AF_0这是因为GD32VW553的SPI复用功能映射需要查数据手册确认。我用的这个引脚配置对应SPI的AF0功能。背光控制引脚OLED_BLK是可选的如果你的模块没有背光或者不需要控制可以不用管。gpio_bit_write是GD32的标准库函数用于快速设置单个引脚电平。3. SPI配置与驱动函数详解3.1 SPI外设初始化OLED驱动最核心的部分就是SPI通信。打开oled.c文件找到OLED_Init()函数我们重点看SPI的配置部分。void OLED_Init(void) { // 使能时钟 OLED_RCU_ENABLE(); // 引脚复用配置SCL和SDA需要配置为SPI功能 gpio_af_set(OLED_SCL_PORT, OLED_SCL_AF, OLED_SCL_PIN); gpio_af_set(OLED_SDA_PORT, OLED_SDA_AF, OLED_SDA_PIN); // 引脚模式设置 gpio_mode_set(OLED_SCL_PORT, GPIO_MODE_AF, GPIO_PUPD_NONE, OLED_SCL_PIN); gpio_mode_set(OLED_SDA_PORT, GPIO_MODE_AF, GPIO_PUPD_NONE, OLED_SDA_PIN); gpio_mode_set(OLED_RES_PORT, GPIO_MODE_OUTPUT, GPIO_PUPD_PULLUP, OLED_RES_PIN); gpio_mode_set(OLED_DC_PORT, GPIO_MODE_OUTPUT, GPIO_PUPD_PULLUP, OLED_DC_PIN); gpio_mode_set(OLED_CS_PORT, GPIO_MODE_OUTPUT, GPIO_PUPD_PULLUP, OLED_CS_PIN); // 输出模式设置 gpio_output_options_set(OLED_SCL_PORT, GPIO_OTYPE_PP, GPIO_OSPEED_25MHZ, OLED_SCL_PIN); gpio_output_options_set(OLED_SDA_PORT, GPIO_OTYPE_PP, GPIO_OSPEED_25MHZ, OLED_SDA_PIN); gpio_output_options_set(OLED_RES_PORT, GPIO_OTYPE_PP, GPIO_OSPEED_25MHZ, OLED_RES_PIN); gpio_output_options_set(OLED_DC_PORT, GPIO_OTYPE_PP, GPIO_OSPEED_25MHZ, OLED_DC_PIN); gpio_output_options_set(OLED_CS_PORT, GPIO_OTYPE_PP, GPIO_OSPEED_25MHZ, OLED_CS_PIN); OLED_CS_Set(); // 片选拉高不选中 OLED_DC_Set(); // 数据/命令拉高默认数据模式 // SPI参数定义结构体 spi_parameter_struct spi_init_struct; /* 配置 SPI 参数 */ spi_init_struct.trans_mode SPI_TRANSMODE_FULLDUPLEX; // 全双工模式 spi_init_struct.device_mode SPI_MASTER; // 配置为主机 spi_init_struct.frame_size SPI_FRAMESIZE_8BIT; // 8位数据帧 spi_init_struct.clock_polarity_phase SPI_CK_PL_HIGH_PH_2EDGE; // 时钟极性相位 spi_init_struct.nss SPI_NSS_SOFT; // 软件控制片选 spi_init_struct.prescale SPI_PSC_4; // 4分频 spi_init_struct.endian SPI_ENDIAN_MSB; // 高位在前 // 将参数填入SPI spi_init(spi_init_struct); /* 使能 SPI */ spi_enable(); delay_1ms(500); // 硬件复位OLED OLED_RES_Clr(); delay_ms(200); OLED_RES_Set(); // 发送初始化命令序列 OLED_WR_Byte(0xAE,OLED_CMD); /*display off*/ OLED_WR_Byte(0x02,OLED_CMD); /*set lower column address*/ OLED_WR_Byte(0x10,OLED_CMD); /*set higher column address*/ // ... 更多初始化命令 OLED_Clear(); OLED_WR_Byte(0xAF,OLED_CMD); /*display ON*/ }这里有几个关键点时钟极性相位SPI_CK_PL_HIGH_PH_2EDGE对应的是模式3CPOL1, CPHA1这是SH1106常用的SPI模式。预分频SPI_PSC_4表示SPI时钟系统时钟/4。如果系统时钟是120MHz那么SPI时钟就是30MHz。SH1106最高支持到10MHz左右所以这个速度是安全的。软件片选设置为SPI_NSS_SOFT后我们需要手动控制CS引脚而不是用硬件自动控制。3.2 字节发送函数SPI通信的核心是OLED_WR_Byte()函数它负责发送一个字节的数据或命令到OLED。void OLED_WR_Byte(u8 dat, u8 cmd) { if(cmd) OLED_DC_Set(); // 命令模式 else OLED_DC_Clr(); // 数据模式 OLED_CS_Clr(); // 片选拉低开始通信 // 等待发送缓冲区为空 while(RESET spi_flag_get(SPI_FLAG_TBE)); // 通过SPI发送一个字节数据 spi_data_transmit(dat); // 等待接收缓冲区非空标志全双工需要读取 while(RESET spi_flag_get(SPI_FLAG_RBNE)); uint8_t recv_data spi_data_receive(); // 读取接收的数据虽然不用 OLED_CS_Set(); // 片选拉高结束通信 OLED_DC_Set(); // 恢复为数据模式 }这个函数的工作流程根据cmd参数设置DC引脚电平0命令1数据拉低CS引脚选中OLED等待SPI发送缓冲区空闲发送数据等待接收完成全双工模式下必须读取接收寄存器拉高CS引脚结束本次传输注意虽然我们只发送不接收但SPI是全双工通信发送的同时也会接收数据。必须读取接收寄存器来清除标志位否则下次发送会卡住。3.3 显示缓冲区与刷新机制SH1106内部有132x64位的显示RAM但实际只显示中间的128x64区域。为了编程方便驱动里定义了一个显示缓冲区u8 OLED_GRAM[144][8];这个二维数组的大小是144x8字节。为什么是144而不是128因为SH1106的RAM是132列这里多分配了一些空间方便实现滚动显示等功能。每个字节对应垂直方向的8个像素点一个Page。比如OLED_GRAM[0][0]的bit0对应屏幕(0,0)位置的像素bit7对应(0,7)位置的像素。当我们要更新显示时先修改OLED_GRAM数组然后调用OLED_Refresh()函数将整个缓冲区的内容发送到OLEDvoid OLED_Refresh(void) { u8 i,n; for(i0;i8;i) // 遍历8个Page { OLED_WR_Byte(0xb0i,OLED_CMD); // 设置页地址 OLED_WR_Byte(0x02,OLED_CMD); // 设置列地址低4位 OLED_WR_Byte(0x10,OLED_CMD); // 设置列地址高4位 for(n0;n128;n) // 遍历128列 OLED_WR_Byte(OLED_GRAM[n][i],OLED_DATA); } }这种双缓冲机制的好处是我们可以随时修改缓冲区内容然后一次性刷新到屏幕避免闪烁。4. 基本显示功能使用4.1 显示字符和字符串驱动提供了多种字体大小的字符显示函数// 显示单个字符 void OLED_ShowChar(u8 x, u8 y, u8 chr, u8 size1, u8 mode); // 显示字符串 void OLED_ShowString(u8 x, u8 y, u8 *chr, u8 size1, u8 mode);参数说明x, y显示起始坐标x: 0-127, y: 0-63chr要显示的字符或字符串size1字体大小8, 12, 16, 24mode0反色显示1正常显示例如在屏幕左上角显示HelloOLED_ShowString(0, 0, Hello, 16, 1);4.2 显示汉字要显示汉字需要先准备好字库。驱动里已经包含了常用的汉字字模通过以下函数调用void OLED_ShowChinese(u8 x, u8 y, u8 num, u8 size1, u8 mode);参数num是汉字在字库数组中的索引。比如字库数组Hzk1里按顺序存放了多个16x16的汉字num0就显示第一个汉字。4.3 显示图片显示图片需要先将图片转换为字节数组。可以使用取模软件如PCtoLCD2002将BMP图片转换为C语言数组。void OLED_ShowPicture(u8 x, u8 y, u8 sizex, u8 sizey, u8 BMP[], u8 mode);例如显示一张128x64的全屏图片// 假设BMP1是128x64的图片数组 OLED_ShowPicture(0, 0, 128, 64, BMP1, 1);4.4 清屏和画点画线// 清屏 OLED_Clear(); // 画点 void OLED_DrawPoint(u8 x, u8 y, u8 t); // t1点亮t0熄灭 // 画线 void OLED_DrawLine(u8 x1, u8 y1, u8 x2, u8 y2, u8 mode); // 画圆 void OLED_DrawCircle(u8 x, u8 y, u8 r);这些基础函数可以组合出更复杂的图形界面。5. 移植验证与调试5.1 编写测试代码在main.c中添加测试代码验证所有功能是否正常#include oled.h #include bmp.h // 包含图片数据 int main(void) { // 系统初始化时钟、延时等 systick_config(); // OLED初始化 OLED_Init(); OLED_ColorTurn(0); // 0正常显示1反色显示 OLED_DisplayTurn(0); // 0正常方向1旋转180度 u8 t ; while(1) { // 测试1显示图片 OLED_ShowPicture(0, 0, 128, 64, BMP1, 1); OLED_Refresh(); delay_ms(1000); OLED_Clear(); // 测试2显示汉字 OLED_ShowChinese(0, 0, 0, 16, 1); // 显示中 OLED_ShowChinese(18, 0, 1, 16, 1); // 显示景 OLED_ShowChinese(36, 0, 2, 16, 1); // 显示园 OLED_ShowString(8, 16, ZHONGJINGYUAN, 16, 1); OLED_Refresh(); delay_ms(1000); OLED_Clear(); // 测试3显示不同大小的字符 OLED_ShowString(0, 0, ABC, 8, 1); // 6x8字体 OLED_ShowString(0, 10, ABC, 12, 1); // 6x12字体 OLED_ShowString(0, 24, ABC, 16, 1); // 8x16字体 OLED_ShowString(0, 42, ABC, 24, 1); // 12x24字体 OLED_Refresh(); delay_ms(1000); OLED_Clear(); // 测试4显示数字 static u32 counter 0; OLED_ShowString(0, 0, Count:, 16, 1); OLED_ShowNum(70, 0, counter, 5, 16, 1); counter; OLED_Refresh(); delay_ms(500); OLED_Clear(); } }5.2 常见问题排查如果屏幕没有显示可以按照以下步骤排查电源问题测量VCC和GND之间是否为3.3V检查连接是否牢固SPI通信问题用逻辑分析仪或示波器检查SCK、MOSI波形确认SPI模式CPOL/CPHA设置正确检查时钟频率是否过高建议先降低到1MHz测试初始化序列问题SH1106和SSD1306的初始化命令略有不同确保使用正确的命令检查复位时序RES拉低至少3μs然后拉高缓冲区问题确保OLED_Refresh()被正确调用检查坐标是否超出范围x:0-127, y:0-63字库问题如果汉字显示乱码检查字库数组是否正确包含确认字模取模方式纵向取模字节倒序5.3 性能优化建议减少全屏刷新频繁调用OLED_Refresh()会影响性能。可以只刷新变化的部分区域。使用局部刷新修改OLED_Refresh()函数增加参数指定刷新区域。DMA传输如果SPI支持DMA可以用DMA传输显示数据解放CPU。双缓冲使用两个缓冲区一个用于绘制一个用于显示避免闪烁。移植完成后这个OLED驱动就可以在你的项目中稳定工作了。无论是显示传感器数据、系统状态还是简单的用户界面1.3寸的SH1106 OLED都是一个经济实惠的选择。实际项目中我一般会把它用于调试信息输出比串口打印更直观特别是在没有电脑连接的情况下。