简介一份面向STM32初学者的OLED显示屏学习钟项目源码适配野火指南者开发板与0.96寸OLED屏可直接作为毕业设计、期末大作业或课程设计的高分模板。项目代码内附详细注释从底层驱动到上层显示逻辑均有清晰梳理新手也能快速上手功能上涵盖计时显示、界面切换等完整逻辑系统经过严格调试解压后简单配置即可运行。压缩包共202个文件约6.8MB以C源码34个.c、头文件37个.h及Keil工程文件.uvprojx/.uvoptx为主另含编译中间文件、hex固件和辅助脚本工程结构标准便于模块化移植与二次开发。目前已有187人学习下载对于需要快速完成STM32相关课设或入门OLED驱动的开发者是一份务实且可直接落地的参考资料。1. 这个项目到底解决了什么问题把标题拆开看它其实同时回答了两个问题一块 0.96 寸 OLED 在 STM32 上怎么跑起来以及跑起来之后怎么把它变成一个能看的学习钟。很多做毕业设计或自学的朋友拿到野火指南者开发板第一件事就是点灯第二件事很可能就是点亮那块 0.96 寸的小屏幕。屏幕上能显示文字和数字了自然会想做一个电子钟。但这个过程的坑往往不在代码本身而在 I2C 时序、汉字取模、RTC 时钟源这几个交叉点上。项目源码的意义就在于把这些点串成一条可复现的路径从 GPIO 模拟 I2C 到 SSD1306 驱动再到时间显示和按键调时最后落到野火指南者的具体引脚和库函数版本上。这篇文章沿这条路径把关键决策和踩坑点讲清楚适合手里有野火指南者、准备用 OLED 做课程设计或自己玩法的开发者。如果你是那种连最小系统板都还没点亮过的纯新手建议先把 GPIO 和定时器过一遍再来看会顺畅得多。2. 野火指南者开发环境与 OLED 硬件连接2.1 先从硬件引脚说起野火指南者开发板的 MCU 是 STM32F103VET6属于大容量产品片上资源充沛。0.96 寸 OLED 模块有两种常见接口四针 I2C 和七针 SPI。标题明确写了 0.96 寸 OLED最容易买到的就是四针 I2C 版本因此后面统一按 I2C 讲。四个引脚分别是 VCC、GND、SCL、SDA。野火指南者板载 3.3V 电源VCC 直接接 3.3V 即可不要接 5VOLED 模块上的稳压芯片在 5V 下虽然也能跑但长时间工作发热明显且 I2C 上拉电阻可能被拉高到 5V直接灌进 STM32 引脚会出问题。SCL 和 SDA 我一般复用板上的 PB6 和 PB7正好是 I2C1 的硬件引脚。但实际写代码时多数人会用 GPIO 模拟 I2C原因有二硬件 I2C 在 STM32F1 上用法别扭要处理事件标志软件模拟 I2C 移植到别的板子时只需改两个引脚宏方便得多。所以引脚分配定为 PB6SCLPB7SDA。2.2 Keil5 工程骨架与标准外设库选择在 Keil5 里建工程时目标器件选择 STM32F103VE。固件库我建议用标准外设库StdPeriph_Lib而不是 HAL 库。原因也很直白野火指南者出厂资料里自带标准库版本的工程模板尤其是 GPIO、RCC、EXTI 这些外设的例子直接复制过来就能用省去自己对照参考手册配时钟的功夫。HAL 库虽然代码可读性好但野火指南者的板级支持包和大量例程都是标准库风格混用容易出问题。工程目录建议按下述结构组织Project/ ├── User/ │ ├── main.c │ └── stm32f10x_it.c ├── Hardware/ │ ├── oled.c │ ├── oled.h │ ├── bsp_i2c.c │ └── bsp_i2c.h ├── App/ │ ├── clock.c │ └── clock.h └── Libraries/ ├── CMSIS/ └── STM32F10x_StdPeriph_Driver/main.c 只做初始化和调度Hardware 层封装 OLED 和 I2C 底层的裸机驱动App 层放学习钟的状态逻辑。有人会把字库数组直接塞进 oled.c文件动辄几百行这没问题但如果后续要跑 RTOS 或者放大 Flash 占用率可以把字库单独拆成 font.c 再用条件编译控制后面讲代码组织时还会提。3. 驱动层怎么写SSD1306 初始化与 I2C 时序3.1 从 SSD1306 数据手册抓关键指令0.96 寸 OLED 的驱动芯片绝大多数是 SSD1306分辨率 128x64。它跟 STM32 之间的通信本质是往一系列寄存器里写配置数据和控制数据。I2C 模式下SSD1306 的从机地址是 0x787 位地址 0x3C 左移一位。每次传输要先发控制字节0x00 表示后续字节是命令0x40 表示后续字节是显存数据。初始化序列常被抄来抄去真正需要理解的只有五个指令块功能指令说明关闭显示0xAE初始化期间先关屏避免花屏闪烁设置显示时钟分频0xD5 0x80默认即可振荡器频率和分频系数共同决定刷新率设置多路复用比0xA8 0x3F0x3F 对应 64 行设置显示偏移0xD3 0x00垂直滚动偏移正常显示填 0开启显示0xAF初始化最后一步打开显示提醒初始化序列的长短可以裁剪但不能漏掉 0xAF。有初学者调试时发现屏幕怎么都不亮查到最后是只发了配置指令忘了发开启显示指令。3.2 软件 I2C 的时序实现细节软件模拟 I2C 的本质是操作 GPIO 输出高低电平来模拟起始、停止、应答和数据位。写驱动之前先确认 GPIO 配置为开漏输出。开漏的好处是总线空闲时靠外部上拉电阻拉高任何一个设备拉低总线都不会造成短路。初始化代码里要同时把 I2C 引脚配置为开漏并开启内部上拉作为外部上拉的补充void I2C_GPIO_Config(void) { GPIO_InitTypeDef GPIO_InitStructure; RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOB, ENABLE); GPIO_InitStructure.GPIO_Pin GPIO_Pin_6 | GPIO_Pin_7; GPIO_InitStructure.GPIO_Speed GPIO_Speed_50MHz; GPIO_InitStructure.GPIO_Mode GPIO_Mode_Out_OD; // 开漏输出 GPIO_Init(GPIOB, GPIO_InitStructure); GPIO_SetBits(GPIOB, GPIO_Pin_6 | GPIO_Pin_7); // 初始化为高电平 }SCL 和 SDA 在开漏模式下都能被外部设备拉低这是 I2C 协议能工作的物理基础。之后写起始信号时先拉高 SDA再拉高 SCL然后拉低 SDA最后拉低 SCL四个动作之间有延时一般 10us 就够。3.3 驱动函数划分与最小可用代码OLED 驱动不需要把每个功能都做出来最小集合是初始化、清屏、显示字符串、显示汉字、显示数字。在这个基础上再加坐标定位就能完成一个钟面的绘制。void OLED_Init(void) { // 延时等待 SSD1306 内部上电复位完成 Delay_ms(100); I2C_GPIO_Config(); OLED_WriteCmd(0xAE); // 关闭显示 OLED_WriteCmd(0xD5); OLED_WriteCmd(0x80); OLED_WriteCmd(0xA8); OLED_WriteCmd(0x3F); OLED_WriteCmd(0xD3); OLED_WriteCmd(0x00); OLED_WriteCmd(0x40); // 设置显示起始行 OLED_WriteCmd(0x8D); OLED_WriteCmd(0x14); // 开启电荷泵 OLED_WriteCmd(0x20); OLED_WriteCmd(0x00); // 水平寻址模式 OLED_WriteCmd(0xA1); OLED_WriteCmd(0xC8); // 段重映射、扫描方向 OLED_WriteCmd(0xDA); OLED_WriteCmd(0x12); // 引脚配置 OLED_WriteCmd(0x81); OLED_WriteCmd(0xCF); // 对比度 OLED_WriteCmd(0xAF); // 打开显示 OLED_Clear(); }代码里有两个关键点值得注意0x8D 0x14 是开启电荷泵漏掉这行屏幕大概率不亮0xA1 和 0xC8 决定屏幕的左右镜像和上下翻转如果你的屏幕显示内容倒过来改这两个参数就行不需要动硬件。4. 学习钟功能逻辑与 RTC 时间基准4.1 RTC 还是定时器计数做学习钟首先要回答一个问题时间基准从哪里来。常见方案有两类一是 STM32 内部 RTC二是外部时钟芯片 DS3231 或 DS1302。题目里的学习钟项目用内部 RTC 是合理的选择因为野火指南者板载了 32.768kHz 的晶振和后备电池座STM32F103 的 RTC 外设正好需要这个频率的外部低速时钟。用定时器计时也可以但掉电就丢时间且计算时分秒要自己维护溢出次数远不如 RTC 简单。内部 RTC 的配置有三个步骤开启 PWR 和 BKP 时钟、使能备份寄存器访问、选择 LSE 作为 RTC 时钟源并开启。下面给出最小初始化代码void RTC_Init(void) { RCC_APB1PeriphClockCmd(RCC_APB1Periph_PWR | RCC_APB1Periph_BKP, ENABLE); PWR_BackupAccessCmd(ENABLE); RCC_LSEConfig(RCC_LSE_ON); while (RCC_GetFlagStatus(RCC_FLAG_LSERDY) RESET) {} // 等待 LSE 起振 RCC_RTCCLKConfig(RCC_RTCCLKSource_LSE); RCC_RTCCLKCmd(ENABLE); RTC_WaitForSynchro(); RTC_WaitForLastTask(); if (BKP_ReadBackupRegister(BKP_DR1) ! 0xA5A5) { RTC_SetPrescaler(32767); // LSE 为 32.768kHz预分频后得到 1Hz RTC_SetCounter(0); // 从 0 开始计数 BKP_WriteBackupRegister(BKP_DR1, 0xA5A5); // 标志位防止重复初始化 } }用 RTC_SetPrescaler(32767) 而不是 32768这是很多例程里刻意为之的细节。因为 RTC 每秒计数一次需要预分频值等于时钟频率减一32.768kHz 对应 32767。有些教程写 32768实际会让时钟每天快几分钟。开头提到的不起眼的坑可能就是从这里来的。4.2 时间读取与显示刷新的调度RTC 计数值通过 RTC_GetCounter() 获取得到的是自启动以来的秒数。转换成时分秒需要自己写一个换算函数换算成功后存到全局结构体里typedef struct { uint8_t hour; uint8_t minute; uint8_t second; } Time_TypeDef; Time_TypeDef currentTime; void RTC_GetTime(Time_TypeDef *time) { uint32_t counter RTC_GetCounter(); time-hour (counter % 86400) / 3600; time-minute (counter % 3600) / 60; time-second counter % 60; }显示刷新的调度方式决定了 OLED 会不会闪烁。OLED 刷新率本身不低但每次全屏清空再重写数据会在视觉上造成明显闪烁。正确做法是只在秒值发生变化时才更新秒的显示区域分钟和小时同理。在 main 循环里用一个变量记录上一次读到的秒值while (1) { RTC_GetTime(currentTime); if (currentTime.second ! lastSecond) { OLED_ShowNum(60, 4, currentTime.hour, 2, 16); OLED_ShowNum(84, 4, currentTime.minute, 2, 16); OLED_ShowNum(108, 4, currentTime.second, 2, 16); lastSecond currentTime.second; } }每个数字分别占位刷新没有整屏刷新。OLED 的显存是 1KBSSD1306 内置的 GDDRAM 中每一位对应屏幕上的一个像素改写显存的操作本身不慢但 SPI 或 I2C 传输 1KB 数据在 I2C 400kHz 下需要约 20ms体验很差。局部刷新是学习钟这类项目最重要的优化手段。4.3 用按键完成校时逻辑学习钟必须能调时间否则只能看不能改实用价值大打折扣。在野火指南者上用板载的 KEY_UP 和 KEY_DOWN 配合一个 Enter 键完成调时。校时逻辑常见做法是维护一个状态机typedef enum { MODE_RUN, MODE_SET_HOUR, MODE_SET_MINUTE } ClockMode; ClockMode mode MODE_RUN;按键扫描放在定时器中断里每 10ms 检测一次按键状态用于消抖和长按检测。进入调时状态后小时和分钟字段通过 KEY_UP 加一、KEY_DOWN 减一修改。为避免临界区问题RTC 的初始值在退出设置状态时统一写入不要每按一次键就写一次备份寄存器。我在实际调校时发现OLED_ShowNum(60, 4, ...) 这类函数里如果直接写显存地址会覆盖到旁边的字符区域。因此调时状态下显示参数建议单独设计正常显示时分秒用 16x16 字体调时高亮选中字段用反色或边框标记。反色就是取显示缓冲区数据的补码再写回不用额外造字模。5. 野火指南者板级外设的配合5.1 用 EXTI 实现息屏与唤醒学习钟屏幕常亮会加速 OLED 老化尤其夜间卧室使用场景。这时候用野火指南者的按键接 EXTI 外部中断实现息屏和唤醒就是很实用的功能。野火指南者板载的 KEY_UP 接的是 PA0该引脚复用为 EXTI0 中断源。初始化代码直接参考野火的标准库例程配置完成后在中断回调里翻转一个全局标志位void EXTI0_IRQHandler(void) { if (EXTI_GetITStatus(EXTI_Line0) ! RESET) { screenOn !screenOn; if (screenOn) OLED_DisplayOn(); // 发送 0xAF else OLED_DisplayOff(); // 发送 0xAE EXTI_ClearITPendingBit(EXTI_Line0); } }display off 状态下 OLED 的显存内容不会丢失重新开启后直接恢复显示不需要重新初始化或重绘。这个特性是 SSD1306 本身提供的不用自己维护画面恢复逻辑。5.2 定时器 PWM 调背光OLED 没有背光 LED调不了亮度这跟 LCD 不一样。但 0.96 寸 OLED 的对比度可以通过 SSD1306 的 0x81 指令设置取值范围 0x00 到 0xFF。野火指南者的 TIM3 可以用来产生 PWM 波通过一个电位器或按键调整占空比再映射到对比度数值上。这个做法的本质是用硬件产生一个可变的触发信号但不直接控制 OLED 的供电电压。PWM 配置代码和野火给出的 PWM 例程一致唯一的区别是 PWM 值到对比度值的换算关系。我一般做线性映射uint8_t contrast (uint8_t)(pwmValue * 255 / 999);TIM3 的 ARR 设为 999这样 CCR 的值范围是 0 到 999映射到 0 到 255 时用整数除法注意运算顺序。关于 OLED 亮度贴近现实的评价是对比度调低到 0x10 左右的时候夜间看字不会刺眼但 0x40 以下会有明显的颗粒感。如果追求更丝滑的调光体验可以每 50ms 读一次 CCR做个简单的低通滤波再写 SSD1306避免 PWM 值抖动导致屏幕闪烁。5.3 用后备寄存器保存闹钟设定学习钟往往要支持闹钟功能。闹钟设置的本质是存储一个目标时间然后每秒比较一次。STM32 的备份寄存器 BKP_DR1 到 BKP_DR10 在 LSE 供电正常时会持续保存数据掉电不丢失。因此闹钟的小时和分钟可以存进备份寄存器初始化时先读备份寄存器如果值合法就恢复不合法就用默认值。这个方法比外挂 EEPROM 简单也不需要额外芯片。void Alarm_Save(uint8_t hour, uint8_t minute) { uint16_t packed (hour 8) | minute; BKP_WriteBackupRegister(BKP_DR2, packed); }6. 源码组织、移植与调试技巧6.1 把 HAL 库例程移植到标准库工程的三个改动搜索热词里出现了好几次 HAL 库点亮 OLED 的代码网上也有很多文章基于 STM32CubeMX 生成工程。如果把这样的代码移植到野火指南者的标准库工程里三个改动绕不过去HAL_Delay 换成自己的延时函数、HAL_GPIO_WritePin 换成 GPIO_SetBits/GPIO_ResetBits、处理时钟树差异。野火指南者的外部晶振是 8MHzSYSCLK 配到 72MHz这与 CubeMX 默认的 HSE_VALUE 配置一致但有些开发板用 25MHz 晶振直接用上述代码会导致系统时钟不对OLED 刷新慢一截甚至卡死。延时函数是移植最容易出问题的地方。标准库工程里用 SysTick 实现毫秒延时比较简单CubeMX 生成的 HAL_Delay 依赖 HAL_GetTick混用时会出现延时时间加倍或完全不延时。最简单的办法是在 oled.c 里独立维护一个基于 SysTick 的等待函数不依赖任何库void Delay_us(uint32_t us) { uint32_t ticks us * (SystemCoreClock / 1000000); uint32_t start SysTick-VAL; while ((start - SysTick-VAL) ticks) {} }6.2 I2C 通信不稳定时的排查清单OLED 花屏、显示一半正常一半乱码或者完全不亮这类问题在野火指南者的使用中频率不低。排查顺序建议固定下来检查 VCC 和 GND 是否接反接反的瞬间屏幕背面驱动芯片会烫手且大概率已经烧毁用逻辑分析仪抓 SCL 和 SDA 波形确认起始条件、停止条件是否完整确认从机地址是 0x78 而不是 0x7AOLED 模块背面的电阻配置决定地址检查 GPIO 是否配置为开漏输出推挽输出时 SDA 拉低能力太强从机应答信号读不到用示波器看通信速率标准库的 Delay_us 在 72MHz 下如果延时参数写错I2C 速率可能跑到 1MHz 以上SSD1306 会偶发无响应清屏后屏幕有一两个像素点残留多半是显存没有完全清零。OLED_Clear() 要遍历 8 页page和 128 列总共写 128*8 字节。有些精简版代码只清了前几页就会在屏幕底部留下上一帧的残影。建议清屏后用全 0 和全 1 交替测试void OLED_Test(void) { OLED_Clear(); for (uint8_t i 0; i 8; i) OLED_FillPage(i, 0xFF); Delay_ms(500); OLED_Clear(); }6.3 字模与显示函数的坑0.96 寸 OLED 显示汉字要先取模。取模软件选 C51 格式或 A51 格式都行关键是注意字节是列行式还是行列式。SSD1306 的显存排列是按页组织的每页 8 个像素高页内从上到下对应 bit0 到 bit7。取模时选择纵向取模、逐行式代码里把字模按列写入显存就能正常显示。网上常见的问题是取模方向不对显示出来字是旋转 90 度的这种情况不用改代码回取模软件重新选方向即可。16 号字体每个字符占 16 列 2 页写显示函数时页面偏移计算经常出错。建议封装一层void OLED_ShowChar(uint8_t x, uint8_t y, uint8_t ch) { // y 的取值是 0、2、4、6代表从上到下四个页对 // 实际数据写入位置由 SSD1306 的页地址指令决定 }最后的建议是拿到源码不要急着下载到板子里跑。先读 oled.h 里的函数声明理清初始化流程再用 OLED_Test 验证硬件最后才去调时钟逻辑。这样出问题时你能明确知道是驱动层坏了还是业务层坏了。可以留一个调试用的串口打印函数把每次校时的前后 RTC 值打出来时间不准的问题往往一眼就能定位。本文还有配套的精品资源点击获取