STM32 HAL库硬件SPI驱动0.96寸OLED屏(SSD1306)全流程移植指南

1. 项目概述与核心价值

最近在做一个需要小型显示界面的嵌入式项目，手头正好有几片闲置的0.96寸的OLED屏，这种屏幕体积小巧、功耗极低，显示效果又很锐利，非常适合作为单片机系统的“眼睛”。不过，网上常见的驱动代码多是基于标准库或者模拟SPI的，对于已经习惯了使用STM32CubeMX和HAL库进行开发的我来说，直接套用总觉得不够“优雅”，而且硬件SPI在速度和CPU占用率上的优势是模拟IO无法比拟的。于是，我决定动手把这款7针脚（也叫4针IIC/7针SPI二合一屏）的OLED屏，用硬件SPI的方式完整地移植到HAL库环境下。

这个移植过程，远不止是简单地把几个读写函数替换成HAL_SPI_Transmit那么简单。它涉及到对屏幕驱动芯片（通常是SSD1306）底层通信协议的深度理解，对HAL库SPI机制的正确配置，以及对原有驱动代码架构的重构。最终的目标，是封装出一个接口清晰、与硬件耦合度低、便于在不同STM32型号间复用的OLED驱动模块。无论你是刚接触HAL库的新手，还是想优化现有显示方案的开发者，这次从零开始的移植记录都能提供一条清晰的路径和不少避坑经验。接下来，我就从屏幕原理、硬件连接、CubeMX配置、驱动代码逐层剥离与重构，再到最后的测试优化，完整地走一遍这个流程。

2. 硬件解析与方案选型

2.1 认识0.96寸OLED屏及其驱动芯片

我们常说的0.96寸OLED屏，其核心显示驱动芯片绝大多数都是SSD1306。这是一款单片CMOS OLED/PLED驱动芯片，专门为共阴极OLED面板设计。它内部集成了对比度控制、显示RAM和振荡器，减少了外部器件和功耗。其分辨率为128x64，这意味着它有128列和64行，总共8192个像素点。每个像素点对应显示RAM（GDDRAM）中的一个比特（bit），1表示点亮，0表示熄灭。

这款芯片支持三种通信接口：6800/8080并行接口、IIC接口以及我们这次要用的4线SPI串行接口。注意，所谓的“7针脚”屏幕，实际上是把IIC和SPI的引脚做到了一起。当使用SPI模式时，我们只关心其中的7个引脚（有些版本是8个，多一个复位RES）。具体到引脚定义，通常如下：

  • GND: 电源地。
  • VCC: 供电电源，常见为3.3V或5V，需查阅屏幕规格书确认。
  • D0 (SCLK): SPI时钟线。
  • D1 (MOSI): SPI主设备输出从设备输入线，用于发送数据/命令。
  • RES (RST): 复位引脚，低电平有效，用于硬件复位屏幕。
  • DC (D/C): 数据/命令选择引脚。这是SPI控制的关键，它告诉SSD1306当前发送的是命令（Command）还是数据（Data）。通常低电平为命令，高电平为数据。
  • CS (CS): 片选引脚，低电平有效。当有多个SPI设备时，通过此引脚选择当前要通信的设备。

理解每个引脚的功能，是正确接线和编程的基础。其中DC和CS这两个GPIO的控制逻辑，是实现驱动层与硬件层解耦的关键。

2.2 硬件SPI与模拟SPI的抉择

为什么非要折腾硬件SPI？模拟SPI代码不是更简单、移植性更好吗？这确实是个常见的权衡。模拟SPI（Software SPI）是通过编程控制任意GPIO引脚的高低电平时序来模拟SPI协议。它的最大优点是引脚任意、高度可移植，不依赖于特定的硬件外设。但其缺点也非常明显：

  1. CPU占用率高：发送每一个比特都需要CPU参与，进行置高、置低、延时等操作，尤其在刷新全屏或动态显示时，会消耗大量CPU时间。
  2. 速度慢：受限于软件循环和延时，其通信速率远低于硬件SPI。对于需要快速刷新的应用（如动画、波形绘制），这可能成为瓶颈。
  3. 时序精度依赖CPU：时序由软件延时保证，如果系统中有中断或其他任务打断，可能导致通信时序出错。

而硬件SPI则是由STM32内部的专用外设来处理SPI通信协议。一旦配置好并启动传输，CPU只需将数据放入数据寄存器（DR），外设就会自动按照设定的时钟极性（CPOL）、相位（CPHA）、数据大小、波特率等参数，通过硬件引脚完成整个帧的发送/接收。它的优势在于：

  1. 极高的效率：通信过程由DMA或中断驱动，CPU解放出来可以处理其他任务。
  2. 速度飞快：波特率可以轻松达到几兆甚至几十兆赫兹。
  3. 时序精准：由硬件时钟保证，不受其他任务干扰，通信稳定可靠。

对于OLED这种虽然单次数据量不大，但刷新操作可能比较频繁的设备，使用硬件SPI能显著提升系统整体响应能力和效率。因此，在资源允许的情况下，硬件SPI是更优的选择。

2.3 硬件连接示意图与注意事项

以STM32F103C8T6（蓝色药丸板）为例，我们选择SPI1。连接方式如下：

  • OLED VCC->3.3V
  • OLED GND->GND
  • OLED D0 (SCLK)->PA5 (SPI1_SCK)
  • OLED D1 (MOSI)->PA7 (SPI1_MOSI)
  • OLED RES (RST)->PB0(任意GPIO，用于复位)
  • OLED DC (D/C)->PB1(任意GPIO，用于区分命令/数据)
  • OLED CS (CS)->PA4 (SPI1_NSS)或PB10(任意GPIO作为软件片选)

注意1：关于CS引脚的选择。STM32的SPI_NSS引脚可以配置为硬件模式或软件模式。为了代码的通用性和简化配置，我强烈建议将CS也当作一个普通GPIO（软件片选）来控制。这样，在CubeMX中可以将NSS设置为“Software”，然后在代码中手动拉低/拉高对应的GPIO。这避免了硬件NSS模式可能带来的复杂时序问题，移植到其他平台也更方便。

注意2：电源一定要确认。有些OLED屏模块板上自带LDO，可以接受5V输入，输出3.3V给芯片。但有些屏是直接3.3V逻辑的。最稳妥的方法是查看模块背面或购买链接的说明，确认工作电压。接错电压可能永久损坏屏幕。

注意3：上拉电阻。IIC接口的SCL和SDA通常需要上拉，但在纯SPI模式下，我们只用了D0， D1， RES， DC， CS，这些线一般不需要外部上拉，STM32的推挽输出模式足以驱动。

3. STM32CubeMX工程配置详解

3.1 SPI外设参数化配置

打开STM32CubeMX，选择你的芯片型号。首先配置SPI1。

  1. Mode: 选择Full-Duplex Master。OLED屏作为从设备，STM32作为主设备。
  2. Hardware NSS Signal: 选择Disable或Software。如前所述，我们使用软件控制CS，这里选“Software”即可。
  3. Frame Format: 选择Motorola。这是标准的SPI帧格式。
  4. Data Size: 选择8 bits。SSD1306一次接收一个字节（8位）的数据或命令。
  5. First Bit: 选择MSB First。这是最常见的设置，数据高位（MSB）先发送。
  6. Clock Parameters (关键！):
    • Prescaler: 这是设置波特率分频系数的地方。SPI时钟频率 = APB2总线时钟 / Prescaler。对于F103，APB2通常是72MHz。SSD1306的SPI接口最高速率文档中可能未明确标出，但经验表明，在3.3V下，10MHz以内通常很稳定。我们可以先选择一个较大的分频，如8分频，得到9MHz的SCLK，后续可以尝试提高。
    • CPOL (Clock Polarity): 设置为Low。这意味着时钟空闲状态为低电平。
    • CPHA (Clock Phase): 设置为1 Edge。这意味着数据在时钟的第一个边沿（对于CPOL=Low，就是上升沿）被采样。CPOL=0， CPHA=0是SPI Mode 0，CPOL=0， CPHA=1是SPI Mode 1。根据SSD1306的数据手册，它通常工作在SPI Mode 0。但有些驱动代码也使用Mode 3。实测中，Mode 0和Mode 3有时都能工作，但为了严谨，我们应该遵循数据手册。如果手册未明确，Mode 0是更通用的选择。这里我们选择CPOL=Low， CPHA=1Edge，即Mode 0。
  7. CRC Calculation:Disable。
  8. Advanced Parameters: 保持默认。

配置完成后，相应的GPIO（PA5， PA7）会被自动配置为复用推挽输出模式。

3.2 控制引脚GPIO配置

接下来配置我们用于控制OLED的GPIO。

  1. RES (复位引脚): 例如PB0。配置为GPIO_Output， 初始输出电平设为High（因为复位是低电平有效，初始不复位）。
  2. DC (数据/命令引脚): 例如PB1。配置为GPIO_Output， 初始输出电平可以设为Low。
  3. CS (片选引脚): 例如PB10（如果用软件片选）。配置为GPIO_Output， 初始输出电平设为High（片选高电平表示未选中）。

这些引脚的输出速度（Speed）选择Low或Medium即可，因为翻转频率不高。

3.3 时钟树与工程生成

检查系统时钟树，确保核心时钟（HCLK）和APB2外设时钟（PCLK2， SPI1挂载于此）已正确配置到最高频率（如72MHz），以获得最佳的SPI性能。

在Project Manager中，设置好工程名称、路径、IDE（如MDK-ARM V5），并将Code Generator中的“Generated files”设置为“Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral”。这会将每个外设的初始化代码单独成对文件，结构更清晰。

点击“GENERATE CODE”，生成工程。

4. 驱动层代码重构与实现

4.1 底层硬件抽象层（HAL）封装

生成的工程中，SPI和GPIO的初始化代码已经在main.c的MX_SPI1_Init()和MX_GPIO_Init()中完成了。我们的驱动代码不应该直接依赖这些在main.c中的函数和全局变量（如hspi1）。我们需要创建一个独立的驱动层，例如oled.c和oled.h，并在其中通过外部声明来引用这些资源，从而实现硬件与应用的解耦。

首先，在oled.h中定义硬件依赖接口和屏幕参数：

#ifndef __OLED_H #define __OLED_H #include "main.h" // 这会包含 stm32f1xx_hal.h 以及 hspi1 的声明 // 屏幕尺寸定义 #define OLED_WIDTH 128 #define OLED_HEIGHT 64 #define OLED_PAGE_NUM (OLED_HEIGHT / 8) // SSD1306 将屏幕分为8页（Page），每页8行 // 硬件引脚重映射宏（提高可移植性） #define OLED_SPI_HANDLE hspi1 // SPI句柄 #define OLED_RES_Port GPIOB #define OLED_RES_Pin GPIO_PIN_0 #define OLED_DC_Port GPIOB #define OLED_DC_Pin GPIO_PIN_1 #define OLED_CS_Port GPIOB #define OLED_CS_Pin GPIO_PIN_10 // 基础操作宏（直接调用HAL库和GPIO操作，效率高） #define OLED_RES_Low() HAL_GPIO_WritePin(OLED_RES_Port, OLED_RES_Pin, GPIO_PIN_RESET) #define OLED_RES_High() HAL_GPIO_WritePin(OLED_RES_Port, OLED_RES_Pin, GPIO_PIN_SET) #define OLED_DC_Low() HAL_GPIO_WritePin(OLED_DC_Port, OLED_DC_Pin, GPIO_PIN_RESET) // 命令 #define OLED_DC_High() HAL_GPIO_WritePin(OLED_DC_Port, OLED_DC_Pin, GPIO_PIN_SET) // 数据 #define OLED_CS_Low() HAL_GPIO_WritePin(OLED_CS_Port, OLED_CS_Pin, GPIO_PIN_RESET) // 选中 #define OLED_CS_High() HAL_GPIO_WritePin(OLED_CS_Port, OLED_CS_Pin, GPIO_PIN_SET) // 取消选中 // 用户函数声明 void OLED_Init(void); void OLED_Clear(void); void OLED_Refresh(void); // 刷新整个显存到屏幕 void OLED_SetCursor(uint8_t page, uint8_t col); void OLED_PrintChar(uint8_t x, uint8_t y, char chr); void OLED_PrintString(uint8_t x, uint8_t y, char *str); // ... 其他绘图函数 #endif

在oled.c中，我们首先实现最底层的两个通信函数：写命令和写数据。这是驱动芯片的基石。

#include "oled.h" #include "spi.h" // 确保能访问到 hspi1 #include <string.h> // 用于 memcpy // 私有全局变量：显存（GRAM） static uint8_t OLED_GRAM[OLED_PAGE_NUM][OLED_WIDTH]; /** * @brief 向OLED写入一个命令 * @param cmd: 要写入的命令字节 * @retval None */ static void OLED_WriteCmd(uint8_t cmd) { OLED_CS_Low(); // 使能片选 OLED_DC_Low(); // 设置为命令模式 HAL_SPI_Transmit(&OLED_SPI_HANDLE, &cmd, 1, HAL_MAX_DELAY); OLED_CS_High(); // 关闭片选 // 注意：HAL_SPI_Transmit是阻塞式函数，会等待发送完成。 // 对于OLED这种低速设备，阻塞式足够用，且代码简单。 } /** * @brief 向OLED写入一个数据字节 * @param data: 要写入的数据字节 * @retval None */ static void OLED_WriteData(uint8_t data) { OLED_CS_Low(); // 使能片选 OLED_DC_High(); // 设置为数据模式 HAL_SPI_Transmit(&OLED_SPI_HANDLE, &data, 1, HAL_MAX_DELAY); OLED_CS_High(); // 关闭片选 }

实操心得1：关于HAL_MAX_DELAY。这里使用了HAL_MAX_DELAY作为超时参数，意味着函数会一直等待直到发送完成。在单任务或简单系统中这没问题。但在复杂的RTOS环境中，长时间阻塞可能影响其他任务。更优的做法是使用带超时检测的HAL_SPI_Transmit，或者使用DMA+中断的非阻塞方式。但对于初学者和大多数应用，阻塞式是最简单可靠的。

实操心得2：片选（CS）的时机。有些驱动代码会在初始化时拉低CS，之后就一直保持低电平，只在写数据/命令时控制DC。这种方法也可以，但严格来说，SPI协议建议在每个数据传输帧前后控制CS。我们这里遵循更标准的做法：每次传输前拉低，传输后拉高。这有助于避免总线冲突，尤其是在未来可能连接其他SPI设备时。

4.2 SSD1306初始化序列移植

SSD1306上电后需要一系列命令进行初始化，设置对比度、扫描方向、显示开关等。这些命令序列是固定的，我们可以直接从模拟SPI的驱动代码中移植过来，但将里面的写命令、写数据函数调用替换成我们刚实现的OLED_WriteCmd和OLED_WriteData。

/** * @brief OLED初始化函数 * @retval None */ void OLED_Init(void) { // 1. 硬件复位 OLED_RES_Low(); HAL_Delay(100); // 复位低电平保持至少3us，这里给100ms确保稳定 OLED_RES_High(); HAL_Delay(100); // 等待复位完成 // 2. 发送初始化命令序列 OLED_WriteCmd(0xAE); // 关闭显示（Display OFF） OLED_WriteCmd(0xD5); // 设置显示时钟分频比/振荡器频率 OLED_WriteCmd(0x80); // 建议值 OLED_WriteCmd(0xA8); // 设置多路复用率（Multiplex Ratio） OLED_WriteCmd(0x3F); // 0x3F 对应 64行 (HEIGHT-1) OLED_WriteCmd(0xD3); // 设置显示偏移（Display Offset） OLED_WriteCmd(0x00); // 无偏移 OLED_WriteCmd(0x40); // 设置显示起始行（Set Display Start Line） OLED_WriteCmd(0x8D); // 电荷泵设置（Charge Pump Setting） OLED_WriteCmd(0x14); // 使能电荷泵（必须，否则屏幕不亮） OLED_WriteCmd(0x20); // 设置内存地址模式（Memory Addressing Mode） OLED_WriteCmd(0x00); // 水平地址模式（Horizontal Addressing Mode） // 0x00: 水平模式 0x01: 垂直模式 0x02: 页模式（Page Mode） OLED_WriteCmd(0xA1); // 设置段重映射（Segment Re-map） // 0xA0: 列地址0映射到SEG0（默认） // 0xA1: 列地址127映射到SEG0（水平翻转） OLED_WriteCmd(0xC8); // 设置COM扫描方向（COM Output Scan Direction） // 0xC0: 从COM0扫描到COM[N-1]（默认） // 0xC8: 从COM[N-1]扫描到COM0（垂直翻转） OLED_WriteCmd(0xDA); // 设置COM硬件引脚配置（COM Pins Hardware Configuration） OLED_WriteCmd(0x12); // 0x12 for 64行， 0x02 for 32行 OLED_WriteCmd(0x81); // 设置对比度控制（Contrast Control） OLED_WriteCmd(0xCF); // 对比度值， 0x00~0xFF OLED_WriteCmd(0xD9); // 设置预充电周期（Pre-charge Period） OLED_WriteCmd(0xF1); // 建议值 OLED_WriteCmd(0xDB); // 设置VCOMH电压倍率（VCOMH Deselect Level） OLED_WriteCmd(0x40); // 建议值 OLED_WriteCmd(0xA4); // 关闭整体显示开启（Disable Entire Display On） OLED_WriteCmd(0xA6); // 设置正常显示（Set Normal Display， 非反色） OLED_WriteCmd(0xAF); // 开启显示（Display ON） // 3. 清空显存并刷新 OLED_Clear(); OLED_Refresh(); HAL_Delay(200); // 短暂延时，让屏幕稳定 }

注意事项1：电荷泵命令（0x8D， 0x14）。这是最关键的命令之一！SSD1306需要内部电荷泵来产生驱动OLED像素点的高电压。如果忘记发送0x8D 0x14这个序列，屏幕将完全不会点亮，但通信逻辑可能是正常的（用逻辑分析仪能看到波形）。这是新手最常踩的坑。

注意事项2：地址模式（0x20）。我们这里选择了水平地址模式（0x00）。在这种模式下，每次设置起始行列地址后，发送数据字节，列地址会自动加1，当到达右边界后，行地址会自动跳到下一行。这非常方便我们进行全屏刷新或绘制连续图形。页模式（0x02）则需要手动管理分页，更适合逐页更新文本。

4.3 显存管理机制与刷新函数

SSD1306内部有GDDRAM，但我们通常在单片机端维护一个同样大小的“显存”（GRAM）数组。所有绘图操作（画点、画线、写字）都先修改这个数组，修改完成后，再通过一个刷新函数将整个数组一次性发送到屏幕的GDDRAM。这就是“双缓冲”的思想，可以避免屏幕闪烁。

我们已经在文件开头定义了OLED_GRAM数组。现在实现清空和刷新函数。

/** * @brief 清空显存（将所有像素点置0） * @retval None */ void OLED_Clear(void) { memset(OLED_GRAM, 0x00, sizeof(OLED_GRAM)); } /** * @brief 将本地显存（OLED_GRAM）全部更新到屏幕GDDRAM * @retval None */ void OLED_Refresh(void) { uint8_t page, col; for(page = 0; page < OLED_PAGE_NUM; page++) { // 1. 设置页地址（Page Addressing Mode 在水平模式下也需要设置页和列） // 实际上，在水平地址模式下，我们只需设置起始地址，然后连续发送数据。 // 但为了清晰，我们按页发送。 OLED_WriteCmd(0xB0 + page); // 设置页起始地址（Set Page Start Address） OLED_WriteCmd(0x00); // 设置列地址低4位（Set Lower Column Start Address） OLED_WriteCmd(0x10); // 设置列地址高4位（Set Higher Column Start Address） // 2. 连续发送该页的128列数据 OLED_CS_Low(); OLED_DC_High(); // 数据模式 // 使用HAL_SPI_Transmit发送一整页数据，效率远高于单字节发送 HAL_SPI_Transmit(&OLED_SPI_HANDLE, OLED_GRAM[page], OLED_WIDTH, HAL_MAX_DELAY); OLED_CS_High(); } }

核心技巧：批量传输提升刷新速度。注意OLED_Refresh函数中，对于每一页（Page），我们使用了HAL_SPI_Transmit一次性发送该页的128个字节（OLED_WIDTH）。这比用循环调用128次OLED_WriteData要高效得多！因为后者每次都要操作CS和DC引脚，产生大量函数调用和GPIO操作开销。批量传输是优化硬件SPI性能的关键一步。

4.4 基础绘图函数实现（画点、字符、字符串）

有了显存和刷新机制，我们就可以实现基础的绘图函数了。首先是画点函数，它是所有图形和文字显示的基础。

/** * @brief 在指定坐标画点（或擦除点） * @param x: 横坐标，范围 0~127 * @param y: 纵坐标，范围 0~63 * @param mode: 1-点亮， 0-熄灭 * @retval None */ void OLED_DrawPoint(uint8_t x, uint8_t y, uint8_t mode) { uint8_t page, bit_pos; if(x >= OLED_WIDTH || y >= OLED_HEIGHT) return; // 坐标越界保护 page = y / 8; // 计算点在哪一页（每页8行） bit_pos = y % 8; // 计算点在该页中的具体比特位 if(mode) { OLED_GRAM[page][x] |= (1 << bit_pos); // 置1，点亮 } else { OLED_GRAM[page][x] &= ~(1 << bit_pos); // 清0，熄灭 } // 注意：画点后不会立即刷新屏幕，需要手动调用OLED_Refresh() }

基于画点函数，我们可以实现显示字符。通常我们会使用一个字库数组（如oledfont.h），里面存储了ASCII字符的位图数据（例如8x16像素）。显示字符就是按位图数据在显存中画点。

// 假设在 oledfont.h 中定义了外部字库数组 // extern const uint8_t Font8x16[][16]; // 每个字符16字节，每字节代表一列（8行），即字符宽8像素，高16像素。 /** * @brief 在指定位置显示一个ASCII字符（8x16） * @param x: 起始列坐标 * @param y: 起始页坐标（0~7，因为字符高16像素，占2页） * @param chr: 要显示的字符 * @retval None */ void OLED_PrintChar(uint8_t x, uint8_t y, char chr) { uint8_t i, j, page; uint8_t *pFont; // 指向该字符字模数据的指针 if(chr < ' ' || chr > '~') return; // 只显示可打印ASCII字符 pFont = (uint8_t*)&Font8x16[(chr - ' ') * 16]; // 找到字模起始地址 for(i = 0; i < 8; i++) // 字符宽度8列 { uint8_t data = pFont[i]; // 获取该列的字模数据（8位，对应一列的8个点） for(j = 0; j < 8; j++) // 处理该列的上半部分（第一页） { if(data & (1 << j)) { OLED_DrawPoint(x + i, y * 8 + j, 1); } } data = pFont[i + 8]; // 获取该列下半部分的字模数据（第二页） for(j = 0; j < 8; j++) // 处理该列的下半部分（第二页） { if(data & (1 << j)) { OLED_DrawPoint(x + i, y * 8 + 8 + j, 1); } } } } /** * @brief 在指定位置显示字符串 * @param x: 起始列坐标 * @param y: 起始页坐标（0~6，因为字符串可能多行） * @param str: 要显示的字符串 * @retval None */ void OLED_PrintString(uint8_t x, uint8_t y, char *str) { uint8_t x_pos = x; while(*str != '\0') { OLED_PrintChar(x_pos, y, *str); str++; x_pos += 8; // 字符宽度8像素，加1像素间距，这里简单加8 // 简单换行处理（可根据需要完善） if(x_pos + 8 > OLED_WIDTH) { x_pos = 0; y += 2; // 字符高占2页 if(y >= OLED_PAGE_NUM) break; // 超出屏幕底部 } } }

5. 应用测试与性能优化

5.1 主程序测试与现象验证

在main.c中，包含oled.h，初始化后调用我们的驱动函数进行测试。

#include "oled.h" int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_SPI1_Init(); OLED_Init(); // 初始化OLED OLED_PrintString(0, 0, "Hello, OLED!"); OLED_PrintString(0, 2, "HAL SPI Driver"); OLED_PrintString(0, 4, "Test OK!"); OLED_Refresh(); // 将显存内容刷到屏幕 while (1) { // 可以在这里添加动态效果，如滚动、动画等 HAL_Delay(1000); } }

编译下载程序，如果一切顺利，屏幕上应该会清晰显示“Hello， OLED!”等三行文字。如果屏幕不亮，请按以下步骤排查。

5.2 典型问题排查与解决方法

  1. 屏幕完全不亮，无任何显示

    • 检查电源和背光：确认VCC和GND连接正确，电压符合要求。有些OLED屏本身不发光，需要检查是否有背光引脚（BL）需要接高电平。
    • 检查复位时序：确保复位引脚（RES）的时序正确。我们的代码是先拉低至少3us（实际给了100ms），再拉高。可以用逻辑分析仪或示波器查看波形。
    • 检查电荷泵命令：这是最常见的原因！确认初始化序列中包含了0x8D， 0x14这两条命令。
    • 检查SPI波形：使用逻辑分析仪连接SCLK， MOSI， DC， CS引脚。观察发送初始化命令时是否有正确的波形。重点看DC引脚是否在发送命令时为低电平，发送数据时为高电平。

  2. 屏幕全亮或显示乱码

    • 检查显存刷新逻辑：可能是OLED_Refresh函数中的地址设置命令（0xB0， 0x00， 0x10）有误，或者SPI发送的数据顺序不对。
    • 检查字库数据：如果只是字符显示乱码，而画点正常，可能是字库数组提取不正确，或者字符编码计算有误（chr - ' '）。
    • 检查SPI模式（CPOL/CPHA）：这是硬件SPI最容易出错的地方。如果模式不匹配，数据会在错误的时钟边沿被采样，导致全部错位。尝试改为Mode 3（CPOL=1， CPHA=1）看看。最好以屏幕数据手册为准。

  3. 显示内容错位或镜像

    • 检查重映射命令：初始化序列中的0xA1（段重映射）和0xC8（COM扫描方向）控制了屏幕的水平和垂直翻转。如果显示是反的，可以尝试将0xA1改为0xA0，或将0xC8改为0xC0。
    • 检查坐标系统：确认你的画点函数OLED_DrawPoint中的坐标计算（页、比特位）是正确的。可以写一个测试函数，点亮四个角和对角线的点来验证坐标系统。

  4. 刷新速度慢，有闪烁感

    • 优化刷新函数：确保OLED_Refresh函数使用的是批量传输HAL_SPI_Transmit发送一整页数据，而不是单字节发送。
    • 提高SPI波特率：在CubeMX中尝试减小SPI的Prescaler，提高SCLK频率。可以从36MHz（2分频）开始测试，逐步提高，直到屏幕显示异常，然后退回一个稳定值。
    • 使用DMA：对于需要极高刷新率的应用（如动画），可以将SPI设置为DMA模式。在CubeMX中SPI配置的“DMA Settings”添加SPI_TX的DMA流（如DMA1 Channel3），然后在代码中使用HAL_SPI_Transmit_DMA。这需要更复杂的缓冲区管理和传输完成回调处理，但能彻底解放CPU。

5.3 高级优化：局部刷新与DMA应用

全屏刷新（OLED_Refresh）虽然简单，但每次都要发送1024字节（128*64/8），对于只修改了局部区域（如更新一个数字）的应用来说效率低下。我们可以实现局部刷新函数。

思路是：在显存OLED_GRAM之外，再维护一个同样大小的“脏矩阵”（dirty map），记录哪些页的哪些列被修改过。在刷新时，只发送这些被标记为“脏”的列数据。这需要更复杂的内存管理，但能极大减少SPI通信量。

对于DMA的应用，步骤大致如下：

  1. 在CubeMX中为SPI_TX启用DMA（选择任意一个可用的流/通道）。
  2. 在代码中定义一个大缓冲区（如uint8_t dma_buffer[1024]）用于存放要发送的整个GDDRAM数据。
  3. 修改OLED_Refresh函数，先将分散的OLED_GRAM按顺序整合到dma_buffer中，然后调用HAL_SPI_Transmit_DMA。
  4. 实现SPI发送完成回调函数（HAL_SPI_TxCpltCallback），在DMA发送完成后进行后续处理（如设置标志位）。

使用DMA后，CPU在SPI传输过程中完全自由，可以处理其他任务，系统实时性更好。这是将硬件SPI性能发挥到极致的方案。

移植完成后，这个基于HAL库硬件SPI的OLED驱动模块就具备了良好的可移植性。你只需要修改oled.h中的硬件引脚映射和SPI句柄，就可以快速应用到其他STM32系列（如F4， H7）甚至其他品牌的ARM芯片上。整个过程中，对SSD1306协议的理解、对HAL库SPI接口的封装、以及双缓冲和批量传输的思想，其价值远超过代码本身。