1. 项目概述Pico OLED 2.23 是什么最近在捣鼓一些嵌入式的小玩意儿发现手头这块Pico OLED 2.23屏幕挺有意思。这名字听起来可能有点陌生但如果你玩过树莓派 Pico、ESP32 或者 Luckfox Pico 这类微控制器那你大概率见过它。简单来说Pico OLED 2.23 指的是一块对角线尺寸为 2.23 英寸的 OLED 显示屏模块通常设计成可以直接插在像树莓派 Pico 这种开发板的 GPIO 排针上即插即用非常方便。它不像那些需要额外焊接转接板的屏幕其核心价值就在于“模块化”和“易用性”。这块屏幕的分辨率通常是 128x32 或 128x64 像素采用单色通常是白色或蓝色OLED 技术。OLED 的特性是自发光每个像素点独立开关所以显示黑色时完全不发光对比度极高显示效果非常锐利功耗也比传统的 LCD 屏要低尤其是在显示深色内容时。对于嵌入式项目来说它是个绝佳的信息输出窗口你可以用它来显示传感器读数比如温度、湿度、系统状态CPU 负载、网络连接、简易的图形界面菜单甚至是滚动文本或者简单的动画。无论是做一个小型气象站、一个网络时钟还是一个设备的状态监控面板这块小屏幕都能派上大用场。接下来我就结合自己的实际使用经验从硬件连接到软件驱动再到几个具体的应用实例带你彻底玩转这块 Pico OLED 2.23 屏幕。2. 硬件连接与接口解析拿到 Pico OLED 2.23 模块第一步就是把它和你的主控板连接起来。别看它小接口的选择和连接方式直接决定了你后续编程的复杂度和性能。2.1 物理接口与引脚定义市面上常见的 Pico OLED 2.23 模块其接口通常是排针形式可以直接与树莓派 Pico 的 GPIO 排母对插。这是最理想的情况实现了真正的“即插即用”。如果你的主控板不是树莓派 Pico比如 ESP32、STM32 等或者引脚定义不匹配那就需要用到杜邦线进行飞线连接。模块的引脚定义虽然因厂商略有差异但核心信号线是固定的。一个典型的 4 针脚 OLED 模块I2C 接口引脚如下GND电源地必须连接。VCC电源正极。这里需要特别注意绝大多数这种小尺寸 OLED 屏的工作电压是 3.3V。严禁接入 5V否则会永久损坏屏幕。在连接前务必用万用表确认你的主控板 GPIO 电压或者查阅主控板和数据手册。SCLI2C 时钟线。SDAI2C 数据线。有些模块可能还有额外的引脚比如RES复位和DC数据/命令选择这通常出现在 SPI 接口的屏幕上。I2C 接口因为协议简单只有两根数据线占用 GPIO 少是这类显示模块最常用的接口也是我们重点讨论的。连接时确保电源极性正确信号线 SCL、SDA 分别连接到主控板的 I2C 引脚上。以树莓派 Pico 为例其默认的 I2C0 接口是 GPIO 4 (SDA) 和 GPIO 5 (SCL)。注意I2C 总线需要上拉电阻。幸运的是树莓派 Pico 和许多 OLED 模块内部已经集成了上拉电阻。如果你的模块没有或者连接后通信不稳定你可能需要在 SCL 和 SDA 线上各添加一个 4.7kΩ 到 10kΩ 的电阻连接到 3.3V。2.2 I2C 地址扫描与确认硬件连接好后第一件事不是急着写显示代码而是先确认通信是否正常。最有效的方法就是进行 I2C 地址扫描。每个 I2C 从设备都有一个唯一的 7 位地址OLED 屏也不例外。常见的 OLED 驱动芯片如 SSD1306、SH1106的地址通常是0x3C或0x3D。你可以写一个简单的地址扫描程序。以在树莓派 Pico 上使用 MicroPython 为例import machine import time i2c machine.I2C(0, sclmachine.Pin(5), sdamachine.Pin(4), freq400000) print(‘Scanning I2C bus...’) devices i2c.scan() if len(devices) 0: print(“No I2C devices found! Check wiring.”) else: print(‘I2C devices found:’, [hex(device) for device in devices])运行这个程序如果能在输出中看到0x3c或0x3d恭喜你硬件连接和基础通信已经成功了。如果没找到请按以下步骤排查检查电源用万用表测量模块 VCC 和 GND 之间的电压是否为稳定的 3.3V。检查连接确认所有杜邦线接触良好没有虚焊或错位。检查引脚映射确认代码中的 SCL、SDA 引脚号与实际物理连接一致。尝试降低频率将 I2C 频率freq从 400000 (400kHz) 降低到 100000 (100kHz)。3. 软件驱动与基础显示通信建立后我们就可以开始让屏幕显示内容了。这里的关键是找到并初始化合适的驱动库。3.1 驱动库的选择与初始化对于 SSD1306 或 SH1106 这类 OLED 驱动芯片社区有非常成熟的库。在 MicroPython 环境中最常用的是ssd1306.py库。你需要将这个库文件上传到你的 Pico 的文件系统中。初始化屏幕的代码如下import machine import ssd1306 # 1. 初始化 I2C i2c machine.I2C(0, sclmachine.Pin(5), sdamachine.Pin(4), freq400000) # 2. 初始化 OLED 对象 # 参数宽度(像素), 高度(像素), I2C对象, I2C地址 oled ssd1306.SSD1306_I2C(128, 64, i2c, addr0x3c) # 3. 清屏 oled.fill(0) # 0 表示黑色1 表示白色 oled.show()oled.show()是一个非常重要的函数。在修改了显示缓冲区比如画了点、写了字之后必须调用show()才能将缓冲区的内容真正发送到屏幕硬件上显示出来。这是一个常见的“坑”新手经常会忘记调用show()然后疑惑为什么代码执行了屏幕却没变化。3.2 文本与图形绘制基础驱动库提供了基础的绘图函数让我们可以在屏幕上任意位置绘制像素、文字和简单图形。显示文本oled.text(‘Hello World!’, 0, 0, 1) # 在坐标(0,0)处用白色(1)显示文字 oled.text(‘Temp: 25.6C’, 0, 16, 1) # 第二行Y坐标增加16像素取决于字体高度 oled.show()这里(0, 0)是左上角坐标。字体的高度通常是 8 像素所以 Y 坐标每次增加 8 或 16 来换行是比较安全的做法。绘制图形# 画线 oled.line(0, 0, 127, 63, 1) # 从(0,0)到(127,63)画一条白线 # 画矩形框 oled.rect(10, 10, 50, 20, 1) # 左上角(10,10)宽50高20的矩形框 # 画填充矩形 oled.fill_rect(70, 10, 40, 30, 1) # 左上角(70,10)宽40高30的填充白色矩形 # 画单个像素点 oled.pixel(64, 32, 1) # 在屏幕中心画一个白点 oled.show()清屏与局部刷新频繁地fill(0)然后重画所有内容是最简单的方式但有时为了效率或实现动画效果我们需要局部刷新。例如只更新屏幕上变化的部分如一个变化的数字而不是整个屏幕。这可以通过在绘制新内容前先用fill_rect在特定区域绘制黑色背景来实现然后再绘制新的文本或图形。4. 实战应用一网络时钟与天气显示有了基础显示能力我们就可以做一些有趣的项目了。一个非常经典的应用就是制作一个网络时钟甚至可以加上简单的天气信息显示。这个项目会涉及到网络连接、时间同步NTP和 API 数据获取。4.1 连接网络与获取NTP时间首先你的主控板需要具备网络功能比如使用 ESP32-S3 或者给树莓派 Pico 搭配一个 WiFi 模块如 ESP-01S。这里以 MicroPython 为例演示连接 WiFi 和同步时间。import network import ntptime import time # WiFi 配置 WIFI_SSID “your_wifi_ssid” WIFI_PASSWORD “your_wifi_password” def connect_wifi(): wlan network.WLAN(network.STA_IF) wlan.active(True) if not wlan.isconnected(): print(‘Connecting to WiFi...’) wlan.connect(WIFI_SSID, WIFI_PASSWORD) # 等待连接最多10秒 for i in range(10): if wlan.isconnected(): break time.sleep(1) if wlan.isconnected(): print(‘WiFi connected:’, wlan.ifconfig()) return True else: print(‘WiFi connection failed!’) return False def sync_ntp_time(): try: ntptime.settime() # 从默认的 NTP 服务器同步时间 print(“Time synchronized via NTP.”) except Exception as e: print(“NTP sync failed:”, e) # 主流程 if connect_wifi(): sync_ntp_time() # 此时 machine.RTC() 已经设置为 UTC 时间4.2 在OLED上格式化显示时间获取到时间后我们需要将其从 UTC 时间转换为本地时间并格式化成美观的字符串显示在 OLED 上。import machine import utime def get_local_time(): # 获取 UTC 时间元组 (year, month, day, hour, minute, second, weekday, yearday) t utime.localtime() # 假设东八区 (UTC8)进行时区转换 local_hour (t[3] 8) % 24 # 重新组装时间元组 local_t (t[0], t[1], t[2], local_hour, t[4], t[5], t[6], t[7]) return local_t def format_time_display(t): # t 为本地时间元组 year, month, day, hour, minute, second, weekday, yearday t # 格式化成字符串例如 “2023-10-27” 和 “14:30:05” date_str ‘{:04d}-{:02d}-{:02d}’.format(year, month, day) time_str ‘{:02d}:{:02d}:{:02d}’.format(hour, minute, second) return date_str, time_str # 在显示循环中 while True: local_time get_local_time() date_str, time_str format_time_display(local_time) oled.fill(0) oled.text(date_str, 0, 0, 1) oled.text(time_str, 0, 16, 1) # 可以添加星期几 weekdays [‘Mon’, ‘Tue’, ‘Wed’, ‘Thu’, ‘Fri’, ‘Sat’, ‘Sun’] oled.text(weekdays[local_time[6]], 0, 32, 1) oled.show() utime.sleep(0.5) # 每0.5秒刷新一次这样一个基本的网络时钟就完成了。屏幕上半部分显示日期中间显示精确到秒的时间下面显示星期。4.3 集成简易天气信息要显示天气我们需要从一个天气 API 获取数据。这里以心知天气、和风天气等免费 API 为例。你需要先注册账号获取 API Key。import urequests import json API_KEY “your_weather_api_key” CITY “beijing” URL “https://api.seniverse.com/v3/weather/now.json?key{}location{}languagezh-Hansunitc”.format(API_KEY, CITY) def fetch_weather(): try: response urequests.get(URL) data json.loads(response.text) response.close() # 解析数据结构因API而异 weather_text data[‘results’][0][‘now’][‘text’] # 例如“晴” temperature data[‘results’][0][‘now’][‘temperature’] # 例如“23” return weather_text, temperature except Exception as e: print(“Fetch weather failed:”, e) return “N/A”, “N/A” # 在主循环中可以每隔一段时间如10分钟获取一次天气 weather_update_interval 600 # 秒 last_weather_update 0 current_weather (“N/A”, “N/A”) while True: now utime.time() # 更新天气 if now - last_weather_update weather_update_interval: current_weather fetch_weather() last_weather_update now # 显示 oled.fill(0) # 显示时间和日期... # 显示天气 weather_str “{} {}C”.format(current_weather[0], current_weather[1]) oled.text(weather_str, 0, 48, 1) # 显示在屏幕底部 oled.show() utime.sleep(0.5)实操心得网络请求可能会失败或阻塞。在实际项目中一定要将网络请求urequests.get放在try...except块中并且考虑设置超时。对于实时性要求不高的天气信息可以降低更新频率如每小时一次并将获取到的数据缓存起来避免因网络问题导致屏幕显示异常或程序卡死。5. 实战应用二嵌入式系统状态监控面板另一个非常实用的场景是将 Pico OLED 2.23 作为一个微型系统监控面板。你可以用它来显示树莓派 Pico 或 ESP32 的实时信息比如 CPU 频率、内存使用情况如果支持、ADC 采集的电压值、GPIO 状态等。5.1 获取并显示系统信息在 MicroPython 中我们可以通过一些内置模块获取基础信息。import machine import gc import utime def get_system_info(): info {} # 获取 CPU 频率 (MHz) info[‘freq’] machine.freq() // 1000000 # 获取内存信息 gc.collect() # 先进行垃圾回收获取更准确的内存视图 info[‘mem_free’] gc.mem_free() info[‘mem_alloc’] gc.mem_alloc() info[‘mem_total’] info[‘mem_free’] info[‘mem_alloc’] info[‘mem_percent’] (info[‘mem_alloc’] / info[‘mem_total’]) * 100 if info[‘mem_total’] 0 else 0 # 获取内部温度传感器读数如果芯片支持如 RP2040 try: sensor_temp machine.ADC(4) conversion_factor 3.3 / (65535) reading sensor_temp.read_u16() * conversion_factor # RP2040 温度传感器公式T 27 - (reading - 0.706)/0.001721 info[‘temp’] 27 - (reading - 0.706) / 0.001721 except: info[‘temp’] ‘N/A’ return info5.2 设计监控界面布局在 128x64 的屏幕上设计一个信息密集但清晰的界面需要一些技巧。我们可以将屏幕划分为几个区域顶部区域显示标题或静态信息如 “System Monitor”。中部区域显示动态变化的核心参数如 CPU 频率、内存使用率、温度每行一个参数。底部区域可以显示滚动日志、ADC 输入的实时波形草图或额外的状态标志。显示代码示例def display_system_info(info): oled.fill(0) # 标题 oled.text(“Sys Monitor”, 0, 0, 1) oled.hline(0, 10, 128, 1) # 画一条分隔线 # 动态信息 line_height 12 start_y 15 oled.text(“Freq: {} MHz”.format(info[‘freq’]), 0, start_y, 1) oled.text(“Mem: {:.1f}%”.format(info[‘mem_percent’]), 0, start_y line_height, 1) oled.text(“Temp: {:.1f}C”.format(info[‘temp’]) if isinstance(info[‘temp’], float) else “Temp: N/A”, 0, start_y 2*line_height, 1) # 可以添加一个简单的内存使用进度条 bar_width 100 bar_x 20 bar_y start_y 3*line_height 5 oled.rect(bar_x, bar_y, bar_width, 8, 1) # 外框 fill_width int((info[‘mem_percent’] / 100) * bar_width) oled.fill_rect(bar_x, bar_y, fill_width, 8, 1) # 填充部分 oled.show()在主循环中定期比如每秒调用get_system_info()和display_system_info()就能实现一个动态更新的系统监控面板。5.3 扩展ADC波形显示如果你需要监控一个模拟信号比如电位器的电压变化可以增加一个简单的波形显示功能。由于屏幕宽度只有 128 像素我们可以实现一个滚动波形图。# 初始化一个列表来存储最近的ADC读数用于绘图 waveform_data [0] * 128 adc_pin machine.ADC(26) # 假设使用GPIO26 (ADC0) def update_waveform(): global waveform_data # 读取ADC值 (0-65535)并缩放到屏幕高度范围内 (0-63) adc_value adc_pin.read_u16() scaled_value int((adc_value / 65535) * 63) # 将新数据点添加到列表末尾并移除最旧的数据点实现滚动效果 waveform_data.append(scaled_value) waveform_data.pop(0) # 在屏幕底部区域绘制波形 plot_y_base 50 # 波形图起始Y坐标 oled.fill_rect(0, plot_y_base, 128, 14, 0) # 清除旧的波形区域 for x in range(127): y1 plot_y_base (63 - waveform_data[x]) # 注意Y坐标方向 y2 plot_y_base (63 - waveform_data[x1]) oled.line(x, y1, x1, y2, 1)将update_waveform()和display_system_info()结合到主循环中你的小屏幕就能同时显示系统状态和实时波形了功能非常强大。6. 进阶技巧与性能优化当项目变得复杂时直接、简单的编程方式可能会遇到性能瓶颈或显示闪烁的问题。这里分享几个进阶技巧。6.1 双缓冲与局部刷新以消除闪烁直接调用oled.fill(0)清屏再绘制在内容复杂或刷新快时人眼会看到明显的闪烁。这是因为清屏全黑和绘制新内容之间有一个时间差。解决方案是双缓冲或局部刷新双缓冲在内存中创建另一个与屏幕缓冲区同样大小的帧缓冲区framebuffer。所有绘图操作先在帧缓冲区中进行完成后再一次性将整个帧缓冲区复制到显示驱动器的缓冲区最后调用一次show()。MicroPython 的framebuf模块支持此操作。不过对于 SSD1306 库通常我们使用更简单的局部刷新。局部刷新只重绘屏幕上发生变化的部分。例如对于时钟只有秒数字段每秒变化。我们可以在绘制新秒数之前先用背景色黑色矩形覆盖旧秒数的区域然后再绘制新的数字。# 局部刷新时钟秒数的例子 last_second -1 while True: _, _, _, hour, minute, second, _, _ utime.localtime() if second ! last_second: # 只有秒数变化时才更新对应区域 # 1. 清除旧秒数区域 (假设秒数显示在位置 (xx, yy)宽度约20像素) oled.fill_rect(second_x, second_y, 20, 8, 0) # 2. 绘制新秒数 oled.text(‘{:02d}’.format(second), second_x, second_y, 1) oled.show() last_second second utime.sleep(0.1)6.2 自定义字体与图形显示内置的text()函数字体是固定的 8x8 像素可能不够美观。我们可以使用取模软件如 PCtoLCD2002将自己喜欢的字体或图标转换成字节数组然后通过blit()方法显示。步骤用取模软件生成字符或图标的字节数组注意设置正确的扫描方式通常是逐列、高位在前。将字节数组存入代码中。使用framebuf.FrameBuffer对象包裹这个字节数组然后使用oled.blit()将其复制到屏幕的指定位置。# 示例显示一个 16x16 的自定义图标 import framebuf # 假设这是取模得到的 16x16 图标数据 (16*16/832字节) icon_data bytearray([0x00, 0x00, 0x1E, 0x00, ... ]) # 此处省略具体数据 icon_fb framebuf.FrameBuffer(icon_data, 16, 16, framebuf.MONO_HLSB) # 在屏幕 (10,10) 位置绘制图标 oled.blit(icon_fb, 10, 10) oled.show()6.3 低功耗优化策略对于电池供电的项目功耗至关重要。OLED 屏幕本身在显示深色内容时功耗很低但微控制器和程序逻辑也会耗电。优化建议降低刷新率如果不是必须实时更新可以显著降低屏幕刷新频率。比如监控面板从每秒刷新改为每 5 秒刷新。使用深度睡眠在不需要工作的间隙让主控芯片进入深度睡眠模式。例如一个每小时更新一次的天气站可以在更新显示后立即进入深度睡眠设置一个定时器如 ESP32 的 RTC 定时器或 Pico 的machine.lightsleep在一小时后唤醒。这能将平均电流从毫安级降至微安级。关闭屏幕当设备处于闲置状态时如夜晚可以调用oled.poweroff()完全关闭屏幕显示需要时再oled.poweron()。优化代码避免不必要的循环和延迟使用中断代替轮询来响应事件。7. 常见问题与深度排查指南在实际操作中你肯定会遇到各种各样的问题。这里我整理了一份从简单到复杂的排查清单覆盖了大部分常见坑点。7.1 硬件连接与通信类问题问题现象可能原因排查步骤与解决方案屏幕不亮无任何显示1. 电源未接通或接反。2. 电压错误接了5V。3. 屏幕本身损坏。1. 用万用表检查 VCC 和 GND 之间电压是否为稳定的 3.3V。2.立即检查是否误接5V这是烧屏最常见原因。3. 尝试更换模块。I2C 扫描不到设备 (地址为 [])1. SDA/SCL 线接错或接触不良。2. 主控板 I2C 引脚未正确配置。3. 模块 I2C 地址非标准。4. 缺少上拉电阻。1. 反复检查接线尝试更换杜邦线。2. 确认代码中 I2C 引脚编号与实际物理连接一致。3. 尝试扫描整个 I2C 地址空间 (0x08 到 0x77)。4. 在 SDA 和 SCL 上各接一个 4.7kΩ 电阻到 3.3V。屏幕显示乱码、花屏或部分显示1. 初始化参数宽度、高度、地址错误。2. I2C 通信受到干扰或速度过快。3. 电源不稳定。1. 核对SSD1306_I2C初始化时的宽度、高度和地址参数。2. 降低 I2C 频率如从 400kHz 降到 100kHz。3. 检查电源确保其能提供足够电流必要时在 VCC 和 GND 间加一个 10uF 的电容稳压。显示内容有残影或刷新不正常1. 忘记调用oled.show()。2. 缓冲区操作错误。1.确保每次更新显示内容后都调用了oled.show()。2. 检查绘图逻辑确保是在正确的缓冲区上操作。7.2 软件与驱动类问题问题现象可能原因排查步骤与解决方案导入ssd1306库时报错ModuleNotFoundError驱动库文件未上传到设备。将ssd1306.py文件通过 Thonny、rshell 或mpremote等工具上传到 Pico 的根目录或lib目录。显示英文正常但中文或自定义图形乱码1. 字体取模方式不匹配。2. 显示函数使用错误。1. 确认取模软件的设置扫描方向、字节位顺序与代码中FrameBuffer的格式如MONO_HLSB一致。这是一个大坑需要反复调试。2. 使用blit()显示自定义图形而非text()。程序运行一段时间后死机或重启1. 内存泄漏尤其在频繁创建对象时。2. 网络请求阻塞且未处理超时。3. 硬件看门狗触发。1. 定期调用gc.collect()回收内存。避免在循环中创建大的对象如字符串拼接。2. 为网络请求设置超时并使用try...except包裹。3. 检查代码中是否有长时间阻塞的操作如长time.sleep考虑使用异步或定时器中断。刷新复杂图形时非常慢使用了全屏fill(0)和重绘且绘图指令过多。采用局部刷新策略。只更新变化的部分区域。对于复杂静态界面可以预先绘制到内存中的一个帧缓冲区然后一次性blit到屏幕。7.3 项目集成类问题问题现象可能原因排查步骤与解决方案同时使用多个 I2C 设备如OLED和传感器冲突I2C 地址冲突或总线锁死。1. 确保每个 I2C 设备地址唯一。2. 所有设备共用一组 SDA/SCL 线并确保上拉电阻足够通常一个 4.7kΩ 即可。3. 如果某个设备导致总线锁死尝试重新初始化 I2C 或重启主控。在显示循环中网络请求导致显示卡顿同步网络请求阻塞了主循环。将网络请求改为异步或放在独立的线程/任务中。在 MicroPython 中可以使用_thread模块如果固件支持或使用uasyncio库进行简单的多任务管理。核心原则是不能让一个可能长时间阻塞的操作卡住显示刷新。电池供电下续航时间远短于预期未进行低功耗优化。实施第 6.3 节的低功耗策略降低刷新率、使用深度睡眠、关闭屏幕、优化代码逻辑。测量不同模式下的工作电流找到耗电大户。一个高级调试技巧逻辑分析仪抓取 I2C 波形。如果遇到极其诡异的通信问题软件排查无效可以借助逻辑分析仪甚至一些软件模拟的查看 SDA 和 SCL 线上的实际波形检查起始信号、地址、数据、ACK/NACK 是否完全符合 I2C 协议规范。这能帮你发现时序问题、信号完整性问题等底层硬件故障。玩转 Pico OLED 2.23 的关键在于理解其作为“信息窗口”的定位并熟练掌握 I2C 通信、帧缓冲区操作和主控板的资源管理。从显示一行文字开始逐步扩展到网络应用、系统监控和自定义界面这个小模块能带来的乐趣和成就感远超其本身的价值。最重要的是多动手多调试每一个踩过的坑都会让你对嵌入式系统的理解更深一层。