.TH mmcli 8 "October 2012" GNU "User Commands"

.SH NAME
mmcli \- Control and monitor the ModemManager

.SH SYNOPSIS
\fBmmcli\fR [\fIOPTION\fR...]

.SH DESCRIPTION
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.

.SH HELP OPTIONS
.TP
.B \-h, \-\-help
Show summary of options by group.
.TP
.B \-\-help\-all
Show all groups and options.
.TP
.B \-\-help\-manager
Show manager specific options.
.TP
.B \-\-help\-common
Show common options. These are used for defining the device an option
operates on. For example, modems, bearers, SIMs, SMS', etc.
.TP
.B \-\-help\-modem
Show modem specific options.
.TP
.B \-\-help\-3gpp
Show 3GPP specific options.
.TP
.B \-\-help\-cdma
Show CDMA specific options.
.TP
.B \-\-help\-simple
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.
.TP
.B \-\-help\-location
Show location or positioning specific options.
.TP
.B \-\-help\-messaging
Show messaging specific options. See also \fB\-\-help\-sms\fR which
.B \-\-help\-bearer
Show bearer specific options.
.TP
.B \-\-help\-sms
Show SMS specific options. See also \fB\-\-help\-messaging\fR which
is related.

.SH MANAGER OPTIONS
.TP
.B \-G, \-\-set\-logging=[ERR|WARN|INFO|DEBUG]
Set the logging level in ModemManager daemon. For debugging information you can supply \fBDEBUG\fR. Each value above \fBDEBUG\fR provides less detail. In most cases \fBERR\fR (for displaying errors) are the important messages.

The default mode is \fBERR\fR.
.TP
.B \-L, \-\-list\-modems
List available modems.
.TP
.B \-M, \-\-monitor\-modems
List available modems and monitor modems added or removed.
.TP
.B \-S, \-\-scan-modems
Scan for any potential new modems. This is only useful when expecting pure
RS232 modems, as they are not notified automatically by the kernel.

.SH COMMON OPTIONS
All options below take a \fBPATH\fR or \fBINDEX\fR argument. If no action is
provided, the default information about the modem, bearer, etc. is
shown instead.

The \fBPATH\fR and \fBINDEX\fR are created automatically when the
modem is plugged in. They can be found using \fBmmcli \-L\fR. This
produces something like (for modems only):

.RS 7
Found 1 modems:
/org/freedesktop/ModemManager1/Modem/\fB4\fR
.RE

In this case, the \fBINDEX\fR is \fB4\fR and the \fBPATH\fR is the entire string above.

However, for the bearers, SIMs and SMS cases, the \fBPATH\fR is
slightly different. The \fIModem\fR is replaced with the object name
in use, like \fIBearer\fR. For example:

.RS 7
/org/freedesktop/ModemManager1/\fIBearer\fR/4
.RE

.TP
.B \-m, \-\-modem=[PATH|INDEX]
Specify a modem.
.TP
combination of the modes actually supported by the modem. In the
perfect case, the following are possible:

.Bd -literal -compact
\fB'2G'\fR - 2G technologies, e.g. EDGE, CDMA1x
\fB'3G'\fR - 3G technologies, e.g. HSPA, EV-DO
\fB'4G'\fR - 4G technologies, e.g. LTE
\fB'ANY'\fR - for all supported modes.
.Ed
.TP
.B \-w, \-\-monitor\-state
Monitor the state of a given modem.
.TP
.B \-e, \-\-enable
Enable a given modem.

This powers the antenna, starts the automatic registration process and
in general prepares the modem to be connected.
.TP
.B \-d, \-\-disable
Disable a given modem.

This disconnects the existing connection(s) for the modem and puts it
into a low power mode.
.TP
.B \-r, \-\-reset
Resets the modem to the settings it had when it was power cycled.
.TP
.B \-\-factory\-reset=CODE
Resets the modem to its original factory default settings.

The \fBCODE\fR provided is vendor specific. Without the correct vendor
code, it's unlikely this operation will succeed. This is not a common
user action.
.TP
.B \-\-command=COMMAND
Send an AT \fBCOMMAND\fR to the given modem. For example,
\fBCOMMAND\fR could be 'AT+GMM' to probe for phone model information. This
operation is only available when ModemManager is run in debug mode.
.TP
.B \-\-list\-bearers
List packet data bearers that are available for the given modem.
.TP
.B \-\-create\-bearer=['KEY1=VALUE1,KEY2=VALUE2,...']
Create a new packet data bearer for a given modem. The \fBKEY\fRs and
some \fBVALUE\fRs are listed below:
.RS 9
.TP
\fB'apn'\fR
Access Point Name. Required in 3GPP.
.TP
\fB'ip-type'\fR
\fB'rm-protocol'\fR
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.
.TP
\fB'number'\fR
Telephone number to dial. Required in POTS.
.RE
.TP
.B \-\-delete\-bearer=PATH
Delete bearer from a given modem. This option explicitly uses a
\fBPATH\fR to define the bearer, you can not use an \fBINDEX\fR to be
deleted.
.TP
.B \-\-set\-allowed\-modes=[MODE1|MODE2|...]
Set allowed modes for a given modem. For possible modes, see the
beginning of this section.
.TP
.B \-\-set\-bands=[BAND1|BAND2|...]
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.
.TP
.B \-\-set\-preferred\-mode=MODE
Set the preferred \fBMODE\fR for the given modem. The \fBMODE\fR
\fIMUST\fR be one of the allowed modes as set with the
\fB\-\-set\-allowed\-modes\fR option. Possible \fBMODE\fR arguments
are detailed at the beginning of this section.

.SH 3GPP OPTIONS
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 \fB\-\-modem\fR or
\fB\-m\fR switch to specify the modem to act on.
.TP
.B \-\-3gpp\-scan
Scan for available 3GPP networks.
.TP
.B \-\-3gpp\-register\-home
Request a given modem to register in its home network.

This registers with the default network(s) specified by the modem,
.TP
.B \-\-3gpp\-register\-in\-operator=MCCMNC
Request a given modem to register on the network of the given
.B \-\-3gpp\-ussd\-respond=RESPONSE
When initiating an USSD session, a \fRRESPONSE\fR may be needed by a
network-originated request. This option allows for that.
.TP
.B \-\-3gpp\-ussd\-cancel
Cancel an ongoing USSD session for a given modem.

.SH CDMA OPTIONS
All CDMA (Code Division Multiple Access) options require the
\fB\-\-modem\fR or \fB\-m\fR option.

.TP
.B \-\-cdma\-activate=CARRIER
Activate the given modem using OTA (Over the Air) settings. The
\fBCARRIER\fR is a code provided by the network for the default
settings they provide.

.SH SIMPLE OPTIONS
All simple options must be used with \fB\-\-modem\fR or \fB\-m\fR.

.TP
.B \-\-simple\-connect=['KEY1=VALUE1,KEY2=VALUE2,...']
Run a full connection sequence using \fBKEY\fR / \fBVALUE\fR pairs.
You can use the \fB\-\-create\-bearer\fR options, plus any of the
following ones:
.RS 9
.TP
\fB'pin'\fR
SIM-PIN unlock code.
.TP
\fB'operator-id'\fR
ETSI MCC-MNC of a network to force registration.
.RE
.TP
.B \-\-simple\-disconnect
Disconnect \fIALL\fR connected bearers for a given modem.
.TP
.B \-\-simple\-status
Display the status of the given modem.

.SH LOCATION OPTIONS
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 \fB\-\-modem\fR or \fB\-m\fR.

.TP
.B \-\-location\-status
Show the current status for discovering our location.
.TP
.B \-\-location\-get
.B \-\-location\-disable\-gps\-nmea
Disable location discovery using GPS and NMEA traces.
.TP
.B \-\-location\-get\-gps\-nmea
Show GPS based location with NMEA trace information.
.TP
.B \-\-location\-enable\-gps\-raw
Enable location discovery using GPS and reported with raw (i.e.
longitude/latitude) values.
.TP
.B \-\-location\-disable\-gps\-raw
Disable location discovery using GPS and raw values.
.TP
.B \-\-location\-get\-gps\-raw
Show GPS based location information with raw values (e.g. latitude, longitude).
.TP
.B \-\-location\-enable\-cdma-bs
Enable location discovery using the 3GPP2 network.
.TP
.B \-\-location\-disable\-cdma-bs
Disable location discovery using the 3GPP2 network.
.TP
.B \-\-location\-get\-cdma-bs
Show 3GPP2 based location information (location of the CDMA base station).

.SH MESSAGING OPTIONS
All messaging options must be used with \fB\-\-modem\fR or \fB\-m\fR.

.TP
.B \-\-messaging\-status
Show the status of the messaging support.
.TP
.B \-\-messaging\-list-sms
List SMS messages available on a given modem.
.TP
.B \-\-messaging\-create-sms=['KEY1=VALUE1,...']
Create a new SMS on a given modem. \fBKEY\fRs can be any of the following:
.RS 9
.TP
\fB'number'\fR
Number to which the message is addressed.
.TP
\fB'text'\fR
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.
.TP
\fB'smsc'\fR
Indicates the SMS service center number.
.TP
\fB'validity'\fR
.B \-\-messaging\-create-sms-with-data=PATH
Use \fBPATH\fR to a filename as the data to create a new SMS.
.TP
.B \-\-messaging\-delete-sms=PATH
Delete an SMS from a given modem. \fBPATH\fR indicates the SMS path.

.SH TIME OPTIONS
All time operations require the \fB\-\-modem\fR or \fB\-m\fR option.

.TP
.B \-\-time
Display the current network time from the operator. This includes the
timezone which is usually of importance.

.SH FIRMWARE OPTIONS
All firmware options require the \fB\-\-modem\fR or \fB\-m\fR option.

.TP
.B \-\-firmware\-list
List all the firmware images installed on a given modem.
.TP
.B \-\-firmware\-select=ID
Select a firmware image from those installed on a given modem. A list
of available firmware images can be seen using the
\fB\-\-firmware\-list\fR option.

The \fBID\fR provided is a \fIUNIQUE\fR identifier for the firmware.

.SH OMA OPTIONS
All OMA options require the \fB\-\-modem\fR or \fB\-m\fR option.

.TP
.B \-\-oma\-status
Show the status of the OMA device management subsystem.
.TP
.B \-\-oma\-start\-client\-initiated\-session=[SESSION TYPE]
Request to start a client initiated session.

The given session type must be one of:
'client\-initiated\-device\-configure'
'client\-initiated\-prl\-update'
'client\-initiated\-hands\-free\-activation'
.TP
.B \-\-oma\-accept\-network\-initiated\-session=[SESSION ID]
Request to accept a network initiated session.
.TP
.B \-\-oma\-reject\-network\-initiated\-session=[SESSION ID]
Request to reject a network initiated session.
.TP
.B \-\-oma\-cancel\-session
Request to cancel current OMA session, if any.

Disable PIN request for a given SIM card. This must be used \fIWITH\fR
\fB\-\-pin\fR.
.TP
.B \-\-change\-pin=PIN
Change the PIN for a given SIM card. It will be set to \fBPIN\fR. This
must be used \fIWITH\fR \fB\-\-pin\fR to supply the old PIN number.

.SH BEARER OPTIONS
All bearer options require the \fB\-\-bearer\fR or \fB\-b\fR option.

.TP
.B \-c, \-\-connect
Connect to a given bearer.
.TP
.B \-x, \-\-disconnect
Disconnect from a given bearer.

.SH SMS OPTIONS
All SMS options require the \fB\-\-sms\fR or \fB\-s\fR option.

.TP
.B \-\-send
Send an SMS.
.TP
.B \-\-store
This option will store the SMS in the default storage defined by the
modem, which may be either modem-memory or SMS-memory. To know what
the existing default storage is, see the \fB\-\-messaging\-status\fR
option.

.TP
.B \-\-store\-in\-storage=STORAGE
This option states which \fBSTORAGE\fR to use for SMS messages.
Possible values for \fBSTORAGE\fR include:
.RS 9
.TP
\fB'sm'\fR
SIM card storage area.
.TP
\fB'me'\fR
Mobile equipment storage area.
.TP
\fB'mt'\fR
Sum of SIM and Mobile equipment storages
.TP
\fB'sr'\fR
Status report message storage area.
.TP
\fB'bm'\fR
Broadcast message storage area.
.TP
\fB'ta'\fR
Returns the version of this program.
.TP
.B \-a, \-\-async
Use asynchronous methods. This is purely a development tool and has no
practical benefit to most user operations.
.TP
.B \-\-timeout=SECONDS
Use \fBSECONDS\fR for the timeout when performing operations with this
command. This option is useful when executing long running operations, like
\-\-3gpp\-scan.

.SH EXAMPLES
.SS 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:
.Bd -literal -compact
$ mmcli -m 0 | grep SIM
SIM | path: '/org/freedesktop/ModemManager1/SIM/0'
.Ed

And after that, you can just use the SIM index:
.Bd -literal -compact
$ mmcli -i 0 --pin=1234
successfully sent PIN code to the SIM
.Ed

.SS Simple connect and disconnect

You can launch the simple connection process like:
.Bd -literal -compact
$ mmcli -m 0 --simple-connect="pin=1234,apn=internet"
successfully connected the modem
.Ed

Then, you can disconnect it like:
.Bd -literal -compact
$ mmcli -m 0 --simple-disconnect
successfully disconnected all bearers in the modem
.Ed

.SS 3GPP network scan

Scanning for 3GPP networks may really take a long time, so a specific timeout
must be given:
.Bd -literal -compact
$ mmcli -m 0 --3gpp-scan --timeout=300

Found 4 networks:
21404 - Yoigo (umts, available)
21407 - Movistar (umts, current)
21401 - vodafone ES (umts, forbidden)

$ sudo mmcli -m 0 --messaging-status
/org/freedesktop/ModemManager1/Modem/0
----------------------------
Messaging | supported storages: 'sm, me'
| default storage: 'me'
.Ed

.SS Sending SMS messages from files

As you can see below, the important part is the
\fB\-\-messaging\-create\-sms\-with\-data\fR and the \fBPATH\fR provided.

.Bd -literal -compact
$ sudo mmcli -m 0 \\
--messaging-create-sms="number='+1234567890'" \\
--messaging-create-sms-with-data=/path/to/your/file
Successfully created new SMS:
/org/freedesktop/ModemManager1/SMS/22 (unknown)

$ sudo mmcli -s 22 --send
successfully sent the SMS
.Ed

.SS Listing SMS messages

When the receiver gets all the parts of the message, they can now
recover the sent file with another \fBmmcli\fR command in their
ModemManager setup:

.Bd -literal -compact
$> sudo mmcli -m 0 --messaging-list-sms
Found 1 SMS messages:
/org/freedesktop/ModemManager1/SMS/0 (received)

$> sudo mmcli -s 0 --create-file-with-data=/path/to/the/output/file
.Ed
| signals: 'no'
.Ed

The output says that the modem supports 3GPP Location area code/Cell
ID, GPS raw and GPS-NMEA location sources. None is enabled yet, as we
didn’t enable the modem, which we can do issuing:

.Bd -literal -compact
$ sudo mmcli -m 0 --enable
successfully enabled the modem

$ mmcli -m 0 --location-status
/org/freedesktop/ModemManager1/Modem/0
----------------------------
Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
| enabled: '3gpp-lac-ci'
| signals: 'no'
.Ed

.SS GPS location technology enabling

We can enable the RAW and NMEA GPS location sources using:

.Bd -literal -compact
$ sudo mmcli -m 0 \\
--location-enable-gps-raw \\
--location-enable-gps-nmea
successfully setup location gathering
.Ed

If we do check again the status, we’ll see the GPS-specific locations are enabled:

.Bd -literal -compact
$ mmcli -m 0 --location-status
/org/freedesktop/ModemManager1/Modem/0
----------------------------
Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
| enabled: '3gpp-lac-ci, gps-raw, gps-nmea'
| signals: 'no'
.Ed

.SS GPS location retrieval

You can query location source specific information with
\fB\-\-location\-get\-3gpp\fR, \fB\-\-location\-get\-gps\-nmea\fR and
\fB\-\-location\-get\-gps\-raw\fR; but also for all at the same time:

.Bd -literal -compact
$ sudo mmcli -m 0 --location-get
/org/freedesktop/ModemManager1/Modem/0
-------------------------
3GPP location | Mobile country code: '214'
-------------------------
CDMA BS | Not available
.Ed

An example of RAW GPS location information:

.Bd -literal -compact
$ sudo mmcli -m 0 --location-get-gps-raw
/org/freedesktop/ModemManager1/Modem/0
-------------------------
Raw GPS | UTC time: '155142.2'
| Longitude: '-3.513941'
| Latitude: '40.502603'
| Altitude: '18.000000'
.Ed

.SH AUTHOR
Martyn Russell <martyn@lanedo.com>

.SH SEE ALSO
\fBModemManager\fR(8), \fBNetworkManager\fR(8)

AT (http://en.wikipedia.org/wiki/AT_commands).

3GPP (http://en.wikipedia.org/wiki/3GPP).

MCCMNC (http://en.wikipedia.org/wiki/Mobile_Network_Code).

USSD (http://en.wikipedia.org/wiki/Unstructured_Supplementary_Service_Data).

CDMA (http://en.wikipedia.org/wiki/Code_division_multiple_access).

OTA (http://en.wikipedia.org/wiki/Over-the-air_programming).

GPS (http://en.wikipedia.org/wiki/Global_Positioning_System)

NMEA (http://en.wikipedia.org/wiki/NMEA_0183)

Man(1) output converted with man2html