ModemManager is a DBus-powered Linux daemon which provides a unified high level API for communicating with (mobile broadband) modems. It acts as a standard RIL (Radio Interface Layer) and may be
used by different connection managers, like NetworkManager. Thanks to the built-in plugin architecture, ModemManager talks to very different kinds of modems with very different kinds of ports. In
addition to the standard AT serial ports, Qualcomm-based QCDM and QMI ports are also supported.
Show summary of options by group.
Show all groups and options.
Show manager specific options.
Show common options. These are used for defining the device an option operates on. For example, modems, bearers, SIMs, SMS', etc.
Show modem specific options.
Show 3GPP specific options.
Show CDMA specific options.
Show simple options. These are useful for getting connected or disconnected and understanding the state of things as fast as possible without worrying so much about the details.
Show location or positioning specific options.
Show messaging specific options. See also --help-sms which is related.
Show time specific options.
Show firmware specific options.
Show OMA specific options.
Show SIM card specific options.
Show bearer specific options.
List available modems and monitor modems added or removed.
Scan for any potential new modems. This is only useful when expecting pure RS232 modems, as they are not notified automatically by the kernel.
All options below take a PATH or INDEX argument. If no action is provided, the default information about the modem, bearer, etc. is shown instead.
The PATH and INDEX are created automatically when the modem is plugged in. They can be found using mmcli -L. This produces something like (for modems only):
Found 1 modems:
In this case, the INDEX is 4 and the PATH is the entire string above.
However, for the bearers, SIMs and SMS cases, the PATH is slightly different. The Modem is replaced with the object name in use, like Bearer. For example:
Specify a modem.
Specify a bearer.
Specify a SIM card.
Specify an SMS.
All of the modem options below make use of the --modem or -m switch to specify the modem to act on.
Some operations require a MODE. MODE can be any combination of the modes actually supported by the modem. In the perfect case, the following are possible:
'2G' - 2G technologies, e.g. EDGE, CDMA1x
'3G' - 3G technologies, e.g. HSPA, EV-DO
'4G' - 4G technologies, e.g. LTE
'ANY' - for all supported modes.
Monitor the state of a given modem.
Enable a given modem.
This powers the antenna, starts the automatic registration process and in general prepares the modem to be connected.
Disable a given modem.
List packet data bearers that are available for the given modem.
Create a new packet data bearer for a given modem. The KEYs and some VALUEs are listed below:
'apn' Access Point Name. Required in 3GPP.
Addressing type. Given as a MMBearerIpFamily value (e.g. 'ipv4', 'ipv6', 'ipv4v6'). Optional in 3GPP and CDMA.
Authentication method to use. Given as a MMBearerAllowedAuth value (e.g. 'none|pap|chap|mschap|mschapv2|eap'). Optional in 3GPP.
'user' User name (if any) required by the network. Optional in 3GPP.
Password (if any) required by the network. Optional in 3GPP.
Flag to tell whether connection is allowed during roaming, given as a boolean value (i.e 'yes' or 'no'). Optional in 3GPP.
Protocol of the Rm interface, given as a MMModemCdmaRmProtocol value (e.g. 'async', 'packet-relay', 'packet-network-ppp', 'packet-network-slip', 'stu-iii'). Optional in CDMA.
Telephone number to dial. Required in POTS.
Delete bearer from a given modem. This option explicitly uses a PATH to define the bearer, you can not use an INDEX to be deleted.
Set allowed modes for a given modem. For possible modes, see the beginning of this section.
Set bands to be used for a given modem. These are frequency ranges the modem should use. There are quite a number of supported bands and listing them all here would be quite extensive. For
details, see the MMModemBand documentation.
An example would be: 'egsm|dcs|pcs|g850' to select all the GSM frequency bands.
Set the preferred MODE for the given modem. The MODE MUST be one of the allowed modes as set with the --set-allowed-modes option. Possible MODE arguments are detailed at the beginning of this
The 3rd Generation Partnership Project (3GPP) is a collaboration between groups of telecommunications associations. These options pertain to devices which support 3GPP.
Included are options to control USSD (Unstructured Supplementary Service Data) sessions.
All of the 3GPP options below make use of the --modem or -m switch to specify the modem to act on.
Request the given modem to initiate a USSD session with COMMAND.
For example, COMMAND could be '*101#' to give your current pre-pay balance.
When initiating an USSD session, a RESPONSE may be needed by a network-originated request. This option allows for that.
Cancel an ongoing USSD session for a given modem.
All CDMA (Code Division Multiple Access) options require the --modem or -m option.
Activate the given modem using OTA (Over the Air) settings. The CARRIER is a code provided by the network for the default settings they provide.
All simple options must be used with --modem or -m.
Run a full connection sequence using KEY / VALUE pairs. You can use the --create-bearer options, plus any of the following ones:
'pin' SIM-PIN unlock code.
ETSI MCC-MNC of a network to force registration.
Disconnect ALL connected bearers for a given modem.
Display the status of the given modem.
These options detail how to discover your location using Global Positioning System (GPS) or directly from your mobile network infrastructure (either 3GPP or 3GPP2).
All location options must be used with --modem or -m.
Show the current status for discovering our location.
Show all location information available.
Enable location discovery using the 3GPP network.
Disable location discovery using the 3GPP network.
Disable location discovery using GPS and raw values.
Show GPS based location information with raw values (e.g. latitude, longitude).
Enable location discovery using the 3GPP2 network.
Disable location discovery using the 3GPP2 network.
Show 3GPP2 based location information (location of the CDMA base station).
Enable location discovery using GPS but without taking control of the NMEA tty port.
Disable location discovery using GPS and unmanaged port.
All messaging options must be used with --modem or -m.
Show the status of the messaging support.
List SMS messages available on a given modem.
Create a new SMS on a given modem. KEYs can be any of the following:
Number to which the message is addressed.
'text' Message text, in UTF-8. When sending, if the text is larger than the limit of the technology or modem, the message will be broken into multiple parts or messages. Note that text and
data are never given at the same time.
'smsc' Indicates the SMS service center number.
Specifies when the SMS expires in the SMSC.
3GPP message class (0..3).
Specifies whether delivery report is requested when sending the SMS ('yes' or 'no')
Specifies the storage where this message is kept. Storages may be 'sm', 'me', 'mt', 'sr', 'bm', 'ta'.
List all the firmware images installed on a given modem.
Select a firmware image from those installed on a given modem. A list of available firmware images can be seen using the --firmware-list option.
The ID provided is a UNIQUE identifier for the firmware.
All OMA options require the --modem or -m option.
Show the status of the OMA device management subsystem.
Request to start a client initiated session.
The given session type must be one of:
Request to accept a network initiated session.
Request to reject a network initiated session.
Request to cancel current OMA session, if any.
Send PIN code to a given SIM card.
Send PUK code to a given SIM card. This must be used WITH --pin.
Enable PIN request for a given SIM card. This must be used WITH --pin.
Disable PIN request for a given SIM card. This must be used WITH --pin.
Change the PIN for a given SIM card. It will be set to PIN. This must be used WITH --pin to supply the old PIN number.
All bearer options require the --bearer or -b option.
This option states which STORAGE to use for SMS messages. Possible values for STORAGE include:
'sm' SIM card storage area.
'me' Mobile equipment storage area.
'mt' Sum of SIM and Mobile equipment storages
'sr' Status report message storage area.
'bm' Broadcast message storage area.
'ta' Terminal adaptor message storage area.
This option takes an SMS that has DATA (not TEXT) and will create a local file described by PATH and store the content of the SMS there.
Perform actions with more details reported and/or logged.
Returns the version of this program.
Use asynchronous methods. This is purely a development tool and has no practical benefit to most user operations.
Use SECONDS for the timeout when performing operations with this command. This option is useful when executing long running operations, like --3gpp-scan.
Send the PIN to the SIM card
You'll need first to know which the proper path/index is for the SIM in your modem:
$ mmcli -m 0 | grep SIM
SIM | path: '/org/freedesktop/ModemManager1/SIM/0'
And after that, you can just use the SIM index:
$ mmcli -i 0 --pin=1234
successfully sent PIN code to the SIM
Simple connect and disconnect
You can launch the simple connection process like:
$ mmcli -m 0 --simple-connect="pin=1234,apn=internet"
successfully connected the modem
Then, you can disconnect it like:
$ mmcli -m 0 --simple-disconnect
successfully disconnected all bearers in the modem
3GPP network scan
Scanning for 3GPP networks may really take a long time, so a specific timeout must be given:
$ sudo mmcli -s 21 --store-in-storage="sm"
successfully stored the SMS
$ sudo mmcli -s 21
Content | number: '+1234567890'
| text: 'Hello world'
Properties | PDU type: 'submit'
| state: 'stored'
| smsc: 'unknown'
| validity: '0'
| class: '0'
| storage: 'sm'
| delivery report: 'not requested'
| message reference: '0'
$ sudo mmcli -m 0 --messaging-status
Messaging | supported storages: 'sm, me'
| default storage: 'me'
Sending SMS messages from files
As you can see below, the important part is the --messaging-create-sms-with-data and the PATH provided.
$ sudo mmcli -m 0 \
Successfully created new SMS:
$ sudo mmcli -s 22 --send
successfully sent the SMS
Listing SMS messages
When the receiver gets all the parts of the message, they can now recover the sent file with another mmcli command in their ModemManager setup:
$> sudo mmcli -m 0 --messaging-list-sms
Found 1 SMS messages:
$> sudo mmcli -s 0 --create-file-with-data=/path/to/the/output/file
GPS location status
You first need to check whether the modem has GPS-specific location capabilities. Note that we’ll assume the modem is exposed as index 0; if you have more than one modem, just use --list-modems to
check the proper modem index:
$ mmcli -m 0 --location-status
| enabled: '3gpp-lac-ci'
| signals: 'no'
GPS location technology enabling
We can enable the RAW and NMEA GPS location sources using:
$ sudo mmcli -m 0 \
successfully setup location gathering
If we do check again the status, we’ll see the GPS-specific locations are enabled:
$ mmcli -m 0 --location-status
Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
| enabled: '3gpp-lac-ci, gps-raw, gps-nmea'
| signals: 'no'
GPS location retrieval
You can query location source specific information with --location-get-3gpp, --location-get-gps-nmea and --location-get-gps-raw; but also for all at the same time:
$ sudo mmcli -m 0 --location-get
3GPP location | Mobile country code: '214'
| Mobile network code: '3'
| Location area code: '21071'
| Cell ID: '7033737'
GPS NMEA traces | $GPGGA,,,,,,0,,,,,,,,*66
Raw GPS | Not available
CDMA BS | Not available
An example of RAW GPS location information:
$ sudo mmcli -m 0 --location-get-gps-raw
Raw GPS | UTC time: '155142.2'
| Longitude: '-3.513941'
| Latitude: '40.502603'
GNU October 2012 mmcli(8)
Man(1) output converted with