Modem Support
Introduction
ModemManager is a DBus activated daemon and controls mobile broadband (2G/3G/4G) devices and connections. It is able to configure and setup connections with a modem, whether they are built-in devices, USB cellular dongles, bluetooth-paired telephones, or professional RS232/USB devices with external power supplies. NetworkManager and Modemamanager in combination can be used to setup a connection to the cellular network on detection. Modemamanager uses libqmi and libmbim to communicate over Qualcomm MSM Interface (QMI) and Mobile Interface Broadband Model (MBIM) protocol.
Keep in mind that the commands may vary slightly according to your modem and cellular provider. It is not possible to cover every single use case there is.
ModemManager on Torizon
Torizon OS provides ModemManager out-of-the-box, just like it also provides NetworkManager which is a program for providing detection and configuration for systems to automatically connect to networks. You can proceed with reading this article to learn how to use it.
Production Release
After you make the changes to the board, you can use the command isolate from the TorizonCore Builder Tool to generate your custom Torizon OS image for the Toradex Easy Installer.
ModemManager on BSP Layers and Reference Images for Yocto Project
If you have a custom Yocto build, you have to integrate ModemManager into your distribution. This article does not go through these steps, it only explains how to use ModemManager.
This article complies with the Typographic Conventions for Torizon Documentation.
Prerequisites
- Computer on Module with Torizon OS or a custom Yocto build with ModemManager.
- A Cellular Module connected to the system.
ModemManager
ModemManager provides a command-line tool mmcli to control and monitor ModemManager. mmcli basic usage is shown below with Sierra MC7455 modem as an example. Sierra MC7455 modem is in QMI mode by default.
Look into mmcli Manpage for more information.
Cellular Network
List Modems
A modem detection can be verified either through utilities of controlling subsystem(like lsusb) or using mmcli.
# mmcli -L
/org/freedesktop/ModemManager1/Modem/0 [Sierra Wireless, Incorporated] MC7455
Here we have just one modem and 0 at the end of /org/freedesktop/ModemManager1/Modem/ is the index of the modem. Index of modem is to be used in rest of the commands to communicate with the modem.
Enable Modem
To enable the Modem:
# mmcli -m 0 -e
successfully enabled the modem
Detailed Information
Detailed information of modem can be gotten by executing:
# mmcli -m 0
--------------------------------
General | dbus path: /org/freedesktop/ModemManager1/Modem/0
| device id: d8a0301f39c8f3b959660cef109e3db4b41546a9
--------------------------------
Hardware | manufacturer: Sierra Wireless, Incorporated
| model: MC7455
| firmware revision: SWI9X30C_02.24.05.06 r7040 CARMD-EV-FRMWR2 2017/05/19 06:23:09
| h/w revision: 1.0
| supported: gsm-umts, lte
| current: gsm-umts, lte
| equipment id: 123456789987654
--------------------------------
System | device: /sys/devices/soc0/soc/2100000.aips-bus/2184200.usb/ci_hdrc.1/usb2/2-1/2-1.1
| drivers: qmi_wwan, qcserial
| plugin: Sierra
| primary port: cdc-wdm1
| ports: wwan1 (net), ttyUSB0 (qcdm), ttyUSB2 (at), wwan0 (net),
| cdc-wdm1 (qmi), ttyUSB1 (gps), cdc-wdm0 (qmi)
--------------------------------
Numbers | own: 12345678910
--------------------------------
Status | lock: sim-pin2
| unlock retries: sim-pin (3), sim-puk (10), sim-pin2 (10), sim-puk2 (10)
| state: registered
| power state: on
| access tech: lte
| signal quality: 96% (recent)
--------------------------------
Modes | supported: allowed: 3g; preferred: none
| allowed: 4g; preferred: none
| allowed: 3g, 4g; preferred: 3g
| allowed: 3g, 4g; preferred: 4g
| current: allowed: 3g, 4g; preferred: 4g
--------------------------------
Bands | supported: utran-1, utran-3, utran-4, utran-5, utran-8, utran-2,
| eutran-1, eutran-2, eutran-3, eutran-4, eutran-5, eutran-7, eutran-8,
| eutran-12, eutran-13, eutran-20, eutran-25, eutran-41
| current: utran-1, utran-3, utran-4, utran-5, utran-8, utran-2,
| eutran-1, eutran-2, eutran-3, eutran-4, eutran-5, eutran-7, eutran-8,
| eutran-12, eutran-13, eutran-20, eutran-25, eutran-41
--------------------------------
IP | supported: ipv4, ipv6, ipv4v6
--------------------------------
3GPP | imei: 123456789987654
| operator id: 123456
| operator name: HOME
| registration: home
--------------------------------
3GPP EPS | ue mode of operation: csps-2
--------------------------------
SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0
There are different sections. The status section tells us about the state of the modem and the SIM inserted into it.
SIM Lock
As it can be seen in the status section, the SIM lock is enabled and locked.
SIM index can be found in the detailed information above, i.e. /org/freedesktop/ModemManager1/SIM/0. Here 0 is the index of SIM to be used in commands to refer to it.
1234 is an example, use the unique PIN number for your SIM card.
# mmcli -i 0 --pin=1234
successfully sent PIN code to the SIM
All other PIN-related commands can be seen in mmcli Man-page. You can, for instance, disable the SIM lock using the --disable-pin argument.
Add Cellular Connection
NetworkManager is configured with ModemManager support so that NetworkManager can automatically bring up the cellular connection whenever ModemManager reports registration of modem. The following command can be executed to add a cellular connection:
In the command below, use the APN that corresponds to your cellular carrier, because wap.tracfone is just an example and most likely yours will be different.
# nmcli c add type gsm ifname * con-name home apn wap.tracfone
ifname option is usually a serial port with pattern tty* or a cdc-wdm* device, not a networking interface. It is the primary port in the output of mmcli -m 0. * is used to use any modem device detected by ModemManager.
Enable the radio switch for mobile broadband(wwan):
# nmcli r wwan on
Connections managed by NetworkManager can be viewed by executing:
# nmcli c
NAME UUID TYPE DEVICE
home 72b3c630-265c-4357-8f1f-bb620d4adf14 gsm cdc-wdm1
network0 958cc5e3-1bbf-3d64-beeb-020d4414e256 ethernet --
network1 78c31df4-8c89-31a6-9aeb-d5603e230e42 ethernet --
As it can be seen that home is in the list with device name cdc-wdm1(primary port).
Connect to Modem
After enabling the modem, you can connect to the cellular network:
In the command below, use the APN that corresponds to your cellular carrier, because wap.tracfone is just an example and most likely yours will be different.
# mmcli -m 0 --simple-connect="apn=wap.tracfone"
successfully connected the modem
A bearer object is created and can be seen at the bottom of output from mmcli -m 0:
Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0
Information related to this bearer can be gotten by:
# mmcli -b 0
--------------------------------
General | dbus path: /org/freedesktop/ModemManager1/Bearer/0
| type: default
--------------------------------
Status | connected: yes
| suspended: no
| interface: wwan1
| ip timeout: 20
--------------------------------
Properties | apn: wap.tracfone
| roaming: allowed
| ip type: ipv4v6
--------------------------------
IPv4 configuration | method: static
| address: 33.214.211.245
| prefix: 30
| gateway: 33.214.211.246
| dns: 10.177.0.34, 10.177.0.210
| mtu: 1500
--------------------------------
IPv6 configuration | method: static
| address: 2607:fb90:1c36:692c:c915:a30b:a0ec:18bb
| prefix: 64
| gateway: 2607:fb90:1c36:692c:d899:5368:2142:b474
| dns: fd00:976a::9, fd00:976a::10
| mtu: 1500
--------------------------------
Statistics | duration: 29
| bytes rx: 584
| bytes tx: 804
As it can be seen that cellular connection has been established. We had already configured NetworkManager to create routes for the new network interface.
It can be verified by looking at the output of ifconfig (NetworkManager auto-connect on next modem registration onward):
# ifconfig
docker0 Link encap:Ethernet HWaddr 02:42:0d:00:2d:d1
inet addr:172.17.0.1 Bcast:172.17.255.255 Mask:255.255.0.0
UP BROADCAST MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
ethernet0 Link encap:Ethernet HWaddr 00:14:2d:a0:d5:9f
UP BROADCAST MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:80 errors:0 dropped:0 overruns:0 frame:0
TX packets:80 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:6128 (5.9 KiB) TX bytes:6128 (5.9 KiB)
wwan1 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
inet addr:33.214.211.245 P-t-P:33.214.211.245 Mask:255.255.255.252
inet6 addr: 2607:fb90:1778:8ea3:f8a3:e514:87f5:5971/64 Scope:Global
UP POINTOPOINT RUNNING NOARP MULTICAST MTU:1500 Metric:1
RX packets:18 errors:0 dropped:0 overruns:0 frame:0
TX packets:47 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:1826 (1.7 KiB) TX bytes:3494 (3.4 KiB)
Set Cellular Connection Retries
On intermittent connectivity scenarios, ModemManager tries to reconnect to the cellular carrier after a connection is lost.
The default number of retries is four, thus you are encouraged to set it to zero (infinite retries):
# nmcli connection modify <connection-name> connection.autoconnect-retries 0
Set Remote Updates Timeout
On low-bandwidth cellular connections, Torizon Remote Updates timeouts may need to be tweaked so the updates work reliably.
To achieve it, you must configure timeouts to be compatible with your use case, as explained on Configuring Options for Low-Bandwidth Connections.
GPS
ModemManager has also support for discovering locations using Global Positioning System (GPS) or directly from mobile network infrastructure.
To check GPS-specific location capabilities:
# mmcli -m 0 --location-status
--------------------------------
Location | capabilities: 3gpp-lac-ci, gps-raw, gps-nmea, agps
| enabled: 3gpp-lac-ci
| signals: no
--------------------------------
GPS | refresh rate: 30 seconds
| supported assistance: xtra
| assistance servers: http://xtrapath1.izatcloud.net/xtra3grc.bin
| http://xtrapath2.izatcloud.net/xtra3grc.bin
| http://xtrapath3.izatcloud.net/xtra3grc.bin
capabilities determines what location sources modem supports and can be enabled. To enable any of the listed capabilities:
# sudo mmcli -m 0 \
> --location-enable-gps-raw \
> --location-enable-gps-nmea
Password:
successfully setup location gathering
To get the location (dummy data is shown):
# mmcli -m 0 --location-get
--------------------------
3GPP | operator code: 111
| operator name: 222
| location area code: FFFF
| tracking area code: A1F9
| cell id: 005B2E0C
--------------------------
GPS | nmea: $GPGSA,A,2,,,,,,,,,,,,,,,*1E
| $GPRMC,,V,,,,,,,,,,N*55
| $GPGSV,4,1,16,03,00,288,,04,07,319,,05,,,,08,20,274,*4C
| $GPGSV,4,2,16,11,04,333,,12,,,,13,26,056,,13,13,234,*42
| $GPGSV,4,3,16,15,65,260,,16,,,,17,,,,18,63,067,*72
| $GPGSV,4,4,16,20,18,100,,21,49,296,,22,32,200,,24,50,078,*7B
| $GPVTG,,T,,M,,N,,K,N*2C
| $GPGGA,,,,,,0,,,,,,,,*66