This is an old revision of the document!
How to use LTE modem in QMI mode for WAN connection
Many of currently available 3G/4G/5G modems use QMI and/or MBIM protocol to interact with the host system, e.g. with a router. For your information, QMI is a proprietary protocol by Qualcomm. In contrast to QMI, MBIM is more standardized protocol for such modems.
This recipe explains how to setup and configure OpenWrt for using 3G/4G/5G USB modems for WAN connection, using QMI interface.
The same applies to external modems connected to USB ports and internal models installed into M.2(NGFF) or mPCIe slots.
You may want to checkout the Multiwan package to use this simultaneously with other connections to the internet.
About
Many modern USB modems may operate in different modes. If your modem provides only serial interface(s) like /dev/ttyUSBx - please refer to How to use 3g/UMTS USB Dongle for WAN connection. For more information about different operational modes available:
If it is possible to switch your modem to provide QMI interface - then this article if for YOU.
Legacy Modem Preparation
If QMI interface is not exposed by the modem initially you may need to switch it to another mode or composition by using USB mode switch tool or a vendor-specific AT command.
Please read about AT commands for your modem.
LTE or 5G Modem Preparation
More recent modems are set by default to MBIM or QMI mode.
This is an example for popular Quectel modems:
AT+QCFG="usbnet" # check the current mode AT+QCFG="usbnet",0 # set QMI or RMNET mode AT+QCFG="usbnet",1 # set ECM mode AT+QCFG="usbnet",2 # set MBIM mode
Reset the power to apply changes.
Router Preparation
1. Install OpenWrt
2. Complete Steps OpenWrt Configuration
Router should be turned on and connected to the Internet to get the needed packages. Please refer to: Internet Connection.
Required Packages
To make use of QMI protocol, packages kmod-usb-net-qmi-wwan (driver) and uqmi (control utility) are needed.
Optional Packages
1. Add QMI protocol support to Luci - install luci-proto-qmi
2. Add support for serial interfaces (ttyUSBx) - install kmod-usb-serial-option or kmod-usb-serial-qualcomm depending on the modem.
That is needed to send AT commands to the modem, for configuration purposes or to be able to send/receive SMS and USSD.
3. Install usb-modeswitch if that is needed for switching the modem into the “working” state.
4. Add support for the storage of your modem - refer to: USB Storage
Installation
1. Install all the needed packages
opkg update opkg install usb-modeswitch kmod-mii kmod-usb-net kmod-usb-wdm kmod-usb-net-qmi-wwan uqmi
If your have not enough space on your device - think of installing Rootfs on External Storage (extroot)
Another option is Hardware memory upgrade. Refer to your router Forum thread for possibility and instructions.
2. Reboot the router
reboot
3. Check that everything is OK and You got new device:
ls -l /dev/cdc-wdm0 crw-r--r-- 1 root root 180, 176 Oct 1 12:03 /dev/cdc-wdm0
If you have no such device - try to find out what went wrong:
try dmesg to read kernel logs on USB init
dmesg
or look info about USB devices and interfaces present in the system:
cat /sys/kernel/debug/usb/devices T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 Spd=480 MxCh= 0 D: Ver= 2.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 P: Vendor=12d1 ProdID=1506 Rev= 0.00 S: Manufacturer=Huawei Technologies S: Product=HUAWEI Mobile C:* #Ifs= 3 Cfg#= 1 Atr=c0 MxPwr=500mA I:* If#= 0 Alt= 0 #EPs= 2 Cls=ff(vend.) Sub=01 Prot=02 Driver=option E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms E: Ad=01(O) Atr=02(Bulk) MxPS= 512 Ivl=4ms I:* If#= 1 Alt= 0 #EPs= 1 Cls=ff(vend.) Sub=01 Prot=09 Driver=qmi_wwan E: Ad=82(I) Atr=03(Int.) MxPS= 64 Ivl=2ms I:* If#= 2 Alt= 0 #EPs= 2 Cls=ff(vend.) Sub=01 Prot=08 Driver=qmi_wwan E: Ad=83(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=4ms
See Troubleshooting Section of this page for more information.
Configuration
With LuCi web interface
If the package luci-proto-qmi is installed, navigate to Network → Interfaces, then Add new interface… → Protocol : QMI, Interface: cdc-wdm0
Enter your APN and select the IP type as instructed by the carrier.
Assign the firewall zone (typically - “wan”).
QMI Protocol Configuration
You can configure UCI manually using uci command line or text editor.
UCI is supporting qmi network protocol configuration.
The package uqmi must be installed to use QMI protocol.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| device | file path | yes | (none) | QMI device node, typically /dev/cdc-wdm0 |
| apn | string | yes | (none) | Used APN |
| auth | string | no | (none) | Authentication type: pap, chap, both, none |
| username | string | no | (none) | Username for PAP/CHAP authentication |
| password | string | no | (none) | Password for PAP/CHAP authentication |
| pincode | number | no | (none) | PIN code to unlock SIM card |
| delay | number | no | 0 | Seconds to wait before trying to interact with the modem (some ZTE modems require up to 30 s.) |
| modes | string | no | (modem default) | Allowed network modes, comma separated list of: all, lte, umts, gsm, cdma, td-scdma |
| pdptype | string | no | IP | Used IP-stack mode, IP (for IPv4), IPV6 (for IPv6) or IPV4V6 (for dual-stack). Some carriers require specific stack or it won't connect. |
| profile | number | no | (none) | Connection profile to use |
| dhcp | boolean | no | 1 | Whether to use dhcp (default) or uqmi (0) to get IPv4 interface configuration |
| dhcpv6 | boolean | no | 0 | Whether to use dhcp (1) or uqmi (default) to get IPv6 interface configuration |
| autoconnect | boolean | no | 1 | |
| plmn | number | no | (none) | First three digits are the mcc (mobile country code) and the last three digits are the mnc (mobile network code), for example if plmn=338020, then the mcc is 338 and the mnc is 020 |
| timeout | number | no | 10 | Timeout (in seconds) to wait for SIM operations |
Here is a brief help about uqmi command line usage.
No device given
Usage: uqmi <options|actions>
Options:
--single, -s: Print output as a single line (for scripts)
--device=NAME, -d NAME: Set device name to NAME (required)
--keep-client-id <name>: Keep Client ID for service <name>
--release-client-id <name>: Release Client ID after exiting
--mbim, -m NAME is an MBIM device with EXT_QMUX support
--timeout, -t response timeout in msecs
Services: dms, nas, pds, wds, wms
Actions:
--get-versions: Get service versions
--set-client-id <name>,<id>: Set Client ID for service <name> to <id>
(implies --keep-client-id)
--get-client-id <name>: Connect and get Client ID for service <name>
(implies --keep-client-id)
--sync: Release all Client IDs
--start-network: Start network connection (use with options below)
--apn <apn>: Use APN
--auth-type pap|chap|both|none: Use network authentication type
--username <name>: Use network username
--password <password>: Use network password
--ip-family <family>: Use ip-family for the connection (ipv4, ipv6, unspecified)
--autoconnect: Enable automatic connect/reconnect
--profile <index>: Use connection profile
--stop-network <pdh>: Stop network connection (use with option below)
--autoconnect: Disable automatic connect/reconnect
--get-data-status: Get current data access status
--set-ip-family <val>: Set ip-family (ipv4, ipv6, unspecified)
--set-autoconnect <val>: Set automatic connect/reconnect (disabled, enabled, paused)
--get-current-settings: Get current connection settings
--get-capabilities: List device capabilities
--get-pin-status: Get PIN verification status
--verify-pin1 <pin>: Verify PIN1
--verify-pin2 <pin>: Verify PIN2
--set-pin1-protection <state>: Set PIN1 protection state (disabled, enabled)
--pin <pin>: PIN1 needed to change state
--set-pin2-protection <state>: Set PIN2 protection state (disabled, enabled)
--pin <pin2>: PIN2 needed to change state
--change-pin1: Change PIN1
--pin <old pin>: Current PIN1
--new-pin <new pin>: New pin
--change-pin2: Change PIN2
--pin <old pin>: Current PIN2
--new-pin <new pin>: New pin
--unblock-pin1: Unblock PIN1
--puk <puk>: PUK needed to unblock
--new-pin <new pin>: New pin
--unblock-pin2: Unblock PIN2
--puk <puk>: PUK needed to unblock
--new-pin <new pin>: New pin
--get-iccid: Get the ICCID
--get-imsi: Get International Mobile Subscriber ID
--get-imei: Get International Mobile Equipment ID
--get-msisdn: Get the MSISDN (telephone number)
--reset-dms: Reset the DMS service
--set-device-operating-mode <m> Set the device operating mode
(modes: online, low_power, factory_test, offline
reset, shutting_down, persistent_low_power,
mode_only_low_power)
--fcc-auth: Set FCC authentication
--uim-verify-pin1 <pin>: Verify PIN1 (new devices)
--uim-verify-pin2 <pin>: Verify PIN2 (new devices)
--set-network-modes <modes>: Set usable network modes (Syntax: <mode1>[,<mode2>,...])
Available modes: all, lte, umts, gsm, cdma, td-scdma
--set-network-preference <mode>: Set preferred network mode to <mode>
Available modes: auto, gsm, wcdma
--set-network-roaming <mode>: Set roaming preference:
Available modes: any, off, only
--network-scan: Initiate network scan
--network-register: Initiate network register
--set-plmn: Register at specified network
--mcc <mcc>: Mobile Country Code (0 - auto)
--mnc <mnc>: Mobile Network Code
--get-plmn: Get preferred network selection info
--get-signal-info: Get signal strength info
--get-serving-system: Get serving system info
--list-messages: List SMS messages
--delete-message <id>: Delete SMS message at index <id>
--get-message <id>: Get SMS message at index <id>
--get-raw-message <id>: Get SMS raw message contents at index <id>
--send-message <data>: Send SMS message (use options below)
--send-message-smsc <nr>: SMSC number
--send-message-target <nr>: Destination number (required)
--send-message-flash: Send as Flash SMS
--wda-set-data-format <type>: Set data format (type: 802.3|raw-ip)
--wda-get-data-format: Get data format
MBIM Protocol configuration
Currently, there is not enough information about mbim protocol as it's being actively developed. If you are curious about setting up mbim protocol, you may ask OpenWrt users/devel mailing lists or OpenWrt forum
Here is a brief help about umbim command line.
umbim help
Usage: mbim <caps|pinstate|unlock|connect|disconnect> [options]
Options:
-d <device> the device (/dev/cdc-wdmX)
-t <transaction> the transaction id
-n no close
-v verbose
Interface configuration
First check that everything works correctly:
root@OpenWrt:~# uqmi -d /dev/cdc-wdm0 --get-data-status "disconnected"
and
root@OpenWrt:~# uqmi -d /dev/cdc-wdm0 --get-signal-info
{
"type": "lte",
"rssi": -71,
"rsrq": -9,
"rsrp": -94,
"snr": 70
}
To start the internet connection - issue a command:
uqmi -d /dev/cdc-wdm0 --start-network internet --autoconnect
Where “internet” is the APN of your provider.
Many providers allow to use “any” APN, so-called “no-settings” connection. So, in many cases “internet” would be just fine
Check the status:
uqmi -d /dev/cdc-wdm0 --get-data-status "connected"
--autoconnect key says that you want always be connected, once dongle is inserted to the router and Cellular Network is in range.
It will be kept after reboot.
In case you need additional authentication, please look at the possible arguments for the uqmi utility:
--start-network <apn>: Start network connection (use with options below)
--auth-type pap|chap|both|none: Use network authentication type
--username <name>: Use network username
--password <password>: Use network password
--autoconnect: Enable automatic connect/reconnect
--stop-network <pdh>: Stop network connection (use with option below)
--autoconnect: Disable automatic connect/reconnect
Network configuration
Now you should add new Interface to /etc/config/network
config interface 'wwan'
option ifname 'wwan0'
option proto 'dhcp'
You can do this using the vi text editor, but if you're not comfortable with that, point your browser to 192.168.1.1 again, choose Network → Interfaces and click Add new interface.
Or if not working, try with this:
config interface 'wwan'
option proto 'qmi'
option 'device' '/dev/cdc-wdm0'
Write wwan as the name of the interface and make it cover the wwan0 interface. Choose DHCP client as the protocol.
Insert a screenshot of LUCI add Interface. I have not enought rights.
Firewall configuration
The only thing that is left - Add wwan interface to WAN zone
Using LUCI:
- go to Network → Firewall, scroll down to wan and click the Edit button
- add a checkmark to the wwan box under Covered networks heading, click Save & Apply
Using CLI:
- Edit /etc/config/firewall, and add wwan interface to WAN zone
config zone
option name wan
list network 'wan'
list network 'wan6'
list network 'wwan'
option input REJECT
option output ACCEPT
option forward REJECT
option masq 1
option mtu_fix 1
That's It!
Insert a Screen Shot from LUCI.
Checking your balance
To check your balance or send any other AT commands, you need to have usb serial device like: /dev/ttyUSB0
If you have it (if not then install missing usb serial drivers), you can run in first terminal:
cat /dev/ttyUSB0
and in the second (*101# is my ussd code):
echo -ne 'AT+CUSD=1,"*101#",15\r\n' > /dev/ttyUSB0
You should see in first terminal USSD response.
Additional Info
Some providers of the cellular internet use redirection to their pages for access activation, when you are connected first time. I.e. YOTA in Russia.
Normally this would be blocked by dnsmasq:
Jan 18 14:36:49 OpenWrt daemon.warn dnsmasq[1325]: possible DNS-rebind attack detected: my.yota.ru
You have 2 options:
- Allow rebind responses RFC1918 (In LUCI goto Network → DHCP and DNS and uncheck Rebind protection checkmark)
- Add Yota.ru domain to Whitelist (In LUCI goto Network → DHCP and DNS and type in “yota.ru” without quotes to the Domain whitelist field.
Save & apply
Notes
Based on: This Article
Troubleshooting
Everything is okay but modem doesn't establish connection. What can I try?
You may want to try adding the argument --get-client-id wds and --set-client-id when running uqmi like:
wds=`uqmi -s -d /dev/cdc-wdm0 --get-client-id wds` uqmi -d /dev/cdc-wdm0 --set-client-id wds,"$wds" --start-network your_apn
Moreover based on this article I discovered that need to reset my modem (tested on Dell Wireless 5804 413c:819b) in boot process, so you can try add the following commands in your /etc/rc.local:
/sbin/uqmi -d /dev/cdc-wdm0 --set-device-operating-mode offline /sbin/uqmi -d /dev/cdc-wdm0 --set-device-operating-mode reset /bin/sleep 20 /sbin/uqmi -d /dev/cdc-wdm0 --set-device-operating-mode online /sbin/uqmi -d /dev/cdc-wdm0 --set-autoconnect enabled /sbin/uqmi -d /dev/cdc-wdm0 --network-register
My router is not detecting the dongle. What should I do?
Try the following commands:
usbmode -l
It should respond with a message about your USB device is detected. If it does, issue the next command. If it doesn't, you might want to get help from the forum.
usbmode -s
Then wait for the dongle to get issued an IP from your ISP.
No serial device is available (cdc_wdm0, ttyUSB0)
You may need to install the packages kmod-usb-net-cdc-mbim and libmbim
opkg install kmod-usb-net-cdc-mbim libmbim
At least for the Sierra Wireless EM7455 is this the case.
I have to issue usbmode -l and usbmode -s every time I reboot my router to detect my USB device. How can I automate it?
Include the following codes into /etc/rc.local just before exit 0:
/sbin/usbmode -l /bin/sleep 2 /sbin/usbmode -s