1. 项目概述一块“麻雀虽小五脏俱全”的交互式显示盾板如果你玩过Arduino或者树莓派Pico这类微控制器肯定遇到过这样的烦恼想给项目加个屏幕显示点信息或者做个简单的交互界面结果发现连线一大堆光是驱动屏幕就要占用好几个宝贵的GPIO引脚更别提还要接按钮、摇杆了。整个项目面包板上线缆纵横交错既不稳定也不美观。Adafruit的1.8英寸TFT Shield V2就是为了解决这个痛点而生的。它不仅仅是一块屏幕更是一个高度集成的“交互子系统”。这块盾板的核心是一块128x160像素的彩色TFT显示屏通过SPI接口与主控通信。但它的精髓在于那颗小小的seesaw I2C扩展芯片——它把屏幕背光控制、复位信号以及板上所有的按钮A、B、C和那个五向摇杆的检测全部“打包”到了I2C总线上。这意味着你只需要占用主控的SPI引脚SCK, MOSI和两个额外的数字引脚D10, D8再加上I2C的两根线SDA, SCL就能获得一个完整的、带输入设备的显示模块。对于GPIO资源紧张的微控制器项目来说这种设计简直是雪中送炭。我最近在一个环境监测仪表项目里用到了它需要实时显示温湿度、气压数据并通过摇杆和按钮切换显示页面、设置阈值。V2 Shield的集成度让我省去了大量底层连线和驱动调试的时间能更专注于应用逻辑本身。接下来我就结合自己的实操经验带你从硬件拆解到软件驱动彻底玩转这块高效的显示盾板。2. 硬件深度解析不只是屏幕更是智能外设集刚拿到这块盾板时别急着上电写代码。花几分钟理解它的硬件架构能让你在后续开发中避开很多坑尤其是区分V1和V2版本这至关重要。2.1 核心显示单元ST7735S驱动芯片与接口位于盾板中央的1.8英寸TFT显示屏其背后的“大脑”是一颗ST7735S驱动芯片。这是一款非常流行的中小尺寸TFT驱动IC支持最高18位色深262K色在这里以16位RGB565格式模式工作。通信接口它采用标准的4线SPI接口这是其高速刷新的基础。SCK (Serial Clock)SPI时钟线由主控提供。MOSI (Master Out Slave In)主控输出、屏幕输入的数据线。CS (Chip Select, 连接至 D10)片选信号低电平有效。这是告诉屏幕“现在数据是发给你的。”DC (Data/Command, 连接至 D8)数据/命令选择线。这是SPI屏驱动中的一个关键引脚。当DC为高电平时MOSI上传送的是要显示的像素数据当DC为低电平时传送的是给ST7735S的配置命令如初始化序列、设置扫描方向等。很多驱动不成功的问题都源于对这个引脚的理解或配置有误。电源与背光屏幕需要3.3V供电。背光由一组LED提供其亮度并非简单的高低电平控制而是由seesaw芯片产生一个PWM脉冲宽度调制信号来调节这意味着你可以在代码中实现背光亮度的平滑调节。注意务必确认你的主控板逻辑电平是3.3V。虽然很多5V Arduino如Uno也能工作因为屏上可能有电平转换电路但最稳妥的方式是使用3.3V逻辑的主控如大多数32位ARM Cortex-M系列板卡以避免长期使用可能对屏幕造成的损害。2.2 交互输入与智慧管理seesaw I2C扩展器这是V2 Shield相对于老版本最大的升级也是其设计巧妙之处。为什么要用seesaw试想如果没有它你需要如何连接屏幕背光控制1个GPIOPWM。屏幕复位1个GPIO。3个按钮A, B, C各需1个GPIO配置为上拉输入。1个五向摇杆上、下、左、右、按下理想情况需要5个GPIO或者通过模拟引脚电阻分压网络读取。这样算下来至少需要8-10个专用GPIO这对于只有20个左右GPIO的常见微控制器如ATmega328P来说是巨大的负担。seesaw芯片通过I2C接口将所有这些输入/输出功能“聚合”起来。主控只需要通过两根I2C线SDA, SCL与seesaw通信就能读取所有按钮和摇杆的状态并控制背光。这极大地释放了主控的GPIO资源。seesaw的工作原理你可以把它理解为一个“远程的GPIO扩展器”。主控通过I2C向seesaw发送指令例如“请把连接背光的那个引脚输出PWM信号占空比设为50%”或者“请告诉我所有按钮引脚当前的输入状态”。seesaw内部处理这些请求并操作其真实的物理引脚。Adafruit提供了封装好的adafruit_seesaw库使得这些操作像读写本地GPIO一样简单。一个关键细节即使你的程序暂时不需要读取按钮或摇杆也必须初始化seesaw。因为屏幕的复位tft_reset()和背光控制set_backlight()函数都是通过seesaw芯片来执行的。忽略这一步会导致屏幕无法正常点亮或初始化。2.3 其他实用组件SD卡与复位按钮Micro SD卡槽通过SPI接口连接与屏幕共享SCK、MOSI但使用独立的片选引脚D4。它主要用于存储图片、字体文件或数据日志。在显示静态图片如启动logo或需要大量字体的项目中非常有用。注意当同时使用屏幕和SD卡时要确保SPI总线的操作是分时复用的避免冲突。通常的库会处理好片选信号。复位按钮直接连接到主控的复位引脚。按下它会导致整个微控制器重启程序从头开始运行。在调试时非常方便。2.4 V1与V2版本的关键区别与识别原始资料中提到了“Original V1 Shield”区分它们非常重要因为驱动方式完全不同。V1旧版没有seesaw芯片。按钮和摇杆直接占用大量GPIO摇杆通常使用一个模拟引脚通过电阻网络读取。屏幕的背光和复位可能由独立引脚控制。代码上需要使用软件SPI或特定的引脚定义兼容性较差尤其在非ATmega328P主控上。V2新版带seesaw就是我们重点讨论的版本。板上有一颗明显的seesaw芯片通常印有标识。所有输入和背光控制都通过I2C。代码使用硬件SPI并依赖adafruit_seesaw.tftshield18库。如何识别最直观的方法是看板子。如果屏幕下方有三个标有A、B、C的按钮并且板子上有一颗除了主控和屏幕驱动IC以外的芯片seesaw那基本就是V2。也可以查看产品页面或包装上的型号。3. 软件环境搭建与CircuitPython驱动详解硬件了然于胸后我们来搞定软件部分。我将以CircuitPython为例进行讲解因为它对显示和高级外设的支持越来越完善代码也更简洁易读。3.1 准备工作固件与库文件刷写CircuitPython固件首先确保你的主控板如Adafruit Metro M4 Express、RP2040等已经刷写了最新版本的CircuitPython固件。去Adafruit官网找到对应板子的页面下载最新的.uf2文件通常通过按住板上的BOOT/USB按钮再上电会出现一个可移动磁盘把.uf2文件拖进去即可。获取必要的库文件CircuitPython通过“库”来扩展功能。你需要下载最新的“Adafruit CircuitPython Library Bundle”。解压后找到以下库文件/文件夹并将其复制到你的CircuitPython设备的lib文件夹中如果lib文件夹不存在就创建一个adafruit_st7735r.mpy- ST7735R显示屏驱动。adafruit_seesaw.mpy- seesaw芯片的核心库。adafruit_seesaw/- seesaw库的辅助文件夹通常包含tftshield18.py等。adafruit_bus_device/- 提供I2C、SPI等总线设备的支持。实操心得在Windows系统下直接复制.mpy文件有时会遇到设备繁忙的提示。一个可靠的方法是先安全弹出CIRCUITPY磁盘然后重新插拔USB线在它被系统重新识别但CircuitPython还未完全挂载文件系统的瞬间快速粘贴。或者使用Mac或Linux系统进行文件操作会更稳定。3.2 核心代码逐行解析下面是一个完整的、带详细注释的测试代码它初始化屏幕并持续检测所有按钮和摇杆的按下状态通过串口打印信息。# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT 1.8英寸 TFT Shield V2 功能测试 初始化显示屏并读取所有按键与摇杆输入 import time import board import displayio # 导入针对此盾板优化的seesaw子模块 from adafruit_seesaw.tftshield18 import TFTShield18 # 导入ST7735R显示屏驱动 from adafruit_st7735r import ST7735R # 处理displayio库版本兼容性问题 (CircuitPython 8.x vs 9.x) try: from fourwire import FourWire except ImportError: from displayio import FourWire # 关键步骤释放之前可能占用的显示资源 # 特别是在软复位后避免引脚冲突 displayio.release_displays() # 初始化seesaw芯片这是控制背光和读取输入的前提 ss TFTShield18() # 设置SPI总线。board.SPI()会自动选择主控板默认的SPI引脚 spi board.SPI() # 定义TFT屏的片选(CS)和数据/命令(DC)引脚 tft_cs board.D10 tft_dc board.D8 # 创建FourWire显示总线对象它封装了SPI通信和DC引脚控制 display_bus FourWire(spi, commandtft_dc, chip_selecttft_cs) # 通过seesaw发送复位信号给TFT屏幕 ss.tft_reset() # 初始化ST7735R驱动 # width160, height128: 定义显示分辨率 # rotation90: 将屏幕旋转90度通常是为了适应盾板的物理安装方向 # bgrTrue: 某些ST7735屏幕的像素颜色顺序是BGR而非RGB需要此设置 display ST7735R(display_bus, width160, height128, rotation90, bgrTrue) # 打开屏幕背光。你也可以传入0.0到1.0之间的值来调节亮度例如ss.set_backlight(0.5) ss.set_backlight(True) print(TFT Shield V2 初始化完成开始检测输入...) # 主循环持续读取输入状态 while True: # 从seesaw一次性读取所有按钮和摇杆的状态 # buttons是一个对象其属性如.up, .a等在按下时为True buttons ss.buttons # 检测五向摇杆的各个方向及按下动作 if buttons.right: print(摇杆: 右) if buttons.down: print(摇杆: 下) if buttons.left: print(摇杆: 左) if buttons.up: print(摇杆: 上) if buttons.select: # 注意在seesaw库中摇杆的按下动作通常映射为‘select’ print(摇杆: 按下(SELECT)) # 检测A、B、C三个独立按钮 if buttons.a: print(按钮 A 被按下) if buttons.b: print(按钮 B 被按下) if buttons.c: print(按钮 C 被按下) # 短暂延时降低CPU占用率并起到简单的防抖作用 # 对于需要快速响应的游戏可以减小或取消这个延时 time.sleep(0.01)代码要点与避坑指南displayio.release_displays()这行代码至关重要。在CircuitPython中显示对象会“锁定”所使用的硬件引脚。如果程序崩溃后软复位或者你重新运行了代码之前的显示对象可能没有正确释放引脚导致新的初始化失败。加上这行代码是一个好习惯。rotation90屏幕的物理0度方向即(0,0)坐标所在的位置可能和你的安装预期不符。通过调整rotation参数0, 90, 180, 270可以轻松旋转显示内容。bgrTrue这是一个常见的坑点。不同批次的ST7735屏幕其内部颜色字节顺序可能不同。如果显示颜色异常比如红色和蓝色反了尝试将bgr设置为False。按钮读取ss.buttons返回的是一个状态“快照”。在主循环中如果按住按钮不放会连续打印信息。在实际项目中你可能需要记录“按下”和“释放”事件这通常通过比较当前状态和上一次状态来实现。3.3 进阶应用使用displayio创建图形界面仅仅打印文本到串口显然浪费了这块彩屏。CircuitPython的displayio模块提供了强大的图形原语支持。下面我们创建一个简单的信息面板显示模拟的系统状态。import terminalio from adafruit_display_text import label import vectorio import adafruit_imageload # ... 前面的初始化代码与之前相同直到创建display对象 ... # 创建一个显示组Group它是所有显示元素的容器 main_group displayio.Group() display.root_group main_group # 将组设置为屏幕的根内容 # 1. 绘制一个背景矩形 # 使用vectorio创建矩形Palette定义颜色 palette displayio.Palette(1) palette[0] 0x000033 # 深蓝色 background vectorio.Rectangle(pixel_shaderpalette, widthdisplay.width, heightdisplay.height, x0, y0) main_group.append(background) # 2. 创建文本标签 # 使用内置字体 font terminalio.FONT text_area1 label.Label(font, textSystem Info, color0xFFFFFF, x10, y10) text_area2 label.Label(font, textCPU: 45%, color0xFFFF00, x10, y30) text_area3 label.Label(font, textMEM: 78%, color0x00FF00, x10, y50) text_area4 label.Label(font, textTEMP: 32C, color0xFF00FF, x10, y70) main_group.append(text_area1) main_group.append(text_area2) main_group.append(text_area3) main_group.append(text_area4) # 3. 加载并显示一张位图图片需将图片放入CIRCUITPY根目录 try: image, palette adafruit_imageload.load(/bg_image.bmp, bitmapdisplayio.Bitmap, palettedisplayio.Palette) # 创建一个TileGrid来放置图片 tile_grid displayio.TileGrid(image, pixel_shaderpalette, x90, y20) main_group.append(tile_grid) except OSError: print(未找到图片文件 /bg_image.bmp) print(图形界面已加载。使用摇杆和按钮交互。) # 主循环更新界面并响应输入 counter 0 while True: buttons ss.buttons # 示例用A按钮切换一个文本的颜色 if buttons.a: text_area1.color 0xFF0000 if text_area1.color 0xFFFFFF else 0xFFFFFF time.sleep(0.2) # 简单防抖 # 示例用摇杆上下移动第二个文本标签 if buttons.up: text_area2.y max(10, text_area2.y - 2) if buttons.down: text_area2.y min(110, text_area2.y 2) # 模拟动态更新文本内容 counter 1 text_area3.text fCOUNT: {counter % 100} time.sleep(0.05)这个例子展示了displayio的核心概念Group、TileGrid、Label和Palette。你可以通过动态修改这些对象的属性如text、color、x、y来创建丰富的动态界面。4. 常见问题排查与实战技巧即使按照步骤操作也可能会遇到问题。下面是我在多个项目中总结的常见故障点及其解决方法。4.1 屏幕无显示或花屏这是最常见的问题通常与初始化顺序、引脚配置或电源有关。现象可能原因排查步骤与解决方案屏幕完全空白背光也不亮1. 电源问题。2. 背光未开启。3. seesaw初始化失败。1. 用万用表检查VIN和3.3V引脚电压是否正常。2. 确认代码中执行了ss.set_backlight(True)。3. 检查I2C连接。在代码开头添加import busio并运行i2c busio.I2C(board.SCL, board.SDA); print(“I2C devices found:”, i2c.scan())看是否能找到seesaw的地址通常是0x49或0x50。背光亮但屏幕全白、全黑或有规律条纹1. 复位时序问题。2. SPI速率过快。3.bgr参数设置错误。4. 分辨率或旋转设置错误。1. 确保在初始化显示驱动之前调用了ss.tft_reset()。2. 尝试在初始化SPI时降低波特率spi board.SPI(baudrate1000000)默认通常很高。3. 尝试将ST7735R初始化中的bgrTrue改为bgrFalse。4. 核对width和height是否为160和128尝试不同的rotation值。显示内容错位、撕裂或部分区域异常1. 内存不足或帧缓冲区错误。2. 主循环处理太慢导致刷新不同步。1. 确保主控板有足够RAM。简化displayio的Group结构减少同时显示的复杂对象。2. 优化代码避免在主循环中进行大量计算或阻塞操作。使用time.monotonic()进行非阻塞延时。4.2 按钮或摇杆无响应输入功能依赖I2C通信和seesaw芯片。现象可能原因排查步骤与解决方案所有按钮和摇杆均无响应1. I2C总线通信失败。2.TFTShield18()对象初始化失败。3. 库文件缺失或版本不匹配。1. 同上述“屏幕无显示”中的I2C扫描步骤确认seesaw被识别。2. 检查lib文件夹中是否有完整的adafruit_seesaw.mpy及其子目录。3. 尝试更新到最新版本的CircuitPython库Bundle。个别按钮无响应1. 硬件接触不良如虚焊。2. 代码中读取的逻辑错误。1. 仔细检查该按钮对应的引脚与seesaw的焊接点。2. 使用示例代码测试确认是硬件问题还是软件问题。示例代码中buttons.a等属性名是固定的不要写错。摇杆方向识别不准1. 摇杆是模拟量数字按键而V2 Shield已将其数字化。此问题在V2上较少见。2. 机械磨损或损坏。1. V2 Shield的摇杆状态是通过seesaw以数字方式按下/未按下报告的而非模拟值。确认你使用的是正确的属性buttons.up,.down等。2. 如果是老V1 Shield需要校准模拟读取的阈值代码中CheckJoystick()函数的数值范围50, 150, 250...可能需要根据实际硬件调整。4.3 性能优化与高级技巧当项目复杂后你可能会觉得刷新速度不够快或者内存紧张。这里有一些进阶技巧使用displayio.OnDiskBitmap显示图片前面的例子用adafruit_imageload将整个位图加载到内存中对于大图片很耗RAM。OnDiskBitmap可以直接从存储设备流式读取并显示图片极大节省内存。odb displayio.OnDiskBitmap(/large_image.bmp) tile_grid displayio.TileGrid(odb, pixel_shaderdisplayio.ColorConverter(), x0, y0) group.append(tile_grid)局部刷新与脏矩形displayio会自动管理刷新但如果你在频繁更新一个很小的区域如一个数字可以尝试将变化的内容放在一个独立的Group中但更有效的方法是理解displayio的刷新机制——它通常足够智能。避免频繁创建和销毁对象重用对象并只修改其属性。处理按钮的长按与短按示例代码只检测了“按下”状态。要实现“长按”、“短按”、“双击”需要记录时间戳。import time a_pressed_time None while True: buttons ss.buttons if buttons.a: if a_pressed_time is None: # 首次按下 a_pressed_time time.monotonic() else: if a_pressed_time is not None: # 刚刚释放 press_duration time.monotonic() - a_pressed_time if press_duration 1.0: print(A按钮长按) else: print(A按钮短按) a_pressed_time None time.sleep(0.05)与SD卡共用SPI总线如果你需要同时使用屏幕和SD卡确保在访问其中一个设备时正确控制其片选CS引脚。adafruit_sdcard库和displayio通常能很好地协同工作因为它们都会在操作前后拉低和拉高各自的CS引脚。关键是确保你的接线正确SD卡CS接D4并且在代码中为SD卡创建SPI对象时使用与屏幕相同的spi总线对象但指定不同的片选引脚。这块1.8英寸TFT Shield V2是我项目箱里的常客它的高度集成性在快速原型开发阶段无可替代。从简单的传感器数据显示到带有菜单的交互设备它都能胜任。最关键的是吃透了seesaw那套I2C管理GPIO的思路后你会发现在资源受限的嵌入式环境里通过I2C扩展器来管理多个低速外设是一种非常优雅和高效的设计模式。下次当你面对一堆需要连接的按钮和LED时不妨想想是否也能用一颗小小的seesaw来简化你的电路和代码。
Adafruit 1.8英寸TFT Shield V2：集成seesaw芯片的微控制器显示交互方案
1. 项目概述一块“麻雀虽小五脏俱全”的交互式显示盾板如果你玩过Arduino或者树莓派Pico这类微控制器肯定遇到过这样的烦恼想给项目加个屏幕显示点信息或者做个简单的交互界面结果发现连线一大堆光是驱动屏幕就要占用好几个宝贵的GPIO引脚更别提还要接按钮、摇杆了。整个项目面包板上线缆纵横交错既不稳定也不美观。Adafruit的1.8英寸TFT Shield V2就是为了解决这个痛点而生的。它不仅仅是一块屏幕更是一个高度集成的“交互子系统”。这块盾板的核心是一块128x160像素的彩色TFT显示屏通过SPI接口与主控通信。但它的精髓在于那颗小小的seesaw I2C扩展芯片——它把屏幕背光控制、复位信号以及板上所有的按钮A、B、C和那个五向摇杆的检测全部“打包”到了I2C总线上。这意味着你只需要占用主控的SPI引脚SCK, MOSI和两个额外的数字引脚D10, D8再加上I2C的两根线SDA, SCL就能获得一个完整的、带输入设备的显示模块。对于GPIO资源紧张的微控制器项目来说这种设计简直是雪中送炭。我最近在一个环境监测仪表项目里用到了它需要实时显示温湿度、气压数据并通过摇杆和按钮切换显示页面、设置阈值。V2 Shield的集成度让我省去了大量底层连线和驱动调试的时间能更专注于应用逻辑本身。接下来我就结合自己的实操经验带你从硬件拆解到软件驱动彻底玩转这块高效的显示盾板。2. 硬件深度解析不只是屏幕更是智能外设集刚拿到这块盾板时别急着上电写代码。花几分钟理解它的硬件架构能让你在后续开发中避开很多坑尤其是区分V1和V2版本这至关重要。2.1 核心显示单元ST7735S驱动芯片与接口位于盾板中央的1.8英寸TFT显示屏其背后的“大脑”是一颗ST7735S驱动芯片。这是一款非常流行的中小尺寸TFT驱动IC支持最高18位色深262K色在这里以16位RGB565格式模式工作。通信接口它采用标准的4线SPI接口这是其高速刷新的基础。SCK (Serial Clock)SPI时钟线由主控提供。MOSI (Master Out Slave In)主控输出、屏幕输入的数据线。CS (Chip Select, 连接至 D10)片选信号低电平有效。这是告诉屏幕“现在数据是发给你的。”DC (Data/Command, 连接至 D8)数据/命令选择线。这是SPI屏驱动中的一个关键引脚。当DC为高电平时MOSI上传送的是要显示的像素数据当DC为低电平时传送的是给ST7735S的配置命令如初始化序列、设置扫描方向等。很多驱动不成功的问题都源于对这个引脚的理解或配置有误。电源与背光屏幕需要3.3V供电。背光由一组LED提供其亮度并非简单的高低电平控制而是由seesaw芯片产生一个PWM脉冲宽度调制信号来调节这意味着你可以在代码中实现背光亮度的平滑调节。注意务必确认你的主控板逻辑电平是3.3V。虽然很多5V Arduino如Uno也能工作因为屏上可能有电平转换电路但最稳妥的方式是使用3.3V逻辑的主控如大多数32位ARM Cortex-M系列板卡以避免长期使用可能对屏幕造成的损害。2.2 交互输入与智慧管理seesaw I2C扩展器这是V2 Shield相对于老版本最大的升级也是其设计巧妙之处。为什么要用seesaw试想如果没有它你需要如何连接屏幕背光控制1个GPIOPWM。屏幕复位1个GPIO。3个按钮A, B, C各需1个GPIO配置为上拉输入。1个五向摇杆上、下、左、右、按下理想情况需要5个GPIO或者通过模拟引脚电阻分压网络读取。这样算下来至少需要8-10个专用GPIO这对于只有20个左右GPIO的常见微控制器如ATmega328P来说是巨大的负担。seesaw芯片通过I2C接口将所有这些输入/输出功能“聚合”起来。主控只需要通过两根I2C线SDA, SCL与seesaw通信就能读取所有按钮和摇杆的状态并控制背光。这极大地释放了主控的GPIO资源。seesaw的工作原理你可以把它理解为一个“远程的GPIO扩展器”。主控通过I2C向seesaw发送指令例如“请把连接背光的那个引脚输出PWM信号占空比设为50%”或者“请告诉我所有按钮引脚当前的输入状态”。seesaw内部处理这些请求并操作其真实的物理引脚。Adafruit提供了封装好的adafruit_seesaw库使得这些操作像读写本地GPIO一样简单。一个关键细节即使你的程序暂时不需要读取按钮或摇杆也必须初始化seesaw。因为屏幕的复位tft_reset()和背光控制set_backlight()函数都是通过seesaw芯片来执行的。忽略这一步会导致屏幕无法正常点亮或初始化。2.3 其他实用组件SD卡与复位按钮Micro SD卡槽通过SPI接口连接与屏幕共享SCK、MOSI但使用独立的片选引脚D4。它主要用于存储图片、字体文件或数据日志。在显示静态图片如启动logo或需要大量字体的项目中非常有用。注意当同时使用屏幕和SD卡时要确保SPI总线的操作是分时复用的避免冲突。通常的库会处理好片选信号。复位按钮直接连接到主控的复位引脚。按下它会导致整个微控制器重启程序从头开始运行。在调试时非常方便。2.4 V1与V2版本的关键区别与识别原始资料中提到了“Original V1 Shield”区分它们非常重要因为驱动方式完全不同。V1旧版没有seesaw芯片。按钮和摇杆直接占用大量GPIO摇杆通常使用一个模拟引脚通过电阻网络读取。屏幕的背光和复位可能由独立引脚控制。代码上需要使用软件SPI或特定的引脚定义兼容性较差尤其在非ATmega328P主控上。V2新版带seesaw就是我们重点讨论的版本。板上有一颗明显的seesaw芯片通常印有标识。所有输入和背光控制都通过I2C。代码使用硬件SPI并依赖adafruit_seesaw.tftshield18库。如何识别最直观的方法是看板子。如果屏幕下方有三个标有A、B、C的按钮并且板子上有一颗除了主控和屏幕驱动IC以外的芯片seesaw那基本就是V2。也可以查看产品页面或包装上的型号。3. 软件环境搭建与CircuitPython驱动详解硬件了然于胸后我们来搞定软件部分。我将以CircuitPython为例进行讲解因为它对显示和高级外设的支持越来越完善代码也更简洁易读。3.1 准备工作固件与库文件刷写CircuitPython固件首先确保你的主控板如Adafruit Metro M4 Express、RP2040等已经刷写了最新版本的CircuitPython固件。去Adafruit官网找到对应板子的页面下载最新的.uf2文件通常通过按住板上的BOOT/USB按钮再上电会出现一个可移动磁盘把.uf2文件拖进去即可。获取必要的库文件CircuitPython通过“库”来扩展功能。你需要下载最新的“Adafruit CircuitPython Library Bundle”。解压后找到以下库文件/文件夹并将其复制到你的CircuitPython设备的lib文件夹中如果lib文件夹不存在就创建一个adafruit_st7735r.mpy- ST7735R显示屏驱动。adafruit_seesaw.mpy- seesaw芯片的核心库。adafruit_seesaw/- seesaw库的辅助文件夹通常包含tftshield18.py等。adafruit_bus_device/- 提供I2C、SPI等总线设备的支持。实操心得在Windows系统下直接复制.mpy文件有时会遇到设备繁忙的提示。一个可靠的方法是先安全弹出CIRCUITPY磁盘然后重新插拔USB线在它被系统重新识别但CircuitPython还未完全挂载文件系统的瞬间快速粘贴。或者使用Mac或Linux系统进行文件操作会更稳定。3.2 核心代码逐行解析下面是一个完整的、带详细注释的测试代码它初始化屏幕并持续检测所有按钮和摇杆的按下状态通过串口打印信息。# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT 1.8英寸 TFT Shield V2 功能测试 初始化显示屏并读取所有按键与摇杆输入 import time import board import displayio # 导入针对此盾板优化的seesaw子模块 from adafruit_seesaw.tftshield18 import TFTShield18 # 导入ST7735R显示屏驱动 from adafruit_st7735r import ST7735R # 处理displayio库版本兼容性问题 (CircuitPython 8.x vs 9.x) try: from fourwire import FourWire except ImportError: from displayio import FourWire # 关键步骤释放之前可能占用的显示资源 # 特别是在软复位后避免引脚冲突 displayio.release_displays() # 初始化seesaw芯片这是控制背光和读取输入的前提 ss TFTShield18() # 设置SPI总线。board.SPI()会自动选择主控板默认的SPI引脚 spi board.SPI() # 定义TFT屏的片选(CS)和数据/命令(DC)引脚 tft_cs board.D10 tft_dc board.D8 # 创建FourWire显示总线对象它封装了SPI通信和DC引脚控制 display_bus FourWire(spi, commandtft_dc, chip_selecttft_cs) # 通过seesaw发送复位信号给TFT屏幕 ss.tft_reset() # 初始化ST7735R驱动 # width160, height128: 定义显示分辨率 # rotation90: 将屏幕旋转90度通常是为了适应盾板的物理安装方向 # bgrTrue: 某些ST7735屏幕的像素颜色顺序是BGR而非RGB需要此设置 display ST7735R(display_bus, width160, height128, rotation90, bgrTrue) # 打开屏幕背光。你也可以传入0.0到1.0之间的值来调节亮度例如ss.set_backlight(0.5) ss.set_backlight(True) print(TFT Shield V2 初始化完成开始检测输入...) # 主循环持续读取输入状态 while True: # 从seesaw一次性读取所有按钮和摇杆的状态 # buttons是一个对象其属性如.up, .a等在按下时为True buttons ss.buttons # 检测五向摇杆的各个方向及按下动作 if buttons.right: print(摇杆: 右) if buttons.down: print(摇杆: 下) if buttons.left: print(摇杆: 左) if buttons.up: print(摇杆: 上) if buttons.select: # 注意在seesaw库中摇杆的按下动作通常映射为‘select’ print(摇杆: 按下(SELECT)) # 检测A、B、C三个独立按钮 if buttons.a: print(按钮 A 被按下) if buttons.b: print(按钮 B 被按下) if buttons.c: print(按钮 C 被按下) # 短暂延时降低CPU占用率并起到简单的防抖作用 # 对于需要快速响应的游戏可以减小或取消这个延时 time.sleep(0.01)代码要点与避坑指南displayio.release_displays()这行代码至关重要。在CircuitPython中显示对象会“锁定”所使用的硬件引脚。如果程序崩溃后软复位或者你重新运行了代码之前的显示对象可能没有正确释放引脚导致新的初始化失败。加上这行代码是一个好习惯。rotation90屏幕的物理0度方向即(0,0)坐标所在的位置可能和你的安装预期不符。通过调整rotation参数0, 90, 180, 270可以轻松旋转显示内容。bgrTrue这是一个常见的坑点。不同批次的ST7735屏幕其内部颜色字节顺序可能不同。如果显示颜色异常比如红色和蓝色反了尝试将bgr设置为False。按钮读取ss.buttons返回的是一个状态“快照”。在主循环中如果按住按钮不放会连续打印信息。在实际项目中你可能需要记录“按下”和“释放”事件这通常通过比较当前状态和上一次状态来实现。3.3 进阶应用使用displayio创建图形界面仅仅打印文本到串口显然浪费了这块彩屏。CircuitPython的displayio模块提供了强大的图形原语支持。下面我们创建一个简单的信息面板显示模拟的系统状态。import terminalio from adafruit_display_text import label import vectorio import adafruit_imageload # ... 前面的初始化代码与之前相同直到创建display对象 ... # 创建一个显示组Group它是所有显示元素的容器 main_group displayio.Group() display.root_group main_group # 将组设置为屏幕的根内容 # 1. 绘制一个背景矩形 # 使用vectorio创建矩形Palette定义颜色 palette displayio.Palette(1) palette[0] 0x000033 # 深蓝色 background vectorio.Rectangle(pixel_shaderpalette, widthdisplay.width, heightdisplay.height, x0, y0) main_group.append(background) # 2. 创建文本标签 # 使用内置字体 font terminalio.FONT text_area1 label.Label(font, textSystem Info, color0xFFFFFF, x10, y10) text_area2 label.Label(font, textCPU: 45%, color0xFFFF00, x10, y30) text_area3 label.Label(font, textMEM: 78%, color0x00FF00, x10, y50) text_area4 label.Label(font, textTEMP: 32C, color0xFF00FF, x10, y70) main_group.append(text_area1) main_group.append(text_area2) main_group.append(text_area3) main_group.append(text_area4) # 3. 加载并显示一张位图图片需将图片放入CIRCUITPY根目录 try: image, palette adafruit_imageload.load(/bg_image.bmp, bitmapdisplayio.Bitmap, palettedisplayio.Palette) # 创建一个TileGrid来放置图片 tile_grid displayio.TileGrid(image, pixel_shaderpalette, x90, y20) main_group.append(tile_grid) except OSError: print(未找到图片文件 /bg_image.bmp) print(图形界面已加载。使用摇杆和按钮交互。) # 主循环更新界面并响应输入 counter 0 while True: buttons ss.buttons # 示例用A按钮切换一个文本的颜色 if buttons.a: text_area1.color 0xFF0000 if text_area1.color 0xFFFFFF else 0xFFFFFF time.sleep(0.2) # 简单防抖 # 示例用摇杆上下移动第二个文本标签 if buttons.up: text_area2.y max(10, text_area2.y - 2) if buttons.down: text_area2.y min(110, text_area2.y 2) # 模拟动态更新文本内容 counter 1 text_area3.text fCOUNT: {counter % 100} time.sleep(0.05)这个例子展示了displayio的核心概念Group、TileGrid、Label和Palette。你可以通过动态修改这些对象的属性如text、color、x、y来创建丰富的动态界面。4. 常见问题排查与实战技巧即使按照步骤操作也可能会遇到问题。下面是我在多个项目中总结的常见故障点及其解决方法。4.1 屏幕无显示或花屏这是最常见的问题通常与初始化顺序、引脚配置或电源有关。现象可能原因排查步骤与解决方案屏幕完全空白背光也不亮1. 电源问题。2. 背光未开启。3. seesaw初始化失败。1. 用万用表检查VIN和3.3V引脚电压是否正常。2. 确认代码中执行了ss.set_backlight(True)。3. 检查I2C连接。在代码开头添加import busio并运行i2c busio.I2C(board.SCL, board.SDA); print(“I2C devices found:”, i2c.scan())看是否能找到seesaw的地址通常是0x49或0x50。背光亮但屏幕全白、全黑或有规律条纹1. 复位时序问题。2. SPI速率过快。3.bgr参数设置错误。4. 分辨率或旋转设置错误。1. 确保在初始化显示驱动之前调用了ss.tft_reset()。2. 尝试在初始化SPI时降低波特率spi board.SPI(baudrate1000000)默认通常很高。3. 尝试将ST7735R初始化中的bgrTrue改为bgrFalse。4. 核对width和height是否为160和128尝试不同的rotation值。显示内容错位、撕裂或部分区域异常1. 内存不足或帧缓冲区错误。2. 主循环处理太慢导致刷新不同步。1. 确保主控板有足够RAM。简化displayio的Group结构减少同时显示的复杂对象。2. 优化代码避免在主循环中进行大量计算或阻塞操作。使用time.monotonic()进行非阻塞延时。4.2 按钮或摇杆无响应输入功能依赖I2C通信和seesaw芯片。现象可能原因排查步骤与解决方案所有按钮和摇杆均无响应1. I2C总线通信失败。2.TFTShield18()对象初始化失败。3. 库文件缺失或版本不匹配。1. 同上述“屏幕无显示”中的I2C扫描步骤确认seesaw被识别。2. 检查lib文件夹中是否有完整的adafruit_seesaw.mpy及其子目录。3. 尝试更新到最新版本的CircuitPython库Bundle。个别按钮无响应1. 硬件接触不良如虚焊。2. 代码中读取的逻辑错误。1. 仔细检查该按钮对应的引脚与seesaw的焊接点。2. 使用示例代码测试确认是硬件问题还是软件问题。示例代码中buttons.a等属性名是固定的不要写错。摇杆方向识别不准1. 摇杆是模拟量数字按键而V2 Shield已将其数字化。此问题在V2上较少见。2. 机械磨损或损坏。1. V2 Shield的摇杆状态是通过seesaw以数字方式按下/未按下报告的而非模拟值。确认你使用的是正确的属性buttons.up,.down等。2. 如果是老V1 Shield需要校准模拟读取的阈值代码中CheckJoystick()函数的数值范围50, 150, 250...可能需要根据实际硬件调整。4.3 性能优化与高级技巧当项目复杂后你可能会觉得刷新速度不够快或者内存紧张。这里有一些进阶技巧使用displayio.OnDiskBitmap显示图片前面的例子用adafruit_imageload将整个位图加载到内存中对于大图片很耗RAM。OnDiskBitmap可以直接从存储设备流式读取并显示图片极大节省内存。odb displayio.OnDiskBitmap(/large_image.bmp) tile_grid displayio.TileGrid(odb, pixel_shaderdisplayio.ColorConverter(), x0, y0) group.append(tile_grid)局部刷新与脏矩形displayio会自动管理刷新但如果你在频繁更新一个很小的区域如一个数字可以尝试将变化的内容放在一个独立的Group中但更有效的方法是理解displayio的刷新机制——它通常足够智能。避免频繁创建和销毁对象重用对象并只修改其属性。处理按钮的长按与短按示例代码只检测了“按下”状态。要实现“长按”、“短按”、“双击”需要记录时间戳。import time a_pressed_time None while True: buttons ss.buttons if buttons.a: if a_pressed_time is None: # 首次按下 a_pressed_time time.monotonic() else: if a_pressed_time is not None: # 刚刚释放 press_duration time.monotonic() - a_pressed_time if press_duration 1.0: print(A按钮长按) else: print(A按钮短按) a_pressed_time None time.sleep(0.05)与SD卡共用SPI总线如果你需要同时使用屏幕和SD卡确保在访问其中一个设备时正确控制其片选CS引脚。adafruit_sdcard库和displayio通常能很好地协同工作因为它们都会在操作前后拉低和拉高各自的CS引脚。关键是确保你的接线正确SD卡CS接D4并且在代码中为SD卡创建SPI对象时使用与屏幕相同的spi总线对象但指定不同的片选引脚。这块1.8英寸TFT Shield V2是我项目箱里的常客它的高度集成性在快速原型开发阶段无可替代。从简单的传感器数据显示到带有菜单的交互设备它都能胜任。最关键的是吃透了seesaw那套I2C管理GPIO的思路后你会发现在资源受限的嵌入式环境里通过I2C扩展器来管理多个低速外设是一种非常优雅和高效的设计模式。下次当你面对一堆需要连接的按钮和LED时不妨想想是否也能用一颗小小的seesaw来简化你的电路和代码。
