树莓派2.8寸SPI LCD驱动全攻略：从硬件连接到图形界面开发

1. 项目概述2.8寸RPi LCD (A) 是什么如果你手头有一块树莓派想给它配个小屏幕但又不想用那些笨重、耗电的HDMI显示器那么这块“2.8寸RPi LCD (A)”很可能就是你正在找的东西。简单来说这是一块专门为树莓派GPIO接口设计的2.8英寸电阻触摸屏模块。它通过SPI接口与树莓派通信直接插在树莓派的40针GPIO排针上就能用无需额外的转接板或复杂的飞线极大地简化了嵌入式图形界面项目的硬件集成。这块屏幕的核心价值在于它的“即插即用”属性和极低的功耗。对于制作便携式游戏机、智能家居控制面板、工业现场监控终端或者任何需要一个小巧、交互式界面的树莓派项目来说它都是一个非常经典且成熟的选择。我最早接触这类屏幕还是在做一个小型气象站的时候当时需要一个能实时显示温湿度曲线和天气图标的界面又希望整个设备能靠移动电源长时间供电这块2.8寸屏就成了不二之选。它功耗低点亮后整机电流通常不超过200mA而且SPI驱动对树莓派CPU的占用也相对友好。从技术角度看“(A)”这个后缀通常指代特定的驱动芯片方案比如常见的ILI9341。这决定了后续软件驱动配置的具体参数。而相关热词中提到的“STM32H750 DMA驱动SPI LCD问题”恰恰从侧面印证了这类SPI LCD在嵌入式领域的通用性——无论是树莓派这样的Linux单板计算机还是STM32这类微控制器驱动逻辑是相通的核心难点往往在于如何高效地利用DMA直接存储器访问来减轻CPU负担实现流畅的刷屏。理解了在树莓派上驱动这块屏的原理你甚至可以把经验迁移到STM32项目中去。接下来我们就从硬件连接到软件配置一步步拆解如何让这块小屏幕在树莓派上完美工作起来。2. 硬件连接与引脚定义解析拿到这块2.8寸屏第一步肯定是把它正确地连接到树莓派上。这块屏通常配有一个可以直接插在树莓派GPIO排针上的接口实现了“傻瓜式”连接。但知其然更要知其所以然我们得搞清楚每一根线的作用这样在遇到问题或者进行定制化开发时才能心里有数。2.1 引脚对应关系与功能说明这块LCD模块与树莓派的连接本质上是将屏幕的SPI、背光控制、触摸屏控制等信号线与树莓派GPIO的特定引脚一一对应。虽然模块插上就行但了解背后的映射关系至关重要。通常其引脚定义如下表所示以常见的40针树莓派3B/4B为例LCD模块引脚树莓派GPIO引脚 (BCM编号)物理引脚号功能描述VCC3.3VPin 1电源正极 (3.3V)GNDGNDPin 6电源地DIN (MOSI)GPIO10 (MOSI)Pin 19SPI数据输入主出从入CLK (SCLK)GPIO11 (SCLK)Pin 23SPI时钟信号CS (LCD_CS)GPIO8 (CE0)Pin 24LCD芯片选择低电平有效DC (LCD_D/C)GPIO25Pin 22LCD数据/命令选择RST (LCD_RST)GPIO27Pin 13LCD复位低电平复位BL (LCD_BL)GPIO18Pin 12背光控制PWM调光T_IRQGPIO24Pin 18触摸屏中断信号T_DO (MISO)GPIO9 (MISO)Pin 21触摸屏SPI数据输出T_CSGPIO7 (CE1)Pin 26触摸屏芯片选择T_DIN (MOSI)GPIO10 (MOSI)Pin 19触摸屏SPI数据输入与LCD DIN共用T_CLK (SCLK)GPIO11 (SCLK)Pin 23触摸屏SPI时钟与LCD CLK共用注意上表中的“BCM编号”是树莓派Broadcom芯片的原始GPIO编号在编程如使用RPi.GPIO或pigpio库时必须使用这个编号而不是物理引脚号。物理引脚号只是帮你定位插槽位置。从表格可以看出几个关键点电源屏幕由3.3V供电务必确保连接正确接5V会烧毁屏幕。SPI总线复用LCD显示和触摸屏控制器共用同一组SPI时钟SCLK和数据输出MOSI线这是典型的SPI多从设备架构。通过不同的片选信号LCD_CS和T_CS来区分操作对象。关键控制线DC线这是SPI驱动LCD区别于其他SPI设备的关键。发送命令如设置显示区域时需要拉低DC发送显示数据时需要拉高DC。RST线硬件复位通常在初始化时需要一个低电平脉冲。BL线背光控制可以通过PWM输出调节亮度。T_IRQ线触摸屏中断当有触摸事件时触摸芯片会通过此线主动通知树莓派避免了轮询带来的CPU开销。2.2 连接实操与安全注意事项连接本身非常简单确保树莓派已断电将LCD模块的排针插座与树莓派的40针GPIO排针对准轻轻按下即可。模块的防反插设计通常能防止你插反。实操心得连接前的必查项在通电前我强烈建议你做两件事目视检查对着光线仔细看一下排针有没有弯曲、对不齐的情况。我曾因为一个针脚微微弯曲没插到位导致背光不亮排查了半天。确认屏幕版本不同批次的屏幕驱动芯片可能有细微差别如ILI9341 V1.0和V2.0。查看屏幕背面或卖家提供的资料记下驱动IC型号如ILI9341。这会在后续的驱动配置中用到。连接好后可以先不着急上电测试系统。一个更稳妥的做法是先只连接电源VCC和GND看看屏幕背光是否亮起如果背光默认常亮。如果背光亮了说明电源连接正常。然后再连接所有引脚进行后续的软件调试。这样做的好处是万一屏幕模块本身有短路等故障可以避免波及树莓派主板。3. 系统配置与驱动安装详解硬件连接妥当后下一步就是在树莓派的Raspberry Pi OS原Raspbian上启用必要的接口并安装驱动。这个过程主要涉及修改系统配置文件和安装/编译内核模块。3.1 启用SPI接口与配置引导文件树莓派的SPI接口默认是关闭的我们需要手动开启。使用raspi-config工具推荐给新手 在终端中输入sudo raspi-config。 通过方向键选择Interface Options-SPI-Yes启用SPI接口。 完成后选择Finish并重启树莓派。手动编辑config.txt文件更灵活 对于有经验的用户或者需要更精细的控制可以直接编辑/boot/config.txt文件。sudo nano /boot/config.txt在文件末尾添加或确保有以下几行dtparamspion # 以下参数针对GPIO分配如果与其它设备冲突可调整 # dtoverlayspi1-3cs # 如果需要启用额外的SPI片选可以取消注释dtparamspion这一行就足够了它启用了主SPI接口SPI0。保存CtrlO并退出CtrlX然后重启。验证SPI是否启用 重启后在终端输入ls /dev/spi*。如果看到/dev/spidev0.0和/dev/spidev0.1这两个设备文件说明SPI启用成功。这两个文件分别对应CE0GPIO8和CE1GPIO7两个片选通道正好对应我们屏幕的LCD_CS和T_CS。3.2 安装与配置FBTFT驱动树莓派内核本身包含了一个非常强大的框架叫FBTFT它允许我们为各种SPI/I2C接口的小屏幕编写内核级的帧缓冲Framebuffer驱动。这意味着屏幕可以被系统识别为一个标准的/dev/fb1显示设备甚至可以通过配置作为主控制台或镜像显示。更新系统与内核头文件 首先确保系统是最新的并安装编译驱动所需的内核头文件。sudo apt update sudo apt upgrade -y sudo apt install -y raspberrypi-kernel-headers下载并编译FBTFT驱动模块 虽然内核包含FBTFT但我们需要针对具体的ILI9341芯片编译并加载对应的模块。# 克隆FBTFT的源码注意原仓库可能已归档可寻找镜像或使用现存版本 git clone https://github.com/tianyoujian/fbtft.git cd fbtft # 编译并安装模块 sudo make sudo make install编译过程可能会因内核版本不同而有警告只要没报错中断一般问题不大。动态加载驱动模块 编译安装后我们可以手动加载针对ILI9341的驱动。# 加载SPI核心模块和FBTFT核心模块 sudo modprobe spi-bcm2835 sudo modprobe fbtft # 加载ILI9341设备模块并指定参数 sudo modprobe flexfb width320 height240 buswidth8 init-1,0xCB,0x39,0x2C,0x00,0x34,0x02,-1,0xCF,0x00,0XC1,0X30,-1,0xE8,0x85,0x00,0x78,-1,0xEA,0x00,0x00,-1,0xED,0x64,0x03,0X12,0X81,-1,0xF7,0x20,-1,0xC0,0x23,-1,0xC1,0x10,-1,0xC5,0x3e,0x28,-1,0xC7,0x86,-1,0x36,0x48,-1,0x3A,0x55,-1,0xB1,0x00,0x18,-1,0xB6,0x08,0x82,0x27,-1,0xF2,0x00,-1,0x26,0x01,-1,0xE0,0x0F,0x31,0x2B,0x0C,0x0E,0x08,0x4E,0xF1,0x37,0x07,0x10,0x03,0x0E,0x09,0x00,-1,0xE1,0x00,0x0E,0x14,0x03,0x11,0x07,0x31,0xC1,0x48,0x08,0x0F,0x0C,0x31,0x36,0x0F,-1,0x11,-2,120,-1,0x29,-3 sudo modprobe fbtft_device nameflexfb speed32000000 gpiosdc:25,reset:27,cs:8 rotate90这一串命令看起来复杂其实核心是最后两条modprobe flexfb ...加载一个通用驱动并传入一长串初始化序列。这个序列是ILI9341芯片上电后必须接收的一系列命令和数据用于配置伽马值、电源控制、内存访问方式等。不同厂商的屏幕初始化序列可能不同如果这个序列不对屏幕可能白屏、花屏或颜色异常。上述序列是一个较通用的ILI9341序列。modprobe fbtft_device ...创建设备实例。这里指定了设备名、SPI速度32MHz、关键GPIO引脚dc, reset, cs和屏幕旋转角度90度。执行后如果成功你应该能看到一个新的帧缓冲设备/dev/fb1。同时屏幕上应该会亮起并清空为黑色或某种颜色。常见问题与排查技巧实录驱动加载失败现象执行modprobe fbtft_device后报错或没有生成/dev/fb1。排查dmesg | tail -30查看内核日志的最后30行这里会有最详细的错误信息。常见错误有“GPIO already requested”说明GPIO引脚被其他程序占用比如之前加载过驱动未卸载。解决引脚冲突使用sudo rmmod fbtft_device flexfb fbtft卸载模块然后再重新加载。确保没有其他程序如自己写的Python脚本占用着GPIO25、27、8等引脚。初始化序列问题如果dmesg显示SPI传输错误很可能是初始化序列不对。尝试寻找卖家提供的特定初始化序列或者使用更简单的序列有时init-1,0x11,-2,120,-1,0x29,-3这个最小序列也能点亮屏幕但颜色可能不准。SPI速度如果树莓派版本较老或线缆较长32MHz可能太高可以尝试降低speed16000000。3.3 配置触摸屏驱动ADS7846这块屏通常使用ADS7846或XPT2046这类芯片处理触摸信号它们也是通过SPI通信。内核中通常已有ads7846的驱动。加载触摸屏驱动模块sudo modprobe ads7846 deviceads7846 model7846 cs7 gpio_pendown24 speed1000000 keep_vref_on1 pressure_max255 x_plate_ohms60 y_plate_ohms30 x_min200 x_max3900 y_min200 y_max3900 invert_x0 invert_y0 swap_xy0参数解释cs7对应触摸芯片的片选引脚GPIO7T_CS。gpio_pendown24对应触摸中断引脚GPIO24T_IRQ。x_min, x_max, y_min, y_max触摸坐标的范围可能需要校准。上述值是常见范围不准的话需要后续校准。swap_xy,invert_x,invert_y根据屏幕方向调整坐标轴。验证触摸设备 加载成功后输入ls /dev/input/event*你应该能看到一个新的event设备比如event1。可以使用evtest工具来测试触摸。sudo apt install evtest sudo evtest选择对应的event编号然后在屏幕上划动终端里应该会输出坐标数据。4. 软件应用与图形界面显示实战驱动成功后/dev/fb1就是一个标准的图形输出设备。我们可以用多种方式向它输出内容。4.1 使用fbi显示图片fbi帧缓冲图像查看器是一个直接在帧缓冲上显示图像的命令行工具非常适合快速测试。sudo apt install fbi # 将一张test.jpg图片全屏显示到fb1设备上并停留5秒 sudo fbi -d /dev/fb1 -T 1 -noverbose -a test.jpg -t 5参数说明-d指定设备-T 1表示使用虚拟终端1可避免干扰主控制台-a自动缩放-t显示时间。4.2 使用PythonPIL/Pillow进行绘图对于自定义图形界面Python的PILPillow库结合pygame或直接写入帧缓冲设备文件是更灵活的方式。安装必要的库sudo apt install python3-pip pip3 install pillow编写一个简单的绘图脚本#!/usr/bin/env python3 # display_test.py from PIL import Image, ImageDraw, ImageFont import struct import time # 帧缓冲设备文件 fb_path /dev/fb1 # 屏幕分辨率 width, height 320, 240 # 颜色格式RGB565 (16位 5-6-5) pixel_format RGB565 def rgb_to_565(r, g, b): 将8位RGB值转换为16位RGB565格式 return ((r 0xF8) 8) | ((g 0xFC) 3) | (b 3) # 创建一个新的图像 image Image.new(RGB, (width, height), colorwhite) draw ImageDraw.Draw(image) # 画一些图形 draw.rectangle([10, 10, 100, 60], fillred, outlineblack) draw.ellipse([150, 10, 250, 110], fillblue, outlineyellow) draw.line([(20, 150), (300, 200)], fillgreen, width3) # 尝试加载字体并写字如果系统有字体 try: font ImageFont.truetype(/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf, 20) draw.text((50, 120), Hello, 2.8\ LCD!, fontfont, fillblack) except: draw.text((50, 120), Hello, 2.8\ LCD!, fillblack) # 将PIL图像转换为RGB565字节流 pixels image.load() with open(fb_path, wb) as fb: for y in range(height): for x in range(width): r, g, b pixels[x, y] pixel_565 rgb_to_565(r, g, b) # 以小端字节序写入 fb.write(struct.pack(H, pixel_565)) print(Image displayed. Waiting...) time.sleep(5) # 清屏为黑色 with open(fb_path, wb) as fb: fb.write(b\x00 * (width * height * 2)) # RGB565每个像素2字节这个脚本演示了如何直接向/dev/fb1写入原始的RGB565数据。这是最底层、最直接的控制方式效率高但需要自己处理像素格式转换。4.3 配置为控制台或镜像显示如果你希望将系统控制台或桌面环境显示到这块小屏上需要进行更深入的配置。将fb1设为控制台 修改/boot/cmdline.txt在原有参数末尾添加fbconmap:1。这会将控制台映射到第二个帧缓冲设备fb1。但注意小屏幕分辨率低控制台字体可能非常小。使用fbcp进行屏幕镜像 一个更流行的方案是使用fbcp帧缓冲复制工具它将主显示器HDMI输出的fb0的内容实时复制到小屏fb1上。git clone https://github.com/tianyoujian/fbcp.git cd fbcp mkdir build cd build cmake .. make -j4 sudo ./fbcp这样你在HDMI显示器上看到的内容就会同步到2.8寸屏上。这对于调试图形化应用非常方便。你可以将fbcp设置为开机自启动的服务。实操心得性能与优化通过SPI驱动320x240的屏幕全屏刷新一帧需要传输 3202402 153600 字节。即使在32MHz的SPI时钟下理论极限帧率也就在20-30帧每秒左右这还没算上命令传输和初始化开销。因此避免全屏频繁刷新在编写应用时尽量采用局部更新脏矩形更新策略只刷新屏幕上发生变化的部分。使用双缓冲在内存中完成一帧画面的绘制然后一次性写入fb设备可以避免屏幕撕裂。降低颜色深度如果项目对颜色要求不高可以尝试使用高位色的灰度图像减少数据传输量。硬件SPI DMA就像热词中提到的STM32 DMA驱动一样树莓派的SPI控制器也支持DMA。内核驱动如FBTFT已经使用了DMA这比用CPU逐个字节搬运要高效得多。我们无需直接操作但理解其原理有助于优化上层应用。5. 触摸屏校准与高级应用触摸屏驱动加载后坐标可能不准需要进行校准。同时我们可以将这块屏集成到更完整的应用中。5.1 使用xinput-calibrator进行校准如果你的系统安装了X Window桌面环境可以使用xinput_calibrator工具。安装与运行sudo apt install xinput-calibrator DISPLAY:0 xinput_calibrator --device 你的触摸设备名设备名可以通过xinput list查看。运行后屏幕上会依次在四个角显示校准点你需要用触笔精确点击。完成后工具会输出一段Section InputClass的配置信息。应用校准配置 将输出的配置信息保存到/etc/X11/xorg.conf.d/99-calibration.conf文件中。重启X服务或系统后触摸校准生效。5.2 在PyGame或Kivy中直接使用触摸事件对于使用PyGame或Kivy这类图形框架的应用它们可以直接读取Linux的输入事件/dev/input/eventX无需经过X Server。PyGame示例片段import pygame import os # 设置SDL环境变量指定使用fb1和触摸设备 os.environ[SDL_FBDEV] /dev/fb1 # 你需要通过 evtest 确定自己的触摸设备event编号比如event1 os.environ[SDL_MOUSEDRV] TSLIB os.environ[SDL_MOUSEDEV] /dev/input/event1 pygame.init() screen pygame.display.set_mode((320, 240)) # ... 你的游戏或应用逻辑 running True while running: for event in pygame.event.get(): if event.type pygame.MOUSEBUTTONDOWN: pos pygame.mouse.get_pos() print(fTouched at: {pos}) # 处理其他事件 pygame.display.flip() pygame.quit()这种方式绕过了桌面系统直接控制显示和输入效率最高非常适合专用的嵌入式应用。5.3 常见问题深度排查即使按照步骤操作你也可能会遇到一些“坑”。这里记录几个我踩过的以及社区常见的问题问题一屏幕花屏、错位或颜色怪异可能原因1初始化序列错误。这是最常见的原因。不同厂家、不同批次的ILI9341模块其初始化序列可能有细微差别。最直接的解决方法是联系卖家索取准确的初始化命令序列。你也可以在网上搜索“ILI9341 init sequence”尝试不同的版本。可能原因2SPI模式或相位不对。FBTFT驱动默认使用SPI模式0。极少数屏幕可能需要模式3。这需要在加载fbtft_device时添加参数mode3。但这种情况较少。可能原因3RGB顺序不对。ILI9341支持RGB和BGR格式。如果红色和蓝色反了可以在初始化序列中寻找设置像素格式的命令通常是0x36调整其参数或者尝试在加载驱动时添加bgr1参数。问题二触摸坐标反向或不灵敏校准是关键严格按照校准程序操作。调整驱动参数x_plate_ohms和y_plate_ohms是触摸屏的内部电阻参数如果校准后边缘仍然不准可以微调这两个值通常范围在40-400之间。pressure_max决定了按压识别的灵敏度如果触摸不灵敏可以适当调低此值如200。检查硬件触摸屏排线接触不良也会导致坐标漂移或不识别。轻轻按压屏幕排线连接处看看是否有变化。问题三系统启动后屏幕不亮检查自启动如果你配置了驱动模块自动加载例如写入了/etc/modules或/etc/modprobe.d请检查模块加载顺序。确保spi-bcm2835在fbtft_device之前加载。检查电源用万用表测量GPIO排针的3.3V引脚电压是否稳定。树莓派电源适配器功率不足可能导致带不动屏幕。背光控制BL引脚可能需要上拉才能点亮背光。尝试在加载驱动后手动设置GPIO18为高电平echo 1 | sudo tee /sys/class/gpio/gpio18/value需先导出GPIO。这块2.8寸屏虽然小巧但把它玩转的过程几乎涵盖了嵌入式图形显示和输入的核心知识点从SPI通信协议、帧缓冲原理、内核驱动模块到应用层的图形绘制和事件处理。无论是用于快速原型验证还是作为最终产品的一部分它都是一个性价比极高且充满学习价值的平台。当你看到自己编写的程序在这块小小的屏幕上流畅运行并响应触摸时那种成就感正是嵌入式开发的乐趣所在。