树莓派5搭建低成本媒体中心：Jellyfin与Kodi混合方案实战
2026/8/19 4:18:29
1. 项目概述：为什么要在Arduino上折腾OLED位图？
如果你玩过Arduino，大概率用过OLED屏幕来显示几行文字或者简单的几何图形。但当你想要展示一个Logo、一个自定义图标，或者一个游戏里的小角色时，仅仅靠画线画圆就显得捉襟见肘了。这时，位图（Bitmap）就成了必需品。所谓位图，就是把图像上的每一个像素点，用“亮”或“灭”（对应1或0）的信息存储下来，形成一个二维的数据数组。把这个数组按正确的顺序发送给OLED，屏幕上就能呈现出你想要的任何图案。
这听起来简单，但实际操作起来，从一张电脑上的图片，到最终在128x64像素的小屏幕上亮起来，中间隔着好几道坎。你需要考虑图片的尺寸、颜色模式转换、数据存储格式，以及如何高效地将数据从Arduino的内存或存储空间搬运到OLED的显存里。市面上常见的教程要么只给个代码让你“能用”，要么原理讲得云里雾里。我折腾过不少项目，从简单的状态图标到复杂的动画精灵（Sprite），踩过不少坑，也总结了一套从入门到精通的流程。这篇文章，我就带你彻底搞懂在Arduino上玩转OLED位图的完整链条，不仅告诉你每一步怎么做，更解释清楚背后的“为什么”，让你能举一反三，应用到自己的创意项目中去。
2. 核心原理与准备工作
2.1 OLED显示驱动与通信基础
绝大多数Arduino项目使用的OLED屏，都是基于SSD1306或SH1106这类驱动芯片。它们内部有一块“图形显示数据RAM”（GDDRAM），你可以把它想象成一块画布。这块画布在物理上被划分成若干“页”（Page），对于常见的128x64屏幕，通常是8页，每页8行像素，共64行。每一页横向有128列。数据以字节为单位写入，一个字节的8个比特控制着某一列上、属于当前页的8个垂直像素的亮灭。
通信方式上，I2C和SPI是最常见的两种。I2C接线简单（只需SDA、SCL两根数据线），但速度较慢；SPI需要更多线（MOSI, SCK, CS, DC等），但刷新率高，适合动态图形。选择哪种，取决于你的项目对刷新速度的需求和引脚资源的紧张程度。对于静态位图或简单动画，I2C完全足够；如果是快速滚动的游戏画面，SPI会是更好的选择。
2.2 位图数据的本质：从图片到字节数组
我们电脑上的图片（JPG, PNG）是高度压缩、带有颜色信息的文件，而单色OLED只需要每个像素是“开”或“关”。因此，第一步是转换。这个过程通常被称为“取模”。
- 尺寸调整：首先，你必须将图片的尺寸裁剪或缩放至目标OLED屏幕的分辨率以内，例如128x64。如果图片比屏幕大，信息会丢失；如果太小，则需要考虑在屏幕上的显示位置。
- 二值化：将彩色或灰度图片转换为纯粹的黑白二值图像。这里有个关键技巧：阈值的选择。对于对比度不强的图片，直接转换可能效果很差。我通常会用图像处理软件（如Photoshop或免费的GIMP）先调整对比度和亮度，再进行二值化，这样得到的轮廓更清晰。
- 取模软件与方向：你需要一个工具将二值图像转换为C语言数组。常用的有
LCD Assistant、Img2Code在线工具，或者一些库自带的转换脚本。这里最大的坑是扫描方向。取模软件需要知道：数据是按列从上到下扫描，还是按行从左到右扫描？一个字节内的8个比特，是代表一列像素（MSB在上还是在下），还是代表一行中的8个连续像素？这个设置必须与后续你使用的显示库的drawBitmap函数所期望的数据格式严格匹配，否则显示出来会是乱码或镜像。我个人的经验是，对于最常用的Adafruit_SSD1306库，其drawBitmap函数通常期望垂直字节、高位在上的格式。这意味着，数组中的一个字节对应屏幕上垂直连续的8个像素点，且字节的最高位（bit7）对应最上方的像素。
2.3 库的选择与安装
工欲善其事，必先利其器。对于Arduino OLED，有几个库是绕不开的：
- Adafruit_SSD1306：这是最通用、文档最全的库，支持SSD1306和SH1106，兼容I2C和SPI。它提供了高级的图形函数，包括我们最需要的
drawBitmap。 - Adafruit_GFX：这是图形核心库，
Adafruit_SSD1306依赖于它。它定义了画点、线、圆、矩形以及绘制位图的基本算法。 - U8g2：另一个功能极其强大的库。它的优势在于支持海量的显示控制器和字体，其自带的图形绘制函数性能在某些情况下更优。但对于初学者，其API稍显复杂。
我建议从Adafruit_SSD1306开始，生态好，例子多。在Arduino IDE的库管理中直接搜索安装即可，它会自动安装依赖的Adafruit_GFX和Adafruit_BusIO库。
注意：安装库时，务必查看库的示例（Examples）。
Adafruit_SSD1306库提供了丰富的示例，其中就有专门展示位图的ssd1306_128x64_i2c示例下的ssd1306_128x64_i2c草图，这是最好的起点。
3. 实战：从零显示一张自定义位图
3.1 第一步：准备你的位图图像
假设我们想显示一个自定义的“Wi-Fi信号”图标，大小是16x16像素。
- 用任何绘图软件（甚至Windows画图）创建一个16x16像素的新图像。
- 用纯黑色（RGB 0,0,0）作为背景，纯白色（RGB 255,255,255）画出你的Wi-Fi图标。记住：在Adafruit库的默认设置下，绘制颜色（白色）对应像素“点亮”，背景色（黑色）对应像素“熄灭”。这一点和我们的直觉（黑底白字）是吻合的。
- 将图片保存为PNG或BMP格式。
3.2 第二步：使用取模软件生成数组
这里我以经典的LCD Assistant软件为例。
- 打开
LCD Assistant。 File -> Load Image，加载你的16x16 PNG图片。- 进行关键设置：
Byte orientation: 选择VerticalSize: 由于是16x16，所以Width填16，Height填16。软件会自动计算所需字节数：16 * (16/8) = 16 * 2 = 32字节。Vertical栏的Most significant bit on top需要勾选（这对应高位在上）。Preview可以查看取模效果，确保你的图标轮廓清晰。
- 点击
File -> Save output，保存为一个.c或.h文件。用文本编辑器打开，你会看到类似这样的数组：const unsigned char myWiFiIcon [] PROGMEM = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };实操心得：
PROGMEM关键字至关重要。它告诉编译器将这个数组存储在Arduino的程序存储器（Flash）中，而不是宝贵的静态随机存取存储器（SRAM）里。对于动辄几百、几千字节的位图数据，如果放在SRAM里，Arduino Uno那2KB的SRAM很快就会耗尽，导致程序行为异常。这是新手最容易忽略的导致系统不稳定的问题之一。
3.3 第三步：编写Arduino草图
接下来，我们将数据数组整合到代码中，并调用库函数显示它。
#include <Wire.h> #include <Adafruit_GFX.h> #include <Adafruit_SSD1306.h> // 定义OLED屏幕尺寸 #define SCREEN_WIDTH 128 #define SCREEN_HEIGHT 64 #define OLED_RESET -1 // 如果屏幕有复位引脚则填写其引脚号，否则填-1 Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET); // 将取模软件生成的数组粘贴到这里 const unsigned char myWiFiIcon [] PROGMEM = { // 这里是你实际的32字节数据，上面那串0只是占位符 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }; void setup() { Serial.begin(9600); // 初始化OLED，I2C地址通常是0x3C或0x3D if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { Serial.println(F("SSD1306 allocation failed")); for(;;); // 初始化失败，程序挂起 } // 清屏 display.clearDisplay(); // 绘制位图。参数：(x坐标, y坐标, 位图数据指针, 宽度, 高度, 颜色) display.drawBitmap(10, 10, myWiFiIcon, 16, 16, SSD1306_WHITE); // 执行显示 display.display(); } void loop() { // 空循环，静态显示 }代码关键点解析：
display.drawBitmap(10, 10, myWiFiIcon, 16, 16, SSD1306_WHITE);：这是核心函数。(10,10)是图标左上角在屏幕上的坐标。myWiFiIcon是数据数组。16,16是图标的宽和高。SSD1306_WHITE表示用白色（点亮像素）绘制。display.display();：所有通过drawBitmap、drawPixel等函数进行的绘制操作，都只是在内存中的一个缓冲区里进行。必须调用display()，才会将缓冲区的内容一次性发送到OLED硬件上显示出来。这是一个双缓冲机制，可以避免屏幕闪烁。
3.4 第四步：进阶技巧——显示大尺寸位图与动画
显示大于屏幕的位图： 如果你想显示一张比屏幕大的图片（比如一个横向长图），drawBitmap函数本身不会自动处理裁剪。你需要自己计算。一种常见的做法是，将大图分割成多个与屏幕等宽或等高的片段，然后只将当前需要显示的部分数据传给drawBitmap。这涉及到更复杂的数据管理和取模策略。
创建动画（Sprite）： 动画的本质是连续显示多张略有差异的位图。例如，一个奔跑的小人可以有4帧。你需要准备4个位图数组。
const unsigned char runFrame1[] PROGMEM = {...}; const unsigned char runFrame2[] PROGMEM = {...}; const unsigned char runFrame3[] PROGMEM = {...}; const unsigned char runFrame4[] PROGMEM = {...}; const unsigned char* runFrames[] = {runFrame1, runFrame2, runFrame3, runFrame4}; int currentFrame = 0; void loop() { display.clearDisplay(); // 绘制当前帧 display.drawBitmap(xPos, yPos, runFrames[currentFrame], spriteWidth, spriteHeight, SSD1306_WHITE); display.display(); // 更新到下一帧 currentFrame = (currentFrame + 1) % 4; // 控制动画速度 delay(100); }这里的关键是清屏和重绘。每次循环先clearDisplay()清除上一帧，再绘制新的一帧，最后display()。通过控制delay的时间来控制动画速度。更高级的做法是使用非阻塞定时（如millis()），让动画与其他任务（如读取传感器）并行不悖。
4. 内存优化与高级策略
当你的项目需要大量位图时（比如一个游戏），内存管理就成了头等大事。
4.1 使用PROGMEM与F()宏
我们已经用了PROGMEM来存储位图数据到Flash。但在使用这些数据时，必须通过特殊的函数来读取，因为Arduino的CPU不能直接从Flash读取数据。Adafruit_GFX库的drawBitmap函数内部已经帮我们处理了这个问题，它知道如何从PROGMEM中读取数据。
另一个技巧是使用F()宏来将字符串常量也存到Flash中，以节省SRAM。例如：
Serial.println(F("Initializing OLED...")); // 字符串存储在Flash4.2 数据压缩
对于单色位图，有一种简单的“游程编码”（RLE）压缩方式。例如，连续20个0xFF（白色）可以存储为[0xFF, 20]而不是20个0xFF。但这需要你编写额外的解压缩函数，并在绘制前解压到缓冲区，会消耗CPU时间和一些SRAM作为解压缓冲区。这是一种典型的“以时间换空间”的策略。对于复杂的图形，压缩率可能很高，但对于简单的图标，可能得不偿失。我个人的经验是，除非SRAM真的告急（例如在Uno上做复杂游戏），否则优先使用原始的PROGMEM数组，代码更简单可靠。
4.3 分页加载与动态生成
对于极大尺寸的静态图片（如开机Logo），可以考虑在初始化时，分多次将其从Flash加载到OLED的GDDRAM中，而不是一次性通过Arduino的缓冲区中转。这需要对SSD1306驱动器的底层命令有更深入的了解，直接操作其页地址和列地址指针。
另一种思路是动态生成图形。比如，一个电池电量图标，可以根据ADC读取的电压值，实时计算需要填充的矩形区域大小，并用fillRect函数绘制，而不是准备5张不同的位图。这能极大节省存储空间。
5. 常见问题排查与调试技巧
在实际操作中，你几乎一定会遇到显示不正常的情况。下面是一个快速排查指南：
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 屏幕全白/全黑/乱码 | 1. 接线错误（SDA/SCL接反，电源接错）。 2. I2C地址不正确。 3. 屏幕初始化失败。 | 1. 用万用表检查接线和电源电压（通常是3.3V或5V，看屏幕型号）。 2. 使用I2C扫描程序（Arduino IDE有示例 Wire -> scanner）查找正确的设备地址（0x3C或0x3D）。3. 检查 begin()函数返回值，并确保库已正确安装。 |
| 位图显示为乱码或错位 | 1.取模方向/格式错误（最常见）。 2. 位图宽高参数传递错误。 3. 坐标超出屏幕范围。 | 1.这是重中之重！核对取模软件的Byte orientation（Vertical/Horizontal）和MSB/LSB设置，确保与库函数要求一致。可以先用库自带的示例位图测试，确保硬件和库本身没问题。2. 仔细检查 drawBitmap函数中的宽度和高度值，必须与取模时设置的尺寸完全一致。3. 确保绘制坐标 (x,y)加上位图宽高后没有超出屏幕边界。 |
| 显示内容闪烁 | 1. 在loop()中频繁调用clearDisplay()和display()，且中间没有足够的延时。2. 绘制逻辑太复杂，单帧耗时过长。 | 1. 对于静态内容，只在setup()中绘制一次。对于动画，考虑使用双缓冲以外的技术，或只局部更新变化区域（部分刷新），但这需要更复杂的库或自行实现。2. 优化绘图代码，减少不必要的绘制操作。使用 fillRect清除局部区域代替全局clearDisplay。 |
| 程序编译通过但上传后无反应，或行为异常 | SRAM耗尽（特别是使用了大量未加PROGMEM的位图数组）。 | 1. 在Arduino IDE中查看编译输出信息，关注“全局变量使用了xxx字节的SRAM”。Uno只有2048字节，必须精打细算。 2. 确保所有大的常量数组（如图像、字体）都使用了 PROGMEM。3. 减少全局变量，尽量使用局部变量。 |
| 动画卡顿、不流畅 | 1.loop()中delay()时间过长。2. 绘图运算量太大，每帧时间超过预期。 | 1. 使用millis()进行非阻塞定时，将动画更新与主循环解耦。2. 简化图形，或使用更快的通信方式（如SPI代替I2C）。 3. 使用性能分析工具（如简单的 micros()计时）找出耗时最长的函数。 |
调试心法：当显示异常时，采用隔离法。首先，运行一个最简单的、不包含你自定义位图的库示例（比如ssd1306_128x64_i2c里的ssd1306_128x64_i2c），确保硬件和基础库工作正常。然后，将示例中的位图数组替换成你的数组，但保持其他代码不变。如果此时出问题，那100%是位图数据或参数的问题。如果正常，再逐步将你的逻辑代码合并进来。这个方法能帮你快速定位问题是出在硬件/驱动层，还是应用逻辑层。
6. 项目构思与扩展应用
掌握了基础的单张位图显示后，你可以将这些技能组合起来，实现更酷的项目：
- OLED游戏机：结合几个按钮，你可以制作一个简单的贪吃蛇、Flappy Bird或打飞机游戏。核心就是管理多个精灵（蛇身、鸟、子弹）的位置和状态，并在每一帧重新绘制。
- 动态数据仪表盘：将传感器数据（温度、湿度、速度）用自定义的仪表盘或进度条图形来显示，比纯数字更直观。这需要将数据值映射到位图的显示高度或长度上。
- 图标菜单系统：为你的设备制作一个图形化菜单。每个菜单项用一个图标表示，通过编码器或按钮切换焦点（高亮选中项）。这涉及到状态机和界面层的管理。
- 自定义字体与中文显示：本质上，每个汉字就是一张复杂的位图。你可以使用取模软件为常用汉字生成字库数组，然后像显示位图一样，根据字符编码查找并绘制对应的字模数据。网上也有现成的汉字库可供使用。
- 与ESP32等高性能MCU结合：如果你觉得Arduino Uno的性能或内存有限，可以尝试使用ESP32。它有更多的RAM和Flash，甚至可以通过SPI RAM来存储海量图形数据，还能连接Wi-Fi从网络下载图片显示，实现真正的动态信息展示。
折腾OLED位图的过程，是一个深入理解嵌入式图形显示底层原理的绝佳途径。从最初的“点亮屏幕”到最终让自定义的图形流畅舞动，每一步问题的解决都会带来巨大的成就感。最重要的是，不要被一开始的乱码吓退，按照本文的步骤耐心排查，你一定能让那块小小的屏幕，完美呈现出你脑海中的创意。我个人的体会是，图形化交互的魅力是无穷的，它能将冷冰冰的传感器数据变成有温度的可视化信息，极大提升项目的完成度和可玩性。最后再分享一个小技巧：在规划图形时，尽量使用2的幂次方尺寸（如8x8, 16x16, 32x32），这样在内存对齐和计算上会更方便，有时还能利用位运算来优化绘制速度。