Pi 5 Cellular Modems
This guide builds a runtime that adds USB cellular modem drivers and a systemd-networkd profile to a Raspberry Pi 5, then checks the drivers and the profile on the device.
Prerequisites
- macOS 10.12+ or Linux (Ubuntu 22.04+, Fedora 39+)
- Docker Desktop installed and running
- The latest version of the Avocado CLI
- A Raspberry Pi 5 that already runs Avocado OS (2026 release,
nextchannel) and is reachable over SSH - A USB cellular modem with an active SIM and data plan, for the last check
Initialize
avocado init --reference pi5-cellular-modems pi5-modems
cd pi5-modems
Install
avocado install -f
Build
avocado build
This builds the cellular-modems extension: the USB network and serial drivers (usbnet, cdc_ether, cdc_ncm, cdc_mbim, cdc_wdm, qmi_wwan, rndis_host, cdc_acm, option, usb_wwan, usbserial, qcserial, sierra, sierra_net and tun), lsusb, ethtool, iproute2 and systemd-analyze, the QMI and MBIM tools from libqmi and libmbim, and a networkd profile for every usb* and wwan* link.
Deploy
Deploy to a running device over SSH, or provision a fresh SD card:
avocado deploy --device root@<device-ip> dev
# or
avocado provision -r dev --profile sd
Verify
1. The drivers are in place
ssh root@<device-ip> 'for m in usbnet cdc_ether cdc_ncm cdc_mbim qmi_wwan option cdc_acm; do modprobe -n $m && echo "ok: $m"; done'
Every module prints ok. A modem loads the ones it needs by itself when you plug it in.
2. The network profile is active
The platform starts networkd after the extensions are merged, so it reads the profile on a cold boot. A merge hook also reloads networkd on every merge, including avocadoctl refresh on a running device. Check that a link named usb0 gets the cellular profile, with no manual reload:
ssh root@<device-ip> 'modprobe tun; ip tuntap add dev usb0 mode tap; ip link set usb0 up; sleep 3; networkctl status usb0 --no-pager | grep "Network File"; ip link del usb0'
Expect Network File: /usr/lib/systemd/network/30-cellular.network. Without the profile, the same link would match the stock 80-wired.network and get Ethernet's route metric.
3. A real modem
Plug in the modem and watch the kernel:
ssh root@<device-ip> 'lsusb; dmesg | tail -20; ip -br link; networkctl status usb0 wwan0 --no-pager'
An ECM, NCM or RNDIS modem shows up as usb0 and gets an address by DHCP on its own. Once it has one, ip route lists a default route through it at metric 300, behind eth0 at 10 and wlan0 at 200.
A QMI or MBIM modem shows up as wwan0, but DHCP gets no reply until a data session is open, so the route check above does not apply to it yet. Open the session with qmi-network or qmicli for a QMI modem, or mbim-network or mbimcli for an MBIM one; the extension ships all four. Many modems can also be switched to ECM mode instead, after which they behave like the first case. On a Quectel modem such as the EC25 or EG25, that is AT+QCFG="usbnet",1 on its AT port, followed by a modem reset.
What this reference does not do
- It does not switch a modem between USB modes. Modems that start in a storage or serial mode and need an AT command to expose a network interface need that step added.
- It does not install ModemManager, so nothing sets an APN, manages the SIM or opens a QMI or MBIM data session by itself. The QMI and MBIM tools are there for you to do it.
- It does not dial PPP. The feed has no
pppd, so a modem that only offers a serial data path gets its/dev/ttyUSB*ports for AT commands but no connection. - The drivers and the profile are tested without a modem attached. Step 3 is yours to run.