Provided by: modemmanager_1.6.8-2ubuntu1_amd64 bug


       mmcli - Control and monitor the ModemManager


       mmcli [OPTION...]


       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.


       -h, --help
              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.

              Show SMS specific options. See also --help-messaging which is related.


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

              The default mode is ERR.

       -L, --list-modems
              List available modems.

       -M, --monitor-modems
              List available modems and monitor modems added or removed.

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


       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:


       -m, --modem=[PATH|INDEX]
              Specify a modem.

       -b, --bearer=[PATH|INDEX]
              Specify a bearer.

       -i, --sim=[PATH|INDEX]
              Specify a SIM card.

       -s, --sms=[PATH|INDEX]
              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.

       -w, --monitor-state
              Monitor the state of a given modem.

       -e, --enable
              Enable a given modem.

              This  powers  the antenna, starts the automatic registration process and in general
              prepares the modem to be connected.

       -d, --disable
              Disable a given modem.

              This disconnects the existing connection(s) for the modem and puts it  into  a  low
              power mode.

       -r, --reset
              Resets the modem to the settings it had when it was power cycled.

              Resets the modem to its original factory default settings.

              The  CODE  provided  is  vendor  specific.  Without  the  correct vendor code, it's
              unlikely this operation will succeed. This is not a common user action.

              Send an AT COMMAND to the given modem. For example, COMMAND could  be  'AT+GMM'  to
              probe   for  phone  model  information.  This  operation  is  only  available  when
              ModemManager is run in debug mode.

              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

              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 section.


       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.

              Scan for available 3GPP networks.

              Request a given modem to register in its home network.

              This registers with the default network(s) specified by the modem,

              Request a given modem to register on  the  network  of  the  given  MCCMNC  (Mobile
              Country  Code,  Mobile Network Code) based operator. This code is used for GSM/LTE,
              CDMA, iDEN, TETRA and UMTS public land mobile networks and  some  satellite  mobile
              networks. The ITU-T Recommendation E.212 defines mobile country codes.

              Request the status of ANY ongoing USSD session.

              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.

              Show 3GPP based location information (MCC, MNC, LAC, CI).

              Enable location discovery using GPS and reported with NMEA traces.

              Disable location discovery using GPS and NMEA traces.

              Show GPS based location with NMEA trace information.

              Enable    location    discovery   using   GPS   and   reported   with   raw   (i.e.
              longitude/latitude) values.

              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

              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'.

              Use PATH to a filename as the data to create a new SMS.

              Delete an SMS from a given modem. PATH indicates the SMS path.


       All time operations require the --modem or -m option.

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


       All firmware options require the --modem or -m option.

              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.

       --oma-start-client-initiated-session=[SESSION TYPE]
              Request to start a client initiated session.

              The given session type must be one of:

       --oma-accept-network-initiated-session=[SESSION ID]
              Request to accept a network initiated session.

       --oma-reject-network-initiated-session=[SESSION ID]
              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.

       -c, --connect
              Connect to a given bearer.

       -x, --disconnect
              Disconnect from a given bearer.


       All SMS options require the --sms or -s option.

       --send Send an SMS.

              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 --messaging-status 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.


       -v, --verbose
              Perform actions with more details reported and/or logged.

       -V, --version
              Returns the version of this program.

       -a, --async
              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
           $ mmcli -m 0 --3gpp-scan --timeout=300

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

   Creating a new SMS message & storing it
       Using the “sm” (SIM), you can do this using:

           $ mmcli -m 0 --messaging-create-sms="text='Hello world',number='+1234567890'"
           Successfully created new SMS:
               /org/freedesktop/ModemManager1/SMS/21 (unknown)

           $ sudo mmcli -s 21 --store-in-storage="sm"
           successfully stored the SMS

           $ sudo mmcli -s 21
           SMS '/org/freedesktop/ModemManager1/SMS/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 \
                  --messaging-create-sms="number='+1234567890'" \
           Successfully created new SMS:
               /org/freedesktop/ModemManager1/SMS/22 (unknown)

           $ 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:
               /org/freedesktop/ModemManager1/SMS/0 (received)

           $> 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
             Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
                      |      enabled: 'none'
                      |      signals: 'no'

       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

           $ sudo mmcli -m 0 --enable
           successfully enabled the modem

           $ mmcli -m 0 --location-status
             Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
                      |      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 \
                        --location-enable-gps-raw \
           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
                             | $GPRMC,,V,,,,,,,,,,N*53
                             | $GPGSA,A,1,,,,,,,,,,,,,,,*1E
                             | $GPGSV,4,1,16,24,,,,29,,,,05,,,,18,,,*7A
                             | $GPGSV,4,2,16,22,,,,14,,,,11,,,,17,,,*7B
                             | $GPGSV,4,3,16,03,,,,12,,,,30,,,,13,,,*78
                             | $GPGSV,4,4,16,23,,,,15,,,,27,,,,07,,,*79
                             | $GPVTG,,T,,M,,N,,K,N*2C
             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'
                             |  Altitude: '18.000000'


       Martyn Russell <>


       ModemManager(8), NetworkManager(8)

       AT (

       3GPP (

       MCCMNC (

       USSD (

       CDMA (

       OTA (

       GPS (

       NMEA (