SSD1306 模块
模块介绍
SSD1306 OLED 显示屏驱动类，支持 I2C 接口，继承自 framebuf.FrameBuffer，提供文字显示、图形绘制等功能。适用于 128x64、128x32 等常见尺寸的 OLED 显示屏。
硬件引脚说明
| 引脚名称 | 全称/含义 | 接线颜色 | 功能描述 |
|---|---|---|---|
| SCL | Serial Clock/时钟 | 黄色 | I2C 时钟线（需支持 I2C 功能） |
| SDA | Serial Data/数据 | 绿色 | I2C 数据线（需支持 I2C 功能） |
| VCC | Voltage/电源 | 红色 | 电源电压输入（3.3V 或 5V，取决于模块） |
| GND | Ground/地线 | 黑色 | 接地引脚，完成电路回路 |
初始化参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| width | int | 无 | 屏幕宽度（像素，通常为 128） |
| height | int | 无 | 屏幕高度（像素，通常为 64 或 32） |
| i2c | I2C | 无 | I2C 接口对象（需先初始化） |
| addr | int | 0x3C | I2C 设备地址（通常为 0x3C 或 0x3D） |
| external_vcc | bool | False | 是否使用外部电源（影响电荷泵设置） |
导入和实例创建
python
from machine import I2C, Pin
from ssd1306 import SSD1306
# 初始化 I2C 接口
i2c = I2C(1, scl=Pin(22), sda=Pin(21), freq=115200)
# 初始化 OLED 屏幕（128x64）
screen = SSD1306(128, 64, i2c)核心属性方法
| 属性或方法 | 参数 | 返回类型 | 说明 |
|---|---|---|---|
| width | 无 | int | 只读属性：屏幕宽度（像素） |
| height | 无 | int | 只读属性：屏幕高度（像素） |
| show() | 无 | None | 将缓冲区内容显示到屏幕 |
| fill() | color (int 0/1) | None | 填充整个屏幕（0=黑色，1=白色） |
| pixel() | x (int), y (int), color (int 0/1) | None | 设置单个像素点（0=黑色，1=白色） |
| text() | string (str), x (int), y (int), color (int 1) | None | 显示文字（x, y 为起始坐标，color=1 显示） |
| line() | x1 (int), y1 (int), x2 (int), y2 (int), color (int) | None | 绘制直线 |
| rect() | x (int), y (int), w (int), h (int), color (int) | None | 绘制矩形（空心） |
| fill_rect() | x (int), y (int), w (int), h (int), color (int) | None | 绘制填充矩形 |
| poweron() | 无 | None | 打开屏幕显示 |
| poweroff() | 无 | None | 关闭屏幕显示 |
| contrast() | contrast (int 0~255) | None | 设置对比度 |
| invert() | invert (bool) | None | 反转显示（True=反转，False=正常） |
使用示例
基本文字显示
python
from machine import I2C, Pin
from ssd1306 import SSD1306
# 初始化 I2C 接口
i2c = I2C(1, scl=Pin(22), sda=Pin(21), freq=115200)
# 初始化 OLED 屏幕（128x64）
screen = SSD1306(128, 64, i2c)
# 显示文字
screen.text("Hello, World!", 0, 0, 1)
screen.text("OLED Display", 0, 16, 1)
screen.show() # 刷新显示图形绘制
python
from machine import I2C, Pin
from ssd1306 import SSD1306
# 初始化 I2C 接口和屏幕
i2c = I2C(1, scl=Pin(22), sda=Pin(21), freq=115200)
screen = SSD1306(128, 64, i2c)
# 清屏
screen.fill(0)
# 绘制图形
screen.rect(10, 10, 50, 30, 1) # 空心矩形
screen.fill_rect(70, 10, 50, 30, 1) # 填充矩形
screen.line(0, 0, 127, 63, 1) # 对角线
screen.pixel(64, 32, 1) # 单个像素点
screen.show() # 刷新显示屏幕控制
python
from machine import I2C, Pin
from ssd1306 import SSD1306
# 初始化 I2C 接口和屏幕
i2c = I2C(1, scl=Pin(22), sda=Pin(21), freq=115200)
screen = SSD1306(128, 64, i2c)
# 显示内容
screen.text("Contrast Test", 0, 0, 1)
screen.show()
# 设置对比度
screen.contrast(0) # 最低对比度
screen.contrast(255) # 最高对比度
screen.contrast(128) # 中等对比度
# 反转显示
screen.invert(True)
# 关闭/打开屏幕
screen.poweroff()
screen.poweron()注意事项
硬件接口要求
- 需先初始化 I2C 接口，确保 SCL 和 SDA 引脚支持 I2C 功能
- I2C 地址通常为 0x3C 或 0x3D，可通过 I2C 扫描命令确认
显示更新
修改缓冲区后必须调用 show() 方法才能将内容显示到屏幕
坐标系统
屏幕左上角为 (0, 0)，x 轴向右递增，y 轴向下递增
功能特性
- text() 方法使用内置字体，支持标准 ASCII 字符
- 继承自 framebuf.FrameBuffer，支持所有 framebuf 图形绘制方法
- 支持 128x64 和 128x32 等常见尺寸的 OLED 显示屏