Connect 2G/3G/4G/5G Modems to OpenWrt with ModemManager

ModemManager is a service that sets up and connects 2G/3G/4G/5G modems while presenting their differences through a common abstraction. The OpenWrt documentation lists modem initialization, Internet access, SMS, and firmware upgrades for selected QMI modems as examples of its capabilities.¹

This article uses the source's example APN and sysfs path. The username, password, and pincode values below are safe placeholders; replace them locally and never put SIM credentials in Git.

1. Install ModemManager

When building firmware with menuconfig, ModemManager is under Network. On a running firmware, the 2022 source lists these common USB modules with opkg:

1
2

opkg update
opkg install kmod-usb-serial kmod-usb-net kmod-usb-serial-wwan kmod-usb-serial-option kmod-usb-net-qmi-wwan kmod-usb-net-cdc-mbim

That is the command from the source page. On a newer OpenWrt release using apk, check the release's package names before changing package managers; do not attach an old opkg feed to a new firmware.

2. MBIM and QMI support

ModemManager supports MBIM modems. In menuconfig, select MBIM in the Configuration section of the ModemManager entry.

It also supports QMI modems. Select QMI in the corresponding Configuration section when the modem uses QMI. The required kernel modules depend on the USB modem, so the example's combined package list does not mean every modem needs every module.

3. Define the interface with UCI

ModemManager exposes a modem as a standard Linux network interface. The source's /etc/config/network example is an interface named broadband:

1
2
3
4
5
6
7
8

config interface 'broadband'
        option device   '/sys/devices/platform/soc/20980000.usb/usb1/1-1/1-1.2/1-1.2.1'
        option proto    'modemmanager'
        option apn      'ac.vodafone.es'
        option username '[REDACTED]'
        option password '[REDACTED]'
        option pincode  '[REDACTED]'
        option lowpower '1'

The most important detail is device: the source requires a full sysfs path, such as the example above, and explicitly says not to use /dev/cdc-wdm0 for this option. Find the modem's actual path under /sys before committing the UCI section.

After adding the section, reload networking using the mechanism appropriate for the release and check the interface state. Do not enable lowpower merely because the option exists if the modem must remain online.

4. Options listed by the documentation

iptype must match the carrier service. If the SIM has a PIN, unlock it correctly before other operations; do not repeatedly guess the PIN.

5. LuCI support

Install:

1

opkg install luci-proto-modemmanager

LuCI can then create an interface using the ModemManager protocol. Menus and package names vary by release, so I still verify the package feed and modem detection before saving the configuration.

6. Checks and limits

The source does not provide a full throughput test or a modem-specific diagnostic script. My safe check order is:

1. Confirm that the modem appears in sysfs and identify MBIM or QMI.
2. Confirm that the required kernel module is loaded.
3. Check device, APN, iptype, and SIM PIN.
4. Verify that broadband has an address and the intended default route.
5. Review logs during reconnects and power-state changes.

Do not copy one carrier's APN or credentials to another SIM, do not publish a PIN, and do not treat an interface coming up as proof of long-term modem stability.

Conclusion

ModemManager is useful when OpenWrt needs to expose a cellular modem through a normal network interface, but success depends on the USB driver, MBIM/QMI mode, sysfs path, APN, and SIM policy. Keeping the source's UCI fields, replacing credentials with local secrets, and selecting packages for the actual release are the key safety boundaries.

Sources