树莓派3B+搭配EC20 4G模块联网全攻略：从硬件选型到QMI拨号

1. 项目缘起与整体方案设计1.1 为什么要在树莓派上折腾4G联网把树莓派3B和Quectel EC20这套组合拿出来聊是因为它解决了一个非常具体的痛点在没有固定宽带、没有稳定WiFi的环境里让树莓派依然能独立上网。这个需求听起来小众但实际场景一点都不少。比如户外数据采集节点、移动车载终端、临时监控点位、农业大棚里的环境监测甚至是展会现场的临时演示设备这些场景要么拉网线不现实要么WiFi信号覆盖不到要么就是需要设备能跟着载体移动。树莓派3B本身自带WiFi和以太网口但这两样都依赖外部网络基础设施。WiFi需要热点以太网需要交换机或路由器。一旦设备要放到野外、车上、船上或者只是临时布点这两种方式就都不好使了。4G模块的价值就在这里只要有基站信号设备就能联网跟手机一样。而Quectel EC20这个模块在创客圈和工业物联网圈子里口碑很稳价格适中资料相对齐全支持国内主流频段是树莓派4G联网方案里出现频率极高的一个选择。这个项目适合谁看如果你手上有树莓派3B想给它加一个4G上网能力或者你正在做物联网终端、远程数据回传、移动设备联网这类事情那这套方案可以直接参考。哪怕你是刚接触树莓派的新手只要跟着步骤走也能跑通。我会把原理、接线、配置、踩坑点都讲清楚尽量让你少走弯路。1.2 硬件选型背后的考量先说说为什么是树莓派3B而不是别的型号。3B在树莓派家族里属于非常成熟的一代40针GPIO、四个USB口、自带WiFi和蓝牙社区支持极其完善。它的USB接口对于EC20这种USB接口的4G模块来说供电和带宽都够用。虽然树莓派4或者5性能更强但3B的功耗更低价格更便宜作为联网终端来说完全够用性价比很高。再说Quectel EC20。这个模块本质上是一个4G LTE Cat.4模块下行速率最高150Mbps上行50Mbps支持FDD-LTE、TDD-LTE、WCDMA、TD-SCDMA、GSM等多种制式。它通过USB接口与主机通信主机侧看到的是一个USB设备通常会枚举出多个串口ttyUSB0到ttyUSB3以及一个网络接口通常是usb0或者wwan0。EC20在国内有多个版本比如EC20-CE、EC20-CEHD等频段支持略有差异选购时要注意确认支持你所用运营商的频段。这里有个关键点EC20是USB接口的模块不是通过GPIO的串口通信。很多人第一次接触会以为要接TX/RX到树莓派的GPIO上其实不是。EC20通过USB与树莓派通信数据走USB通道速度远高于普通串口。模块上通常有一个USB接口通过一根USB线或者转接板连接到树莓派的USB口。供电方面EC20在搜网和传输时峰值电流可能达到2A左右所以供电一定要足这是后面会反复强调的坑。1.3 整体联网架构拆解整个方案的联网逻辑可以这样理解EC20负责跟基站通信建立一个4G数据通道树莓派通过USB识别到EC20把它当作一个网络设备然后在树莓派的操作系统里通过拨号工具或者网络管理工具让这个设备激活并获取IP地址最后配置路由和DNS让树莓派的流量走4G通道出去。在软件层面主要有两条路线。第一条是传统的PPP拨号用pppd配合chat脚本通过串口发送AT指令完成拨号建立一个ppp0网络接口。这种方式经典、可控但配置稍繁琐。第二条是QMI或者MBIM方式利用模块的QMI接口通过qmi_wwan驱动和libqmi工具或者用ModemManager和NetworkManager来管理。这种方式更现代配置相对简洁尤其是在较新的系统上。我这次采用的是QMI方式配合NetworkManager因为树莓派官方系统Raspberry Pi OS自带的NetworkManager对4G模块的支持已经比较友好配置起来比手写ppp脚本省事而且断线重连、信号管理这些都能自动处理。当然PPP方式我也会提一下方便你在不同系统版本上做选择。2. 核心细节解析与实操要点2.1 硬件连接与供电的关键细节硬件连接看起来简单但细节决定成败。EC20模块通常是一个小板子上面有USB接口、SIM卡座、天线接口。你需要准备的东西包括树莓派3B、EC20模块、匹配的天线主天线和分集天线至少接主天线、一张已经开通流量套餐的4G SIM卡注意是标准卡、micro卡还是nano卡看模块卡座、一根USB线或者USB转接板。连接步骤很直接把SIM卡插入EC20的卡座注意方向芯片朝下还是朝上要看卡座丝印插反了识别不到。天线拧到模块的IPEX或者SMA接口上主天线标着MAIN分集标着AUX至少接MAIN。然后用USB线把EC20连到树莓派的USB口。供电是第一个大坑。树莓派3B的USB口输出能力有限四个USB口共享总电流官方建议是每个口不超过1.2A。EC20在搜网瞬间和发射数据时电流会突然拉高如果供电不足会出现模块反复重启、树莓派掉电重启、甚至USB设备直接消失的情况。我实测下来用树莓派自身的USB口给EC20供电在信号好的时候勉强能用但信号弱或者传输量大时就不稳。稳妥的做法是给EC20单独供电。有两种方式一是用带外部供电的USB HUB把EC20插在HUB上HUB接树莓派的同时接一个5V/2A以上的电源二是直接用EC20模块上的供电接口如果有的话单独接一个5V电源。我推荐第一种简单可靠。另外树莓派本身的电源也要够官方推荐5V/2.5A最好用5V/3A的给整个系统留足余量。注意千万不要用那种只有数据线没有供电增强的劣质USB线线阻大压降明显模块供电会不稳。选线径粗一点的短线。2.2 系统识别与驱动确认硬件接好之后给树莓派上电等系统启动。然后通过SSH或者直接接显示器键盘登录系统。第一步是确认系统有没有识别到EC20。在终端里输入lsusb正常的话你应该能看到类似这样的一行Bus 001 Device 004: ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC20 LTE modem如果看到了Quectel或者2c7c开头的设备说明USB层面已经识别到了。如果没看到先检查USB线、供电、模块是否上电。有时候模块上有个电源指示灯确认它亮了。接着看串口设备ls /dev/ttyUSB*EC20通常会枚举出四个串口ttyUSB0、ttyUSB1、ttyUSB2、ttyUSB3。其中ttyUSB2一般是AT指令口ttyUSB3是PPP拨号口不同固件可能略有差异。如果只看到部分或者一个都没有可能是驱动没加载。树莓派官方系统内核一般已经内置了option和qmi_wwan驱动正常情况下插上就能识别。如果没有可以尝试sudo modprobe option sudo modprobe qmi_wwan然后再看设备节点。如果还是没有可能需要更新内核或者手动添加USB串口ID这个后面在问题排查里细说。再看网络接口ip link show应该能看到一个类似wwan0或者usb0的接口。如果看到了说明QMI网络接口也出来了。这一步确认下来硬件和驱动层面基本就通了。2.3 软件方案选型QMI还是PPP前面提到两条路线这里展开说说为什么选QMI。PPP方式的历史很久兼容性极好几乎任何Linux系统都能跑。它的原理是通过串口发送AT指令让模块进入PPP模式然后pppd在串口上建立PPP连接生成ppp0接口。配置需要写chat脚本、peers文件还要处理拨号、认证、断线重连。优点是可控性强出问题容易定位缺点是配置繁琐而且PPP本身效率略低断线重连要自己写脚本。QMI方式利用的是模块的QMIQualcomm MSM Interface协议通过qmi_wwan驱动把模块当作一个网络设备来管理。配合libqmi或者ModemManager可以查询信号、注册网络、激活数据连接整个过程更接近现代移动网络的管理方式。NetworkManager对QMI的支持已经比较成熟配置好之后插上模块就能自动联网断线也能自动重连。我选QMI的理由很简单省事、稳定、可维护。尤其是在树莓派这种经常无人值守的场景里自动重连太重要了。PPP方式虽然也能做但要自己写重连逻辑维护成本高。当然如果你的系统版本很老或者NetworkManager版本太低QMI可能配置起来也有坑那时候退回PPP也是合理选择。3. 实操过程与核心环节实现3.1 系统准备与依赖安装开始配置之前先把系统更新到比较新的状态。树莓派官方系统用apt管理包执行sudo apt update sudo apt upgrade -y这个过程可能比较久取决于网络和SD卡速度。更新完之后安装必要的工具sudo apt install -y libqmi-utils udhcpc modemmanager network-managerlibqmi-utils提供了qmicli工具可以用来手动测试QMI连接udhcpc是轻量级DHCP客户端有时候需要它来获取IPmodemmanager和network-manager是自动管理模块的核心。安装完之后确认ModemManager服务在运行sudo systemctl status ModemManager如果没运行启动并设置开机自启sudo systemctl enable ModemManager sudo systemctl start ModemManagerNetworkManager一般默认就在跑确认一下sudo systemctl status NetworkManager这两个服务是后面自动联网的关键。3.2 用qmicli手动验证模块状态在交给NetworkManager自动管理之前我习惯先用qmicli手动验证一遍确认模块能正常注册网络、能激活数据连接。这样万一自动配置不成功能快速定位是模块问题还是配置问题。首先确认QMI设备节点ls /dev/cdc-wdm*应该能看到/dev/cdc-wdm0。这是QMI通信的控制节点。然后查询模块信息sudo qmicli -d /dev/cdc-wdm0 --dms-get-manufacturer sudo qmicli -d /dev/cdc-wdm0 --dms-get-model正常会返回Quectel和EC20之类的信息。接着查询SIM卡状态sudo qmicli -d /dev/cdc-wdm0 --uim-get-card-status如果SIM卡正常会显示卡的状态是present并且能读到ICCID等信息。如果显示absent或者error检查SIM卡是否插好、是否欠费、是否被锁定。查询网络注册状态sudo qmicli -d /dev/cdc-wdm0 --nas-get-serving-system这个命令返回的信息比较多重点看Registration state是不是registered以及当前注册的网络制式LTE、WCDMA等。如果显示not registered或者searching说明还没注册上网络可能是信号弱、天线没接好、频段不支持或者SIM卡问题。信号强度可以这样查sudo qmicli -d /dev/cdc-wdm0 --nas-get-signal-strength返回的RSSI、RSRP、RSRQ等值可以判断信号质量。一般来说RSRP在-80dBm以上算好-100dBm左右勉强-110dBm以下就很差了。如果以上都正常可以尝试手动激活数据连接sudo qmicli -d /dev/cdc-wdm0 --wds-start-networkip-type4 --client-no-release-cid这个命令会返回一个CIDclient ID记下来。然后给网络接口配IPsudo udhcpc -i wwan0如果成功wwan0会拿到一个运营商分配的IP地址。这时候可以测试联网ping -I wwan0 8.8.8.8能ping通说明整个链路是通的。手动验证这一步非常关键它把问题范围缩小到了模块和网络层面排除了上层管理工具的干扰。3.3 配置NetworkManager自动联网手动验证通过之后就可以让NetworkManager接管了。首先确保ModemManager不要和NetworkManager抢管理权。在较新的系统里两者可以协同工作但有时候需要调整。创建一个NetworkManager的连接配置。可以用nmcli命令行工具sudo nmcli con add type gsm ifname cdc-wdm0 con-name 4g-auto apn 你的APN这里的APN要换成你所用运营商的接入点。比如某运营商的APN是cmnet另一家是3gnet或者uninet具体要查你SIM卡对应的运营商。APN填错是连不上网的常见原因之一。添加之后启用连接sudo nmcli con up 4g-auto然后查看连接状态nmcli con show nmcli device status如果看到wwan0或者cdc-wdm0的状态是connected说明自动联网成功了。这时候树莓派应该已经通过4G上网了。可以测试ping -c 4 8.8.8.8 curl ifconfig.mecurl返回的IP应该是运营商分配的公网或者内网IP。如果希望开机自动连接NetworkManager默认会记住连接配置并自动尝试。可以用sudo nmcli con mod 4g-auto connection.autoconnect yes确保自动连接开启。3.4 路由与DNS的细节处理有时候4G连接上了但树莓派还是走WiFi或者以太网出去这是因为默认路由的优先级问题。Linux会根据路由metric来决定走哪个接口。如果WiFi的metric更低流量就优先走WiFi。查看路由表ip route show你会看到多条default路由每条后面有个metric值。metric越小优先级越高。如果想让4G优先可以调整metricsudo nmcli con mod 4g-auto ipv4.route-metric 50 sudo nmcli con mod 你的WiFi连接名 ipv4.route-metric 100这样4G的metric是50WiFi是1004G优先。反过来如果想让WiFi优先4G做备份就反过来设置。这个在双网冗余场景里很有用。DNS方面NetworkManager一般会自动从运营商获取DNS。如果发现DNS不工作可以手动指定sudo nmcli con mod 4g-auto ipv4.dns 223.5.5.5 114.114.114.114 sudo nmcli con mod 4g-auto ipv4.ignore-auto-dns yes然后重启连接sudo nmcli con down 4g-auto sudo nmcli con up 4g-auto提示如果树莓派同时连着WiFi和4GDNS查询可能会走WiFi的DNS服务器导致解析慢或者失败。手动指定DNS并设置ignore-auto-dns可以避免这个问题。4. 常见问题与排查技巧实录4.1 模块识别不到怎么办这是最常见的问题。插上EC20之后lsusb看不到设备或者只看到一个未知设备。排查顺序如下。先确认供电。模块上的电源灯亮不亮如果不亮说明根本没上电。换USB线、换供电方式。如果灯亮但lsusb没设备换一个USB口试试树莓派的USB口有时候会因为供电问题导致枚举失败。如果lsusb能看到设备但ID不对比如显示的是别的VID/PID可能是模块处于不同的工作模式。EC20有时候会枚举成CD-ROM模式或者别的模式需要发送AT指令切换。不过正规渠道买的模块一般默认就是USB modem模式。如果lsusb正常但/dev/ttyUSB*没有检查驱动dmesg | grep -i usb dmesg | grep -i option看内核日志里有没有报错。有时候需要手动添加USB ID到option驱动sudo modprobe option echo 2c7c 0125 | sudo tee /sys/bus/usb-serial/drivers/option1/new_id这个命令把EC20的VID/PID告诉option驱动让它生成串口设备。2c7c是Quectel的VID0125是EC20的一个常见PID具体以lsusb输出为准。4.2 能识别但连不上网模块识别了串口也有了但NetworkManager显示disconnected或者qmicli激活失败。这时候按层次排查。先看SIM卡。qmicli查卡状态确认卡被识别。如果卡没识别检查卡座、卡方向、卡是否欠费。有些物联网卡需要先激活才能用。再看网络注册。qmicli查serving system确认registered。如果一直searching检查天线。天线没接或者接错接口信号极差注册不上。把天线接到MAIN口放在窗边或者室外试试。然后看APN。APN填错是连不上的高频原因。不同运营商的APN不同甚至同一运营商不同套餐的APN也可能不同。最准确的方法是问运营商客服或者把SIM卡插到手机里看APN设置。还要看频段。EC20有多个版本支持的频段不一样。如果你买的版本不支持当地运营商的频段那就永远注册不上。买之前一定要确认频段匹配。4.3 联网不稳定、频繁掉线这个问题在供电不足时特别常见。表现是联网一会儿就断或者传输大流量时断。解决方法就是前面说的给EC20独立供电用带电源的USB HUB。另一个原因是信号弱。信号弱的时候模块会加大发射功率电流需求更大更容易触发供电问题。同时弱信号下也容易掉线。改善天线位置用增益高一点的天线或者加天线延长线把天线放到信号好的地方。还有可能是NetworkManager和ModemManager的兼容问题。有些版本组合下两者会互相干扰导致连接被反复重置。可以尝试更新到较新的系统版本或者调整ModemManager的配置让它不要管理这个设备。4.4 常见问题速查表现象可能原因排查方法解决方向lsusb看不到设备供电不足、USB线坏、模块没上电看电源灯、换线换口独立供电、换线有USB设备但无ttyUSB驱动未加载、模式不对dmesg看日志、modprobe手动添加USB ID有串口但无cdc-wdmqmi_wwan未加载ls /dev/cdc-wdm*modprobe qmi_wwanSIM卡不识别卡座接触不良、卡欠费qmicli查卡状态重插卡、查套餐注册不上网络天线没接、频段不支持qmicli查serving system接天线、换模块版本激活数据失败APN错误、无流量核对APN改APN、查套餐联网频繁掉线供电不稳、信号弱观察掉线时机独立供电、改善天线有IP但无法上网路由/DNS问题ip route、nslookup调metric、指定DNS4.5 几个容易被忽略的实操心得第一个心得是先手动后自动。不要一上来就配NetworkManager先用qmicli手动跑通一遍。手动能通说明硬件、SIM、网络、APN都没问题剩下的就是管理工具的配置问题。手动不通自动肯定也不通而且更难排查。第二个心得是日志是最好的朋友。出问题的时候dmesg、journalctl -u NetworkManager、journalctl -u ModemManager这三个日志看下来基本能定位到问题在哪一层。很多人不看日志瞎试浪费时间。第三个心得是供电别省。我见过太多因为供电问题导致的玄学故障模块时好时坏换这换那都解决不了最后发现是USB线太细或者HUB供电不够。在供电上多花几十块钱能省下大量排查时间。第四个心得是天线要接对。EC20一般有MAIN和AUX两个天线口MAIN是必须接的AUX是分集接收接了能改善信号但非必须。有人把天线接到AUX上结果信号极差还以为模块坏了。看清楚丝印再接。第五个心得是APN要确认。不同运营商、不同套餐的APN可能不一样尤其是物联网卡。最靠谱的方法是问运营商或者把卡插手机里看。别凭记忆填填错了连不上还找不到原因。5. 进阶玩法与场景延展5.1 双网冗余与自动切换树莓派3B自带WiFi加上4G就具备了双网能力。可以配置成WiFi优先、4G备份或者反过来。NetworkManager支持根据连接优先级自动切换。当WiFi断开时自动切到4GWiFi恢复时再切回来。这个在无人值守场景里非常实用比如放在店里的数据终端平时走WiFi省流量WiFi断了自动走4G保活。配置方法就是前面说的调整route-metric再配合NetworkManager的autoconnect-priority。把WiFi的priority设高4G设低NetworkManager会优先连WiFiWiFi不可用时自动连4G。5.2 远程管理与数据回传4G联网通了之后树莓派就可以做远程数据回传了。常见的做法是跑一个MQTT客户端把传感器数据发到云端或者跑一个轻量级Web服务通过4G网络对外提供接口再或者用SSH反向隧道让外部能访问到内网的树莓派。需要注意的是运营商给4G分配的IP通常是内网IP不是公网IP。也就是说外部无法直接访问树莓派。如果需要外部访问要么用内网穿透工具要么用MQTT这类由设备主动发起连接的协议。这个在方案设计阶段就要考虑清楚。5.3 功耗与散热考量EC20在传输数据时功耗不低峰值能到2A以上。如果整个设备是电池供电续航会是个问题。可以考虑在不需要联网时让模块进入低功耗模式需要时再唤醒。qmicli支持设置模块的工作模式可以切换飞行模式或者低功耗模式。散热方面EC20长时间传输会发热模块背面摸起来会烫手。如果放在密闭外壳里要注意散热否则高温可能导致模块降速或者不稳定。加个小散热片或者留通风孔都有帮助。6. 个人实操体会这套树莓派3B加EC20的4G联网方案我从第一次折腾到稳定跑起来前后花了大概两三天时间其中大部分时间都耗在供电和APN这两个坑上。最开始用树莓派USB口直接供电模块时好时坏lsusb一会儿有一会儿没有换了带电源的HUB之后立马稳定。APN也是一开始凭记忆填了一个死活连不上后来问运营商客服确认了正确的APN一次就通了。现在这套配置已经稳定跑了大半年放在一个户外机柜里做数据采集每天定时回传数据中间经历过几次运营商网络波动NetworkManager都自动重连了没需要人工干预。EC20这个模块的稳定性确实对得起它的口碑。如果你也在做类似的事情我的建议是供电给足、天线接对、APN确认、先手动后自动。这四句话能帮你避开大部分坑。剩下的就是耐心看日志问题总能解决。这套方案不复杂但细节不少把细节做到位它就能稳定干活。