用MicroPython点亮你的第一块OLED屏：ESP32图形显示实战指南
你有没有过这样的经历？手里的ESP32连上了Wi-Fi，传感器数据也读出来了，但就是不知道它到底“活”没活着——没有屏幕、没有反馈，调试全靠串口打印一堆数字。这时候，一块小小的OLED屏，就能让你的项目瞬间“看得见”。
今天，我们就来手把手教你如何用MicroPython在ESP32上驱动I²C接口的OLED屏幕，从刷固件到显示文字、画图、甚至展示自定义图标，一步不落，全程无坑。
先别急着接线，先把MicroPython装上ESP32
在开始任何硬件操作之前，得先让ESP32“听懂”Python。出厂的ESP32默认跑的是AT指令或Arduino固件，我们要换成MicroPython——一个能让微控制器运行Python代码的轻量级系统。
第一步：刷入MicroPython固件
下载官方MicroPython固件（
.bin文件）
官网地址： https://micropython.org/download/esp32/
推荐使用稳定版本，比如ESP32_GENERIC-*.bin使用
esptool.py刷写：bash esptool.py --port /dev/ttyUSB0 erase_flash esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash 0 esp32-generic.bin
📌 提示：Windows用户把
/dev/ttyUSB0换成COM3或对应端口号。
- 刷完后重启，你会看到串口输出类似：
```
MicroPython v1.20.0 on 2023-04-26; ESP32 module with ESP32
Type “help()” for more information.```
恭喜！你现在拥有了一个会说Python的ESP32！
第二步：连接REPL，试试看能不能说话
用串口工具（如PuTTY、rshell、Thonny IDE）连接ESP32，波特率设为115200。
推荐新手直接使用Thonny IDE，安装后选择解释器为“MicroPython (ESP32)”，自动识别设备，还能一键上传脚本。
硬件怎么接？一张表搞定OLED与ESP32的I²C连线
市面上最常见的OLED模块是0.96英寸、128×64分辨率、SSD1306驱动芯片、I²C接口的蓝色/白色屏。我们以它为例。
| OLED引脚 | 功能说明 | 接ESP32引脚 |
|---|---|---|
| VCC | 电源（3.3V） | 3.3V |
| GND | 地 | GND |
| SCL | I²C时钟线 | GPIO22 |
| SDA | I²C数据线 | GPIO21 |
⚠️ 注意事项：
- 不要用5V供电！ESP32和这类OLED都是3.3V逻辑电平。
- 建议在SCL和SDA线上各加一个4.7kΩ上拉电阻到3.3V（不过大多数模块已内置）。
- 引脚可以换，但优先使用硬件I²C通道（I2C1默认用GPIO21/22）。
接好线后，先验证一下OLED是否被正确识别。
from machine import I2C, Pin # 初始化I2C总线 i2c = I2C(scl=Pin(22), sda=Pin(21), freq=400_000) # 扫描总线上的设备地址 devices = i2c.scan() if devices: print("找到I²C设备:", [hex(d) for d in devices]) else: print("❌ 未检测到I²C设备，请检查接线")正常情况下你应该看到输出类似：
找到I²C设备: ['0x3c']如果没反应，重点排查：
- 接线是否松动？
- 是否接反了SCL和SDA？
- OLED模块是否损坏？
让屏幕亮起来：初始化OLED并显示第一行字
接下来要用到MicroPython社区广泛使用的ssd1306驱动库。好消息是——很多MicroPython固件已经自带这个库了！不需要额外安装。
如果没有，可以从GitHub下载ssd1306.py，然后上传到ESP32根目录。
初始化OLED对象
import ssd1306 # 创建OLED实例（宽, 高, I2C对象） oled = ssd1306.SSD1306_I2C(128, 64, i2c)这行代码完成了几件事：
- 向OLED发送初始化命令序列；
- 分配一块128×64÷8 = 1024字节的帧缓冲区；
- 准备好绘图环境。
现在你可以开始往屏幕上“写东西”了。
显示文本 & 清屏
# 清空屏幕（填黑） oled.fill(0) # 写两行字 oled.text("Hello World!", 0, 0) oled.text("来自ESP32", 0, 10) # 刷新！必须调用show()才会真正显示 oled.show()📌 关键点解析：
-fill(0)：清屏（0=灭，1=亮）
-text(string, x, y)：左上角坐标(x,y)，单位像素
-show()：将内存中的图像推送到OLED显存，否则你看不到变化！
试着改改坐标，你会发现文字是可以精确定位的。比如(0, 0)是左上角，(0, 56)就快到底部了。
画点、画线、画框，做个简单界面
除了文字，ssd1306库还支持基本图形绘制，虽然功能不多，但对于状态面板完全够用。
oled.fill(0) # 画个边框 oled.rect(0, 0, 128, 64, 1) # x,y,w,h,color # 画一条对角线 oled.line(0, 0, 127, 63, 1) # 画一个小方块表示信号强度 oled.rect(110, 2, 10, 8, 1) oled.fill_rect(112, 4, 6, 4, 1) # 实心矩形 # 添加标题 oled.text("状态面板", 40, 20) oled.show()常用绘图函数一览：
| 函数 | 作用 |
|---|---|
pixel(x, y[, c]) | 设置单个像素 |
line(x1,y1,x2,y2,c) | 画直线 |
rect(x,y,w,h,c) | 画空心矩形 |
fill_rect(x,y,w,h,c) | 画实心矩形 |
hline/vline(...) | 快速画水平/垂直线 |
这些组合起来，足够做一个漂亮的仪表盘了。
想显示Logo？教你把图片变成代码
原生MicroPython不支持BMP/PNG等格式，但我们可以通过预处理的方式，把黑白图片转成字节数组嵌入代码。
步骤一：准备一张单色图
尺寸建议不超过128×64，最好是8的倍数宽度（方便对齐）。可以用Photoshop、GIMP或在线工具转换为黑白位图。
推荐工具：
👉 https://javl.github.io/image2cpp/
支持导出C数组格式，勾选“Horizontal layout”即可用于ssd1306。
步骤二：复制数组到代码中
假设生成了一个WiFi图标的数组：
wifi_icon = [ 0x18, 0x3C, 0x7E, 0xDB, 0xDB, 0x7E, 0x3C, 0x18 ]每个字节代表一列8个垂直像素（高位在上），共8列，即8×8图标。
步骤三：编写绘图函数
def draw_icon(data, x, y, width, height): for i in range(width): byte = data[i] for bit in range(8): if byte & (1 << (7 - bit)): oled.pixel(x + i, y + bit, 1)调用：
oled.fill(0) draw_icon(wifi_icon, 60, 28, 8, 8) oled.show()💡 进阶技巧：如果你需要频繁刷新图像，建议直接操作帧缓冲区（oled.buffer），通过framebuf模块批量写入，性能提升显著。
实战案例：做一个联网状态显示器
结合Wi-Fi连接和OLED显示，做一个实用的小工具。
import network import time from machine import I2C, Pin import ssd1306 # 初始化I2C和OLED i2c = I2C(scl=Pin(22), sda=Pin(21), freq=400000) oled = ssd1306.SSD1306_I2C(128, 64, i2c) def connect_wifi(ssid, pwd): wlan = network.WLAN(network.STA_IF) wlan.active(True) wlan.connect(ssid, pwd) for _ in range(10): if wlan.isconnected(): break time.sleep(1) return wlan def show_status(ip=None, rssi=None): oled.fill(0) oled.rect(0, 0, 128, 64, 1) oled.text("Status:", 0, 10) if ip: oled.text("Connected", 0, 20) oled.text(f"IP: {ip}", 0, 30) oled.text(f"RSSI: {rssi}dBm", 0, 40) else: oled.text("No Network", 0, 20) # 显示时间（模拟） oled.text("12:34:56", 80, 54) oled.show() # 主程序 wlan = connect_wifi("your_ssid", "your_password") while True: if wlan.isconnected(): info = wlan.ifconfig() rssi = -70 # 可通过wlan.status('rssi')获取 show_status(info[0], rssi) else: show_status() time.sleep(5)这个小系统已经在做真正的“人机交互”了：本地显示IP地址、信号强度、时间，即使断网也能提示状态。
踩过的坑我都替你踩好了：常见问题与避坑指南
❌ 屏幕不亮 / 扫不到设备？
- 检查VCC/GND是否接反；
- 确认I²C地址是
0x3C还是0x3D（有些模块ADR脚拉高会变地址）； - 更换I2C引脚试试，避免与其他外设冲突。
❌ 文字闪烁或残影？
- 忘记调用
oled.fill(0)导致旧内容残留； - 多次
show()之间未清屏。
❌ 内存不足怎么办？
- 避免加载大图或复杂结构；
- 图像尽量压缩，只保留关键轮廓；
- 使用
del删除不用的变量释放内存。
❌ 刷新太慢影响性能？
- 减少不必要的
show()调用； - 只在内容变更时刷新；
- 使用定时器控制刷新频率（如每秒一次）。
不止于显示：未来的扩展方向
一旦你能控制这块小屏幕，可能性就打开了：
- 加一个按键 → 实现菜单切换页面
- 接DHT11温湿度传感器 → 显示实时环境数据
- 使用
uasyncio做非阻塞刷新 - 引入
lv_micropython构建更复杂的GUI界面 - 结合NTP同步时间，做个迷你电子钟
最后一句掏心窝的话
别再让你的ESP32“默默工作”了。一块十几块钱的OLED屏，加上几十行Python代码，就能让它开口“说话”。无论是教学演示、原型验证，还是做个个性化的桌面小工具，这都是最值得掌握的基础技能之一。
动手试试吧，当你第一次在屏幕上看到自己写的“Hello World!”时，那种成就感，绝对值得。
如果你在实现过程中遇到任何问题，欢迎留言交流，我们一起debug。
