STM32F103实战：0.96寸OLED屏显示动态二维码（附完整代码）

STM32F103实战0.96寸OLED屏显示动态二维码附完整代码最近在做一个智能门禁的原型需要在小巧的嵌入式设备上显示动态变化的二维码比如临时的访客码。手头正好有最常见的STM32F103C8T6“蓝板”和几片0.96寸的OLED屏这个组合成本低廉、资源适中是很多创客和产品原型开发的首选。但要把动态生成的二维码流畅地显示在这块小小的OLED上可不是简单移植个库就能搞定的事你得和有限的RAM、独特的驱动方式以及实时性要求“斗智斗勇”。市面上很多教程都基于带帧缓冲的LCD屏对于OLED这种直接操作显存、且尺寸极小的屏幕直接套用往往会遇到内存溢出、显示错乱或者刷新率过低的问题。这篇文章我就把自己从硬件连接、驱动适配、内存优化到动态刷新的完整踩坑经验和解决方案分享出来。你会发现即使是在这颗只有20KB RAM的Cortex-M3核心上也能优雅地实现二维码的动态更新。1. 硬件选型与工程环境搭建选择STM32F103C8T6和0.96寸OLEDSSD1306驱动这个组合本质上是在成本、功耗和功能之间寻找一个精妙的平衡点。STM32F103C8T6拥有64KB Flash和20KB RAM主频72MHz对于生成中等复杂度的二维码比如Version 2 25x25模块并驱动OLED来说性能是足够的。而0.96寸OLED通常为128x64分辨率功耗极低无需背光在显示静止图像时几乎不耗电非常适合电池供电的物联网设备。核心硬件清单MCU: STM32F103C8T6 最小系统板即“蓝板”或“黑金板”。显示屏: 0.96寸OLED驱动芯片为SSD1306通信接口为I2C4线或5线。本文以最普遍的I2C接口为例。连接线: 杜邦线若干。电源: 5V USB供电或3.3V稳压电源。软件与工具链准备我强烈推荐使用STM32CubeIDE作为开发环境它集成了STM32CubeMX配置工具和Eclipse IDE能极大简化外设初始化和工程管理。当然如果你习惯Keil MDK或IAR步骤也大同小异。创建STM32CubeMX工程选择正确的芯片型号STM32F103C8T6。配置系统核心SYS: Debug 选择 Serial Wire如果要用ST-Link调试。RCC: HSE 选择 Crystal/Ceramic Resonator如果板载了8MHz晶振。配置I2C1用于OLED因为OLED的SSD1306驱动通常支持标准I2C。在Pinout视图找到I2C1 将模式设置为I2C。默认引脚通常是PB6 (I2C1_SCL) 和 PB7 (I2C1_SDA)。确保你的硬件连接与此一致。在Configuration标签页的I2C1参数设置中保持默认的100kHz速率即可SSD1306完全兼容。配置一个定时器用于动态刷新可选但推荐我们可以用定时器中断来周期性地更新二维码内容实现“动态”效果。例如使用TIM2。将TIM2模式设置为Internal Clock。在Parameter Settings中配置预分频器PSC和自动重载值ARR使得定时器中断频率在1Hz到10Hz之间根据你需要的二维码更新速度调整。例如系统时钟72MHzPSC7199ARR9999则中断频率为 72MHz / (7200 * 10000) 1Hz。开启TIM2的全局中断NVIC Settings。生成代码点击GENERATE CODE生成基于HAL库的初始化代码。注意OLED屏的I2C地址通常是0x78写或0x7A读但具体需查看手册。常见的模块地址可能是0x78或0x7A在代码中需要正确定义。至此一个基础的、包含I2C和定时器外设驱动的工程框架就准备好了。接下来我们需要解决两个核心问题让OLED亮起来以及让二维码库在MCU上跑起来。2. SSD1306 OLED驱动适配与优化网络上能找到的SSD1306驱动代码很多但直接拿来用在动态二维码显示上可能会遇到效率瓶颈。我们需要一个经过优化、支持局部刷新和直接位图操作的驱动。首先建立驱动文件。在工程中创建ssd1306.c和ssd1306.h。核心是实现以下几个函数// ssd1306.h 中的关键声明 #define OLED_I2C_ADDR 0x78 // 根据你的模块修改 #define OLED_WIDTH 128 #define OLED_HEIGHT 64 void SSD1306_Init(void); void SSD1306_Clear(void); void SSD1306_UpdateScreen(void); // 将显存数据全部发送到OLED void SSD1306_DrawPixel(uint16_t x, uint16_t y, uint8_t color); void SSD1306_DrawBitmap(const uint8_t *bitmap, uint16_t x, uint16_t y, uint16_t w, uint16_t h);SSD1306_DrawBitmap函数是我们显示二维码的关键它需要将二维码库生成的位图数据高效地“画”到OLED的显存中。其次设计显存管理。SSD1306的显存对应着屏幕的像素通常我们会在MCU的RAM中开辟一个缓冲区buffer来镜像这块显存。对于128x64的分辨率如果每个像素用1位表示1为亮0为灭那么需要的缓冲区大小是(128 * 64) / 8 1024字节。这在STM32F103C8T6的20KB RAM中是完全可接受的。// 在ssd1306.c中定义显存缓冲区 static uint8_t SSD1306_Buffer[1024]; // 128 * 64 / 8 void SSD1306_DrawBitmap(const uint8_t *bitmap, uint16_t x, uint16_t y, uint16_t w, uint16_t h) { // 将位图数据合并到缓冲区 for (uint16_t j 0; j h; j) { for (uint16_t i 0; i w; i) { // 计算位图中的像素值假设位图是1bpp逐行排列 uint16_t byteIndex (j * (w / 8)) (i / 8); uint8_t bitMask 1 (7 - (i % 8)); uint8_t pixelValue (bitmap[byteIndex] bitMask) ? 1 : 0; // 调用DrawPixel将像素画到缓冲区 SSD1306_DrawPixel(x i, y j, pixelValue); } } }但逐像素操作的DrawPixel在刷新整个二维码时效率较低。一个重要的优化是直接操作缓冲区内存。二维码位图通常是按行排列的字节数组我们可以直接计算目标位置在缓冲区中的对应字节和位进行批量操作这能显著提升渲染速度。最后实现高效的屏幕更新。SSD1306_UpdateScreen()函数负责将整个1024字节的缓冲区通过I2C发送到OLED。为了支持动态二维码的“局部更新”虽然我们经常全屏更新可以设计一个“脏矩形”标记机制但鉴于OLED尺寸小全屏刷新约1KB数据在I2C 100kHz下耗时也在百毫秒级对于1-2Hz的动态更新频率是可接受的。如果追求更高刷新率可以考虑提高I2C速率SSD1306支持400kHz Fast Mode或使用SPI接口的OLED模块。驱动调通后你应该能通过简单的测试程序在OLED上画出点、线和图形。这是显示二维码的基石。3. QRCode生成库的移植与内存优化生成二维码我们需要一个轻量级的C语言库。kazimierczak-robert/STMQRCode这个仓库是专门为STM32适配的它是一个不错的选择。但直接将其加入工程可能会遇到编译错误和内存紧张的问题。第一步提取必要的文件。我们不需要整个仓库核心文件通常只有几个qr_encode.c/qr_encode.h: 二维码编码的核心实现。qrcode.c/qrcode.h: 定义二维码数据结构和相关函数。bitbuffer.c/bitbuffer.h: 位缓冲区操作可能被包含。将这几个文件添加到你的工程中。使用STM32CubeIDE只需将.c文件拖入Src文件夹.h文件拖入Inc文件夹并在项目属性中确保包含路径正确。第二步解决编译错误。最常见的错误是缺少标准库类型定义。在qr_encode.h的开头你可能需要添加针对ARM编译器的类型定义// 在qr_encode.h文件顶部添加 #ifdef __GNUC__ #include stdint.h #else // 针对ARM编译器或其他环境的类型定义 typedef unsigned char uint8_t; typedef unsigned short uint16_t; typedef unsigned int uint32_t; #endif此外确保工程中开启了C99标准在Project Properties - C/C Build - Settings - Tool Settings - MCU GCC Compiler - Miscellaneous 中勾选-stdgnu99。第三步也是最具挑战性的——内存优化。QRCode库在编码过程中会分配内存来存储模块数据、数据码字等。对于Version 225x25的二维码其缓冲区大小可能超过1KB。在全局堆上动态分配malloc在资源紧张的嵌入式系统中风险很高容易造成碎片或分配失败。解决方案是使用静态内存池。修改库的源码将动态分配改为使用我们预先定义好的静态数组。找到内存分配点在qr_encode.c中查找malloc或calloc调用。通常有一个函数负责创建二维码数据缓冲区。替换为静态数组在文件顶部定义一个足够大的静态数组作为内存池。// 在qr_encode.c中 #define QR_MEMORY_POOL_SIZE 2048 // 根据Version和纠错等级调整略大于需求 static uint8_t qr_memory_pool[QR_MEMORY_POOL_SIZE]; static size_t qr_mem_offset 0; // 替换malloc的函数 static void* qr_malloc(size_t size) { if (qr_mem_offset size QR_MEMORY_POOL_SIZE) { return NULL; // 内存不足 } void* ptr qr_memory_pool[qr_mem_offset]; qr_mem_offset size; return ptr; } // 需要一个简单的“free”来重置偏移量用于每次生成前 static void qr_mem_reset(void) { qr_mem_offset 0; }修改库的分配调用将原来的malloc(size)替换为qr_malloc(size)。同时在每次调用二维码生成函数之前调用qr_mem_reset()来重置内存池偏移模拟“释放”上一次占用的内存。注意这种方法不支持同时存在多个二维码对象但对于顺序生成、单次显示的场景完全够用。通过以上步骤我们确保了二维码生成过程在可控的、无碎片的静态内存中完成极大增强了系统的可靠性。4. 动态二维码的集成与显示实战现在我们将驱动和二维码库结合起来实现动态内容生成与显示。所谓“动态”意味着二维码承载的信息如字符串可以随时间或外部事件改变。首先设计一个二维码显示模块。创建qrcode_display.c/h。// qrcode_display.h typedef struct { char content[64]; // 存储要编码的字符串例如https://example.com/room/1234 uint8_t version; // 二维码版本0表示自动选择最小版本 uint8_t ecc_level; // 纠错等级0-3对应L, M, Q, H } QRCode_Info_t; void QRCode_GenerateAndDisplay(QRCode_Info_t *qrinfo, uint8_t x, uint8_t y, uint8_t scale);scale参数用于放大显示。因为OLED像素密度高原生的25x25二维码可能太小不易扫描我们需要将其放大。一种简单有效的方法是像素倍增。其次实现生成与显示函数。在qrcode_display.c中void QRCode_GenerateAndDisplay(QRCode_Info_t *qrinfo, uint8_t x, uint8_t y, uint8_t scale) { // 1. 重置二维码内存池 qr_mem_reset(); // 2. 调用二维码库生成位图数据 // 假设库提供的接口函数为uint8_t* QR_EncodeData(...) uint8_t *qrcodeBits QR_EncodeData(qrinfo-content, qrinfo-version, qrinfo-ecc_level); if (qrcodeBits NULL) { // 编码失败处理 return; } // 3. 获取二维码尺寸库函数应提供 uint8_t qr_size QR_GetSize(); // 例如25 // 4. 将二维码位图绘制到OLED缓冲区并进行放大 // 清空OLED上要显示的区域可选动态更新时可能需要 // SSD1306_ClearArea(x, y, qr_size*scale, qr_size*scale); for (uint8_t row 0; row qr_size; row) { for (uint8_t col 0; col qr_size; col) { // 获取原始二维码模块值1或0 uint8_t module QR_GetModule(qrcodeBits, row, col); // 需要实现此辅助函数 // 根据scale放大绘制 for (uint8_t sy 0; sy scale; sy) { for (uint8_t sx 0; sx scale; sx) { SSD1306_DrawPixel(x col*scale sx, y row*scale sy, module); } } } } // 5. 更新OLED屏幕 SSD1306_UpdateScreen(); }最后实现动态逻辑。在主循环或定时器中断服务函数中你可以定期更新QRCode_Info_t结构中的content字段然后调用QRCode_GenerateAndDisplay。例如在定时器中断中注意中断服务函数中不宜进行耗时操作可以设置标志位在主循环中处理// 在stm32f1xx_it.c的TIM2中断处理函数中 void TIM2_IRQHandler(void) { if (__HAL_TIM_GET_FLAG(htim2, TIM_FLAG_UPDATE) ! RESET) { __HAL_TIM_CLEAR_FLAG(htim2, TIM_FLAG_UPDATE); qr_update_flag 1; // 设置一个全局标志 } } // 在主循环中 while (1) { if (qr_update_flag) { qr_update_flag 0; // 生成新的内容例如递增一个计数器 static uint32_t counter 0; counter; snprintf(qr_info.content, sizeof(qr_info.content), ID:%08lu, counter); // 显示二维码 QRCode_GenerateAndDisplay(qr_info, 20, 10, 2); // 从(20,10)开始放大2倍显示 } // ... 其他任务 }性能与优化点生成时间在72MHz的STM32F103上生成一个Version 2L级纠错的二维码大约需要几十到一百毫秒。如果动态更新频率要求高如5Hz需评估性能是否满足。显示时间I2C传输1024字节的显存数据约需100ms。可以考虑使用DMA传输来释放CPU或者探索SSD1306的“页地址模式”进行局部更新以减少数据传输量。内容长度二维码信息容量有限。对于较长的URL可以使用URL短链接服务或者选择更高的二维码版本如Version 4但这会增加生成复杂度和内存占用。通过以上四个部分的拆解我们从硬件选型开始一步步构建了一个能在STM32F103和0.96寸OLED上稳定、高效显示动态二维码的完整系统。这套方案代码结构清晰内存使用可控并且为实际产品化提供了良好的基础。在实际项目中你可能还需要考虑添加看门狗、异常恢复、低功耗模式等但核心的显示与生成逻辑已然打通。