CircuitPython驱动SSD1675墨水屏：从环境搭建到三个实战案例-北京尧图网络

我最近在折腾一块 250×122 的墨水屏驱动包正是 adafruit-circuitpython-ssd1675。这个小东西解决了一个非常具体的问题在 CircuitPython 生态里用十几行代码就能把 SSD1675 电子纸点亮并显示内容。相比裸写寄存器、对着 datasheet 翻 VCOM、LUT、BORDER 那些定义displayio 这套抽象可以帮你省掉大量重复劳动。这篇文章适合两类人一类是刚拿到 SSD1675 模块还没跑通驱动的初学者另一类是已经会用基础显示、想往真实项目落地的开发者。我不会只复述官方示例而是把构造参数、内存对象、刷新时序这些关键点掰开讲最后给三个可以直接抄的实战案例。SSD1675 这块屏幕的定位和普通 LCD、OLED 很不一样所以先花点篇幅说清楚它适合干什么。这块驱动芯片常见于黑白墨水屏模块特性是断电后画面依然保留、无背光、静态显示功耗极低。它适合做电子价签、门牌、信息牌、桌面时钟这类“更新频率低、显示内容稳定”的场景。反过来它不适合做视频播放、动态仪表盘、实时滚动日志——刷新一次要一两秒而且频繁刷新会加速屏幕老化。搞清楚了这些后面的代码选型才有意义。1. 先想清楚SSD1675 这块屏到底适合干什么很多人第一次拿到 SSD1675 屏幕时都会下意识拿它和 OLED 比较分辨率都低都是单色为什么不用 OLED这里有个关键差异OLED 需要持续供电才能保持画面墨水屏靠电泳粒子显色画面写上去之后即使断电也能保持数周甚至更久。也就是说SSD1675 最值钱的特性不是“显示”而是“保持”。我用它做过一个模拟项目X的会议门牌每天只更新一两次其余时间完全断电。如果用同分辨率的 OLED至少得配一个常开电源还得考虑烧屏问题用 SSD1675 之后系统平均电流降到了一个非常低的水平一块小型锂电池能撑很久。这是 SSD1675 的核心使用逻辑把“实时刷新”换成“低频快照”用极低的能耗换取足够长的显示时间。还有一个容易被忽略的物理限制电子纸刷新过程中需要内部的高压驱动来推动电泳粒子所以刷新时屏幕会先整体闪白或闪黑再慢慢浮现内容。这个闪烁是正常的不是花屏也不是驱动错误。很多人第一次跑通 demo 时被这个闪烁吓到以为屏坏了其实只要你看到最终图案正确就说明驱动链路通了。另外SSD1675 是纯单色驱动没有灰度级。如果你想要灰阶那是 SSD1680 或其他芯片的活SSD1675 只能做黑白两色。实际项目中想表现“中间色”只能靠抖动算法模拟比如把半色调图案用黑白像素交织出来。性能和效果都有限所以我一般建议直接在设计上接受黑白二值风格反而更有电子纸质感。2. 从接线到第一个白屏环境搭建速通2.1 硬件清单和连接顺序跑通 SSD1675 需要的硬件不多开发板加一块墨水屏模块就行。常见模块是 250×122 分辨率接口为 SPI 四线板上通常引出 7 个脚VCC、GND、DIN、CLK、CS、DC、RST、BUSY有的模块把 BUSY 标成 BSY。我习惯把开发板放在屏幕左侧用杜邦线按顺序连接避免跳线交叉干扰。屏幕引脚功能开发板建议引脚备注VCC电源3.3V不要接 5V很多模块逻辑电平不兼容GND地GND共地必须接DINSPI MOSI开发板 MOSI 口数据输入CLKSPI 时钟开发板 SCK 口时钟信号CS片选任意 GPIO低电平选中DC数据/命令切换任意 GPIO必须接不能并到地RST复位任意 GPIO低电平复位BUSY忙状态任意 GPIO决定刷新时序的关键接线时最容易犯的错是把 DIN 和 CLK 接到开发板软件模拟的 GPI/O 而不是硬件 SPI 引脚上。虽然逻辑上也能用但速率上不去刷新很容易出现花屏。优先使用开发板自带的 SPI 外设引脚比如很多开发板上标注的 SCK、MOSI 就是硬件 SPI 通道。2.2 固件与库的安装接下来是 CircuitPython 环境。到官方固件下载页面下载对应板卡版本的固件拖进开发板的引导盘完成烧录。然后需要安装驱动库最省事的方式是使用 circup 工具circup install adafruit_ssd1675 adafruit_display_text如果是树莓派这类运行完整 Linux 的开发板也可以用 pip 安装 PyPI 包名 adafruit-circuitpython-ssd1675导入名同样是 adafruit_ssd1675。Adafruit 的驱动依赖 adafruit_bus_device 和 adafruit_display_textcircup 会自动处理依赖不必手动逐个下载。安装完后检查一下 lib 目录能看到 adafruit_ssd1675.mpy 和 adafruit_display_text 文件夹就算到位。如果用的是旧版固件部分 API 名称可能不同比如 display.show 和 display.root_group 的差异后面代码里我会分别提示。2.3 最小代码点亮空白屏幕在开始复杂内容之前先跑一个最小程序目标是让屏幕稳定输出一个全白画面。全部代码就这几段import board import displayio import digitalio from adafruit_ssd1675 import Adafruit_SSD1675 displayio.release_displays() spi board.SPI() cs board.D5 dc board.D6 rst board.D8 busy digitalio.DigitalInOut(board.D9) display_bus displayio.FourWire( spi, commanddc, chip_selectcs, resetrst, baudrate1000000, ) display Adafruit_SSD1675(display_bus, width250, height122, busy_pinbusy) group displayio.Group() bitmap displayio.Bitmap(250, 122, 2) palette displayio.Palette(2) palette[0] 0xFFFFFF palette[1] 0x000000 tilegrid displayio.TileGrid(bitmap, pixel_shaderpalette) group.append(tilegrid) display.root_group group display.refresh() while True: pass刷新之后屏幕会白底全亮表示驱动链路已经打通。display.refresh()是电子纸专属操作普通显示屏没有这一步它会触发完整的刷新时序。如果你的代码卡在这里不动优先检查 BUSY 引脚接线和供电很多初次跑不动的问题都出在这两处。这个最小程序里baudrate1000000是官方示例的常用值。实际项目中如果出现乱码我会先把 baudrate 降到 500000 甚至 250000这是最有效的花屏排查手法之一。需要注意的是硬件 SPI 速率只是总线能力SSD1675 芯片本身的响应速度有限不能一味调高。3. 语法与参数拆解从总线对象到刷新时序3.1 displayio.release_displays() 做了什么很多新手会忽视displayio.release_displays()这行也有很多人直接照抄但不明白为什么要写。它的作用是释放当前所有 displayio 相关资源避免多重初始化导致总线冲突。在同一个板子上如果之前运行过其他屏幕程序或者某个引脚被其他外设占用不执行这一步后续初始化很可能报错。这个函数在每次程序启动时调用一次即可不能放在循环里反复执行。我见过有人为了让屏幕“复位”把它放进刷新循环里结果系统频繁重新分配资源刷新越来越慢。电子纸不需要通过反复重新初始化来复位正常用display.refresh()就好。3.2 FourWire 与 Adafruit_SSD1675 构造参数displayio.FourWire是 CircuitPython 针对 SPI 屏定义的总线对象它把 SPI、数据和命令切换、片选、复位这几个信号封装在一起。它的参数含义很直白参数含义建议值spi已初始化的 board.SPI() 对象不可省略commandDC 引脚数据/命令切换线任意可用 GPIOchip_selectCS 引脚低电平选中屏幕任意可用 GPIOresetRST 引脚低电平复位任意可用 GPIObaudrateSPI 时钟频率1MHz 以内比较稳然后是核心构造器Adafruit_SSD1675(display_bus, width250, height122, busy_pinbusy)。这里的 width 和 height 必须和屏幕物理分辨率一致我的屏幕是 250×122如果你的模块是其他尺寸一定要改成对应值。改错的话画面会整体错位图形显示到屏幕外排查起来很迷惑。busy_pin 参数用于等待屏幕忙状态结束。电子纸刷新时要经过复杂的电平转换过程BUSY 脚会在刷新期间拉高或拉低驱动库内部会根据这个引脚判断何时可以继续操作。很多初学者试图在程序里手动读取 BUSY 引脚写等待逻辑其实没必要直接传给构造函数就行刷新方法内部已经处理了等待逻辑。3.3 Bitmap、Palette、TileGrid 三者关系在 displayio 体系里把画面显示出来需要三个对象Bitmap 存索引值Palette 存颜色表TileGrid 把 Bitmap 和 Palette 绑定后放到屏幕上。可以把 Bitmap 想成一块只写数字的网格纸每个格子是 0 或 1Palette 是一盒颜料0 号位放白色1 号位放黑色TileGrid 则是把网格纸贴到显示屏这个物理画框里的动作。bitmap displayio.Bitmap(250, 122, 2) palette displayio.Palette(2) palette[0] 0xFFFFFF # 白色 palette[1] 0x000000 # 黑色这里的 Bitmap 需要传入 2 作为颜色深度因为 SSD1675 只支持 0 和 1 两个索引。如果你写成 1屏幕显示会出现异常因为驱动至少需要两种颜色来表现黑和白。Palette 里的 0xFFFFFF 是 24 位白色 RGB 值0x000000 是黑色调换这两个值就能让画面黑白反色排查问题时常用来确认屏幕没有硬件故障。如果要在屏幕上显示文字最推荐的方式是用 adafruit_display_text 里的 bitmap_labelfrom terminalio import FONT from adafruit_display_text import bitmap_label label bitmap_label.Label(FONT, color0x000000, x20, y50) label.text Hello group.append(label)这里的 color 要和 Palette 里的索引对应。比如 0x000000 是黑色文字就必须保证 Palette[1] 是黑色并且背景 Bitmap 填充为 0否则文字和背景色会混在一起。Font 用 terminalio.FONT 是内置小字体适合快速验证要更精美的效果可以加载 BDF 格式的自定义字体后面图片案例里我会顺带提到。3.4 refresh、sleep 与 rotation电子纸专属操作display.refresh()是电子纸的灵魂。普通屏幕改完 Bitmap 和 TileGrid 后会自动更新电子纸不会必须显式调用一次刷新。这个设计是有意为之因为每触发一次刷新屏幕内部的电泳粒子就要经历一次完整运动频繁刷新既耗电又加速老化。在代码里可以把它理解成“拍一张照片并固定到纸上”而不是“实时刷视频”。刷新之后display.sleep()可以把驱动芯片切到低功耗模式大幅降低整机功耗。等下次需要更新内容时先display.wake()唤醒再改 Bitmap最后 refresh。实际项目中如果屏幕几小时才更新一次这一步能省很多电。display.rotation决定画面旋转角度可选 0、90、180、270。我第一次把屏幕竖起来用时直接设 rotation90结果坐标轴完全反过来花了半天排查才发现是坐标系统跟着旋转了。后来我养成了一个习惯先用最小代码显示一个大方块验证方位正确后再开始写业务逻辑。这个方法虽然土但非常有效。4. 案例一按键切换的双商品电子价签电子价签是 SSD1675 最经典的应用场景。我在模拟项目X里做了一套按钮切换价格的展示屏按一下按钮屏幕切换到下一件商品再按一下继续切换。完整代码不长import time import board import displayio import digitalio from terminalio import FONT from adafruit_display_text import bitmap_label from adafruit_ssd1675 import Adafruit_SSD1675 displayio.release_displays() spi board.SPI() busy digitalio.DigitalInOut(board.D9) display_bus displayio.FourWire( spi, commandboard.D6, chip_selectboard.D5, resetboard.D8, baudrate1000000, ) display Adafruit_SSD1675(display_bus, width250, height122, busy_pinbusy) display.rotation 0 group displayio.Group() bitmap displayio.Bitmap(250, 122, 2) palette displayio.Palette(2) palette[0] 0xFFFFFF palette[1] 0x000000 tilegrid displayio.TileGrid(bitmap, pixel_shaderpalette) group.append(tilegrid) name_label bitmap_label.Label(FONT, text, color0x000000, x20, y45, scale2) price_label bitmap_label.Label(FONT, text, color0x000000, x20, y80, scale2) group.append(name_label) group.append(price_label) display.root_group group btn digitalio.DigitalInOut(board.D7) btn.switch_to_input(pulldigitalio.Pull.UP) goods [ (可乐, 3.50), (薯片, 6.80), (纸巾, 4.20), ] index 0 def render(): bitmap.fill(0) name_label.text goods[index][0] price_label.text goods[index][1] display.refresh() render() while True: if not btn.value: index (index 1) % len(goods) render() time.sleep(0.5)这里有个容易被忽略的细节第一次上电时我只做了一次白屏填充之后每次切换都是先bitmap.fill(0)再改文字。为什么要先填白因为电子纸有残影机制如果直接把新文字叠加在旧画面上屏幕边缘会残留上一帧的笔画。先清屏再画相当于给画布换了一张白纸残影会大大减轻。另一个经验是按钮的去抖。电子纸刷新需要一两秒按钮如果按得太快程序会陷入连续刷新循环。我在渲染后加了 0.5 秒延时基本够用。如果你想要更严谨的防抖可以用引脚轮询加时间差判断但在这个场景下没必要物理响应已经足够钝化了。生产环境里价签内容往往来自服务器或手机写入而不是写死在数组里。你可以把 goods 列表换成从 SD 卡读取 JSON 文件每次按钮触发时重新读文件这样不用改代码、不用重新烧录固件就能更新商品信息。这也是 SSD1675 类项目比较推荐的架构屏幕显示逻辑和数据源解耦。5. 案例二带RTC的桌面时钟电子屏做桌面时钟最大的争议在于刷新频率。你要么看到的是电子纸低功耗的优点要么看到的是残影和老化风险。我的做法是连接一个外部 RTC 芯片保证时间准确每 15 分钟刷新一次屏幕其余时间让屏幕睡眠。这样每天最多刷新 96 次对 SSD1675 来说毫无压力。import time import board import displayio import digitalio from terminalio import FONT from adafruit_display_text import bitmap_label from adafruit_ds3231 import DS3231 from adafruit_ssd1675 import Adafruit_SSD1675 displayio.release_displays() spi board.SPI() busy digitalio.DigitalInOut(board.D9) display_bus displayio.FourWire( spi, commandboard.D6, chip_selectboard.D5, resetboard.D8, baudrate1000000, ) display Adafruit_SSD1675(display_bus, width250, height122, busy_pinbusy) group displayio.Group() bitmap displayio.Bitmap(250, 122, 2) palette displayio.Palette(2) palette[0] 0xFFFFFF palette[1] 0x000000 tilegrid displayio.TileGrid(bitmap, pixel_shaderpalette) group.append(tilegrid) date_label bitmap_label.Label(FONT, text, color0x000000, x30, y40, scale3) time_label bitmap_label.Label(FONT, text, color0x000000, x30, y80, scale3) group.append(date_label) group.append(time_label) display.root_group group i2c board.I2C() rtc DS3231(i2c) # 首次设置时间之后注释掉避免反复覆盖 # rtc.datetime time.struct_time((2025, 1, 1, 12, 0, 0, 2, 1, -1)) while True: display.wake() now rtc.datetime bitmap.fill(0) date_label.text %04d-%02d-%02d % (now.tm_year, now.tm_mon, now.tm_mday) time_label.text %02d:%02d % (now.tm_hour, now.tm_min) display.refresh() display.sleep() time.sleep(900)这个案例里我用了display.sleep()和display.wake()。睡眠状态下驱动芯片仍然保留 RAM 里的画面但内部大部分电路断电整体功耗显著下降。对于一天刷新不到百次的场景这一步骤带来的续航提升非常可观。有朋友问我为什么不用每秒刷新显示秒数答案是没必要而且对墨水屏来说代价很高。墨水屏刷新一次要一两秒期间屏幕会闪一次做时钟如果每分钟闪一次已经足够烦人了更别说每秒。想要看秒建议在屏幕旁边放一个普通 LED 小显示屏电子纸只负责整体布局和低频信息两者各司其职。这个案例实际上是“低频快照”思路的延伸。你可以把 RTC 换成温湿度传感器变成室内环境信息牌也可以把时间格式改成“星期日期时间”的三行布局只要调整 label 的位置即可。关键是不变的骨架wake → 修改内容 → refresh → sleep → 长睡眠。6. 案例三BMP图片轮播和预处理文字显示跑通了很多人会想显示图片。SSD1675 只支持黑白二值图所以图片预处理这一步是成败关键。你不能直接拿一张彩色 JPG 往里砸必须先把它转换成 250×122 像素的 1 位 BMP。我通常用 ImageMagick 一行命令完成转换magick input.png -colorspace Gray -threshold 50% -resize 250x122! display.bmp这条命令把输入图片先转灰度然后按 50% 阈值二值化最后强制缩放到屏幕分辨率。如果你不想装 ImageMagick用 Python Pillow 也能做from PIL import Image img Image.open(input.jpg).convert(L) img img.resize((250, 122), Image.Resampling.LANCZOS) img img.point(lambda x: 0 if x 128 else 255, mode1) img.save(display.bmp)关键是 mode1 这一步它保证保存的是 1 位位图而不是 8 位灰度 BMP。如果直接保存灰度图OnDiskBitmap 读取时的像素格式和屏幕驱动不匹配显示出来可能是一团乱麻。显示 BMP 的代码比显示文字还简单import board import displayio from adafruit_ssd1675 import Adafruit_SSD1675 displayio.release_displays() display_bus displayio.FourWire( board.SPI(), commandboard.D6, chip_selectboard.D5, resetboard.D8, baudrate1000000, ) display Adafruit_SSD1675(display_bus, width250, height122, busy_pinboard.D9) group displayio.Group() bmp displayio.OnDiskBitmap(open(/display.bmp, rb)) tg displayio.TileGrid(bmp, pixel_shaderbmp.pixel_shader) group.append(tg) display.root_group group display.refresh()我踩过的一个坑是黑白反色。用 Pillow 保存的 1 位 BMP部分图片打开后白色区域变成黑色黑色变成白色。原因在于不同工具生成的 BMP 调色板顺序不一样有的 0 号色是黑色有的 0 号色是白色。解决办法很简单在预处理时把阈值反过来x 128改成x 128或者在 Pillow 输出前img ImageOps.invert(img)。你不需要理解 BMP 内部调色板结构只要记住“如果反色就把图片取反再试一次”就好。轮播多张图片也不复杂在 board 上准备好一组 BMP 文件用一个列表保存文件名程序按顺序显示。如果每张图片之间还要自动切换记得在 refresh 后加足够长的延时否则连续刷新会让屏幕来不及完成一次完整电泳画面会一片混乱。图片轮播还有一个内存提醒OnDiskBitmap 不会把整张图片加载进内存而是边读边显示这是它处理大图也不卡的原因。但代价是每次刷新都可能重新读取文件系统所以不要把 BMP 文件做得太大250×122 分辨率的单色图通常只有几千字节完全够用。7. 调试清单花屏、残影与busy卡死我把实际项目里遇到最多的问题整理成一张表方便你按图索骥。这些问题几乎每个 SSD1675 项目都会碰到遇到时先别急着怀疑屏幕坏了。现象可能原因排查顺序刷新后满屏乱码或雪花SPI 速率过高、接线过长、电平不匹配先降 baudrate 到 500kHz其次缩短杜邦线到 10cm 以内检查 3.3V 供电是否稳定画面黑白颠倒Palette 颜色顺序写反或 BMP 调色板顺序不对交换 palette[0] 和 palette[1]对图片做取反处理文字边缘有上一帧残影没有清屏、刷新间隔太短每次渲染前 bitmap.fill(0)控制刷新间隔至少 30 秒以上BUSY 一直忙refresh 卡死RST 引脚接错、供电电流不足、初始化顺序错误重新上电检查 RST 接线用最小代码排除干扰刷新后只有半边有图width/height 与物理分辨率不匹配确认模块型号核对分辨率参数屏幕偶尔突然全黑刷新过程中电源被拉垮给模块加一个大容量电容或改用质量更好的电源线花屏问题最隐蔽的原因之一是电源。电子纸刷新时需要内部电荷泵升压瞬间电流会比静态显示大不少。如果开发板的 3.3V 输出能力偏弱或者你用了一根材质很差的 USB 线供电刷新瞬间电压跌落SPI 通信就会出现随机错误。遇到间歇性花屏先接一个 100uF 电容在屏幕模块的 VCC 和 GND 之间成本极低但往往立竿见影。残影则是电子纸的物理特性。每次刷新后上一帧画面里的电泳粒子不会完全归位总有一部分会停留在原处。如果屏幕长期显示同一个页面偶尔做一次“全黑全白交替刷新”其实是有益的它能强制粒子回到稳定状态。这也解释了为什么价签类产品每次更新商品信息时屏幕上会先出现一团黑色翻动那是正常的工作流程不是你代码写错了。BUSY 卡死是我排查过最久的问题。有一次我把 RST 引脚插到了只能输出高电平的 GPIO 上结果每次上电驱动都不执行复位refresh 永远停在等待 BUSY 的那一步。后来我把复位改成手动触发重新上电才恢复正常。所以当你 debug 到 refresh 卡住时不要只盯着 BUSY 线还要回头确认 RST 引脚是否真的能正常拉低拉高。花屏和乱码还有一个容易踩的坑就是displayio.FourWire里的 baudrate 参数。SSD1675 的 SPI 接口理论速率能到几 MHz但实际开发板上受接线、引脚毛刺、电源噪声影响1MHz 以下才最稳。我一般在原型阶段固定用 1MHz出现问题时降到 500kHz。代码性能瓶颈从来不在 SPI 速率而在电子纸自身的刷新时间。最后分享一个小技巧调试任何基于 SSD1675 的应用时先在屏幕上画一个填满整个屏幕的大方块再画一个紧贴边框的细线框。大方块能验证白黑切换是否正常细线框能验证坐标范围是否溢出。这两步通过后再往里加文字、图片或业务逻辑你会省掉大量无意义的 debug 时间。屏幕本身不复杂复杂的是你对坐标、颜色和刷新时序的理解把这三件事捋顺SSD1675 就能真正变成一个安静可靠的信息面板。

CircuitPython驱动SSD1675墨水屏：从环境搭建到三个实战案例

相关推荐

空间数据：数字孪生的底线，而非可选项

PreparedStatement 防不住的 SQL 注入盲区与安全实践

数字孪生90%是假象：空间数据底座才是真孪生的命门

更多资讯

CHS-DRG分组器开发实战：Python病案首页数据提取与ICD线性化处理

开放智能体安全平台：从提示词约束到策略引擎的智能体行为管控

MySQL全量备份深度解析：mysqldump参数、恢复演练与自动化脚本

自由能原理如何驱动神经元集群：从预测编码到最小自由能机器

IEEE标准节点系统仿真模型搭建与校验实战指南

无人机河道漂浮检测数据集构建实战：五类目标识别全流程解析

今日更新

智能硬件视频会议集成：从芯片选型到场景落地的全栈实践

FFmpeg音视频处理与5路RTMP推流实战：从原理到118克盒子部署

RK3528+1GB内存如何变身直播节点？硬编解码与六协议实战复盘

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？