树莓派串口通信全解析：UART、SPI、I2C配置与避坑指南

1. 树莓派串口全景认知从调试口到扩展总线的角色分工拿到一块树莓派很多人第一件事是烧系统、接屏幕、连WiFi然后就开始跑代码。但如果你打算让树莓派和单片机、传感器、工业模块打交道串口这件事绕不过去。我见过太多人卡在“为什么我的串口收不到数据”上折腾一整天最后发现是设备树没改、引脚映射搞错了、或者把调试串口当普通串口用了。树莓派上的“串口”其实是一个复数概念。它至少包含三类角色第一类是UART串口包括用于系统调试的primary UART和可以自由支配的secondary UART第二类是SPI总线一种高速同步串行接口常用于屏幕、Flash、ADC等外设第三类是I2C总线两线制低速总线适合挂载多个传感器和EEPROM。这三者都通过GPIO排针引出但电气特性、协议时序、软件配置方式完全不同。这篇文章面向的是刚接触树莓派硬件扩展的开发者或者从STM32、Arduino转过来的朋友。你可能已经用过USB转串口模块知道CH340和FTDI但面对树莓派40针排针上那几个标注着TXD、RXD、SCLK、SDA的引脚还是有点发怵。我会把这三类串口的底层逻辑、配置方法、实操步骤和踩坑经验一次讲透让你看完就能动手接线、写代码、调通设备。注意本文基于树莓派4B和树莓派5的通用架构讲解涉及Ubuntu 22.04和Raspberry Pi OS两种系统环境。不同型号的引脚编号和默认配置有差异操作前请确认你的具体板型。2. 三类串口总线的核心差异与选型逻辑2.1 UART、SPI、I2C的本质区别很多人一开始分不清这三种总线觉得都是“串行通信”随便选一个能用就行。但实际项目里选错了总线轻则速率上不去重则根本通不了。我用一个生活化的类比来解释UART像两个人打电话一对一你说一句我说一句不需要时钟同步但双方要提前约定好语速SPI像老师带学生做操老师喊节拍学生跟着做节拍就是时钟线速度快但占引脚多I2C像一间会议室里的多人讨论只有两条线每个人有唯一座位号发言前先喊座位号速度慢但省线。从技术参数上看三者的差异非常明确特性UARTSPII2C线数2TX/RX4MOSI/MISO/SCLK/CS2SDA/SCL拓扑点对点一主多从每从机一根CS一主多从地址寻址速率通常115200bps~1Mbps可达数十MHz标准100kHz快速400kHz高速3.4MHz时钟异步同步同步典型场景调试终端、GPS、蓝牙模块屏幕、Flash、ADC、射频模块传感器、EEPROM、RTC树莓派4B的GPIO排针上默认引出了1路UARTGPIO14/15物理引脚8/10、2路SPISPI0在GPIO8/9/10/11SPI1在GPIO19/20/21/26附近但SPI1默认未启用、1路I2CI2C1在GPIO2/3物理引脚3/5。树莓派5在此基础上增加了更多外设复用能力但核心逻辑一致。2.2 为什么树莓派要把UART分成primary和secondary这是新手最容易踩的坑。树莓派在Linux系统启动时默认会把primary UART通常是PL011硬件串口分配给系统控制台用来输出启动日志和提供串口登录终端。这意味着你如果直接往/dev/serial0写数据可能会发现数据被系统日志干扰或者根本发不出去。树莓派的UART架构里有两个硬件串口PL011性能好有独立波特率时钟和mini UART性能一般波特率依赖GPU时钟。在树莓派3及以后的型号中默认把PL011分给了蓝牙模块把mini UART引到了GPIO排针上。这就导致了一个经典问题mini UART的波特率会随CPU频率变化而漂移你设了115200实际可能是118000通信不稳定。解决方案是通过/boot/config.txt树莓派5是/boot/firmware/config.txt里的dtoverlay配置把PL011映射到GPIO排针同时禁用串口控制台。具体操作后面会详细讲。这里你只需要记住一个原则做硬件通信项目时一定要把primary UART从系统控制台手里抢回来并且优先使用PL011。2.3 SPI和I2C在树莓派上的复用与冲突树莓派的GPIO引脚是复用的同一个物理引脚可以配置成GPIO、SPI、I2C、PWM、UART等不同功能。这种灵活性带来了一个隐患如果你同时启用了SPI和某个占用相同引脚的I2C设备就会冲突。比如GPIO2和GPIO3默认是I2C1的SDA和SCL但如果你在配置里把这两个引脚改成普通GPIO输出I2C就用不了了。再比如SPI0的CE0和CE1分别占用GPIO8和GPIO7如果你要用这两个引脚做片选就不能再把它们分配给其他功能。我一般的做法是项目开始前先画一张引脚分配表把每个要用的外设、占用的引脚、复用的功能列清楚。树莓派5的引脚复用比4B更复杂因为多了PCIe和更多外设建议直接参考官方引脚图文档。提示在Ubuntu 22.04上树莓派的设备树覆盖配置路径是/boot/firmware/config.txt而不是旧版的/boot/config.txt。这个路径变化坑过不少人。3. UART串口配置与调试实战3.1 硬件接线TX、RX、GND三线到底怎么接UART通信最少需要三根线TX发送、RX接收、GND地。接线规则是“交叉连接”树莓派的TX接对方的RX树莓派的RX接对方的TXGND对GND。这个规则听起来简单但我见过至少五次有人把TX接TX、RX接RX然后纳闷为什么收不到数据。树莓派4B的GPIO14是TXD物理引脚8GPIO15是RXD物理引脚10。GND可以选物理引脚6、9、14、20、25、30、34、39中的任意一个。如果你用USB转串口模块比如CH340或FTDI芯片的模块模块上的TXD接树莓派RXD模块RXD接树莓派TXD模块GND接树莓派GND。电压电平要注意树莓派GPIO是3.3V电平绝对不能直接接5V的串口设备。如果你用的是Arduino Uno这类5V单片机必须加电平转换模块否则长期使用会损坏树莓派的GPIO引脚。STM32F103通常是3.3V可以直接连但也要确认对方板子的逻辑电平。3.2 软件配置释放primary UART并禁用控制台在Raspberry Pi OS上默认配置下GPIO14/15上的UART是mini UART而且串口控制台是启用的。要把它变成可自由使用的PL011串口需要三步操作。第一步打开配置文件sudo nano /boot/firmware/config.txt第二步在文件末尾添加或修改以下内容enable_uart1 dtoverlaydisable-btenable_uart1确保UART硬件启用dtoverlaydisable-bt禁用蓝牙对PL011的占用把PL011释放给GPIO排针。如果你还需要蓝牙功能可以改用dtoverlayminiuart-bt把蓝牙切到mini UART上但这样蓝牙性能会下降。第三步禁用串口控制台。在Raspberry Pi OS中执行sudo raspi-config进入Interface Options-Serial Port当问“Would you like a login shell to be accessible over serial?”时选No当问“Would you like the serial port hardware to be enabled?”时选Yes。在Ubuntu 22.04上操作略有不同。需要编辑/boot/firmware/config.txt添加上述overlay然后修改/boot/firmware/cmdline.txt删除其中的consoleserial0,115200或consolettyAMA0,115200字段。这个文件只有一行修改时不要换行。重启后检查/dev/serial0是否指向ttyAMA0ls -l /dev/serial0如果显示serial0 - ttyAMA0说明PL011已经映射成功。如果指向ttyS0说明还是mini UART需要检查配置。3.3 用Python和串口调试助手验证通信配置完成后先做回环测试把树莓派的GPIO14TX和GPIO15RX用杜邦线短接然后运行Python脚本发送数据看是否能收到自己发的数据。import serial import time ser serial.Serial(/dev/serial0, 115200, timeout1) time.sleep(0.1) ser.write(bHello Raspberry Pi UART\n) time.sleep(0.1) response ser.readline() print(Received:, response) ser.close()如果回环测试通过说明树莓派UART本身工作正常。接下来接上外部设备用串口调试助手比如XCOM、串口调试助手、minicom在电脑端观察数据。电脑端需要USB转串口模块安装CH340驱动或FTDI驱动后在设备管理器里找到COM端口号打开对应端口设置相同的波特率、数据位8、停止位1、无校验。我实测下来树莓派4B的PL011在115200波特率下非常稳定连续传输几MB数据不丢包。但如果你用的是mini UART在CPU负载高的时候会出现乱码这就是波特率漂移导致的。注意树莓派5的UART引脚和4B一致但默认配置可能不同。树莓派5的/boot/firmware/config.txt中UART相关的overlay名称有变化建议查阅树莓派5官方文档确认。4. SPI总线深度解析与设备驱动4.1 SPI四线制时序与树莓派的硬件片选SPI协议的核心是四根线SCLK时钟、MOSI主出从入、MISO主入从出、CS片选。树莓派的SPI0控制器支持两个硬件片选CE0在GPIO8物理引脚24CE1在GPIO7物理引脚26。SPI1则支持三个片选但默认不启用。SPI的时序模式由**CPOL时钟极性和CPHA时钟相位**组合成四种模式Mode 0~3。大部分传感器和Flash芯片使用Mode 0CPOL0CPHA0或Mode 3CPOL1CPHA1。树莓派的SPI控制器支持所有四种模式通过spidev库的mode参数设置。硬件片选和软件片选的区别在于硬件片选由SPI控制器自动拉低和拉高时序精准不占用CPU软件片选需要你用普通GPIO手动控制灵活性高但时序有抖动。我一般优先用硬件片选只有在片选引脚不够或者需要特殊时序时才用软件片选。4.2 启用SPI并编写Python读写程序在Raspberry Pi OS上启用SPIsudo raspi-config进入Interface Options-SPI选择启用。然后在/boot/firmware/config.txt中确认有dtparamspion重启后/dev/spidev0.0和/dev/spidev0.1会出现分别对应CE0和CE1。用Python的spidev库操作SPI设备import spidev spi spidev.SpiDev() spi.open(0, 0) # bus 0, device 0 (CE0) spi.max_speed_hz 1000000 # 1MHz spi.mode 0 # 发送一个字节并接收一个字节 resp spi.xfer2([0x9F]) # 例如读取Flash的JEDEC ID命令 print(Response:, resp) spi.close()xfer2会保持CS在整个传输期间有效适合多字节连续读写。如果你需要分多次传输但保持CS有效可以用spi.xfer配合手动控制CS。4.3 SPI通信不生效的常见原因排查SPI通信失败通常有以下几个原因我按排查优先级列出来第一接线错误。MOSI和MISO接反是最常见的。确认树莓派MOSIGPIO10引脚19接从机MOSIMISOGPIO9引脚21接从机MISOSCLKGPIO11引脚23接从机SCLKCE0GPIO8引脚24接从机CS。第二模式不匹配。从机要求Mode 0你设了Mode 3数据就会错位。查从机数据手册确认CPOL和CPHA。第三速率过高。长杜邦线在高频下信号完整性差先降到100kHz测试通了再逐步提高。第四片选未生效。如果用软件片选确认GPIO在传输前拉低、传输后拉高。如果用硬件片选确认spidev.open(bus, device)的device参数对应正确的CE引脚。第五设备树冲突。如果你在config.txt里同时启用了SPI和其他占用相同引脚的overlaySPI可能被禁用。用dtoverlay -l查看已加载的overlay。提示树莓派5的SPI控制器性能更强支持更高的时钟频率但引脚复用更复杂。如果你在树莓派5上遇到SPI问题先检查/boot/firmware/config.txt中的dtparamspion是否生效。5. I2C总线原理与多设备挂载5.1 I2C开漏输出与上拉电阻的底层逻辑I2C只有两根线SDA数据和SCL时钟。这两根线都是开漏输出结构意味着设备只能把线拉低不能主动拉高。线的高电平靠上拉电阻拉到VCC。这个设计的好处是多个设备挂载在同一总线上任何一个设备拉低线其他设备都能检测到不会出现电源短路。上拉电阻的阻值选择很关键。阻值太小功耗大且设备拉低时电流过大可能损坏引脚阻值太大上升沿变缓高速通信时波形失真。标准模式100kHz下常用4.7kΩ快速模式400kHz下常用2.2kΩ或1.8kΩ。树莓派的GPIO2和GPIO3上已经焊了1.8kΩ的上拉电阻所以直接接传感器通常不需要额外加上拉。但如果你挂载的传感器模块自带4.7kΩ上拉并联后等效电阻变成1.8k||4.7k≈1.3kΩ对于3.3V系统来说电流约2.5mA还在安全范围内。如果挂载多个模块每个都带上拉等效电阻会进一步降低可能导致某些设备拉低时电流过大。我一般会检查模块上的上拉电阻如果已经有多个就把多余的拆掉。5.2 扫描I2C地址与读写EEPROM示例启用I2Csudo raspi-config进入Interface Options-I2C选择启用。确认/boot/firmware/config.txt中有dtparami2c_armon重启后安装i2c-toolssudo apt install i2c-tools扫描总线上的设备sudo i2cdetect -y 1输出会显示所有响应地址的设备。比如一个AT24C02 EEPROM的地址是0x50一个BMP280传感器的地址是0x76或0x77。用Python读写EEPROMimport smbus2 bus smbus2.SMBus(1) addr 0x50 # 向地址0x00写入一个字节0xAB bus.write_byte_data(addr, 0x00, 0xAB) # 从地址0x00读取一个字节 value bus.read_byte_data(addr, 0x00) print(Read:, hex(value))smbus2比smbus更稳定支持重复启动和更灵活的错误处理。如果你在Ubuntu 22.04上可能需要先安装python3-smbus2包。5.3 I2C通信失败的典型场景与解决I2C通信失败最常见的原因是地址冲突。比如你挂了两个相同型号的传感器默认地址都是0x76就会冲突。解决方法是通过传感器的地址选择引脚如果有改变地址或者用I2C多路复用器如TCA9548A扩展总线。第二个原因是上拉电阻不足。如果你用长导线连接传感器线缆电容会导致上升沿变缓100kHz都可能通信失败。这时候需要减小上拉电阻或者降低总线速率。在/boot/firmware/config.txt中添加dtparami2c_arm_baudrate50000把速率降到50kHz牺牲速度换稳定性。第三个原因是时序问题。某些传感器要求特定的启动时序比如先写寄存器地址再读数据中间不能有停止条件。smbus2的read_byte_data会自动处理这种重复启动但如果你用write和read分开调用中间会产生停止条件导致读取失败。注意I2C总线上的设备数量受限于总线电容一般不超过400pF。每个设备的引脚电容约10pF导线每米约100pF。如果你挂载很多设备考虑用多路复用器分总线。6. 串口调试工具链与驱动适配6.1 USB转串口模块选型CH340 vs FTDI vs CP2102USB转串口模块是调试树莓派串口的必备工具。市面上主流芯片有CH340、FTDI、CP2102三种。CH340便宜几块钱一个但驱动兼容性一般在Windows 10/11上需要手动安装驱动在macOS新版本上可能不识别。FTDI稳定驱动完善但价格贵而且市面上有很多山寨FTDI芯片会被官方驱动屏蔽。CP2102介于两者之间驱动安装简单稳定性不错。我个人的选择是Windows上用CH340便宜够用macOS和Linux上用FTDI或CP2102免驱。如果你在Ubuntu 22.04上CH340和CP2102都自带驱动插上就能用。FTDI可能需要安装ftdi_sio模块但通常内核已经包含。6.2 串口调试助手与虚拟串口软件的使用串口调试助手如XCOM、SSCOM、minicom用于在电脑端发送和接收串口数据。设置参数时注意波特率、数据位、停止位、校验位必须和树莓派端一致。流控一般选“无”除非你的设备明确要求硬件流控。虚拟串口软件用于在没有物理串口的情况下创建虚拟端口对方便本机测试。比如你可以创建COM10和COM11一对虚拟串口一个给串口调试助手一个给Python脚本模拟真实串口通信。这类工具在Windows上有Virtual Serial Port DriverLinux上可以用socat创建虚拟串口对socat -d -d pty,raw,echo0 pty,raw,echo0输出会显示两个/dev/pts/X设备你可以把它们当作串口使用。6.3 树莓派5串口使用的特殊注意事项树莓派5的串口架构和4B有差异。首先树莓派5的/boot/firmware/config.txt是唯一配置文件旧版的/boot/config.txt不存在。其次树莓派5的UART默认映射可能不同需要确认/dev/serial0指向哪个设备。第三树莓派5增加了PCIe接口如果你用了M.2 HAT或其他PCIe设备可能会影响GPIO引脚的可用性。在树莓派5上部署Ubuntu 22.04时串口配置路径同样是/boot/firmware/config.txt。但Ubuntu的cmdline.txt路径是/boot/firmware/cmdline.txt修改时注意不要破坏文件结构。我实测树莓派5的PL011串口在1Mbps波特率下依然稳定比4B的mini UART强很多。如果你要做高速串口通信树莓派5是更好的选择。7. 常见问题速查与避坑经验汇总7.1 串口通信问题速查表现象可能原因排查方法解决方案收不到任何数据TX/RX接反检查接线交叉连接TX和RX收到乱码波特率不匹配确认双方波特率统一波特率数据偶尔丢失mini UART波特率漂移检查/dev/serial0指向切换到PL011SPI无响应片选未拉低用示波器看CS引脚检查片选配置I2C扫描不到设备上拉电阻不足测量SDA/SCL高电平减小上拉电阻I2C地址冲突多个相同地址设备用i2cdetect扫描改地址或用多路复用器权限拒绝用户不在dialout组ls -l /dev/serial0sudo usermod -aG dialout $USER7.2 我踩过的五个坑第一个坑在树莓派4B上直接用/dev/ttyAMA0发现数据发不出去。原因是ttyAMA0被蓝牙占用了应该用/dev/serial0它会自动指向正确的设备。第二个坑在Ubuntu 22.04上改了/boot/config.txt重启后没生效。原因是Ubuntu用的是/boot/firmware/config.txt旧路径不存在。第三个坑SPI通信时用spi.xfer而不是spi.xfer2导致多字节传输时CS在字节之间拉高从机状态机复位。改用xfer2后正常。第四个坑I2C总线上挂了三个传感器其中两个地址相同扫描时只看到一个。后来用TCA9548A多路复用器分总线解决。第五个坑用CH340模块在Windows 11上调试设备管理器显示黄色感叹号。下载了最新CH340驱动后解决。建议从官方渠道下载驱动不要用系统自动安装的。7.3 进阶建议与扩展方向如果你已经调通了基本的UART、SPI、I2C通信可以进一步探索用SPI驱动TFT屏幕用I2C挂载多个传感器做数据采集用UART连接GPS模块做定位。树莓派5的PCIe接口还可以接高速ADC或FPGA做更复杂的数据采集系统。在软件层面可以学习用设备树overlay自定义引脚复用用libgpiod替代wiringPi做GPIO控制用pigpio做高精度PWM。这些技能在树莓派项目里非常实用。我个人在实际操作中的体会是串口通信的坑大多不在代码而在硬件配置和系统默认设置。每次开始新项目前先花十分钟确认引脚分配、设备树配置、权限设置能省下后面几小时的调试时间。另外手边常备一个USB转串口模块和一根杜邦线遇到问题先做回环测试能快速定位是树莓派端的问题还是外部设备的问题。