Orange Pi 5 Plus这个板子我玩了大半年从最开始连串口都调不通到现在UART、I2C、SPI、PWM、CAN五个接口全部稳定跑起来中间踩过的坑确实不少。如果你也是刚入手这块板子想在嵌入式Linux上做点正经东西——比如接个传感器、驱动个舵机、连个CAN总线设备——那这篇教程就是给你准备的。很多人拿到Orange Pi 5 Plus之后第一反应是这板子这么强RK35888核A76A55双2.5G网口跑个Linux肯定啥都能干。但真到了要接硬件的时候就会发现系统里UART、I2C、SPI这些接口压根没开或者开了这个就丢了那个原理图上的40个引脚看半天也搞不明白哪个是哪个。这篇文章我会把整个配置过程从头到尾捋一遍讲清楚背后的机制再给你一份可以直接抄作业的配置清单和一件开启全部接口的脚本。内容偏实操新手也能跟着一步步完成。1. 这块板子到底能干什么以及为什么要折腾这些接口在动手改配置之前先花点时间说清楚我们到底在做什么。Orange Pi 5 Plus的核心芯片是瑞芯微的RK3588这颗SoC本身接口资源非常丰富内部集成了10路UART、9路I2C、5路SPI、16路PWM、3路CAN控制器。但因为物理引脚数量有限这些控制器不可能全部引出到40Pin排针上板卡设计者必须在原理图阶段就做取舍。所以你会发现一个现象芯片手册里写着支持的东西实际板卡上可能根本没有引出引脚或者即便引出了也和另一个功能复用在同一组引脚上。这就是为什么你直接改配置文件往往会失败因为你没搞懂引脚复用关系。去折腾这些接口通常是因为有具体需求。UART串口是调试和对接旧设备最常用的方式很多工控模块、GPS模块、蓝牙模块都走串口I2C则是最简单的传感器总线温湿度、气压、加速度计几乎都是I2C接口SPI速度快适合刷屏幕、接Flash存储、跑一些需要高速传输的外设PWM最常用的是控制舵机、风扇调速、LED调光CAN则是汽车电子和工业控制里绕不开的总线。把这些接口都调通这块板子基本上就能承担一个边缘计算网关加传感器采集中枢的角色了。在开始之前你要保证手头有这些东西一块Orange Pi 5 Plus主板、电源建议5V/4A以上、TF卡或NVMe硬盘。系统镜像建议用官方Orange Pi OSDebian版或者Armbian都行本文的方法差异不大。杜邦线若干、USB转TTL串口模块注意必须是3.3V电平的FT232系列常见但跳线要调对、面包板可选。如果想测CAN还需要一个CAN收发器模块比如SN65HVD230。准备好之后把系统烧进TF卡正常开机进入命令行我们就开始。2. 系统准备与引脚资源总览2.1 烧录系统与首次开机配置烧录系统这一步本身没什么难度用balenaEtcher把镜像写到TF卡里就行但有几个细节会影响后续接口配置。第一尽量下载最新版本的系统镜像。Orange Pi官方和Armbian都会持续更新内核和overlay文件旧版本可能缺少新接口的overlay或者存在已知bug。我自己的例子是最早用的一个内核版本里PWM overlay的节点路径是错的导致导出的PWM值完全不对后来升级系统才解决。第二首次开机建议直接走有线网络连接或者用串口调试线进入系统因为有些系统镜像默认不开启SSH。用串口的话记住接法是USB转TTL模块的TX接板子的RXRX接板子的TXGND共地。千万别接反接反了通常没输出但也不会坏不过还是细心点好。进入系统后先更新一下软件源和内核头文件后面编译设备树或者装驱动会用到sudo apt update sudo apt upgrade -y sudo apt install -y linux-headers-$(uname -r) device-tree-compiler2.2 读懂40Pin引脚图Orange Pi 5 Plus的40Pin排针和树莓派在物理尺寸上兼容但引脚定义完全是另一套逻辑。你必须在官方文档里下载对应版本的原理图或者引脚图不要拿树莓派的定义来套。一张合格的引脚图会标注每个引脚的序号、默認功能、复用功能、电压域。以我手里的这块板子为例几个关键引脚大致是这样不同批次可能有差异务必以官方原理图为准功能引脚位置复用说明UART4_TX引脚8与I2C4_SCL复用UART4_RX引脚10与I2C4_SDA复用I2C2_SCL引脚3与PWM0复用I2C2_SDA引脚5与GPIO3_B6复用SPI1_MOSI引脚19与PWM1复用SPI1_MISO引脚21与GPIO复用SPI1_CLK引脚23与GPIO复用SPI1_CS0引脚24与GPIO复用PWM3引脚7与GPIO3_B5复用CAN0_TX引脚27与UART7_TX复用CAN0_RX引脚28与UART7_RX复用看见没有引脚8既能当UART4_TX又能当I2C4_SCLPIN27既是CAN0_TX又是UART7_TX。这就是RK3588的IOMUX机制在起作用——每个物理引脚在芯片内部都连到多个外设控制器到底启用哪条通路由软件层面决定。这个“软件层面”就是我们下面要讲的设备树。你可以把设备树理解成给内核的一份说明书告诉它“某某引脚现在要当UART4用了不要再当I2C用”。你不改这份说明书内核就按默认的复用关系来很多功能当然就是关闭的。2.3 一个容易踩的坑引脚复用冲突我见过不少人在论坛里问“为什么我开了UART4之后I2C4就没了”答案很简单——因为这俩功能在物理上就共用同一组引脚引脚只有一组不可能既当串口又当I2C。这不是系统bug是硬件物理限制。所以配置接口之前最关键的一步是先确定自己的需求画一张引脚占用表。比如你接下来要接3个I2C传感器、1个串口GPS、1个舵机那就要先规划I2C用哪一组引脚串口用哪一组PWM用哪一个确保它们的物理引脚没有重叠。规划好了再改配置而不是配置到一半发现冲突再回头重新改。3. 配置核心机制设备树overlay到底是什么3.1 设备树与overlay的类比设备树Device Tree是Linux内核用来描述硬件资源的数据结构文件它描述了CPU、内存、UART、I2C这些硬件设备挂在哪个总线上、占用哪些寄存器地址、中断号是多少、引脚复用怎么配置。你可以把它理解成一张“装修图纸”。房子芯片的结构已经定死了但你可以在图纸上标注哪些房间当卧室、哪些当书房。设备树就干这个事它告诉内核“芯片第27脚给我当CAN的TX引脚用。”overlay设备树覆盖层则是更高一层的玩法。它有点像是装修图纸上追加的“贴纸”不需要重新画整张图纸只需要一张小小的贴纸标注“这里改一下那里改一下”。Linux内核在启动的时候把基础设备树和overlay合并形成最终设备树。这样改起来就很快——不用重新编译整个内核改一个文本文件重启就生效。Orange Pi官方系统和Armbian都使用了这种overlay机制。在Armbian里overlay的开关配置通常放在/boot/armbianEnv.txt文件里在文件末尾加上一行overlaysuart4 i2c2 spi1 pwm3 can0多个overlay用空格分隔。改完保存重启对应的接口就启用了。Orange Pi官方OS则可能是/boot/orangepiEnv.txt或者/boot/uEnv.txt路径有差异但原理一样。3.2 怎么查看系统里有哪些可用的overlay配置之前先摸清楚系统到底提供了哪些overlay文件。在Armbian系统中overlay文件位于/boot/dtb/rockchip/overlay/目录下也有的系统在/boot/overlay-user/前者是系统内置的后者是用户自己放进去的文件名通常是rk3588-*.dtbols /boot/dtb/rockchip/overlay/你会看到一堆.dtbo文件名字里都带功能说明比如rk3588-uart4.dtbo、rk3588-i2c2.dtbo、rk3588-spi1.dtbo。这些就是现成的overlay。你只需要在armbianEnv.txt里写上对应名称不带路径和.dtbo后缀就行。如果你发现某个功能没有对应的overlay文件那就得自己写。好在RK3588的资料还算齐全可以从参考板的overlay源码改。但这是进阶玩法本文就不展开了。3.3 配置文件修改与校验用vim或者nano改armbianEnv.txt的时候要小心这个文件同时也会被其他工具修改比如armbian-config所以一上来最好先备份sudo cp /boot/armbianEnv.txt /boot/armbianEnv.txt.bak然后编辑文件在末尾追加overlays行。修改完不要立刻重启先用以下命令确认语法没问题dmesg | grep -i overlay这一步不一定能完全验证但能看出系统有没有加载overlay的报错。最稳妥的办法是重启后用ls /dev/ttyS*、ls /dev/i2c-*检查设备节点是否出现。我们后面每个接口都会给出对应的验证方法。4. 逐一开启UART / I2C / SPI / PWM / CAN4.1 UART串口查看、启用、回环测试串口方案里首先要知道哪些串口被系统默认占用了。RK3588的UART2通常作为调试串口也就是你在命令行里敲命令用的那个不建议改它留着调试用。其他串口默认都是关闭的。假设你想启用UART4就在armbianEnv.txt里加overlaysuart4重启后执行ls /dev/ttyS*正常你会在列表里看到ttyS4具体数字以实际情况为准。用dmesg | grep ttyS4可以看到内核为它分配的基地址和中断号。然后做一次回环测试验证收发都没问题找一根杜邦线把TX和RX短接然后用串口工具发数据。命令行里可以用这个脚本快速验证sudo chmod 666 /dev/ttyS4 stty -F /dev/ttyS4 115200 raw echo hello uart /dev/ttyS4如果TX和RX已经短接这个echo的数据会原样打回来用cat /dev/ttyS4能看到自己发的字符串。能看到就说明通路OK。实际操作中有几个问题很容易碰到权限问题。普通用户访问不了/dev/ttyS4要么用sudo要么把用户加入dialout组。Ubuntu系一般是sudo usermod -aG dialout $USER。电平问题。Orange Pi的UART是3.3V TTL电平不能直接接RS232电平的设备中间需要MAX232电平转换芯片。接USB转串口模块时也注意模块要支持3.3V。波形排查。如果数据发出去对方收不到用逻辑分析仪看TX引脚波形UART空闲时是高电平起始位是低电平。如果空闲不是高检查是不是接线问题。4.2 I2C接口扫描设备与上拉电阻的那些事I2C只需要两根线SCL和SDA接传感器非常方便。假设启用I2C2配置overlaysi2c2重启后查看总线是否生成ls /dev/i2c-* i2cdetect -li2cdetect是i2c-tools包提供的工具先安装sudo apt install -y i2c-tools设备接上后扫描总线地址i2cdetect -y 2假设你接了一个地址为0x48的传感器扫描结果就能看到。如果你发现设备明明接好了却扫不出来先别怀疑接线看看是不是下面几个原因总线上没有上拉电阻或者上拉电阻值不对。I2C是开漏输出必须有上拉电阻才能把电平拉高。板载通常已经预埋了上拉但如果外接的传感器模块离得远、线太长你可以尝试在SCL和SDA上外接4.7kΩ上拉到3.3V。上拉太小比如1kΩ在低功耗器件上可能导致灌电流过大上拉太大比如100kΩ则沿太缓、时序走样。地址冲突。总线上如果有两个设备地址一样扫描可能只显示地址但通信异常。可以用i2cdetect -y -r 2强制用SMBus读有时候能排除设备的时序兼容问题。电平域不对。I2C的上拉必须接到同一个电压域你板子上的I2C2如果是3.3V域就不要把它接到5V的传感器模块上而不做电平转换。另外用i2cget、i2cset可以读写寄存器调试驱动前可以先在命令行手动读写确认时序正确。4.3 SPI接口选硬件片选还是软件片选SPI和I2C不一样它至少4根线MOSI、MISO、SCLK、CS。SPI速度快适合屏幕、Flash等设备。启用SPI1的做法overlaysspi1重启后检查ls /dev/spidev*如果有/dev/spidev1.0说明控制器已经注册好了。但注意SPI设备节点不会自动出现只有当内核中存在一个spidev用户设备时才生成节点。overlay一般已经默认创建了spidev所以你才能看到。接下来用一个叫spidev_test的工具做回环测试。先把MOSI和MISO短接然后执行sudo apt install -y spidev-tools # 有的系统里叫这个包 spidev_test -D /dev/spidev1.0 -p hello spi如果终端打印出你发送的字符串说明SPI通路正常。SPI这块新手容易纠结的是片选。硬件片选Hardware CS是SPI控制器自动把CS线拉低来选中设备好处是时序精准不占用额外GPIO。软件片选Software CS是用一个普通GPIO当CS用好处是灵活比如一个SPI总线上挂多个设备除了控制器自带的CS0/CS1还能用别的GPIO扩展坏处是你要自己在代码里控制拉低拉高时序如果控制不好设备可能因为片选时序异常而误判。在设备树层面如果你要用软件片选一般是在SPI设备节点里把cs-gpios指向一个GPIO引脚。比如把CS0替换成GPIO3_B2cs-gpios gpio3 RK_PB2 GPIO_ACTIVE_LOW;这样配置后内核就会通过GPIO来控制片选。但对Linux下的spidev应用来说你在用户态仍然操作/dev/spidev1.0片选的控制方式对应用是透明的所以两种方案在功能上能通达只是接线时要把对应的CS引脚接对。用SPI还有个高频踩坑点MISO和MOSI接反。接反了通常不会损坏硬件但数据肯定通信不了。再次确认引脚定义非常关键实在不行用万用表量一下确认通路。4.4 PWM接口推舵机、控风扇、调LED亮度PWM脉宽调制本质上就是控制一个引脚输出方波的占空比通过占空比大小来控制功率输出。舵机角度、风扇转速、LED亮度本质都在调占空比。Orange Pi 5 Plus的PWM接口比较分散。假设启用PWM3引脚7配置overlayspwm3重启后PWM骨架子系统会把对应的chip注册到内核ls /sys/class/pwm/你会看到pwmchip0、pwmchip1之类。要操作某一路PWM先找到它对应的chip比如PWM3可能对应pwmchip4然后用sysfs接口导出通道cd /sys/class/pwm/pwmchip4 echo 0 export cd pwm0 echo 20000000 period # 周期 20ms对应50Hz适合舵机 echo 1500000 duty_cycle # 占空比1.5ms舵机回中位 echo 1 enable这套操作你看熟了就会发现它其实就是在往/sys文件系统里写数字而已非常直观。给舵机供电要特别注意Orange Pi板子上的3.3V/5V引脚电流有限一般舵机启动电流很大靠板子供电很容易电压跌落导致单片机重启最好外接独立的5V电源只把PWM信号线接到板子上地线共地。如果做四针风扇调速就得看风扇PWM输入的电气规格了。四针风扇通常红12V、黑GND、黄转速反馈、蓝PWM控制。板子的PWM输出是3.3V直接驱动12V风扇的PWM引脚可能不够或者烧板子稳妥的接法是PWM先接一个MOS管比如AO3400或2N7002做电平转换再去控制风扇。之前有个朋友直接在3.3V PWM引脚上挂12V风扇的PWM线结果板子烧了教训深刻。MOS管接PWM时如果发热大概率是开关频率过高导致开关损耗大或者是栅极驱动电阻没加导致振铃。记住PWM频率不是越高越好电平域不匹配就要加转换这是基础中的基础。4.5 CAN接口必须外接收发器才能跑起来CAN总线是工业领域最常用的总线之一RK3588内置CAN控制器CAN0/CAN1等但注意SoC上的CAN TX/RX是数字信号物理层必须通过CAN收发器芯片比如TJA1050、SN65HVD230转成CAN_H和CAN_L差分信号才能接到总线上。假设你的板卡把CAN0引到了引脚27和28具体看原理图配置overlayscan0重启后检查是否出现can接口ip link show你会看到can0但它是关闭状态。需要配置波特率并启用sudo ip link set can0 up type can bitrate 500000 sudo ip link set can0 up验证可以和其他CAN节点通信用can-utils工具sudo apt install -y can-utils # 终端1接收 candump can0 # 终端2发送 cansend can0 123#DEADBEEF如果总线配置没问题发送方会提示发送成功接收方能看到对应的帧。如果提示错误或者总线上有off状态多半是以下原因终端电阻缺失。CAN总线两端都需要120Ω终端电阻如果你的测试环境只有一块板子和一个收发器模块大概率没有这个电阻可以在CAN_H和CAN_L之间并一个120Ω电阻否则信号反射严重。波特率不一致。所有节点必须用同一波特率。用ip -details link show can0可以确认实际波特率。没接共地。这不是开玩笑实际测试中很容易忽略不同设备的GND不连在一起CAN收发器的共模电压就乱飘通信时好时坏。5. 一键脚本自动化配置全部接口手把手改配置文件已经跑通了但如果每次换系统都要重新配一遍肯定嫌麻烦。我把整个配置过程打包成了一个脚本你拿到手直接跑就能自动完成备份、修改、校验并且给出清晰提示。下面是完整脚本内容基于Armbian系统路径如果跟你的系统有差异改成你自己的路径#!/bin/bash # orange-pi-5plus-enable-all.sh # 一键开启 UART4 / I2C2 / SPI1 / PWM3 / CAN0 # 用法: sudo bash orange-pi-5plus-enable-all.sh set -e # 检测配置文件路径 ENV_FILE if [ -f /boot/armbianEnv.txt ]; then ENV_FILE/boot/armbianEnv.txt elif [ -f /boot/orangepiEnv.txt ]; then ENV_FILE/boot/orangepiEnv.txt elif [ -f /boot/uEnv.txt ]; then ENV_FILE/boot/uEnv.txt else echo 找不到系统配置文件脚本退出。 exit 1 fi echo 检测到配置文件: $ENV_FILE # 备份 BACKUP_FILE${ENV_FILE}.bak.$(date %Y%m%d%H%M%S) cp $ENV_FILE $BACKUP_FILE echo 已备份配置文件到 $BACKUP_FILE # 定义要启用的overlay OVERLAYSuart4 i2c2 spi1 pwm3 can0 # 判断是否已存在overlays行 if grep -q ^overlays $ENV_FILE; then echo 检测到已有overlays行将追加到现有列表... # 提取现有值 EXISTING$(grep ^overlays $ENV_FILE | cut -d -f2-) # 去掉末尾空白和可能的多余空格 EXISTING$(echo $EXISTING | sed s/[[:space:]]*$//) # 把新overlay追加进去如果已经有同名则不重复添加 for ov in $OVERLAYS; do if echo $EXISTING | grep -q $ov; then echo overlay $ov 已在列表中跳过 else EXISTING$EXISTING $ov fi done # 替换原行 sed -i s|^overlays.*|overlays$EXISTING| $ENV_FILE else echo 未找到overlays行追加到文件末尾... echo overlays$OVERLAYS $ENV_FILE fi # 安装依赖工具 echo 安装依赖工具... apt update apt install -y i2c-tools can-utils spidev-tools # 输出提示 echo echo 配置完成。当前配置内容 cat $ENV_FILE echo echo 重启后请检查以下设备节点 echo ls /dev/ttyS4 # UART4 echo ls /dev/i2c-2 # I2C2编号可能偏差以i2cdetect -l为准 echo ls /dev/spidev1.0 # SPI1 echo ls /sys/class/pwm # PWM chip echo ip link show can0 # CAN0 echo echo 如果需要回滚执行: cp $BACKUP_FILE $ENV_FILE脚本逻辑拆开就是三步第一自动识别配置文件路径。不同系统的引导环境文件位置不同脚本挨个探测找到一个就用哪个。第二备份原文件避免改坏了回不去。第三处理overlays行。如果文件里已经有一行overlaysxxx说明可能之前配置过其他功能脚本会做合并去重而不是覆盖。比如你已经开了i2c2现在跑这个脚本就不会把i2c2清掉而是把uart4、spi1这些添加上去。执行sudo bash orange-pi-5plus-enable-all.sh 重启后分别检查设备节点是否生成即可。 如果你不需要一次全开改脚本顶部的 OVERLAYS 变量比如只要UART和PWM就写 OVERLAYSuart4 pwm3。 到这里你要回头想一下2.3说的引脚冲突。这个脚本默认开的是UART4和I2C4冲突问题我特意避开了——UART4和I2C4在物理上复用所以脚本里不会同时出现这俩我用的是I2C2和UART4物理引脚不重叠。如果你要抄到自己的系统里务必根据目标板卡原理图调整千万别照搬。 ## 7. 常见问题与排查技巧实录 前面每个接口都单独说了踩坑点这里再整理一张速查表方便你在排查问题时快速定位原因。 | 现象 | 可能原因 | 解决办法 | | --- | --- | --- | | 重启后 /dev 下没有对应设备 | overlay名称拼错或系统不支持该overlay | ls /boot/dtb/rockchip/overlay/ 确认文件名ls /dev/ttyS* /dev/i2c-* 实时检查 | | 接口设备存在但收发无数据 | 引脚复用冲突、TX/RX或MOSI/MISO接反、电平不匹配 | 检查原理图确认复用关系用回环测试排除通路问题用逻辑分析仪看波形 | | I2C扫描不到设备 | 上拉缺失/太小、地址冲突、设备供电异常 | 外接4.7k上拉i2cdetect -y -r 总线号先测设备3.3V供电 | | SPI传输乱码 | CS片选时序不对、SCLK极性/相位不一致、接线过长 | 确认设备树里spi极性spi-cpol/spi-cpha缩短杜邦线换硬件片选 | | PWM输出没有波形 | 没有export、enable没写1、引脚复用冲突 | ls /sys/class/pwm确认pwmchip编号看原理图确认引脚有没有被其他overlay占用 | | CAN启动报错或者总线上没事但收不到帧 | 没有120Ω终端电阻、波特率不一致、各节点没共地 | 并120Ω电阻ip -details link show can0 核对波特率接好共地 | | 一开机系统无法启动 | 配置了不存在的overlay名称 | 用备份文件恢复cp /boot/armbianEnv.txt.bak.xxx /boot/armbianEnv.txt | 排查逻辑其实就三步先看设备节点有没有生成有节点说明驱动层没大问题再做回环或总线扫描确认物理通路最后用逻辑分析仪或示波器看波形确认时序参数。从前往后一项项排除比瞎猜快得多。 再说一个排查利器dmesg。每次重启后用 dmesg | grep -E uart|i2c|spi|pwm|can 过滤内核日志经常能看到类似“failed to request GPIO”或者“resource busy”的报错这些信息直指问题根源。 另外强烈建议你在改配置前把当前的内核命令、设备节点列表都截个图或者记下来。有时候不是你没配对而是你之前手动测试时设置的一些残留状态比如PWM导出过的通道没释放、GPIO被别的手续占用导致新配置起不来。干净环境先测试一遍能排除掉很多环境因素。 最后再分享一个小经验也是我踩过很多次坑之后总结出来的所有接线操作一定要在断电状态下完成尤其是CAN和PWM这种可能涉及外部电源的接口。带电插拔轻则通信异常重则烧掉GPIO或者整个板子的电源管理芯片。板子坏了还能换数据丢了才是最心疼的。按照本文的方法一步步来你的Orange Pi 5 Plus很快就能变成一台功能齐全的“接口百宝箱”后面不管接什么外设都能随手就拿过来用。