1. 项目缘起为什么是2.8寸SPI屏如果你玩过树莓派大概率会和我一样在某个时刻对那块小小的、分辨率有限的官方屏幕感到不满足。想显示更多信息想有更灵活的交互但又不希望外设过于臃肿、接线复杂或者成本太高。这时候一块2.8英寸、通过SPI接口驱动的LCD触摸屏就成了一个非常“甜点”的选择。我手头这块标着“2.8inch RPi LCD (A)”的屏幕就是这类产品的典型代表。它尺寸适中既能显示比命令行丰富得多的图形界面又不会像7寸屏那样占用过多空间和GPIO资源。其核心卖点就是“简单”一根排线直接插在树莓派的GPIO排针上利用SPI和几个GPIO引脚就能完成显示和触摸控制无需额外的USB转接板或复杂的驱动板供电也直接从树莓派取真正做到即插即用。但“简单”的背后其实藏着不少值得深究的细节。为什么是SPI而不是DPI或HDMI2.8寸这个尺寸和常见的320x240分辨率搭配起来体验如何所谓的“驱动”到底包含了哪些层次的工作在实际项目中除了点亮屏幕我们还会遇到哪些坑又能玩出哪些花样这篇文章我就结合自己多次使用这类屏幕的经验从硬件拆解、驱动原理、软件配置到实战应用为你完整梳理一遍目标是让你不仅能点亮它更能用好它。2. 硬件深潜拆解“2.8inch RPi LCD (A)”的物理构成拿到一块屏幕第一步不是急着上电而是先把它看明白。这块2.8寸屏的硬件可以看作是由三个核心部分叠加而成的显示面板、触摸面板和驱动板。2.1 显示核心ILI9341驱动IC与SPI接口掀开屏幕背面的屏蔽罩如果有的话或者查阅产品资料你会发现它的显示驱动芯片大概率是ILI9341。这是一颗非常经典且廉价的TFT LCD控制器支持262K色18位RGB最大分辨率就是320x240。它之所以在开源硬件和DIY领域如此流行根本原因在于其接口的灵活性。ILI9341支持多种接口模式包括8位/16位并行8080系列接口以及我们这里用到的SPI串行外设接口。选择SPI模式意味着数据传输从并行的十几根线减少到3-4根线MOSI, MISO, SCK 外加一根可选的片选CS这极大地节省了宝贵的GPIO资源尤其对于GPIO数量并不算特别宽裕的树莓派Zero/W系列来说是至关重要的。代价则是速度SPI的速率远低于并行接口但对于320x240这种分辨率刷新一些UI界面、图表数据是完全可以接受的全屏刷动画则会比较吃力。注意有些屏幕为了在SPI下获得稍好的刷新率会使用“8线SPI”模式即利用两个SPI数据线MOSI1, MISO1, MOSI2, MISO2来同时传输数据但这需要主控支持双路SPI且接线和驱动会更复杂。我们这块屏大概率是标准的4线SPI。除了SPI数据线驱动屏幕还需要几个重要的控制引脚DC (Data/Command) 这是一根关键引脚。它告诉ILI9341当前通过SPI发送的数据是命令如设置显示区域、旋转方向还是实际的像素数据。没有它芯片无法正确解析数据流。RST (Reset) 复位引脚。用于对ILI9341进行硬件复位在初始化或出现异常时非常有用。BL (Backlight) 背光控制。通常连接到一个GPIO通过PWM脉冲宽度调制可以调节屏幕亮度。有些简化版设计可能直接接VCC亮度就不可调了。2.2 触摸层XPT2046电阻屏控制器这块屏标注了“(A)”通常意味着它附带了触摸功能。对于这个尺寸和价位的屏幕搭载的几乎肯定是电阻式触摸屏而非电容屏。电阻屏的优势是成本低且可以用任何物体包括手套、触笔按压操作缺点则是透光性稍差、不耐刮以及需要一定的按压力度。触摸功能的实现依赖于另一颗芯片——XPT2046。这是一款兼容ADS7843的4线电阻式触摸屏控制器。它的工作逻辑是通过SPI接口注意它和ILI9341共享同一组SPI总线但使用不同的片选CS引脚与树莓派通信。当你触摸屏幕时XPT2046会测量按压点的X轴和Y轴坐标对应的电压值并将其转换为数字信号通过SPI读出。这里就引出了一个关键点SPI总线复用。树莓派的同一组SPI如SPI0的MOSI、MISO、SCK引脚被同时连接到了ILI9341和XPT2046。树莓派通过控制不同的片选CS引脚来“选中”当前要通信的设备。对ILI9341的CS拉低时与之通信对XPT2046的CS拉低时则读取触摸坐标。这种设计最大限度地节约了引脚。2.3 “驱动板”关键的引脚转换与电平匹配严格来说这块屏模块自带的那个小PCB不能算完整的“驱动板”更像是一个引脚转换与电平适配板。它的核心作用有两个物理接口转换将屏幕柔性排线FPC上密集的引脚转换到适合插在树莓派GPIO排针上的2.54mm间距排母。电平匹配树莓派的GPIO是3.3V逻辑电平而ILI9341和XPT2046通常也工作在3.3V。这个板子确保电源和信号电平一致有时还会集成一个简单的背光驱动电路可能就是一个三极管。板上通常还会有几个跳线帽用于选择屏幕旋转方向通过交换X/Y坐标映射或者配置其他硬件选项。务必根据你希望的物理安装方向来设置这些跳线。3. 软件驱动全景从内核到应用的四层架构硬件连接妥当后要让屏幕工作起来就需要软件驱动。这个过程并非一个“万能驱动”就能搞定而是一个从底层到上层的完整栈。理解这个栈是解决一切驱动问题的钥匙。3.1 第一层Linux内核中的SPI与FB设备驱动这是最底层的一环。树莓派OSRaspbian / Raspberry Pi OS内核已经内置了BCM2835 SPI控制器驱动例如spi-bcm2835。当你启用SPI接口后通过raspi-config或修改/boot/config.txt这个驱动负责管理SPI总线的时序、时钟、中断等硬件资源。在此之上我们需要一个帧缓冲Framebuffer设备驱动来管理显示。对于ILI9341内核中并没有直接可用的标准驱动。因此社区通常采用两种方式fbtft项目这是一个开源的内核模块集合为众多SPI TFT屏幕提供Framebuffer驱动。你需要为ILI9341编译并加载对应的模块如fb_ili9341。加载后系统会出现一个/dev/fb1这样的设备文件/dev/fb0是HDMI主显示应用程序向这个设备写入RGB数据驱动会通过SPI将数据发送给屏幕。厂商提供的预编译内核/驱动很多屏幕卖家会提供定制化的内核镜像或驱动安装脚本。这些脚本的本质也是帮你编译、配置和加载fbtft或类似的内核模块。这一层驱动只负责最基础的“点亮屏幕”和“显示内存位图”不涉及图形加速、2D/3D绘制等高级功能。3.2 第二层触摸屏输入驱动evdev触摸屏需要被系统识别为一个输入设备。XPT2046的驱动通常以内核模块形式提供如ads7846因为XPT2046兼容它。这个驱动会通过SPI读取坐标并经过校准后将触摸事件转换为标准的Linux输入事件。加载成功后你会在/dev/input/下看到类似event0的设备。更直观的方法是使用evtest命令来测试sudo evtest选择对应的设备触摸屏幕你会看到实时输出的坐标和按压事件。这一步验证了触摸硬件和底层驱动是正常的。3.3 第三层显示服务器与坐标变换X11/Wayland如果你的树莓派运行着带有桌面环境如Pixel的系统那么它一定运行着一个显示服务器传统的是X11Xorg较新的可能是Wayland。我们需要做两件事将Framebuffer设备纳入显示服务器对于X11这通常通过在/usr/share/X11/xorg.conf.d/目录下创建一个配置文件如99-fbdev.conf来实现告诉Xorg除了HDMIfb0之外还有另一个显示设备fb1并为其指定位置如HDMI的右侧RightOf。映射触摸事件到正确的显示区域触摸驱动上报的坐标是物理屏幕的原始坐标。如果我们在X11中将fb1屏幕设置为镜像模式或扩展模式的某个位置就需要通过工具如xinput来设置触摸设备的坐标变换矩阵Coordinate Transformation Matrix让触摸位置和显示位置对齐。这一步是触摸屏“点不准”问题的根源所在。3.4 第四层应用层图形库SDL2, PyGame, GTK, Qt对于开发者而言直接操作Framebuffer或X11 API是繁琐的。我们通常使用高级图形库。这些库会自己处理与显示服务器或Framebuffer的交互。SDL2 非常适合游戏和多媒体应用。它可以被配置为直接输出到指定的Framebuffer设备SDL_VIDEODRIVERfbcon SDL_FBDEV/dev/fb1从而完全绕过X11获得更低延迟和更直接的控制非常适合专用信息展示或嵌入式仪表盘。PyGame 基于SDL2的Python库用法类似。GTK / Qt 大型的桌面应用框架。它们通常依赖于X11或Wayland。你需要确保显示服务器正确配置了多屏幕然后应用程序窗口就可以被移动到副屏我们的LCD上显示了。4. 实战配置一步步点亮屏幕并校准触摸理论说再多不如动手做一遍。以下是我在最新版Raspberry Pi OSBookworm上针对这类SPI LCD的通用配置流程其中包含了许多脚本不会告诉你的细节。4.1 硬件连接与系统准备首先确保屏幕排线牢固地插在树莓派的GPIO排针上注意方向通常屏幕的排线插座和树莓派GPIO的“PIN 1”标识要对齐。然后启动树莓派并通过SSH或HDMI主屏进行操作。第一步是启用SPI接口。你可以使用sudo raspi-config进入Interface Options-SPI选择Yes启用。或者直接编辑/boot/config.txt文件确保包含以下行dtparamspion保存并重启。4.2 安装与配置Framebuffer驱动FBTFT这里我们使用最通用的fbtft方法。首先安装必要的编译工具和内核头文件sudo apt update sudo apt install git raspberrypi-kernel-headers build-essential dkms然后克隆并安装fbtft的DKMS版本这样内核更新后驱动会自动重新编译git clone https://github.com/notro/fbtft.git cd fbtft sudo ./install安装脚本会编译模块并将其加入DKMS管理。接下来我们需要在/boot/config.txt中添加设备树覆盖Device Tree Overlay来具体描述我们的屏幕。这是最关键的一步参数不对屏幕就不亮。添加如下内容注释很重要# 启用SPI dtparamspion # 加载ILI9341的设备树覆盖并指定关键参数 dtoverlayfb-ili9341 # 旋转方向0度根据你的安装方式调整090180270 dtoverlayfb-ili9341:rotate0 # 指定SPI总线速率单位MHz。30是一个比较稳定的值太高可能花屏 dtoverlayfb-ili9341:speed30000000 # 关键指定树莓派GPIO引脚与屏幕引脚的对应关系。 # 格式gpiodc,reset,cs,led # 你需要根据屏幕PCB的接线图来确定。以下是一个常见接法对应BCM编码 # dc25, reset24, cs8, led18 (背光控制) dtoverlayfb-ili9341:gpio25,24,8,18保存文件执行sudo reboot重启。重启后检查驱动是否加载成功lsmod | grep fb_ili9341 # 应看到fb_ili9341模块 ls /dev/fb* # 应看到除了fb0还有fb1如果看到/dev/fb1恭喜显示部分的基础驱动已经就绪。你可以用一个简单命令测试sudo apt install fbi sudo fbi -d /dev/fb1 -T 1 -noverbose -a some_image.jpg这条命令使用fbi帧缓冲图像查看器在/dev/fb1上全屏显示一张图片。如果图片能正常显示说明从SPI到ILI9341的整个通路是畅通的。4.3 配置触摸屏驱动与校准接下来处理触摸。XPT2046的驱动模块通常是ads7846。我们需要通过设备树覆盖来加载并配置它。在/boot/config.txt中继续添加# 加载ads7846设备树覆盖用于XPT2046触摸芯片 dtoverlayads7846 # 关键参数指定触摸芯片连接的GPIO # cs7 # 触摸芯片的片选引脚BCM编码根据你的接线修改 # penirq17 # 触摸中断引脚用于通知有触摸动作根据接线修改 # penirq_pull2 # 中断引脚上拉模式2表示上拉 # swapxy1 # 是否交换X/Y坐标根据屏幕物理方向调整 # xmin200 # 原始坐标最小值校准后调整 # xmax3900 # 原始坐标最大值校准后调整 # ymin200 # ymax3900 # xohms150 # 触摸屏的X轴电阻通常150单位欧姆 # 一个完整的示例参数需根据实际测量调整 dtoverlayads7846,cs7,penirq17,penirq_pull2,swapxy0,xmin200,xmax3900,ymin200,ymax3900,xohms150保存并重启。重启后检查触摸设备ls /dev/input/by-path/ # 应该能看到一个以“spi”开头的事件设备 sudo evtest # 运行后选择对应的spi设备触摸屏幕看是否有坐标输出如果evtest有反应说明底层触摸驱动正常。但此时的坐标是原始的、未校准的且可能不对应屏幕的显示区域。进行触摸校准对于X11环境最常用的校准工具是xinput_calibrator。sudo apt install xinput-calibrator首先你需要确保图形界面X11正在使用这个触摸设备。你可以通过xinput list查看所有输入设备找到名字里带“ADS7846”或“touch”的设备记下其id。然后运行校准程序。一个更直接的方法是暂时将显示输出切换到我们的LCD屏fb1上进行校准。这可以通过在命令行指定DISPLAY来实现但过程稍复杂。一个更稳妥的“土办法”是暂时注释掉HDMI的显示让系统只使用我们的SPI LCD作为唯一显示。在/boot/config.txt中临时添加hdmi_blanking1或hdmi_ignore_edid0xa5000080并重启这样HDMI可能无输出桌面会显示在fb1上。在SPI LCD显示的桌面上打开终端直接运行xinput_calibrator。程序会提示你依次点击屏幕四个角出现的十字标志。校准完成后程序会输出一段Section InputClass的配置文本。你需要将其保存到/etc/X11/xorg.conf.d/99-calibration.conf文件中。这个文件包含了校正矩阵能永久修正触摸坐标。校准完成后记得恢复HDMI的配置。此后在X11桌面环境下触摸就应该基本准确了。4.4 配置双屏显示扩展/镜像如果你希望SPI LCD作为HDMI主屏的扩展或镜像需要在X11中配置。创建文件/etc/X11/xorg.conf.d/99-fbdev.confSection Device Identifier HDMI Driver modesetting Option Primary true EndSection Section Device Identifier SPILCD Driver fbdev Option fbdev /dev/fb1 EndSection Section Monitor Identifier HDMI-Monitor EndSection Section Monitor Identifier SPILCD-Monitor EndSection Section Screen Identifier HDMI-Screen Device HDMI Monitor HDMI-Monitor EndSection Section Screen Identifier SPILCD-Screen Device SPILCD Monitor SPILCD-Monitor EndSection Section ServerLayout Identifier MultiDisplay Screen 0 HDMI-Screen Screen 1 SPILCD-Screen RightOf HDMI-Screen # 扩展模式SPI屏在HDMI右侧 # 如果要镜像模式使用 Option Clone true InputClass Touchscreen calibration MatchProduct ADS7846 Touchscreen # 与你的触摸设备名匹配 # 下面这行是xinput_calibrator输出的校准数据必须填写 Option CalibrationMatrix 1.02 0. -0.02 0. 1.03 -0.01 0. 0. 1. Option SwapAxes 0 EndSection EndSection这个配置定义了双屏并将触摸校准矩阵应用到了触摸设备上。重启图形界面sudo systemctl restart lightdm或直接重启系统生效。5. 性能调优与常见问题排查配置成功只是第一步要让体验流畅还需要一些调优。5.1 SPI速率与刷新率的权衡在/boot/config.txt中设置的speed参数单位是Hz30MHz即30000000直接影响刷屏速度。提高它可以增加刷新率但过高的速率可能导致SPI信号不稳定屏幕出现雪花、花屏或根本点不亮。ILI9341的SPI时钟极限通常在30-40MHz左右但树莓派的GPIO和布线质量也会影响稳定性。建议从20MHz开始测试逐步增加直到出现不稳定现象然后退回一档。稳定的30MHz通常是安全值。你可以通过一个简单的测试程序来估算实际刷新率。例如写一个循环用SDL2全屏填充不同颜色计算每秒能完成多少次。对于320x24030MHz SPI下全屏刷新3202402字节150KB的理论帧率可能在30-60fps但受CPU处理、SPI传输协议开销等影响实际应用帧率会低很多。5.2 内存与CPU占用优化直接操作Framebuffer进行全屏刷新是CPU密集型的。优化方法包括局部更新只刷新屏幕上发生变化的部分区域而不是整个屏幕。这需要应用层逻辑支持。使用双缓冲在内存中完成一帧画面的绘制然后一次性通过SPI发送到屏幕。这可以避免屏幕撕裂但需要额外内存。降低颜色深度ILI9341支持18位色262K但通过SPI传输时你可以选择传输16位色RGB565这样每像素数据量从3字节减少到2字节能显著提升传输速度。很多图形库如SDL2都支持设置RGB565模式。5.3 典型问题与解决方案问题1屏幕点亮但花屏、错位或颜色异常。检查首先确认/boot/config.txt中的rotate参数是否与屏幕物理安装方向匹配。0°、90°、180°、270°都试试。检查确认gpio参数dc, reset, cs, led的引脚编号是否正确。务必使用BCM编码即GPIO编号而不是物理引脚编号。最可靠的依据是屏幕供应商提供的原理图或接线表。检查SPI速率speed是否过高。尝试降低到20MHz或10MHz测试。问题2触摸完全无反应。检查ads7846设备树覆盖是否加载。dmesg | grep ads7846查看内核信息。检查cs和penirq引脚定义是否正确。中断引脚penirq必须正确连接否则驱动无法感知触摸事件。检查使用evtest直接测试底层事件。如果evtest都没输出问题在硬件连接或驱动加载层面。问题3触摸有反应但点不准坐标错乱。首要任务运行xinput_calibrator进行校准并正确保存校准矩阵到X11配置中。检查swapxy,xmin/xmax/ymin/ymax这些参数。如果校准后仍不准可以手动调整这些原始坐标范围。使用evtest记录下触摸屏幕四个角时输出的原始坐标值填入设备树覆盖参数中能提供一个更准确的初始映射。检查在双屏模式下触摸区域是否映射到了正确的屏幕。使用xinput map-to-output [触摸设备id] [屏幕名称]命令可以将触摸设备绑定到指定的X屏幕。问题4系统启动后屏幕不亮但用fbi命令可以显示图片。原因这通常是因为图形桌面环境X11或Wayland没有正确配置使用/dev/fb1。你需要按照第4.4节配置双屏或者配置为单屏输出。问题5SPI LCD显示内容但HDMI无输出或反之。检查/etc/X11/xorg.conf.d/下的配置文件确保ServerLayout中两个Screen的排列和克隆设置符合你的预期。尝试使用命令行工具xrandr来动态调整屏幕布局这比修改配置文件重启更快捷。6. 超越基础高级应用与项目思路当屏幕能稳定工作后就可以用它来做一些有趣的项目了。6.1 打造专属信息仪表盘这是最经典的应用。你可以编写一个Python脚本使用psutil库获取树莓派的CPU温度、负载、内存使用、网络流量等信息然后使用PILPython Imaging Library或pygame绘制成图表和数字最后通过SDL2输出到SPI LCD上。让这块小屏幕成为你树莓派主机的实时监控面板。关键技巧为了避免频繁全屏刷新可以只更新数据变化的区域。例如将屏幕划分为几个固定的“窗口”分别显示不同信息每个窗口独立更新。6.2 构建轻量级图形界面GUI对于需要简单交互的项目你可以使用tkinterPython自带或更轻量的guizero库来创建窗口。虽然这些库默认针对X11但通过一些配置可以将窗口直接显示在Framebuffer上需要设置DISPLAY环境变量或使用特定的后端。更直接的方法是使用PyGame它原生支持Framebuffer非常适合制作全屏的、带触摸交互的嵌入式应用界面比如智能家居中控、实验室设备控制面板等。6.3 结合传感器与物理按钮SPI LCD的GPIO引脚并没有被全部占用。你可以利用树莓派上剩余的GPIO连接各种传感器温湿度、光照、运动或物理按钮。在屏幕上实时显示传感器数据并通过触摸屏或物理按钮进行控制形成一个完整的嵌入式人机交互系统。例如制作一个带有触摸屏的温湿度环境监测站屏幕同时显示实时曲线和历史数据。6.4 无头模式下的控制与调试终端对于运行在无头模式无HDMI显示器的树莓派服务器这块SPI LCD可以作为一个本地的“应急”控制台。通过修改系统配置可以将一个虚拟终端如tty1的输出重定向到/dev/fb1并配合USB键盘实现一个独立的控制终端。这在网络出现故障时进行本地调试非常有用。实现这个功能需要用到fbcon帧缓冲控制台和fbcp帧缓冲拷贝等工具配置较为复杂但可行性很高。这块小小的2.8寸SPI LCD其价值远不止于“点亮”。从理解SPI总线复用、内核驱动栈到调试触摸校准、优化显示性能整个过程是对嵌入式Linux系统软硬件结合的一次绝佳实践。它成本低廉但涉及的知识点却非常全面。我最开始用它只是为了显示IP地址后来却因为它把Linux的输入子系统、X11配置、设备树覆盖都摸了一遍。现在它已经是我很多树莓派项目中不可或缺的交互窗口。希望这篇超详细的指南能帮你绕过我踩过的那些坑顺利地把这块屏幕的潜力都发挥出来。
