1. 项目概述为什么要在APM32F411上折腾U8g2最近在做一个需要小型显示界面的嵌入式项目主控选用了极海半导体的APM32F411。这颗MCU性价比不错Cortex-M4内核主频100MHz内存和Flash也够用最关键的是它的外设资源对于我的项目来说刚刚好。显示部分我手头有几块常见的0.96寸和1.3寸的OLED屏驱动芯片是SSD1306。这种屏在嵌入式圈子里太常见了便宜、省电、显示效果也清晰。一开始我打算像往常一样找个现成的SSD1306驱动库自己写几个画点画线的函数凑合用。但这次的项目界面稍微复杂点有菜单、有图标、还有动态数据刷新自己从头造轮子太费时间。这时就想到了U8g2这个图形库。它在Arduino社区大名鼎鼎支持几乎你能想到的所有单色显示器字体、图标资源丰富API也成熟稳定。但问题来了U8g2在Arduino生态里是“开箱即用”的而我要把它移植到基于标准库或HAL库的APM32F411工程里这中间有不少坑要填。这个移植过程本质上是在MCU的硬件抽象层HAL或标准外设库与U8g2这个高度硬件无关的图形库之间搭建一座“通信桥梁”。你需要告诉U8g2“嘿这是我的MCU这是我们的I2C或者SPI引脚这是我们的延时函数现在请你开始工作吧。” 这篇指南就是记录我如何一步步搭建这座桥并解决过程中遇到的各种问题的完整过程。无论你是刚接触APM32系列还是对U8g2移植感到困惑希望这篇详尽的记录能帮你省下大量摸索的时间。2. 核心思路与方案选型I2C还是SPI在动手之前首先要确定通信方式。U8g2支持并行、I2C、SPI等多种接口对于OLED这种小屏I2C和SPI是最常用的。我的两块屏都支持这两种方式这就涉及到一个选择。I2C方案只需要两根信号线SCL和SDA再加电源和地总共四根线就能驱动。优点是接线极其简单节省IO口。缺点是通信速度相对较慢尤其是在刷新整屏或复杂图形时可能会感觉到肉眼可见的延迟。U8g2的I2C驱动是软件模拟时序对MCU的CPU有一定开销。SPI方案需要四根线SCLK, MOSI, CS, DC有时还需要一根RESET线。优点是通信速度飞快刷屏流畅CPU开销小因为可以利用MCU的硬件SPI外设。缺点是占用IO口稍多。考虑到我的APM32F411的IO口资源还算充裕且项目对界面流畅度有一定要求菜单切换、数据滚动不希望有卡顿我最终选择了硬件SPI方案。另一个重要原因是U8g2库对硬件SPI的支持通常更稳定性能也更有保障。如果你追求极简布线且对刷新率不敏感I2C也是完全可行的移植的底层函数会有所不同但整体思路一致。确定了SPI方案后接下来就是具体的移植步骤。整个过程可以分解为三个核心部分获取并集成U8g2库源码、实现底层硬件驱动函数、配置与初始化并编写测试程序。3. 环境准备与U8g2库集成3.1 开发环境与工程创建我使用的是Keil MDK作为开发环境因为极海官方提供了完善的MDK支持包Device Family Pack。首先你需要从极海官网下载APM32F4xx系列的SDK里面包含了标准外设库SPL或HAL库、启动文件和各种例程。我习惯使用标准外设库感觉更直观一些。新建工程在Keil中创建一个基于APM32F411CEU6的工程选择好对应的启动文件startup_apm32f4xx.s。添加库文件将SDK中Libraries/APM32F4xx_StdPeriphDriver目录下的inc和src文件夹添加到工程并包含头文件路径。同时将Libraries/CMSIS下的相关文件也添加进来。配置系统时钟这是一个关键步骤。APM32F411最高可运行在100MHz。你需要根据你的外部晶振通常是8MHz或25MHz正确配置PLL将系统时钟设置为100MHz。这一步可以参考SDK中的系统时钟配置例程。一个稳定且正确的系统时钟是后续所有外设包括SPI正常工作的基础。3.2 获取与集成U8g2库U8g2的源码托管在GitHub上。我们不需要整个仓库只需要核心文件。下载源码访问U8g2的GitHub仓库找到csrc文件夹。这个文件夹里包含了所有C语言源码。我们主要需要其中的几个文件u8g2.h- 主头文件。u8x8.h- 底层抽象层头文件。u8g2.c- 图形功能实现这个文件很大包含了所有显示驱动。u8x8.c- 底层硬件抽象层实现。与SPI和GPIO相关的u8x8_d_ssd1306_*.c文件以及u8x8_cad.c,u8x8_byte.c,u8x8_gpio.c等通信基础文件。精简文件为了工程简洁我建议只添加必要的文件。对于SSD1306 128x64的SPI驱动你需要u8g2.c(必须)u8x8.c(必须)u8x8_byte.c(必须)u8x8_cad.c(必须)u8x8_gpio.c(必须)u8x8_d_ssd1306_128x64_noname.c(根据你的屏幕分辨率选择也可能是_128x32等)添加到工程在Keil工程中新建一个U8g2分组将上述.c文件添加进去。同时在工程设置中将包含u8g2.h和u8x8.h的目录路径添加到Include Paths中。注意直接添加整个csrc文件夹可能会编译通过但会导致工程体积庞大编译缓慢。按需添加是更好的实践。另外u8g2.c默认包含了所有字体编译后代码体积会非常大。我们可以在u8g2.h中注释掉不需要的字体定义来瘦身这一步可以放在移植成功后再做优化。4. 底层硬件驱动函数实现这是移植的核心环节。U8g2通过一个名为u8x8_t的结构体与硬件交互我们需要填充这个结构体中的几个关键函数指针特别是字节传输(byte_cb)和GPIO控制(gpio_and_delay_cb)。4.1 实现GPIO与延时回调函数 (gpio_and_delay_cb)U8g2需要控制几个关键引脚并需要微秒级延时。我们需要在u8x8_gpio.c提供的框架下实现针对APM32F411的具体控制。首先规划硬件连接以4线SPI为例SCLK(SPI时钟) - PA5 (APM32F411的SPI1_SCK)MOSI(SPI数据输出) - PA7 (APM32F411的SPI1_MOSI)CS(片选低有效) - 自定义如PA4DC(数据/命令选择高数据低命令) - 自定义如PA3RES(复位低有效复位通常可接高电平或MCU控制) - 自定义如PA2在工程中新建一个文件如u8g2_apm32f4_hal.c并实现以下函数#include “apm32f4xx_gpio.h” #include “apm32f4xx_spi.h” #include “apm32f4xx_rcm.h” #include “u8x8.h” // 引脚定义 #define OLED_SPI SPI1 #define OLED_CS_PORT GPIOA #define OLED_CS_PIN GPIO_PIN_4 #define OLED_DC_PORT GPIOA #define OLED_DC_PIN GPIO_PIN_3 #define OLED_RES_PORT GPIOA #define OLED_RES_PIN GPIO_PIN_2 // 微秒延时函数基于SysTick或简单循环需根据100MHz主频校准 void Delay_us(uint32_t us) { // 这里是一个粗略的循环延时实际项目中建议使用SysTick定时器实现更精确的延时 volatile uint32_t count; for (count 0; count us * (SystemCoreClock / 1000000) / 10; count) { __NOP(); } } uint8_t u8x8_gpio_and_delay_apm32(U8X8_UNUSED u8x8_t *u8x8, U8X8_UNUSED uint8_t msg, U8X8_UNUSED uint8_t arg_int, U8X8_UNUSED void *arg_ptr) { switch(msg) { case U8X8_MSG_GPIO_AND_DELAY_INIT: // 初始化阶段可以在这里初始化GPIO但建议在main函数中统一初始化 break; case U8X8_MSG_DELAY_MILLI: // 毫秒延时调用HAL_Delay或自己的延时函数 Delay_ms(arg_int); break; case U8X8_MSG_DELAY_10MICRO: // 10微秒延时 Delay_us(arg_int * 10); break; case U8X8_MSG_DELAY_100NANO: // 100纳秒延时对于SPI通常不需要特殊处理 break; case U8X8_MSG_GPIO_CS: // 控制CS引脚 GPIO_WriteBitValue(OLED_CS_PORT, OLED_CS_PIN, (arg_int ? BIT_SET : BIT_RESET)); break; case U8X8_MSG_GPIO_DC: // 控制DC引脚 GPIO_WriteBitValue(OLED_DC_PORT, OLED_DC_PIN, (arg_int ? BIT_SET : BIT_RESET)); break; case U8X8_MSG_GPIO_RESET: // 控制RESET引脚 GPIO_WriteBitValue(OLED_RES_PORT, OLED_RES_PIN, (arg_int ? BIT_SET : BIT_RESET)); break; default: break; } return 1; }实操心得Delay_us函数的实现需要小心。如果使用简单的循环延时其精确度严重依赖于编译器优化和CPU频率。在APM32F411上最好使用SysTick定时器来实现高精度微秒延时。这里为了简化示例用了循环在实际项目移植时建议你实现一个基于SysTick的HAL_Delay_us函数这样更可靠。4.2 实现SPI字节传输回调函数 (byte_cb)U8g2通过这个函数来发送一个字节的数据或命令。我们需要在这个函数里调用APM32的硬件SPI发送函数。uint8_t u8x8_byte_apm32_hw_spi(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr) { switch(msg) { case U8X8_MSG_BYTE_SEND: { // 发送多个字节 uint8_t *data (uint8_t *)arg_ptr; while(arg_int 0) { // 等待发送缓冲区空 while(SPI_I2S_ReadStatusFlag(OLED_SPI, SPI_I2S_STATUS_TXBE) RESET); SPI_I2S_TxData(OLED_SPI, *data); data; arg_int--; } break; } case U8X8_MSG_BYTE_INIT: // 初始化可以什么都不做因为SPI已在main中初始化 break; case U8X8_MSG_BYTE_SET_DC: // 设置DC引脚电平这个实际上由gpio_and_delay_cb处理 // 这里可以调用u8x8_gpio_call但我们已经在gpio回调里处理了 u8x8_gpio_SetDC(u8x8, arg_int); break; case U8X8_MSG_BYTE_START_TRANSFER: // 开始传输片选拉低 u8x8_gpio_SetCS(u8x8, u8x8-display_info-chip_enable_level); // 对于SPI可能需要一个小延时 u8x8_gpio_Delay(u8x8, U8X8_MSG_DELAY_NANO, u8x8-display_info-post_chip_enable_wait_ns); break; case U8X8_MSG_BYTE_END_TRANSFER: // 结束传输片选拉高 u8x8_gpio_Delay(u8x8, U8X8_MSG_DELAY_NANO, u8x8-display_info-pre_chip_disable_wait_ns); u8x8_gpio_SetCS(u8x8, u8x8-display_info-chip_disable_level); break; default: return 0; } return 1; }注意事项在U8X8_MSG_BYTE_SEND中我使用了查询方式发送数据。你也可以使用中断或DMA但对于OLED这种低速设备查询方式最简单可靠。确保在初始化SPI时将其配置为仅主机发送模式数据格式为8位并设置合适的波特率预分频例如SPI_BAUDRATE_DIV_8或DIV_16。太快可能导致屏幕无法识别。4.3 硬件初始化函数在main函数中或在专门的硬件初始化函数里我们需要初始化用到的GPIO和SPI外设。void OLED_Hardware_Init(void) { GPIO_Config_T gpioConfig; SPI_Config_T spiConfig; // 1. 开启时钟 RCM_EnableAHB1PeriphClock(RCM_AHB1_PERIPH_GPIOA); RCM_EnableAPB2PeriphClock(RCM_APB2_PERIPH_SPI1); // 2. 初始化CS, DC, RESET引脚为推挽输出 gpioConfig.pin OLED_CS_PIN | OLED_DC_PIN | OLED_RES_PIN; gpioConfig.mode GPIO_MODE_OUT; gpioConfig.speed GPIO_SPEED_50MHz; gpioConfig.otype GPIO_OTYPE_PP; gpioConfig.pupd GPIO_PUPD_NO; GPIO_Config(OLED_CS_PORT, gpioConfig); // 默认拉高CS和RESET拉低DC命令模式 GPIO_SetBits(OLED_CS_PORT, OLED_CS_PIN | OLED_RES_PIN); GPIO_ResetBits(OLED_DC_PORT, OLED_DC_PIN); // 3. 初始化SPI引脚 (PA5-SCK, PA7-MOSI) gpioConfig.pin GPIO_PIN_5 | GPIO_PIN_7; gpioConfig.mode GPIO_MODE_AF; gpioConfig.otype GPIO_OTYPE_PP; gpioConfig.pupd GPIO_PUPD_NO; gpioConfig.altFun GPIO_AF5_SPI1; GPIO_Config(GPIOA, gpioConfig); // 4. 配置SPI1为主机仅发送 SPI_Reset(OLED_SPI); spiConfig.mode SPI_MODE_MASTER; spiConfig.direction SPI_DIRECTION_1LINE_TX; // 单线发送 spiConfig.dataSize SPI_DATA_SIZE_8BIT; spiConfig.firstBit SPI_FIRSTBIT_MSB; // SSD1306要求MSB在先 spiConfig.baudRateDiv SPI_BAUDRATE_DIV_8; // 100MHz / 8 12.5MHz spiConfig.clockPolarity SPI_CLOCK_POLARITY_LOW; // 时钟极性根据屏幕规格书调整 spiConfig.clockPhase SPI_CLOCK_PHASE_1EDGE; // 时钟相位根据屏幕规格书调整 spiConfig.nss SPI_NSS_SOFT; // 软件控制NSS即我们的CS引脚 SPI_Config(OLED_SPI, spiConfig); SPI_Enable(OLED_SPI); }5. U8g2初始化与显示测试硬件底层驱动完成后就可以在main函数中初始化U8g2并开始绘图了。5.1 初始化U8g2对象#include “u8g2.h” #include “u8g2_apm32f4_hal.h” // 包含我们刚才写的驱动文件 u8g2_t u8g2; // 定义一个全局的U8g2对象 void U8g2_Init(void) { // 1. 初始化U8g2结构体 u8g2_Setup_ssd1306_128x64_noname_f(u8g2, // u8g2对象 U8G2_R0, // 旋转方向 u8x8_byte_apm32_hw_spi, // 我们的字节发送函数 u8x8_gpio_and_delay_apm32); // 我们的GPIO和延时函数 // 2. 初始化显示 u8g2_InitDisplay(u8g2); // 3. 唤醒显示从睡眠模式 u8g2_SetPowerSave(u8g2, 0); // 4. 清屏 u8g2_ClearBuffer(u8g2); }5.2 编写一个简单的测试程序在main函数的初始化部分依次调用系统时钟配置、硬件初始化、U8g2初始化。int main(void) { // 系统初始化时钟、中断等 SystemInit(); // 初始化硬件SPI和GPIO OLED_Hardware_Init(); // 初始化U8g2库 U8g2_Init(); while(1) { // 开始绘制一帧 u8g2_ClearBuffer(u8g2); // 设置字体使用内置的6x10像素字体 u8g2_SetFont(u8g2, u8g2_font_6x10_tf); // 绘制字符串 u8g2_DrawStr(u8g2, 0, 15, “Hello APM32F411!”); u8g2_DrawStr(u8g2, 0, 30, “U8g2移植成功”); // 画一个框 u8g2_DrawFrame(u8g2, 5, 40, 118, 20); // 画一条对角线 u8g2_DrawLine(u8g2, 10, 45, 115, 55); // 将缓冲区内容发送到屏幕显示 u8g2_SendBuffer(u8g2); // 延时一段时间 Delay_ms(2000); // 可以再画点别的比如一个进度条动画 static uint8_t pos 0; u8g2_ClearBuffer(u8g2); u8g2_DrawBox(u8g2, 10, 20, pos, 10); // 画一个实心矩形作为进度条 u8g2_SendBuffer(u8g2); pos (pos 5) % 110; Delay_ms(100); } }如果一切顺利上电后你应该能在OLED屏幕上看到“Hello APM32F411!”的文字、一个方框、一条斜线以及一个会移动的进度条。这标志着U8g2图形库已经在你的APM32F411上成功运行起来了。6. 深度优化与高级功能配置基础显示成功后我们可以进行一些优化让显示效果更好代码更高效。6.1 字体管理与代码瘦身默认情况下u8g2.c包含了巨量的字体编译出来的代码体积可能超过100KB。这对于APM32F411有限的Flash通常256KB或512KB来说是个负担。优化方法在u8g2.h文件中找到字体定义的部分通常是大量以U8G2_FONT_SECTION开头的宏注释掉所有你确定用不到的字体。或者更简单的方法是在Keil的工程选项里只包含你需要的特定字体文件。U8g2库的font文件夹下每个字体都是独立的.c文件。例如如果你只需要u8g2_font_6x10_tf你可以在工程中移除庞大的u8g2.c转而添加u8g2_font_6x10_tf.c和u8g2_d_setup.c等核心文件。这是最有效的瘦身方式能将图形库部分压缩到20KB以下。6.2 使用硬件SPI的DMA传输对于需要高速刷屏或复杂动画的应用查询方式发送数据会占用大量CPU时间。此时可以启用SPI的DMA传输。初始化DMA配置一个DMA通道用于SPI_TX。修改字节发送函数在U8X8_MSG_BYTE_SEND消息中不再使用循环查询发送而是启动DMA传输并等待DMA传输完成标志。注意同步确保在U8X8_MSG_BYTE_END_TRANSFER之前本次DMA传输已经完成。可以使用DMA_GetFlagStatus来检查。使用DMA能极大解放CPU但代码复杂度会增加。对于大多数OLED菜单应用查询方式已经足够流畅。6.3 利用U8g2的缓冲区与局部刷新U8g2有两种绘图模式全缓冲模式(u8g2_Setup_..._f)我们上面用的就是这种。它在MCU内存中开辟一个完整的屏幕缓冲区对于128x64就是1024字节所有绘图操作都在这个缓冲区进行最后调用u8g2_SendBuffer一次性发送到屏幕。优点是编程简单支持所有图形函数。缺点是占用RAM多。页面缓冲模式(u8g2_Setup_..._1,_2,_...)缓冲区只存储一页通常是8行的数据。绘图时你需要使用u8g2_FirstPage和u8g2_NextPage函数来循环更新每一页。优点是极其节省RAM可能只需128字节。缺点是需要重构你的绘图逻辑所有绘图代码必须放在一个循环里。如果你的项目RAM紧张APM32F411的SRAM通常128KB且显示内容可以按页更新页面缓冲模式是更好的选择。初始化函数需要改为u8g2_Setup_ssd1306_128x64_noname_11表示1页缓冲。绘图循环会变成这样u8g2_FirstPage(u8g2); do { // 所有的u8g2_DrawXXX函数调用都放在这里 u8g2_SetFont(u8g2, u8g2_font_6x10_tf); u8g2_DrawStr(u8g2, 0, 15, “Page Buffer Mode”); // ... } while (u8g2_NextPage(u8g2));7. 常见问题排查与调试心得移植过程中屏幕不亮、花屏、显示错位是常见问题。下面是一个排查清单现象可能原因排查步骤屏幕完全不亮电源接反或电压不对RESET引脚一直为低屏幕已损坏。1. 检查VCC和GND。2. 用万用表或逻辑分析仪测量RESET引脚电平应为高。3. 尝试给RESET一个低脉冲拉低1ms再拉高进行硬件复位。屏幕亮但无显示白屏或乱码SPI通信失败初始化序列错误DC引脚电平不对。1.最有效方法用逻辑分析仪抓取SPI波形。检查SCLK、MOSI是否有数据CS、DC时序是否正确。2. 确认SPI模式CPOL/CPHA与屏幕规格书一致。SSD1306通常模式0CPOL0 CPHA0或模式3。3. 单步调试确保u8g2_InitDisplay被正确调用。显示内容错位或镜像屏幕旋转设置错误初始化命令不对。1. 检查u8g2_Setup_...函数中的旋转参数U8G2_R0,R1,R2,R3。2. SSD1306有专门的命令设置扫描方向COM Scan Direction, Segment RemapU8g2内部已处理但可以尝试更换不同的u8g2_Setup_...函数如nonamevsvcomh0。显示内容有拖影或残影对比度设置不合适VCOMH电压未设置。在初始化后尝试调用u8g2_SetContrast(u8g2, 128)调整对比度值范围0-255。有些屏幕需要特定的初始化序列来设置内部电荷泵和VCOMH。编译后代码体积过大包含了所有字体。按照6.1节的方法进行字体瘦身。调试心得逻辑分析仪是你的好朋友没有比直接看波形更直接的调试方式了。花几十块钱买个简易的逻辑分析仪能节省你无数个小时的瞎猜时间。重点关注CS、DC信号是否在正确的时刻变化以及MOSI上的数据是否与预期命令相符。从简单开始先不要画复杂的图形就用u8g2_DrawStr显示一行固定的文字。成功了再逐步增加功能。检查延时屏幕驱动芯片对时序有要求。如果你的Delay_us函数不准可能导致初始化失败。如果软件延时不行尝试在GPIO回调的延时消息里直接调用__NOP()循环或者使用更精确的定时器。参考官方例程极海APM32的SDK中可能有SPI驱动OLED的例程虽然可能不是U8g2。参考其SPI配置参数和GPIO初始化代码能帮你排除硬件配置错误。移植成功只是第一步。U8g2库功能非常强大支持绘制位图、多级字体、用户自定义图标等等。你可以利用它轻松构建出漂亮的嵌入式图形界面。结合APM32F411的性能实现流畅的菜单切换和动画效果完全不在话下。整个移植过程最关键的就是耐心地搭建好底层的那几个回调函数一旦通信链路打通剩下的就是享受U8g2带来的图形编程便利了。