微型OLED显示模块是在Raspberry Pi项目中添加小屏幕的好方法。它们有各种尺寸,但常见尺寸包括128×32 and 128×64像素。较便宜的像素具有白色,黄色或蓝色的单色像素。我的设备有白色像素,并使用I2C接口,该接口仅需要将四根线连接到Pi。
在本教程中,我’ll解释我如何设置我的 0.96″使用Pi的OLED显示模块’I2C接口。设置完成后,很容易使用Python放置文本,绘制形状,甚至显示简单的图像和动画。
OLED模块
我的OLED 显示模块是0.96″I2C IIC SPI串行128X64 OLED 液晶屏 LED显示模块。


它有四个针脚。两个是电源(Vcc和Gnd),两个是I2C接口(SDA和SCL)。在使用插头之前,可能需要先将其焊接。
更新操作系统
与我所有的项目一样,我从创建具有最新Raspbian映像的SD卡开始。然后我通过运行以下命令来确保它是最新的:
sudo apt update sudo apt upgrade
此步骤可能需要 几分钟(如果有很多要更新的软件包),但通常可以节省将来的麻烦。
显示模块设置
我的屏幕有四个引脚,两个用于电源,另外两个用于I2C接口。

我直接将它们连接到Raspberry Pi’s 通用输入输出头使用以下方案:
OLED引脚 | Pi 通用输入输出引脚 | 笔记 |
---|---|---|
Vcc | 1 * | 3.3V |
nd | 14 ** | 地面 |
SCL | 5 | I2C SCL |
SDA | 3 | I2C SCA |
* 您 can connect the Vcc pin to either Pin 1 or 17 as they both provide 3.3V.
** 您 can connect the nd pin to either Pin 6, 9, 14 , 20, 25, 30, 34 or 39 as they all provide 地面.
启用I2C接口
The I2C 接口 is disabled by default so you need to enable it. 您 can do this within the raspi-config tool 上 the command line by running :
sudo raspi-config
有关此步骤的其他详细信息,请参阅我的操作方法 在Raspberry Pi上启用I2C接口 发布。
以下库可能已经安装,但无论如何都要运行以下命令以确保:
sudo apt install -y 蟒蛇3-dev sudo apt install -y 蟒蛇-smbus i2c工具 sudo apt install -y 蟒蛇3-pil sudo apt install -y 蟒蛇3-pip sudo apt install -y 蟒蛇3-setuptools sudo apt install -y 蟒蛇3-rpi.gpio
如果您使用的是Python 2,请改用以下命令:
sudo apt install -y 蟒蛇-dev sudo apt install -y 蟒蛇-smbus i2c工具 sudo apt install -y 蟒蛇-pil sudo apt install -y 蟒蛇-pip sudo apt install -y 蟒蛇-setuptools
除非您有充分的理由使用Python 2,否则我建议您使用Python 3。
查找OLED显示模块’s Address
安装了I2C库后,我使用了i2cdetect命令在I2C总线上查找模块。
i2cdetect -y 1
我得到以下结果:

这是一个好消息,因为它表明已检测到该设备的地址为“0x3c”。这是此类设备的默认十六进制地址。一世’我不知道为什么设备PCB提示地址是“0x78” when it is clearly “0x3c”.
如果您有原始的Model B Rev 1 Pi,请输入以下命令:
i2cdetect -y 0
安装OLED 蟒蛇库
为了显示文本,形状和图像,您可以使用Adafruit 蟒蛇库。它应该与所有基于SSD1306的显示器一起使用,包括它们自己的显示器 128×32 and 128×64 devices.
要安装该库,我们将克隆Adafruit git存储库。通过运行以下命令确保已安装git:
sudo apt install -y git
然后使用以下命令克隆存储库:
git clone //github.com/adafruit/Adafruit_Python_SSD1306.git
完成后,导航到库’s directory :
cd Adafruit_Python_SSD1306
并安装Python 2库:
sudo 蟒蛇 setup.py安装
和/或Python 3:
sudo 蟒蛇3 setup.py install
通过此过程,您可以将库包含在自己的Python脚本中。
示例Python脚本
现在,我们准备测试一些示例脚本。 Navigate into the “examples” directory :
cd 例子
在其中,您应该找到许多示例脚本,例如:
- 动画
- button.py
- image.py
- shapes.py
- stats.py
These 例子 can be run using :
蟒蛇 shapes.py
或使用Python 3:
蟒蛇3 shapes.py
The 例子 should give you 屏幕s that appear in the 例子 below :

通过修改这些脚本,您可以根据项目创建具有形状,图像和文本的图形。看看您是否能猜出是我从Google图片下载到我的Pi上的照片!
屏幕尺寸调整
阿达果示例假设您有一个128×32屏。他们仍然以128运行×64像素的屏幕,但最好在进行任何更复杂的操作之前进行更改。为此,只需编辑脚本并禁用128×通过在前面放置#字符来配置32行,并启用128×通过从前面删除#字符来删除第64行。脚本中的部分现在应如下所示:

如果要开始创建自己的图像以显示在屏幕上,则此步骤至关重要。
创建新图像
因此,您尝试了image.py示例,并想知道如何创建自己的图像?它’如果您具有Photoshop或GIMP之类的图像编辑应用程序,则非常简单。我更喜欢使用GIMP,因为它是免费的。
理想情况下,您希望图像为:
- 128×64 resolution
- 1位彩色(即黑白)
默认情况下,image.py示例会将图像转换为1位,但假定分辨率正确。
您’您会在脚本中注意到另一行,该行会调整图像的大小并进行转换,因此您可以加载图像而不必担心图像的大小和颜色。
加载图像并转换为1位颜色:
image = Image.open('happycat_oled_64.ppm').convert('1')
加载图像,调整大小并转换为1位:
image = Image.open('example.png').resize((disp.width, disp.height), Image.ANTIALIAS).convert('1')
您使用哪种技术取决于您。调整大小和转换会花费额外的处理时间,因此在高性能应用程序中,最好输入已经调整大小的脚本图像。
调整大小和转换图像
如果要加载图像或照片,则将其加载到图形应用程序中并执行以下步骤:
- 载入图片
- 调整大小/缩放到128×64
- 转换为1位彩色(单色)
- 导出为“.pbm” or “.png” file
- 复制到您的Pi上与Python脚本相同的位置
- 更新Python脚本以使用新文件
阿达果示例图片是“ppm” file because it is colour although it is converted to monochrome at the point it is 显示ed 上 the 屏幕. 阿达果 use 百万分之几 as the library also supports their colour OLED modules. If you don’没有彩色屏幕,可以切换到pbm或png。
我更喜欢创造“pbm”文件,因为它们是黑白的,文件要小得多。这也意味着您的Python脚本没有’不需要转换它们。该库可以处理这两种情况,只需确保在脚本中使用正确的文件名和扩展名即可。
提高I2C总线速度
如果每秒显示多个图像,则值得提高接口的总线速度,因为它可以提高性能。请看 更改Raspberry Pi I2C总线速度 发布。
故障排除
如果您的屏幕不’要工作,您应该从本教程的开头开始并逐步进行。这是要考虑的一些事情:
- 做过you enable I2C and instal “python-smbus” and “i2c-tools”?
- 四个模块的连接是否正确?您是否混淆了SDA和SCL?
- 做过“i2cdetect -y 1”给您I2C总线上显示器的地址?
- 如果您的屏幕使用的地址不是0x3c,您是否调整了Python脚本?
购买微型OLED屏幕
这些屏幕可从许多零售商处购买,因此请看一下并选择一个对您所在位置方便的屏幕:
像一些OLED一样仔细阅读说明 显示模块使用SPI接口而不是I2C。那些很好,但是你’需要使用其他教程才能使用该样式。
32条留言
谢谢马特。这是一个非常有用的教程。除了设置这些小屏幕外,关于这些小屏幕的信息很少。这是我阅读过的有关显示您自己的图像的最简洁,最详尽的教程。
你好,
感谢您提供有用的教程。
安装python库时出现问题。当我执行命令
sudo 蟒蛇 setup.py安装
我得到以下输出:
在/ tmp / tmpoaIjab中提取
追溯(最近一次通话):
文件“setup.py”, line 4, in
use_setuptools()
文件“/home/pi/Adafruit_Python_SSD1306/ez_setup.py ”,在use_setuptools中的第128行
返回_do_download(版本,download_base,to_dir,download_delay)
文件“/home/pi/Adafruit_Python_SSD1306/ez_setup.py ”,_do_download中的第108行
_build_egg(egg,archive,to_dir)
文件“/home/pi/Adafruit_Python_SSD1306/ez_setup.py ”,_build_egg中的第57行
使用archive_context(archive_filename):
文件“/usr/lib/python2.7/contextlib.py”,在__ent__中的第17行
返回self.gen.next()
文件“/home/pi/Adafruit_Python_SSD1306/ez_setup.py ”,第88行,在archive_context中
使用get_zip_class()(filename)作为存档:
文件“/usr/lib/python2.7/zipfile.py”__init__中的第770行
self._RealGetContents()
文件“/usr/lib/python2.7/zipfile.py”_RealGetContents中的第813行
引发BadZipfile,“文件不是zip文件”
zipfile.BadZipfile: 文件is not a zip file
库未安装。我该如何解决?谢谢!
文件丢失似乎存在问题。有人在Adafruit github页面上提出了此问题,他们已将问题分配给某人进行调查。 //github.com/adafruit/Adafruit_Python_SSD1306/issues/22。希望他们会尽快解决。
是否可以连接两个屏幕?
应该有可能,但是您需要一个允许您更改默认I2C地址的屏幕。有些人通过将两个触点焊接在一起来允许这样做。
嗨,伊凡,您可以获得一个I2C多路复用器来添加8个屏幕。我认为您可以让2个8通道多路复用器运行16个屏幕
马特-PCB表示0x78而您的原因’从i2c-tools重新读取0x3C是:
I2c工具将整个地址向左移动1(为R / W添加最后一位)。将0x3C左移1可得到0x78(显然也相反)。
祝一切顺利!
感谢您的解释。一世’ve刚刚对其进行了搜索并立即了解。这7位111100为0x3c,但一旦包含R / W位,则变为这8位1111000,即0x78。
我必须在安装脚本运行正常之前安装python3-dev。 * sudo apt-get安装python3-dev *
蟒蛇3-dev应该已经安装在最新的Raspbian映像中。
不在`-lite`图片中。
还需要`setuptools`,Image / PIL / pillow(?!)和RPi.GPIO,但是我不能’不能在此时安装它们,所以我暂时放弃了。
I’我刚刚在一个项目上使用了本指南,并进行了一些更新。我认为如果使用Raspbian Lite,则必须安装更多的库。
谢谢你的教程–引导我的屏幕并在大约30秒内运行
谢谢!
我试图通过屏幕的官方教程使它工作数小时,但这远不复杂,并且确实’nt work.
幸运的是,我找到了本教程,它使我免于浪费大量时间<3
你好!这真的很棒,我可以完美地工作。我想知道在哪里可以更改GPIO引脚,因为我想在那里设置我的继电器(分别是预见的设置)。
我不能’在代码中指定的任何位置都找不到引脚1,3,5,14。
谢谢你的帮助。
1 and 14 are 3.3V and 地面. 您 can use any of the other 功率 pins 上 the header :

另外只有一个3.3V引脚,也就是引脚17。有很多接地引脚。
The I2C pins are the defaults. 您 can configure a new software I2C 接口 by editing the /boot/config.txt file and adding :
dtoverlay=i2c-gpio,i2c_gpio_sda=5,i2c_gpio_scl=6
这将在/ dev / i2c-3处设置一个新接口。但是,我’我从来没有尝试过这个。
要在新界面上检测设备,可以使用:
i2cdetect -y 3
谢谢MATT,我编辑为config.txt并从i2cdetect -y 3命令获得了输出,但结果为空…表示没有检测到。
我假设使用i2c_gpio_sda = 5和i2c_gpio_scl = 6表示引脚5和6,我将这些更改为’s say 19 and 21?
再说一次,我读了一些关于BUS的东西,我可以用sam引脚控制不同的接口… ughhh. difficult & clueless I am
使用dtoverlay,这些数字是GPIO参考,而不是物理引脚号。因此i2c_gpio_sda = 5表示GPIO5,物理引脚29。
小错别字:
它应该拼写“sudo apt-get upgrade” and not “ugrade”
发现得好。我已经更新了文字ðŸ™,
屏幕与Raspberry 皮零兼容吗?
它可以通过I2C工作,因此在Pi Zero上应该可以正常工作。
嗨,很棒的教程– very clear!
我想知道您是否知道为什么在使用此i2c屏幕时会影响我同时使用DS18B20温度传感器的能力? (DS18b20使用单线(w1)协议连接到BCM 4)。
在检测OLED之前,当我在cmd中运行以下命令时:
cd / sys / bus / w1 / devices
ls
它返回一个序列号(28-xxxx)。
连接i2c屏幕后,似乎已更换温度传感器–替换为一组DS18b20不相关的序列号…关于什么的任何想法’继续进行将不胜感激!
I’OLED显示器以蓝色/黄色显示– it’也基于1306。我如何制作同时使用这两种颜色的图像?一世’我猜在图像文件中使用两种颜色,但是哪一种呢?
愚蠢的问题,但我’m new to all this!
我没有’没得到其中的一块蓝色/黄色板,但我怀疑颜色在屏幕的特定区域固定。一世’我只看过屏幕顶部和底部的不同颜色。
如您从128所述,如何更改屏幕尺寸×32 to 128×64我不知道该怎么做,请帮助
使用文本编辑器编辑示例python脚本,并按照的说明进行更改“屏幕尺寸调整”部分。您可以使用以下命令在命令行上编辑示例脚本:
sudo nano shapes.py
进行更改,然后使用CTRL-X,Y然后按ENTER保存/退出。
您好,在此之后,几乎可以解决我遇到的唯一问题。见下文。如果有人可以提供帮助,将不胜感激。Traceback(最近拨打电话):
文件“monitor.py”, line 26, in
从PIL导入图片
ImportError:没有名为PIL的模块
您是从Raspbian的最新版本开始的吗?我在重建Pi-Hole系统时亲自浏览了这篇文章。我似乎记得由于PIL软件包的更改而对软件包安装列表进行了一些更改。
关于我的上一篇文章,关于将i2c连接到显示器的问题…我发现我的面包板电线之一没有导电。它工作正常。感谢您的教程。抱歉,如果我浪费您的时间来考虑我的帖子。
谢谢您的教程。我设法让我的OLED屏幕可以在Pi3上运行,但是无法使其在Pi zero w上运行。
最初在零上逐步执行所有步骤后,它不会显示在oled detect命令中。然后,我将SD卡放入Pi3中,它确实检测到了屏幕以及示例。
我有什么想念的零设置停止了吗?
做过you try
i2cdetect -y 0
?