Mobile broadband modem

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: does not conform to Help:Style, partially written in first person (Discuss in Talk:Mobile broadband modem)

A number of mobile phone carriers around the world offer internet access via mobile broadband (e.g. LTE, UMTS, EDGE, GSM, etc.).

This article focuses on mobile broadband modems in the format of portable USB devices and mini PCIe cards. For standalone mobile broadband routers, simply connect to them using an interface they provide (e.g. Ethernet or Wi-Fi).

Device identification

Install usbutils.

Examine the output of:

$ lsusb

and

$ lspci -nn

which will show the vendor and product IDs of the device. Note that some devices will show two different product IDs at different times as explained below.

Note: PCIe adapters that expose themselves as USB devices will show up in lsusb instead of lspci.

Mode switching

From mass storage mode

Often these devices will have two modes (1) USB flash memory storage (2) USB modem. The first mode, sometimes known as ZeroCD, is often used to deliver an internet communications program for another operating system and is generally of no interest to Linux users. Additionally some have a slot into which the user can insert an additional flash memory card.

A useful utility for switching these devices into modem mode is usb_modeswitch. It ships with udev rules /usr/lib/udev/rules.d/40-usb_modeswitch.rules that contain entries for many devices, which it will switch to modem mode upon insertion.

When a device is switched, its product ID may change to a different value. The vendor ID will remain unchanged. This can be seen in the output of lsusb.

Some devices are supported in the USB serial kernel module called option (named after the "Option" devices, but not limited to just those) and may be used without usb_modeswitch.

Tip: An alternative is to use the eject command as described in ZTE MF110/MF190#Switch from CD mode to modem mode on the device.

From router mode

This article or section needs expansion.

Reason: Add instructions for switching these devices to "modem mode". (Discuss in Talk:Mobile broadband modem)

Depending on the device, it may expose an Ethernet network interface or provide Wi-Fi. In that case you will need to have the interface up. If the device has a DHCP server, you can use a DHCP client to match it. Otherwise, you will have to have some knowledge about the network the device expects. Such information might be obtained from its behavior in another OS. Or by searching the web. Or from the drivers, and other information, stored in the initial USB flash memory storage (ZeroCD). Some Huawei HiLink devices, for example, sometime operate at 192.168.8.0/24, with a gateway at 192.168.8.1. They also might have a web interface at http://192.168.8.1.

Modem mode

In general, at this point you should note if mode switching left you with additional /dev/ttyUSB* serial device and a ww* network interface. You can do that with journalctl or by shell commands such as:

$ ls /dev/ttyUSB*
$ ip link

Remove the PIN

First of all use your SIM card in a normal phone and disable the PIN request if present. If the SIM card asks the PIN wvdial will not work.

Failing that, you can use mmcli (provided by modemmanager) or AT commands, to unlock the SIM card.

Using mmcli

First, list the modems and find the modem's index:

$ mmcli -L

Look for /org/freedesktop/ModemManager1/Modem/MODEM_INDEX.

Find the SIM card index:

$ mmcli -m MODEM_INDEX

Just as with the modem index, look for primary sim path: /org/freedesktop/ModemManager1/SIM/SIM_INDEX.

Unlock the SIM card:

$ mmcli --sim=SIM_INDEX --pin=PIN

Remove the requirement for PIN:

$ mmcli --sim=SIM_INDEX --pin=PIN --disable-pin

Using AT commands

Follow the instructions in https://unix.stackexchange.com/a/313878.

Connection

To connect to the mobile network, use one of the following methods.

This article or section needs expansion.

Reason: Explain what protocol[1][2] is used by each software and which should be preferred. (Discuss in Talk:Mobile broadband modem)

ModemManager

Install modemmanager and usb_modeswitch.

Start and enable ModemManager.service.

Use mmcli(1) to communicate with the modem.

The simplest way to establish a connection is to use mmcli's --simple-connect option.

First, list the modems and find the modem's index:

$ mmcli -L

Look for /org/freedesktop/ModemManager1/Modem/MODEM_INDEX.

Next connect to the mobile network. For example:

$ mmcli -m MODEM_INDEX --simple-connect="apn=internet.myisp.example"

Replace internet.myisp.example with your ISP's provided APN. If a user name and password is required, set them accordingly:

$ mmcli -m MODEM_INDEX --simple-connect="apn=internet.myisp.example,user=user_name,password=password"

Note:

IP connectivity on broadband networks is subtly different from wireless or wired LAN networks. For LTE modems, ModemManager documentation provides a good explanation that might be helpful for troubleshooting.
ModemManager only establishes a connection between the modem and the mobile network. Once connected, ModemManager will request to use a specific IP setup method in the connected bearer: either ppp (so the user should launch pppd on the reported serial port), or static (so the user should manually configure IP settings on the reported network interface), or dhcp (so the user should run a DHCP client on the reported network interface. Instead of all this manual setup, it's suggested to use NetworkManager.
The network interface name will start with ww, e.g. wwp0s20u8i2.
ModemManager does not save modem configuration, i.e. it does not have anything like connection profiles. The modem will need to be configured each time it is attached. If persistent configuration is desired, use NetworkManager.

To disconnect from the mobile network run:

$ mmcli -m MODEM_INDEX --simple-disconnect

NetworkManager

NetworkManager uses ModemManager to work with mobile broadband modems. See NetworkManager#Mobile broadband support.

libmbim

Install libmbim. To bring up the modem you can use mbim-network which is a wrapper for mbimcli calls. First create a profile for mbim-network.

/etc/mbim-network.conf

APN=apn=internet.myisp.example

Now connect to the network with:

# mbim-network /dev/cdc-wdmX start

Then follow Network configuration to bring up the ww* interface and get an IP address using DHCP.

pppd

pppd can be used to configure 3g connections. Step by step instruction is available on 3G and GPRS modems with pppd. Optionally, pppconfig^AUR can be used to simplify the pppd configuration using dialog interface.

wvdial

See main article: wvdial

netctl

Netctl can be used to establish a connection using a USB modem. An example configuration file provided by netctl is located at /etc/netctl/examples/mobile_ppp. Minimally you will probably have to specify

/etc/netctl/mobile_ppp

Interface=cdc-wdmX
Connection=mobile_ppp
AccessPointName=apn=internet.myisp.example

See the netctl article and netctl.profile(5) for more information.

Tips and tricks

Disable mode switching

Some ways to disable usb_modeswitch from operating on a device before the device was inserted, for example to be able to read the initial flash memory (ZeroCD), are:

By the configuration file

/etc/usb_modeswitch.conf

DisableSwitching=1

With a udev rule

Masking the udev rule the package is using can be achieved with

# ln -s /dev/null /etc/udev/rules.d/40-usb_modeswitch.rules

AT commands

There are some useful commands:

AT^U2DIAG=0 - the device is only Modem
AT^U2DIAG=1 - device is in modem mode + CD ROM
AT^U2DIAG=255 - the device in modem mode + CD ROM + Card Reader
AT^U2DIAG=256 - the device in modem mode + Card Reader
AT+CPIN=PIN-CODE - enter PIN-code
AT+CUSD=1,PDU-encoded-USSD-code,15 - USSD request, result can be found (probably) in /dev/ttyUSB2.

Encode *100# to PDU format:

$ perl -e '@a=split(//,unpack("b*","*100#")); for ($i=7; $i < $#a; $i+=8) { $a[$i]="" } print uc(unpack("H*", pack("b*", join("", @a))))."\n"'

Decode AA180C3602 from PDU format:

$ perl -e '@a=split(//,unpack("b*", pack("H*","AA180C3602"))); for ($i=6; $i < $#a; $i+=7) {$a[$i].="0" } print pack("b*", join("", @a)).""'

Answer decoding (this example is balance response: 151.25):

$ perl -e 'print pack("H*", "003100350031002C003200350020044004430431002E0020");'

Some operators return USSD result in PDU encoding, so you should check proper decoding method.

AT+CSQ - get signal quality (AT+CSQ=?)
AT+GMI - get manufacturer
AT+GMM - get model
AT+GMR - get revision
AT+GMN - get IMEI
AT+COPS? - get operator info
AT^CARDLOCK="NCK-code" - unlock modem. NCK-code should be calculated by IMEI. After that modem can work with any GSM-provider.
AT^SYSCFG=mode, order, band, roaming, domain - System Config

Mode:

2 Automatic search
13 2G ONLY
14 3G ONLY
16 No change

Order:

0 Automatic search
1 2G first, then 3G
2 3G first, then 2G
3 No change

Band:

80 GSM DCS systems
100 Extended GSM 900
200 Primary GSM 900
200000 GSM PCS
400000 WCDMA IMT 2000
3FFFFFFF Any band
40000000 No change of band

Roaming:

0 Not supported
1 Roaming is supported
2 No change

Domain:

0 CS_ONLY
1 PS_ONLY
2 CS_PS
3 ANY
4 No change

Monitor used bandwidth

Frequently a 3G connection obtained via a mobile phone operator comes with restricted bandwidth, so that you are only allowed to use a certain bandwidth per time (e.g. 1GB per month). While it is quite straight-forward to know which type of network applications are pretty bandwidth extensive (e.g. video streaming, gaming, torrent, etc.), it may be difficult to keep an overview about overall consumed bandwidth.

A number of tools are available to help with that. Two console tools are vnstat, which allows to keep track of bandwith over time, and iftop to monitor bandwidth of individual sessions.

The internal web server found in some devices, such as some Huawei HiLink, might also show information about bandwidth usage.

Reading SMS

With dedicated software

This was tested on a Huawei EM770W (GTM382E) 3g card integrated into an Acer Aspire AS3810TG laptop. Install gnokii^AUR, then:

$ mkdir -p $XDG_CONFIG_HOME/gnokii

Usually the configuration directory is ~/.config/gnokii.

$ cp /etc/gnokiirc ~/.config/gnokii/config

Edit ~/.config/gnokii/config as follows:

port = /dev/ttyUSB0

You may have to use a different port depending on your configuration, for example /dev/ttyUSB1 or something else:

model = AT
connection = serial

You need to be part of the uucp group to use /dev/ttyUSB0.

Then launch gnokii:

$ xgnokii

Click on the "SMS" icon button, a window opens up. Then click: "messages->activate sms reading". Your messages will show up in the window.

Command line script:

A small command line script using gnokii to read SMS on your SIM card (not phone memory) without having to start a GUI:

$ gnokii --getsms SM 0 end 2>&1|grep Text -A1 -B3|grep -v Text

What it does:

gnokii # invoke gnokii
--getsms SM 0 end # read SMS from SM-memory location (=SIM card) starting at 0 and reading all occupied memory locations ("end")
2>&1 # connect STDERR to STDOUT to make sure the output from the --getsms command can be piped to grep
|grep Text # pipe output from gnokii to grep, anchoring at output containing "Text"
-A1 -B3 # print one line after the matched pattern and three lines before the matched pattern
|grep -v Text # grep result to another grep to exclude the "Text" line (-v for inverting the pattern)

Granted this does not work very well if your SMS contains the word "Text", but you may adapt the script to your liking.

Another option is to use mmcli, you can use simple bash script like this one^{[dead link 2024-10-12 ⓘ]} that is also used to write messages or this one below:

#!/bin/sh
#get modem number
MODEMNO=$(mmcli -L | grep -o "Modem/[0-9]" | grep -o [0-9]$)
#list all SMS messages, and select this with highest id (usually newest one)
SMSNO=$(mmcli -m ${MODEMNO} --messaging-list-sms | awk '/received/{split($1, ar, /\//); print ar[6]; exit}')
#read message with highest id
mmcli -m ${MODEMNO} -s ${SMSNO}

With email like web interface

Some Devices, such as some Huawei HiLink, include an email like web interface for SMS. It is included in the device internal web server, which is used for other purposes too.

Writing SMS

#!/bin/sh
#get modem number
MODEMNO=$(mmcli -L | grep -o "Modem/[0-9]" | grep -o [0-9]$)
#create sms in modem and get number
SMSNO=$(mmcli -m ${MODEMNO} --messaging-create-sms="text='$1',number=+$2" |  grep -o [0-9]*$)
#send message
mmcli -s ${SMSNO} --send
# delete all sent messages
for i in $(mmcli -m ${MODEMNO} --messaging-list-sms | grep " (sent)" | cut -f5 -d' ') ; do
    mmcli -m ${MODEMNO} --messaging-delete-sms=$i
done

You may need give permission by creating file with content like

/etc/polkit-1/rules.d/49-nopasswd_mmcli.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.ModemManager1.Messaging" &&
        subject.isInGroup("uucp"))
    {
        return polkit.Result.YES;
    }
});

Commands to restart the device

Unplugging, and plugging, the device is sometimes used to restart the USB device. The following describes how to do that from the shell. Doing that from the shell might be useful, if, for example, the plug is at the rear side of the PC. The method described is not just for USB modems. It should be good for many other USB devices.

The important part is that the requirements are for the USB bus, and the port, the device is attached to. There could be one, or more, sub ports too. Suppose I obtained bus 2 and port 4, without sub ports, for my device from the output of lsusb -t. This information is also recorded in the journal. With

$ cat /sys/bus/usb/drivers/usb/2-4/product

I can verify it is the intended device.

The following sequence will restart the device:

# echo 2-4 > /sys/bus/usb/drivers/usb/unbind
# sleep 10
# echo 2-4 > /sys/bus/usb/drivers/usb/bind

Some more comments are at, for example, https://askubuntu.com/questions/1036341/unplug-and-plug-in-again-a-usb-device-in-the-terminal.

Troubleshooting

Connection halts after few minutes running

This problem commonly occurs on some modems which locked by a mobile operator. You can successfully connect to the internet but after few minutes connection halts and your modem reboots. That happens because an operator built a some checks into modem firmware so a modem checks if a branded software is running on your pc, but usually that software is Windows-only, and obviously you do not use it. Fix (it works on ZTE-mf190 at least) is simple - send this command through serial port (use minicom or similar soft):

AT+ZCDRUN=E\r\n

This command will delete a NODOWNLOAD.FLG file in the modem's filesystem - it will disable such checks.

Another possibility for such disconnections is to help the customer save bandwidth, which might be expensive. With Huawei HiLink devices with a web interface, there might be an option there to set a longer period of inactivity before the connection hangs up.

Low connection speed

Someone claims that the connection speed under Linux is lower than Windows [3]. This is a short summary for possible solutions which are not fully verified.

In most of conditions, the low speed is caused by bad receiver signals and too many people in cell. But you still could use the following method to try to improve the connection speed:

QoS parameter can be set with the AT+CGEQMIN and AT+CGEQREQ commands. It should also be possible to decrease and limit the connection speed. Add the following Init command in /etc/wvdial.conf:

Init6 = AT+CGEQMIN=1,4,64,640,64,640
Init7 = AT+CGEQREQ=1,4,64,640,64,640

Baud parameter in /etc/wvdial.conf could be used to increase the connection speed:

Baud = 460800

It is advisable to see the baud rate set by the official modem application for Windows (possibly 9600 on Vista).

Fix image quality

If you are getting low quality images while browsing the web over a mobile broadband connection with the hints shift+r improves the quality of this image and shift+a improves the quality of all images on this page, follow these instructions:

Install tinyproxy.

Edit /etc/tinyproxy/tinyproxy.conf and insert the following two lines:

AddHeader "Pragma" "No-Cache"
AddHeader "Cache-Control" "No-Cache"

Start tinyproxy.service

Configure your browser to use localhost:8888 as a proxy server and you are all done. This is especially useful if you are using, for example, Google Chrome which, unlike Firefox, does not allow you to modify the Pragma and Cache-Control headers.

ModemManager does not recognize the modem

In case ModemManager does not recognize the modem, check the unit status of ModemManager.service. If you get error messages such as Couldn't check support for device and not supported by any plugin, you may have to whitelist your device using the ModemManager filter rules.

FCC locking

The FCC lock is a software lock integrated in WWAN modules shipped by several different laptop manufacturers like Lenovo, Dell, or HP. This lock prevents the WWAN module from being put online until some specific unlock procedure (usually a magic command sent to the module) is performed.

Since release 1.18.4, the ModemManager daemon no longer automatically performs the FCC unlock procedure [4].

ModemManager will keep on providing support for the known FCC unlock procedures, but no longer automatically: the user must install and select the FCC unlock procedure needed in the specific laptop being used. This applies to: EM7355, MC8805, MC7355, EM7455, SDX55, EM120.

The modemmanager package ships several scripts installed under /usr/share/ModemManager/fcc-unlock.available.d and named as vid:pid with either the PCI or USB vendor and product IDs. However, they are not used if they are not in the /etc/ModemManager directory.

For each device the vid:pid can be found in the brackets at the end of the line:

# lspci -nn

To enable unlock script for the device it must be symlinked like so:

# ln -sft /etc/ModemManager/fcc-unlock.d /usr/share/ModemManager/fcc-unlock.available.d/vid:pid

For a Quectel EM120 modem that would be:

# ln -sft /etc/ModemManager/fcc-unlock.d /usr/share/ModemManager/fcc-unlock.available.d/1eac:1001

See the ModemManager documentation for more information.

NetworkManager: Device not available / rfkill block

If NetworkManager persists on that the device (e.g. /dev/cdc-wdm0) is not available while ModemManager can use it, it could either be, that the device is blocked using a hardware switch, by rfkill or just NetworkManager believes that.

Check rfkill with:

# rfkill
ID TYPE      DEVICE                   SOFT      HARD
 0 bluetooth tpacpi_bluetooth_sw unblocked unblocked
 1 wwan      tpacpi_wwan_sw      unblocked unblocked
 2 wlan      phy0                unblocked unblocked
 8 bluetooth hci0                unblocked unblocked

The wwan device should be listed as unblocked for both SOFT & HARD. If it is HARD blocked, a hardware switch blocks the device. If it is SOFT blocked, unblock it using:

# rfkill unblock wwan

If NetworkManager still declares the device not available, it could be that NetworkManager is not synced with rfkill. Check that using:

$ nmcli radio
WIFI-HW  WIFI     WWAN-HW  WWAN
enabled  enabled  enabled  enabled

If WWAN is listed as disabled, enable it using:

$ nmcli radio wwan on

ModemManager connects successfully but the interface does not show any IP address

This has been reported to happen on some LTE modems with buggy or incompatible firmware versions. In this scenario, when inspecting the bearer with:

$ mmcli -m [your modem index] -b 1

It can be seen how the IPv4 configuration section shows no IP address, and may show dhcp as the method despite the associated interface (e.g. wwan0) not being dhcp-capable. In this cases, the modem firmware is not behaving correctly and it should be upgraded.