ESP32-C3 SPI实战：手把手教你驱动OLED屏幕（附完整代码）

第一次拿到ESP32-C3开发板和OLED屏幕时，那种既兴奋又忐忑的心情至今记忆犹新。作为嵌入式开发的入门项目，点亮OLED屏幕堪称"Hello World"级别的经典案例。本文将带你从零开始，用最直观的方式理解SPI通信，并最终在0.96寸OLED上显示自定义内容。

1. 硬件准备与连接

在开始编程前，正确的硬件连接是成功的第一步。ESP32-C3的SPI引脚分配灵活，但为了简化操作，我们推荐使用默认的SPI2（GP-SPI2）接口：

提示：不同厂商的OLED模块引脚标注可能略有差异，建议对照产品手册确认。SSD1306驱动的OLED通常不需要MISO引脚。

连接时需注意：

• 确保所有接地（GND）引脚相连
• 检查供电电压（多数OLED模块支持3.3V）
• 避免过长的连接线（建议使用杜邦线长度<15cm）

常见连接错误排查：

1. 白屏现象：检查RESET引脚是否正常初始化
2. 花屏/乱码：确认SPI时钟频率是否过高
3. 无反应：核对电源和接地是否接反

2. 开发环境搭建

我们将使用PlatformIO作为开发环境，它比Arduino IDE更适合嵌入式开发。以下是具体配置步骤：

1. 安装VSCode和PlatformIO插件
2. 创建新项目，选择"Espressif ESP32-C3"板型
3. 添加必要的库依赖：

   lib_deps = adafruit/Adafruit GFX Library@^1.11.3 adafruit/Adafruit SSD1306@^2.5.7

验证环境是否正常工作：

#include <Arduino.h> void setup() { Serial.begin(115200); } void loop() { Serial.println("Environment check passed!"); delay(1000); }

注意：如果遇到编译错误，请检查板型是否选择正确（ESP32-C3-DevKitM-1是常见型号）

3. SPI驱动配置详解

ESP32-C3的SPI控制器配置需要关注几个关键参数：

#define SCK_PIN 6 #define MOSI_PIN 7 #define CS_PIN 10 #define DC_PIN 3 #define RES_PIN 4 // SPI配置结构体 SPIClass spi(HSPI); SPISettings spiSettings(1000000, MSBFIRST, SPI_MODE0); void initSPI() { spi.begin(SCK_PIN, -1, MOSI_PIN, CS_PIN); // -1表示不使用MISO pinMode(DC_PIN, OUTPUT); pinMode(RES_PIN, OUTPUT); // 复位OLED digitalWrite(RES_PIN, LOW); delay(10); digitalWrite(RES_PIN, HIGH); delay(10); }

关键参数说明：

• 时钟频率：SSD1306典型值为1MHz（过高会导致显示异常）
• 数据模式：SPI_MODE0或SPI_MODE3（由OLED控制器决定）
• 位顺序：MSBFIRST（高位在前）是大多数SPI设备的默认设置

时钟频率与显示效果的关系：

4. 完整示例代码与功能实现

下面是一个完整的OLED驱动示例，包含文本显示和图形绘制功能：

#include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h> #define SCREEN_WIDTH 128 #define SCREEN_HEIGHT 64 #define OLED_RESET -1 Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &spi, DC_PIN, CS_PIN, RES_PIN); void setup() { initSPI(); if(!display.begin(SSD1306_SWITCHCAPVCC)) { Serial.println("OLED allocation failed"); for(;;); // 死循环 } display.clearDisplay(); display.setTextSize(1); display.setTextColor(SSD1306_WHITE); display.setCursor(0,0); display.println("Hello, ESP32-C3!"); display.display(); // 绘制图形 drawDemo(); } void drawDemo() { // 绘制线段 display.drawLine(0, 20, 127, 20, SSD1306_WHITE); // 绘制矩形 display.drawRect(10, 30, 40, 20, SSD1306_WHITE); // 填充圆形 display.fillCircle(80, 40, 10, SSD1306_WHITE); display.display(); delay(2000); } void loop() { // 显示动态内容 display.clearDisplay(); display.setCursor(0,0); display.println("System Running"); display.print("Uptime: "); display.print(millis()/1000); display.println("s"); display.display(); delay(100); }

进阶功能实现：

1. 自定义字体：

#include <Fonts/FreeSans9pt7b.h> display.setFont(&FreeSans9pt7b);

2. 位图显示：

void showBitmap() { static const unsigned char PROGMEM logo[] = { // 这里放置位图数据 }; display.drawBitmap(0, 0, logo, 128, 64, SSD1306_WHITE); display.display(); }

3. 多级菜单系统：

typedef struct { String title; void (*action)(); } MenuItem; MenuItem mainMenu[] = { {"Display Info", showInfo}, {"Draw Shapes", drawShapes}, {"Show Bitmap", showBitmap} }; void showMenu() { for(int i=0; i<3; i++) { display.setCursor(10, 15*(i+1)); display.println(mainMenu[i].title); } display.display(); }

5. 性能优化与调试技巧

当项目复杂度增加时，这些技巧能帮你提升显示性能：

刷新优化策略：

• 使用display.startWrite()和display.endWrite()包裹批量操作
• 局部刷新代替全屏刷新
• 降低非必要区域的刷新频率

内存节省技巧：

// 使用PROGMEM存储大容量数据 const char longText[] PROGMEM = "Very long text..."; // 分段显示长文本 void showLongText() { char buffer[21]; // 每行显示20字符 for(int i=0; i<strlen_P(longText); i+=20) { memcpy_P(buffer, longText+i, 20); buffer[20] = '\0'; display.println(buffer); } display.display(); }

SPI信号质量检测：

1. 使用逻辑分析仪观察波形
2. 检查时钟边沿是否清晰
3. 确认CS信号在传输期间保持低电平

常见问题快速排查表：

6. 项目扩展与进阶应用

掌握了基础显示功能后，可以尝试这些进阶应用：

传感器数据可视化：

#include <Adafruit_Sensor.h> #include <Adafruit_BME280.h> Adafruit_BME280 bme; void showSensorData() { display.clearDisplay(); display.setCursor(0,0); display.print("Temp: "); display.print(bme.readTemperature()); display.println(" C"); // 类似显示湿度和气压 display.display(); }

UI动画实现：

void animateProgressBar() { for(int i=0; i<SCREEN_WIDTH; i+=5) { display.drawRect(0, 50, i, 10, SSD1306_WHITE); display.display(); delay(50); display.drawRect(0, 50, i, 10, SSD1306_BLACK); } }

多屏级联控制：

#define NUM_DISPLAYS 3 Adafruit_SSD1306 displays[NUM_DISPLAYS] = { Adafruit_SSD1306(SCREEN_WIDTH, SCREEN_HEIGHT, &spi, DC_PIN1, CS_PIN1, RES_PIN1), // 其他显示屏实例 }; void setupDisplays() { for(int i=0; i<NUM_DISPLAYS; i++) { displays[i].begin(SSD1306_SWITCHCAPVCC); displays[i].clearDisplay(); } }

实际项目中，我曾用这种方案实现了工业控制面板的多屏同步显示，关键是要合理安排SPI片选信号的切换时序，避免总线冲突。一个实用的技巧是为每个显示屏分配独立的CS引脚，并在切换时加入微小延时：

void updateAllDisplays() { for(int i=0; i<NUM_DISPLAYS; i++) { digitalWrite(displays[i].csPin, LOW); displays[i].display(); delayMicroseconds(10); digitalWrite(displays[i].csPin, HIGH); } }