Arduino I2C OLED显示入门：从硬件连接到自定义图片显示-开发者社区

1. 项目概述：为什么选择I2C OLED？

如果你玩过Arduino，肯定遇到过这样的问题：想给项目加个屏幕显示点信息，结果发现引脚不够用了。一堆传感器、几个按钮，再加上电机驱动，UNO板上那几十个IO口转眼就捉襟见肘。这时候，I2C OLED屏的优势就凸显出来了。

I2C，全称Inter-Integrated Circuit，中文常叫“I方C”或者“I2C总线”。它本质上是一种“主从式”的串行通信协议。说人话就是，它像一条“数据公交线”，Arduino作为“司机”（主设备），可以沿着这条线，去不同的“车站”（从设备，比如OLED屏、温湿度传感器、陀螺仪）接送数据。最关键的是，这条公交线只需要两根电线：一根是时钟线SCL，负责同步节奏；一根是数据线SDA，负责传输实际信息。这意味着，无论你接多少个支持I2C的设备，理论上都只占用Arduino的两个IO口，极大地节省了宝贵的引脚资源。

而OLED（Organic Light-Emitting Diode，有机发光二极管）屏幕，则是显示技术的“后起之秀”。和我们更常见的LCD屏不同，OLED的每个像素点都能自己发光，不需要背光板。这带来的好处非常直观：黑色可以做到纯黑（像素点直接关闭），对比度极高；屏幕可以做得非常薄；可视角度广，几乎从任何角度看都不会有明显的颜色失真；而且响应速度极快，显示动态内容毫无拖影。对于嵌入式项目来说，它的低功耗特性（显示深色画面时更省电）也很有吸引力。

所以，将I2C和OLED结合，你得到的就是一个接线极其简单（4根线）、占用资源极少、显示效果出色的完美显示方案。无论是做一个小型气象站、一个迷你游戏机，还是给机器人做个状态仪表盘，它都是上佳之选。本教程将以市面上最常见的1.3英寸、分辨率128x64的I2C OLED屏为例，带你从零开始，完成硬件连接、驱动测试，直到最终显示你自己的图片。

2. 硬件准备与连接详解

工欲善其事，必先利其器。在开始写代码之前，确保你手头有正确的部件并理解如何连接它们，是成功的第一步。

2.1 核心组件清单

你需要准备以下几样东西：

Arduino开发板一块：UNO、Nano、Mega等主流型号均可。本教程以最普及的Arduino UNO R3为例，其他板子引脚定义可能不同，需查阅对应资料。
1.3英寸 I2C OLED显示模块一块：这是本教程的主角。请注意，虽然都叫1.3寸OLED，但驱动芯片主要有两种：SSD1306和SH1106。它们绝大部分功能兼容，但在底层驱动上有细微差别，这决定了你后续需要安装的库文件。通常模块背面会印有芯片型号。
杜邦线若干：至少需要4根（公对公或公对母，取决于你的模块和Arduino的接口）。建议使用不同颜色的线以便区分，这是保持电路清晰、避免接错的好习惯。
USB数据线一根：用于给Arduino供电并上传程序。
一台安装好Arduino IDE的电脑：这是我们的编程和调试环境。

注意：在购买OLED模块时，务必确认其通信接口是“I2C”而不是“SPI”。SPI接口的OLED虽然刷新率可能更高，但需要占用4-5个IO口，接线也更多。I2C版本通常有4个引脚：VCC、GND、SCL、SDA，而SPI版本会有更多的引脚如RES、DC、CS等。

2.2 引脚定义与连接原理

让我们仔细看看OLED模块和Arduino UNO上的引脚：

OLED模块（I2C接口）通常有4个引脚：

VCC：电源正极。绝大多数模块工作电压为3.3V或5V。务必先查看你的模块规格！很多模块虽然标称支持5V，但逻辑电平是3.3V，长期接5V可能损坏屏幕。保险起见，接到Arduino的3.3V引脚。如果模块明确支持5V，则可接5V。
GND：电源地线。与Arduino的GND相连，形成共同的参考零电位。
SCL：I2C时钟线。用于同步数据传输的节奏脉冲。
SDA：I2C数据线。用于实际的数据传输。

Arduino UNO R3上的I2C引脚位置：在UNO板子的左上角（以USB接口朝下为准），有一组专门的引脚排针，旁边标有“A4 (SDA)”和“A5 (SCL)”。是的，UNO的I2C功能是复用在了模拟输入引脚A4和A5上。

SDA对应A4引脚。
SCL对应A5引脚。
VCC：可以选择接3.3V或5V输出引脚，根据上述电压要求决定。
GND：接任意一个GND引脚。

2.3 接线步骤与安全注意事项

现在，按照下图所示的对应关系，用杜邦线将它们连接起来：

OLED VCC->Arduino 3.3V(首选，更安全。若确认模块兼容5V，可接5V)
OLED GND->Arduino GND
OLED SDA->Arduino A4 (SDA)
OLED SCL->Arduino A5 (SCL)

实操心得：连接时，最好先断开Arduino与电脑的USB连接，或者将Arduino的电源开关（如果有）关闭。待所有线缆连接无误后再上电，这是一个保护电子元件的好习惯，可以避免因误接导致的短路烧毁。接完后，花几秒钟检查一遍：电源正负极有没有接反？SCL和SDA有没有接错？确认无误后再进行下一步。

连接完成后，你的硬件部分就准备好了。整个连接非常简洁，只有四根线，这正是I2C总线在小型项目中的魅力所在。

3. 驱动库安装与设备地址扫描

硬件连通只是物理上的准备，要让Arduino“认识”并“指挥”这块屏幕，还需要软件层面的驱动——这就是库文件。而在这之前，我们还需要弄清楚一个关键信息：这块屏幕在I2C总线上的“门牌号”，也就是设备地址。

3.1 为何需要扫描I2C地址？

I2C总线允许多个设备挂载在同两条线上，那么主设备（Arduino）如何区分它们呢？靠的就是每个从设备都有一个唯一的7位或10位地址（常用7位）。OLED屏幕的I2C地址通常是出厂预设的，常见的有0x3C或0x3D（十六进制表示）。但这个地址有时可以通过模块上的电阻进行配置修改。所以，在安装专用驱动库之前，先扫描确定地址是避免后续“屏幕不亮”问题的关键一步。

3.2 运行I2C扫描程序

Arduino社区提供了一个非常通用的I2C扫描示例程序。打开你的Arduino IDE，按照以下步骤操作：

打开示例代码：点击菜单栏的文件->示例->Wire->Scanner。Wire库是Arduino内置的I2C核心库，这个Scanner示例就是用来搜索总线上所有设备的。
上传代码：用USB线连接Arduino和电脑，选择正确的板卡型号（如 Arduino Uno）和端口，然后点击上传按钮。
查看结果：上传成功后，打开工具->串口监视器。确保右下角的波特率设置为9600（扫描程序默认使用此波特率）。这时，你应该能看到串口监视器开始输出信息。

如果一切正常，且OLED屏已正确连接，你会看到类似这样的输出：

I2C Scanner Scanning... Device found at address 0x3C ! done

这行“Device found at address 0x3C”就是你要找的关键信息！请记下这个地址（可能是0x3C或0x3D）。

常见问题排查：
如果显示“No I2C devices found”：
检查接线：这是最常见的原因。重新拔插一遍杜邦线，确保接触良好，尤其是SDA和SCL没有接反。
检查电源：确认VCC是否已连接，GND是否共地。可以尝试将VCC从3.3V换到5V（反之亦然），看是否是电压问题。
检查模块：极少数情况下模块可能损坏。
如果发现多个地址：说明你的总线上挂了不止一个I2C设备，这是正常现象。请根据设备数量判断哪个是你的OLED屏地址（通常OLED是0x3C）。

3.3 安装OLED驱动库

知道了地址，接下来就需要让Arduino具备驱动这块屏幕的能力。这里根据你的OLED驱动芯片型号，选择安装对应的库。

如何判断芯片型号？最直接的方法是看OLED模块背面，通常会用丝印标明“SSD1306”或“SH1106”。如果看不到，可以尝试先安装SSD1306的库进行测试，因为它的普及率更高。如果测试不成功，再换SH1106库。

我们将使用Arduino IDE的库管理器进行安装，这是最方便的方法：

打开库管理器：点击工具->管理库...。
搜索库：
- 对于SSD1306芯片：在搜索框输入“Adafruit SSD1306”，找到由Adafruit Industries发布的库，点击安装。这个库功能强大且稳定。
- 对于SH1106芯片：输入“SH1106”，可以找到由“olikraus”或“winneymj”等人维护的库，选择一个评分较高的进行安装。教程原文中提到的winneymj/SH1106库也可以在GitHub找到，但通过库管理器安装更简单。
安装依赖库：在安装Adafruit SSD1306时，IDE通常会提示你需要同时安装Adafruit GFX Library（图形核心库）和Adafruit BusIO（总线IO支持库）。务必点击“全部安装”来安装这些依赖库。GFX库提供了画点、线、圆、文字等基本图形功能，是显示的基础。

注意事项：库的版本有时会带来兼容性问题。如果后续测试发现编译报错，可以尝试在库管理器中查看已安装库的版本，或者回退到稍旧一些的稳定版本。Adafruit的库生态维护得很好，通常使用最新版即可。

库安装完成后，重启一下Arduino IDE，以确保所有新库被正确加载。至此，软件环境就搭建好了。

4. 基础功能测试与驱动验证

安装好库之后，我们不要急于显示复杂内容，先运行一个最简单的测试程序，验证整个链路（硬件连接、库安装、地址配置）是否全部通畅。这就像给新设备做一次“开机自检”。

4.1 运行官方示例测试

我们将使用刚安装的库自带的示例程序。这里以SSD1306库为例（SH1106库操作类似）：

打开示例：点击文件->示例-> 在示例列表中，找到Adafruit SSD1306（或你安装的SH1106库名）-> 选择ssd1306_128x64_i2c（或其他类似名称，确保是I2C接口、128x64分辨率的示例）。
关键修改：设置I2C地址：打开示例代码后，你需要找到设置地址的地方。通常是在setup()函数之前，有一行类似于#define SCREEN_ADDRESS 0x3D的代码。将其中的0x3D修改为你之前通过扫描得到的地址（很可能是0x3C）。这是整个测试成败的关键一步！
```
// 修改前（示例默认可能是0x3D） #define SCREEN_ADDRESS 0x3D // 修改后（根据你的扫描结果） #define SCREEN_ADDRESS 0x3C
```

检查分辨率定义：在同一区域，确认分辨率定义是否正确，对于1.3寸屏通常是128x64：

#define SCREEN_WIDTH 128 // OLED display width, in pixels #define SCREEN_HEIGHT 64 // OLED display height, in pixels

上传并观察：保存代码，选择正确的板和端口，点击上传。上传成功后，你的OLED屏幕应该会亮起，并显示Adafruit的Logo以及一些测试图形和文字（如画线、画圆、显示“Hello World!”）。

如果屏幕成功点亮并显示内容，那么恭喜你，最困难的部分已经过去了！你的硬件连接、库安装和地址配置都是正确的。

4.2 测试失败问题深度排查

如果屏幕没有如预期点亮，别着急，这是学习过程中最有价值的部分。请按照以下步骤系统排查：

电源与背光：首先确认屏幕是否通电。有些OLED在无信号时处于几乎全黑状态。仔细观察屏幕边缘或特定角度，看是否有非常微弱的亮光（OLED的特性）。或者，在代码中尝试增加屏幕亮度设置（如果库函数支持）。
复查I2C地址：这是最高频的错误原因！再次运行I2C扫描程序，百分之百确认你记下的地址，并确保在测试代码中已修改正确。0x3C和0x3D就差一位，很容易看错。
复查库与芯片匹配：确认你安装的库是否与屏幕驱动芯片匹配。SSD1306的库驱动不了SH1106，反之亦然。症状可能是屏幕亮但显示乱码、花屏，或者完全不亮。如果不确定芯片型号，可以分别用SSD1306和SH1106的示例程序都试一次。
检查接线稳定性：杜邦线接触不良是创客项目的“隐形杀手”。用手轻轻按压各个连接点，或者重新插拔一次。有条件的话，可以使用面包板或焊接来获得更稳定的连接。
检查代码中的分辨率：确保代码中定义的SCREEN_WIDTH和SCREEN_HEIGHT与你的物理屏幕分辨率一致。128x64的定义用在128x32的屏幕上会导致显示异常。
尝试重置OLED：有些OLED模块有一个额外的RESET引脚。如果它存在且未被连接，需要在代码中通过一个GPIO引脚对其进行控制，或者在初始化前给出一个硬件复位信号。查看你所使用库的文档，看是否需要此操作。

实操心得：我遇到过最诡异的一次问题是，屏幕时亮时不亮。最后发现是SDA线内部接触不良，稍微一动就断开。所以，当出现随机性问题时，首要怀疑对象就是物理连接。备一套质量好的杜邦线或直接使用焊接，能省去很多调试的烦恼。

5. 显示自定义图片：从图片到代码

基础测试通过，意味着我们已经掌握了让屏幕“听话”的方法。接下来，就是实现本教程最有趣的部分：让这块小屏幕显示你喜欢的任意图片。这个过程本质上是将一张普通的JPG或PNG图片，转换成单片机能够理解和显示的二进制位图数据。

5.1 图片预处理：为OLED量身定制

OLED屏幕是单色（或双色，如黄蓝）的，且分辨率很低（128x64）。直接扔一张彩色高清照片上去是行不通的。在转换之前，我们需要对图片进行预处理，以达到最佳显示效果。

尺寸裁剪与缩放：首先，将你的图片裁剪或缩放至128像素宽，64像素高。这是屏幕的物理分辨率。可以使用Photoshop、GIMP，甚至Windows自带的画图工具（选择“重新调整大小”，取消“保持纵横比”，然后输入像素值）。
转换为黑白二值图：因为我们的OLED是单色（每个像素点只有亮/灭两种状态），所以需要将图片处理成高对比度的黑白图，也称为“1位位图”。
- 方法：在图像处理软件中，将图片模式改为“灰度”，然后使用“阈值”或“亮度/对比度”调整工具，拖动滑块，使得图片的轮廓和主要细节清晰可见，背景尽可能干净。目标是让需要显示的部分变成纯白色，背景变成纯黑色。
- 技巧：选择线条简洁、轮廓分明的图标、Logo或文字图片，效果会更好。人像或复杂风景图需要经过精心调整阈值才能有可辨别的效果。

5.2 使用在线工具生成位图数组

手动编写一个128x64=8192个像素点的数据是不现实的。幸运的是，有非常方便的在线工具可以帮我们完成这个转换。教程中提到的diyusthad.com/image2cpp是一个经典选择，国内访问也基本顺畅。

操作步骤详解：

打开网站并上传：在浏览器中打开https://diyusthad.com/image2cpp。点击 “Choose images” 按钮，上传你预处理好的128x64黑白PNG图片。
关键设置（务必按此配置）：
- Canvas size：这个应该自动匹配为你的图片尺寸（128x64），无需改动。
- Background：选择Transparent（透明）或White。这里指的是工具如何看待图片中“非显示”的部分。通常保持默认即可。
- Brightness：拖动滑块，实时预览转换效果，确保你的图片主体清晰。
- 最重要的设置 - Scan Method：选择Vertical - 1 bit per pixel。这是Arduino SSD1306/GFX库最常用的数据排列方式（垂直扫描，每像素1比特）。
- 最重要的设置 - Code Output Format：选择Arduino Code。
- 其他设置：Draw Mode选择Vertical，Invert Image Colors根据你的需要勾选（如果希望白底黑字就勾选）。Preview区域可以实时看到转换后的效果。
生成并复制代码：点击网站下方的 “Generate Code” 按钮。在右侧的 “Generated Code” 框中，你会看到一大段以const unsigned char epd_bitmap_[] PROGMEM = { ... };开头的C语言数组定义代码。这就是代表你图片的二进制数据。点击 “Copy Code” 按钮复制全部代码。

5.3 整合代码并上传

现在，我们将这段图片数据“注入”到一个Arduino程序中。

创建新程序框架：在Arduino IDE中新建一个空白项目。

包含必要的库：在代码开头，引入你测试时使用的显示库和图形库。

#include <Wire.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h> // 如果是SH1106，则改为对应的头文件

定义屏幕参数与对象：和测试程序一样，定义地址、分辨率，并创建显示对象。

#define SCREEN_WIDTH 128 #define SCREEN_HEIGHT 64 #define OLED_ADDR 0x3C // 替换为你的地址 Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1); // -1表示无RESET引脚

粘贴图片数据：将从网站复制的整段const unsigned char ...数组定义代码，粘贴到setup()函数之前的位置。

编写setup()和loop()函数：

void setup() { Serial.begin(9600); // 初始化OLED，如果失败则打印错误并无限循环 if(!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR)) { Serial.println(F("SSD1306 allocation failed")); for(;;); // 死循环，阻止程序继续 } Serial.println("OLED Init OK!"); // 清空屏幕缓冲区 display.clearDisplay(); // 绘制位图 // 参数：x坐标, y坐标, 位图数据, 位图宽度, 位图高度, 颜色(1为白色，0为黑色) display.drawBitmap(0, 0, epd_bitmap_你的图片数组名, 128, 64, SSD1306_WHITE); // 将缓冲区内容发送到屏幕显示 display.display(); delay(2000); // 显示2秒 } void loop() { // loop函数留空，图片只显示一次 // 你也可以在这里添加动画或交替显示多张图片的逻辑 }

关键点：drawBitmap函数中的epd_bitmap_你的图片数组名需要替换成你从网站复制的代码中实际的数组变量名，通常是epd_bitmap_后跟一个名字。

编译与上传：检查无误后，编译并上传代码。上传成功后，你的自定义图片就应该出现在OLED屏幕上了！

避坑技巧：
数组名冲突：如果你要显示多张图片，每张图片转换后会生成不同的数组名（如epd_bitmap_img1,epd_bitmap_img2）。在代码中调用时务必使用正确的名字。
内存不足：一张128x64的全屏黑白位图，需要128 * 64 / 8 = 1024字节的存储空间。Arduino UNO的SRAM（运行内存）只有2KB，如果定义多个大型全屏位图数组，很容易导致内存不足，程序行为异常。解决方法：1) 将图片数据存放在PROGMEM（程序存储器）中，网站生成的代码已经使用了PROGMEM关键字，这很好；2) 减少图片数量或尺寸；3) 使用压缩算法（对新手较复杂）。
显示位置：drawBitmap(0, 0, ...)中的前两个参数是图片左上角在屏幕上的坐标。你可以通过修改它们来调整图片显示的位置。

通过以上步骤，你已经完成了从图片处理、数据转换到代码整合的完整流程。这不仅仅是显示一张图片，更是理解了单片机图形显示的基本原理：将视觉图像数字化为一串二进制数据，再通过驱动程序逐点“绘制”到屏幕上。

6. 进阶应用与创意拓展

掌握了显示静态图片后，你的OLED屏就不再只是一块简单的显示器，而是一个可以交互、可以动态变化的项目核心输出设备。下面介绍几个进阶方向，帮你打开思路。

6.1 显示动态信息与传感器数据

这是OLED屏最实用的场景。你可以结合各种传感器，将实时数据直观地显示出来。

示例：温湿度计假设你有一个DHT11温湿度传感器（同样可以使用I2C接口的版本，以节省引脚）。

安装DHT库：通过库管理器安装DHT sensor library。
编写代码逻辑：在loop()函数中，周期性地读取传感器数据，然后使用display.setTextSize(),display.setCursor(),display.print()等函数将数据打印到屏幕上。
优化显示：为了避免屏幕闪烁，可以采用“部分更新”的策略。先display.clearDisplay()清空缓冲区，然后绘制所有元素（如标题、图标、数据），最后再调用display.display()一次性刷新。而不是读一次数据就清屏刷新一次。

void loop() { float h = dht.readHumidity(); float t = dht.readTemperature(); display.clearDisplay(); display.setCursor(0, 0); display.setTextSize(1); display.print("Temp: "); display.print(t); display.println(" C"); display.setCursor(0, 20); display.print("Humi: "); display.print(h); display.println(" %"); // 这里可以画一个简单的小图标，比如温度计符号 // display.drawBitmap(...); display.display(); delay(2000); // 每2秒更新一次 }

6.2 制作简单动画与帧序列

动画的本质是快速连续地显示一系列静态图片。利用drawBitmap和delay函数，你可以轻松实现。

准备帧图片：用图像处理软件制作一系列连续的、尺寸相同的黑白图片（比如一个跳动的小球的不同位置）。
转换每一帧：使用image2cpp工具将每一帧图片都转换为位图数组，在代码中为每个数组起好名字（如frame0,frame1,frame2）。

创建动画循环：在loop()函数中，按顺序显示每一帧，并加上一个短暂的延时。

const unsigned char* frames[] = {frame0, frame1, frame2, frame3}; // 指针数组 int frameCount = 4; int currentFrame = 0; void loop() { display.clearDisplay(); display.drawBitmap(0, 0, frames[currentFrame], 128, 64, WHITE); display.display(); currentFrame = (currentFrame + 1) % frameCount; // 循环到下一帧 delay(100); // 控制动画速度，100毫秒一帧 }

注意事项：动画帧越多、分辨率越高，占用的内存就越大。需要精心设计动画，控制帧数和图片复杂度。也可以考虑使用程序绘制（如用drawCircle画一个移动的圆）来代替预渲染位图，这样更节省内存。

6.3 多页面切换与菜单系统

对于功能复杂的项目，你可以设计一个简单的菜单系统。

定义状态：用一个全局变量（如int menuPage = 0;）来记录当前所在的页面。
添加输入：连接一个按钮或旋转编码器到Arduino。
根据状态显示：在loop()函数中，根据menuPage的值，使用if...else if...或switch...case语句来决定调用哪个显示函数。
处理输入：检测按钮动作，并相应地改变menuPage的值。

void drawPage0() { /* 显示主页面，如传感器数据 */ } void drawPage1() { /* 显示设置页面 */ } void drawPage2() { /* 显示关于页面 */ } void loop() { if(digitalRead(BUTTON_PIN) == LOW) { // 假设按钮按下为低电平 delay(50); // 简单消抖 if(digitalRead(BUTTON_PIN) == LOW) { menuPage = (menuPage + 1) % 3; // 在0,1,2三个页面间循环 while(digitalRead(BUTTON_PIN) == LOW); // 等待按钮释放 } } display.clearDisplay(); switch(menuPage) { case 0: drawPage0(); break; case 1: drawPage1(); break; case 2: drawPage2(); break; } display.display(); }

6.4 性能优化与内存管理心得

随着项目复杂度的提升，内存和性能会成为瓶颈。这里分享几个实战心得：

使用F()宏包装字符串：在display.print()中直接打印字符串常量（如display.print("Hello")）会将这些字符串复制到宝贵的SRAM中。使用F()宏可以将它们保留在更大的Flash程序存储器中：display.print(F("Hello"));。对于任何不变的提示文本，都应养成这个习惯。
避免频繁清屏：clearDisplay()会填充整个显示缓冲区（1024字节），频繁调用可能影响性能。对于局部更新（如只改变一个数字），可以尝试用fillRect函数先“擦除”旧内容，再绘制新内容。
精简图形：自定义位图是内存消耗大户。尽量使用几何图形绘制函数（drawLine,drawRect,drawCircle）来组合成界面元素，而不是全部使用位图。
分时操作：如果程序还需要处理其他耗时任务（如网络请求、复杂计算），可以考虑将屏幕刷新放在非阻塞的定时器中断中，或者确保刷新频率不会太高（如每秒刷新1-5次对于数据显示足够了）。

从点亮第一盏LED到让一块精致的屏幕按照你的想法显示信息，这种成就感是驱动我们不断探索的动力。I2C OLED只是一个起点，它所代表的串行通信思想和图形显示框架，在你接触更复杂的传感器、屏幕甚至物联网项目时，会反复出现。希望这篇超详细的教程，不仅能帮你搞定眼前的这块小屏幕，更能为你打开嵌入式显示世界的大门。剩下的，就交给你的创意去发挥了。