1. Raspberry Pi 4B驱动OLED显示模块全攻略树莓派4B作为一款强大的单板计算机在物联网和嵌入式开发领域广受欢迎。而0.96寸OLED显示屏凭借其高对比度、低功耗和体积小巧的特点成为项目开发中常用的显示设备。本文将详细介绍如何用Raspberry Pi 4B驱动OLED显示屏涵盖硬件连接、软件配置、编程实现等完整流程。我曾在多个项目中采用这种组合方案包括智能家居控制面板、工业设备状态监控器等。OLED的清晰显示效果配合树莓派的强大处理能力能够实现丰富的人机交互功能。下面就从最基础的硬件准备开始一步步带你完成整个驱动过程。2. 硬件准备与连接2.1 所需材料清单在开始前你需要准备以下硬件Raspberry Pi 4B主板任何内存版本均可0.96寸OLED显示屏建议选择128×64分辨率的SPI接口型号杜邦线若干建议使用母对母或母对公视OLED模块接口而定可选面包板方便临时连接测试关于OLED模块的选择市面上常见的有4针I2C接口和7针SPI接口两种。SPI接口的刷新率更高适合需要快速更新显示内容的场景I2C接口接线更简单但刷新率相对较低。本文将以7针SPI接口的OLED为例进行说明。2.2 引脚连接详解将OLED模块与树莓派4B按照以下方式连接OLED引脚功能说明树莓派GPIO引脚GND地线GND(任意)VCC电源(3.3V)3.3V电源D0SPI时钟(SCLK)GPIO11(BCM23)D1SPI数据(MOSI)GPIO10(BCM19)RES复位信号GPIO24(BCM24)DC数据/命令选择GPIO25(BCM25)CS片选信号GPIO8(BCM8)注意不同厂商的OLED模块引脚标注可能略有不同务必参考模块附带的数据手册确认各引脚功能。错误的连接可能导致模块损坏。连接时建议先断电操作所有线缆接好后再通电。如果使用面包板可以更方便地检查和调整连接。我曾遇到过因为杜邦线接触不良导致的显示异常问题后来改用质量更好的连接线后解决了。3. 软件环境配置3.1 系统准备与SPI启用首先确保你的树莓派运行的是最新版本的Raspbian系统。通过终端执行以下命令更新系统sudo apt update sudo apt upgrade -y接下来需要启用SPI接口运行sudo raspi-config选择Interface Options SPI选择Yes启用SPI重启树莓派使设置生效验证SPI是否成功启用lsmod | grep spi如果看到spi_bcm2835等相关信息说明SPI已正确加载。3.2 安装必要的库我们将使用Python来控制OLED显示需要安装以下库sudo apt install python3-dev python3-pip libfreetype6-dev libjpeg-dev build-essential sudo pip3 install Pillow numpy RPi.GPIO spidev对于OLED驱动推荐使用luma.oled库它提供了丰富的显示控制功能sudo pip3 install --upgrade luma.oled提示在某些国内网络环境下pip安装可能会很慢。可以尝试使用清华镜像源加速pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple package_name4. 基础显示功能实现4.1 简单文本显示创建一个名为oled_test.py的文件输入以下代码from luma.core.interface.serial import spi from luma.oled.device import ssd1306 from luma.core.render import canvas from PIL import ImageFont # 初始化SPI接口 serial spi(device0, port0, bus_speed_hz8000000) # 创建OLED设备实例 device ssd1306(serial, width128, height64) # 加载字体 font ImageFont.truetype(DejaVuSans.ttf, 12) # 显示文本 with canvas(device) as draw: draw.text((10, 20), Hello, OLED!, fontfont, fillwhite)运行程序python3 oled_test.py如果一切正常你应该能在OLED屏幕上看到Hello, OLED!的文字显示。第一次运行时可能会提示缺少字体文件可以安装以下字体包sudo apt install fonts-dejavu4.2 显示系统信息让我们实现一个更实用的功能显示树莓派的系统信息。修改代码如下import psutil from time import sleep from datetime import datetime def get_system_info(): # 获取CPU使用率 cpu psutil.cpu_percent(interval1) # 获取内存信息 mem psutil.virtual_memory() mem_used mem.used / 1024 / 1024 # MB mem_total mem.total / 1024 / 1024 # MB # 获取磁盘使用情况 disk psutil.disk_usage(/) disk_used disk.used / 1024 / 1024 # MB disk_total disk.total / 1024 / 1024 # MB # 获取IP地址 ip psutil.net_if_addrs()[wlan0][0].address return { cpu: cpu, mem_used: mem_used, mem_total: mem_total, disk_used: disk_used, disk_total: disk_total, ip: ip, time: datetime.now().strftime(%H:%M:%S) } while True: info get_system_info() with canvas(device) as draw: draw.text((0, 0), fIP: {info[ip]}, fontfont, fillwhite) draw.text((0, 15), fCPU: {info[cpu]}%, fontfont, fillwhite) draw.text((0, 30), fMEM: {info[mem_used]:.1f}/{info[mem_total]:.1f}MB, fontfont, fillwhite) draw.text((0, 45), fTIME: {info[time]}, fontfont, fillwhite) sleep(1)这个程序会实时显示树莓派的IP地址、CPU使用率、内存使用情况和当前时间。在实际项目中你可以根据需要显示更多信息如温度传感器数据、网络状态等。5. 高级显示功能实现5.1 显示图形和图片OLED不仅可以显示文字还能显示图形和自定义图片。下面是一个绘制基本图形的例子with canvas(device) as draw: # 绘制矩形边框 draw.rectangle(device.bounding_box, outlinewhite) # 绘制填充矩形 draw.rectangle((10, 10, 50, 30), fillwhite) # 绘制线条 draw.line((60, 10, 100, 40), fillwhite, width2) # 绘制圆形 draw.ellipse((110, 10, 120, 20), outlinewhite)要显示自定义图片需要先将图片转换为OLED兼容的格式。创建一个display_image.py文件from PIL import Image # 加载并转换图片 image Image.open(logo.png).convert(1) # 转换为1位色深 # 调整图片大小以适应OLED屏幕 image image.resize((128, 64)) # 显示图片 device.display(image)注意OLED是单色显示屏建议使用高对比度的黑白图片以获得最佳显示效果。复杂的彩色图片需要先进行二值化处理。5.2 实现多级菜单系统对于需要用户交互的项目可以在OLED上实现简单的多级菜单系统。下面是一个基础实现框架class MenuItem: def __init__(self, text, actionNone, submenuNone): self.text text self.action action self.submenu submenu class MenuSystem: def __init__(self, device, font): self.device device self.font font self.current_menu None self.selected_index 0 self.menu_stack [] def draw_menu(self): with canvas(self.device) as draw: for i, item in enumerate(self.current_menu): prefix if i self.selected_index else draw.text((5, i*15), f{prefix}{item.text}, fontself.font, fillwhite) def handle_input(self, direction): if direction up: self.selected_index max(0, self.selected_index - 1) elif direction down: self.selected_index min(len(self.current_menu)-1, self.selected_index 1) elif direction select: selected_item self.current_menu[self.selected_index] if selected_item.submenu: self.menu_stack.append((self.current_menu, self.selected_index)) self.current_menu selected_item.submenu self.selected_index 0 elif selected_item.action: selected_item.action() def back(self): if self.menu_stack: self.current_menu, self.selected_index self.menu_stack.pop() # 创建菜单结构 main_menu [ MenuItem(System Info, actionlambda: print(Showing system info)), MenuItem(Settings, submenu[ MenuItem(Brightness), MenuItem(Contrast), MenuItem(Back, actionlambda: menu.back()) ]), MenuItem(Exit) ] # 初始化菜单系统 menu MenuSystem(device, font) menu.current_menu main_menu # 主循环 while True: menu.draw_menu() # 这里需要根据实际输入方式获取用户操作 # 例如menu.handle_input(down) sleep(0.1)这个菜单系统支持多级嵌套你可以通过外接按钮或旋转编码器来实现用户输入控制。在实际项目中我曾用这种方式实现了复杂的设备配置界面大大提升了用户体验。6. 常见问题与解决方案6.1 OLED屏幕无显示可能原因及解决方法电源问题检查VCC是否连接到3.3VGND是否接好。我曾遇到过因为误接5V导致模块损坏的情况。SPI未启用确认已通过raspi-config启用SPI接口。引脚连接错误仔细检查每个引脚的连接是否正确特别是时钟和数据线。片选信号问题如果使用多个SPI设备确保CS引脚正确控制。6.2 显示内容闪烁或乱码刷新率过高尝试降低SPI总线速度在初始化时调整bus_speed_hz参数。电源不稳定确保电源供应充足必要时可增加滤波电容。程序逻辑错误检查代码中是否有频繁的清屏和重绘操作。6.3 显示内容不清晰对比度设置不当可以通过修改OLED驱动参数调整对比度device ssd1306(serial, width128, height64, contrast0x7F)字体选择不当尝试使用不同大小或风格的字体确保在低分辨率下可读。OLED老化长期使用的OLED可能会出现亮度下降这是正常现象。7. 性能优化与实用技巧7.1 减少屏幕刷新频率频繁刷新OLED会消耗CPU资源并可能缩短屏幕寿命。对于不常变化的内容可以采用局部刷新策略# 只更新变化的部分 last_value None while True: current_value get_some_value() if current_value ! last_value: with canvas(device) as draw: draw.text((0, 0), fValue: {current_value}, fontfont, fillwhite) last_value current_value sleep(0.1)7.2 使用双缓冲技术对于复杂的图形显示可以使用双缓冲技术避免闪烁from luma.core.render import canvas # 创建离屏缓冲区 with canvas(device) as draw: # 在缓冲区中绘制所有内容 draw.rectangle((0, 0, 127, 63), fillblack) draw.text((10, 10), Double Buffer, fontfont, fillwhite) # 所有绘制完成后一次性显示 device.display(device.image)7.3 低功耗优化对于电池供电的项目可以采取以下措施降低功耗降低刷新频率在不需要显示时关闭OLEDdevice.hide()需要时再重新显示device.show()7.4 扩展应用思路基于OLED和树莓派的组合可以实现许多有趣的应用智能家居控制面板显示温湿度、灯光状态等信息迷你游戏机实现简单的像素游戏设备状态监控器实时显示服务器或网络设备状态电子相框循环显示黑白照片数据可视化仪表展示传感器采集的数据图表我在一个工业监控项目中使用OLED显示实时温度曲线和设备状态配合按钮实现了参数设置功能。这种组合既节省空间又实用特别适合嵌入式应用场景。
树莓派4B驱动OLED显示屏完整教程
发布时间：2026/7/18 5:59:29
1. Raspberry Pi 4B驱动OLED显示模块全攻略树莓派4B作为一款强大的单板计算机在物联网和嵌入式开发领域广受欢迎。而0.96寸OLED显示屏凭借其高对比度、低功耗和体积小巧的特点成为项目开发中常用的显示设备。本文将详细介绍如何用Raspberry Pi 4B驱动OLED显示屏涵盖硬件连接、软件配置、编程实现等完整流程。我曾在多个项目中采用这种组合方案包括智能家居控制面板、工业设备状态监控器等。OLED的清晰显示效果配合树莓派的强大处理能力能够实现丰富的人机交互功能。下面就从最基础的硬件准备开始一步步带你完成整个驱动过程。2. 硬件准备与连接2.1 所需材料清单在开始前你需要准备以下硬件Raspberry Pi 4B主板任何内存版本均可0.96寸OLED显示屏建议选择128×64分辨率的SPI接口型号杜邦线若干建议使用母对母或母对公视OLED模块接口而定可选面包板方便临时连接测试关于OLED模块的选择市面上常见的有4针I2C接口和7针SPI接口两种。SPI接口的刷新率更高适合需要快速更新显示内容的场景I2C接口接线更简单但刷新率相对较低。本文将以7针SPI接口的OLED为例进行说明。2.2 引脚连接详解将OLED模块与树莓派4B按照以下方式连接OLED引脚功能说明树莓派GPIO引脚GND地线GND(任意)VCC电源(3.3V)3.3V电源D0SPI时钟(SCLK)GPIO11(BCM23)D1SPI数据(MOSI)GPIO10(BCM19)RES复位信号GPIO24(BCM24)DC数据/命令选择GPIO25(BCM25)CS片选信号GPIO8(BCM8)注意不同厂商的OLED模块引脚标注可能略有不同务必参考模块附带的数据手册确认各引脚功能。错误的连接可能导致模块损坏。连接时建议先断电操作所有线缆接好后再通电。如果使用面包板可以更方便地检查和调整连接。我曾遇到过因为杜邦线接触不良导致的显示异常问题后来改用质量更好的连接线后解决了。3. 软件环境配置3.1 系统准备与SPI启用首先确保你的树莓派运行的是最新版本的Raspbian系统。通过终端执行以下命令更新系统sudo apt update sudo apt upgrade -y接下来需要启用SPI接口运行sudo raspi-config选择Interface Options SPI选择Yes启用SPI重启树莓派使设置生效验证SPI是否成功启用lsmod | grep spi如果看到spi_bcm2835等相关信息说明SPI已正确加载。3.2 安装必要的库我们将使用Python来控制OLED显示需要安装以下库sudo apt install python3-dev python3-pip libfreetype6-dev libjpeg-dev build-essential sudo pip3 install Pillow numpy RPi.GPIO spidev对于OLED驱动推荐使用luma.oled库它提供了丰富的显示控制功能sudo pip3 install --upgrade luma.oled提示在某些国内网络环境下pip安装可能会很慢。可以尝试使用清华镜像源加速pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple package_name4. 基础显示功能实现4.1 简单文本显示创建一个名为oled_test.py的文件输入以下代码from luma.core.interface.serial import spi from luma.oled.device import ssd1306 from luma.core.render import canvas from PIL import ImageFont # 初始化SPI接口 serial spi(device0, port0, bus_speed_hz8000000) # 创建OLED设备实例 device ssd1306(serial, width128, height64) # 加载字体 font ImageFont.truetype(DejaVuSans.ttf, 12) # 显示文本 with canvas(device) as draw: draw.text((10, 20), Hello, OLED!, fontfont, fillwhite)运行程序python3 oled_test.py如果一切正常你应该能在OLED屏幕上看到Hello, OLED!的文字显示。第一次运行时可能会提示缺少字体文件可以安装以下字体包sudo apt install fonts-dejavu4.2 显示系统信息让我们实现一个更实用的功能显示树莓派的系统信息。修改代码如下import psutil from time import sleep from datetime import datetime def get_system_info(): # 获取CPU使用率 cpu psutil.cpu_percent(interval1) # 获取内存信息 mem psutil.virtual_memory() mem_used mem.used / 1024 / 1024 # MB mem_total mem.total / 1024 / 1024 # MB # 获取磁盘使用情况 disk psutil.disk_usage(/) disk_used disk.used / 1024 / 1024 # MB disk_total disk.total / 1024 / 1024 # MB # 获取IP地址 ip psutil.net_if_addrs()[wlan0][0].address return { cpu: cpu, mem_used: mem_used, mem_total: mem_total, disk_used: disk_used, disk_total: disk_total, ip: ip, time: datetime.now().strftime(%H:%M:%S) } while True: info get_system_info() with canvas(device) as draw: draw.text((0, 0), fIP: {info[ip]}, fontfont, fillwhite) draw.text((0, 15), fCPU: {info[cpu]}%, fontfont, fillwhite) draw.text((0, 30), fMEM: {info[mem_used]:.1f}/{info[mem_total]:.1f}MB, fontfont, fillwhite) draw.text((0, 45), fTIME: {info[time]}, fontfont, fillwhite) sleep(1)这个程序会实时显示树莓派的IP地址、CPU使用率、内存使用情况和当前时间。在实际项目中你可以根据需要显示更多信息如温度传感器数据、网络状态等。5. 高级显示功能实现5.1 显示图形和图片OLED不仅可以显示文字还能显示图形和自定义图片。下面是一个绘制基本图形的例子with canvas(device) as draw: # 绘制矩形边框 draw.rectangle(device.bounding_box, outlinewhite) # 绘制填充矩形 draw.rectangle((10, 10, 50, 30), fillwhite) # 绘制线条 draw.line((60, 10, 100, 40), fillwhite, width2) # 绘制圆形 draw.ellipse((110, 10, 120, 20), outlinewhite)要显示自定义图片需要先将图片转换为OLED兼容的格式。创建一个display_image.py文件from PIL import Image # 加载并转换图片 image Image.open(logo.png).convert(1) # 转换为1位色深 # 调整图片大小以适应OLED屏幕 image image.resize((128, 64)) # 显示图片 device.display(image)注意OLED是单色显示屏建议使用高对比度的黑白图片以获得最佳显示效果。复杂的彩色图片需要先进行二值化处理。5.2 实现多级菜单系统对于需要用户交互的项目可以在OLED上实现简单的多级菜单系统。下面是一个基础实现框架class MenuItem: def __init__(self, text, actionNone, submenuNone): self.text text self.action action self.submenu submenu class MenuSystem: def __init__(self, device, font): self.device device self.font font self.current_menu None self.selected_index 0 self.menu_stack [] def draw_menu(self): with canvas(self.device) as draw: for i, item in enumerate(self.current_menu): prefix if i self.selected_index else draw.text((5, i*15), f{prefix}{item.text}, fontself.font, fillwhite) def handle_input(self, direction): if direction up: self.selected_index max(0, self.selected_index - 1) elif direction down: self.selected_index min(len(self.current_menu)-1, self.selected_index 1) elif direction select: selected_item self.current_menu[self.selected_index] if selected_item.submenu: self.menu_stack.append((self.current_menu, self.selected_index)) self.current_menu selected_item.submenu self.selected_index 0 elif selected_item.action: selected_item.action() def back(self): if self.menu_stack: self.current_menu, self.selected_index self.menu_stack.pop() # 创建菜单结构 main_menu [ MenuItem(System Info, actionlambda: print(Showing system info)), MenuItem(Settings, submenu[ MenuItem(Brightness), MenuItem(Contrast), MenuItem(Back, actionlambda: menu.back()) ]), MenuItem(Exit) ] # 初始化菜单系统 menu MenuSystem(device, font) menu.current_menu main_menu # 主循环 while True: menu.draw_menu() # 这里需要根据实际输入方式获取用户操作 # 例如menu.handle_input(down) sleep(0.1)这个菜单系统支持多级嵌套你可以通过外接按钮或旋转编码器来实现用户输入控制。在实际项目中我曾用这种方式实现了复杂的设备配置界面大大提升了用户体验。6. 常见问题与解决方案6.1 OLED屏幕无显示可能原因及解决方法电源问题检查VCC是否连接到3.3VGND是否接好。我曾遇到过因为误接5V导致模块损坏的情况。SPI未启用确认已通过raspi-config启用SPI接口。引脚连接错误仔细检查每个引脚的连接是否正确特别是时钟和数据线。片选信号问题如果使用多个SPI设备确保CS引脚正确控制。6.2 显示内容闪烁或乱码刷新率过高尝试降低SPI总线速度在初始化时调整bus_speed_hz参数。电源不稳定确保电源供应充足必要时可增加滤波电容。程序逻辑错误检查代码中是否有频繁的清屏和重绘操作。6.3 显示内容不清晰对比度设置不当可以通过修改OLED驱动参数调整对比度device ssd1306(serial, width128, height64, contrast0x7F)字体选择不当尝试使用不同大小或风格的字体确保在低分辨率下可读。OLED老化长期使用的OLED可能会出现亮度下降这是正常现象。7. 性能优化与实用技巧7.1 减少屏幕刷新频率频繁刷新OLED会消耗CPU资源并可能缩短屏幕寿命。对于不常变化的内容可以采用局部刷新策略# 只更新变化的部分 last_value None while True: current_value get_some_value() if current_value ! last_value: with canvas(device) as draw: draw.text((0, 0), fValue: {current_value}, fontfont, fillwhite) last_value current_value sleep(0.1)7.2 使用双缓冲技术对于复杂的图形显示可以使用双缓冲技术避免闪烁from luma.core.render import canvas # 创建离屏缓冲区 with canvas(device) as draw: # 在缓冲区中绘制所有内容 draw.rectangle((0, 0, 127, 63), fillblack) draw.text((10, 10), Double Buffer, fontfont, fillwhite) # 所有绘制完成后一次性显示 device.display(device.image)7.3 低功耗优化对于电池供电的项目可以采取以下措施降低功耗降低刷新频率在不需要显示时关闭OLEDdevice.hide()需要时再重新显示device.show()7.4 扩展应用思路基于OLED和树莓派的组合可以实现许多有趣的应用智能家居控制面板显示温湿度、灯光状态等信息迷你游戏机实现简单的像素游戏设备状态监控器实时显示服务器或网络设备状态电子相框循环显示黑白照片数据可视化仪表展示传感器采集的数据图表我在一个工业监控项目中使用OLED显示实时温度曲线和设备状态配合按钮实现了参数设置功能。这种组合既节省空间又实用特别适合嵌入式应用场景。
