1
2mmcli(8)                         User Commands                        mmcli(8)
3
4
5

NAME

7       mmcli - Control and monitor the ModemManager
8
9

SYNOPSIS

11       mmcli [OPTION...]
12
13

DESCRIPTION

15       ModemManager  is  a  DBus-powered Linux daemon which provides a unified
16       high level API for communicating with  (mobile  broadband)  modems.  It
17       acts  as a standard RIL (Radio Interface Layer) and may be used by dif‐
18       ferent connection managers, like NetworkManager. Thanks to the built-in
19       plugin  architecture,  ModemManager  talks  to  very different kinds of
20       modems with very different kinds of ports. In addition to the  standard
21       AT serial ports, Qualcomm-based QCDM and QMI ports are also supported.
22
23

HELP OPTIONS

25       -h, --help
26              Show summary of options by group.
27
28       --help-all
29              Show all groups and options.
30
31       --help-manager
32              Show manager specific options.
33
34       --help-common
35              Show  common  options. These are used for defining the device an
36              option operates on. For example, modems,  bearers,  SIMs,  SMS',
37              etc.
38
39       --help-modem
40              Show modem specific options.
41
42       --help-3gpp
43              Show 3GPP specific options.
44
45       --help-cdma
46              Show CDMA specific options.
47
48       --help-simple
49              Show  simple  options. These are useful for getting connected or
50              disconnected and understanding the state of things  as  fast  as
51              possible without worrying so much about the details.
52
53       --help-location
54              Show location or positioning specific options.
55
56       --help-messaging
57              Show  messaging  specific  options. See also --help-sms which is
58              related.
59
60       --help-time
61              Show time specific options.
62
63       --help-firmware
64              Show firmware specific options.
65
66       --help-oma
67              Show OMA specific options.
68
69       --help-sim
70              Show SIM card specific options.
71
72       --help-bearer
73              Show bearer specific options.
74
75       --help-sms
76              Show SMS specific options. See also  --help-messaging  which  is
77              related.
78
79

MANAGER OPTIONS

81       -G, --set-logging=[ERR|WARN|INFO|DEBUG]
82              Set  the  logging  level  in  ModemManager daemon. For debugging
83              information you can supply DEBUG. Each value  above  DEBUG  pro‐
84              vides less detail. In most cases ERR (for displaying errors) are
85              the important messages.
86
87              The default mode is ERR.
88
89       -L, --list-modems
90              List available modems.
91
92       -M, --monitor-modems
93              List available modems and monitor modems added or removed.
94
95       -S, --scan-modems
96              Scan for any potential new modems.  This  is  only  useful  when
97              expecting  pure RS232 modems, as they are not notified automati‐
98              cally by the kernel.
99
100

COMMON OPTIONS

102       All options below take a PATH or INDEX argument. If no action  is  pro‐
103       vided,  the  default information about the modem, bearer, etc. is shown
104       instead.
105
106       The PATH and INDEX are created automatically when the modem is  plugged
107       in. They can be found using mmcli -L. This produces something like (for
108       modems only):
109
110              Found 1 modems:
111                /org/freedesktop/ModemManager1/Modem/4
112
113       In this case, the INDEX is 4 and the PATH is the entire string above.
114
115       However, for the bearers, SIMs and SMS cases, the PATH is slightly dif‐
116       ferent. The Modem is replaced with the object name in use, like Bearer.
117       For example:
118
119              /org/freedesktop/ModemManager1/Bearer/4
120
121
122       -m, --modem=[PATH|INDEX]
123              Specify a modem.
124
125       -b, --bearer=[PATH|INDEX]
126              Specify a bearer.
127
128       -i, --sim=[PATH|INDEX]
129              Specify a SIM card.
130
131       -s, --sms=[PATH|INDEX]
132              Specify an SMS.
133
134

MODEM OPTIONS

136       All of the modem options below make use of the --modem or -m switch  to
137       specify the modem to act on.
138
139       Some  operations  require  a  MODE.  MODE can be any combination of the
140       modes actually supported by the modem. In the perfect case, the follow‐
141       ing are possible:
142
143         '2G'  - 2G technologies, e.g. EDGE, CDMA1x
144         '3G'  - 3G technologies, e.g. HSPA, EV-DO
145         '4G'  - 4G technologies, e.g. LTE
146         'ANY' - for all supported modes.
147
148       -w, --monitor-state
149              Monitor the state of a given modem.
150
151       -e, --enable
152              Enable a given modem.
153
154              This  powers  the  antenna,  starts  the  automatic registration
155              process and in general prepares the modem to be connected.
156
157       -d, --disable
158              Disable a given modem.
159
160              This disconnects the existing connection(s) for  the  modem  and
161              puts it into a low power mode.
162
163       -r, --reset
164              Resets  the  modem  to  the  settings  it  had when it was power
165              cycled.
166
167       --factory-reset=CODE
168              Resets the modem to its original factory default settings.
169
170              The CODE provided is vendor specific. Without the correct vendor
171              code,  it's  unlikely this operation will succeed. This is not a
172              common user action.
173
174       --command=COMMAND
175              Send an AT COMMAND to the  given  modem.  For  example,  COMMAND
176              could  be  'AT+GMM'  to  probe for phone model information. This
177              operation is only available when ModemManager is  run  in  debug
178              mode.
179
180       --list-bearers
181              List packet data bearers that are available for the given modem.
182
183       --create-bearer=['KEY1=VALUE1,KEY2=VALUE2,...']
184              Create  a new packet data bearer for a given modem. The KEYs and
185              some VALUEs are listed below:
186
187                'apn'  Access Point Name. Required in 3GPP.
188
189                'ip-type'
190                       Addressing type.  Given  as  a  MMBearerIpFamily  value
191                       (e.g.  'ipv4',  'ipv6', 'ipv4v6'). Optional in 3GPP and
192                       CDMA.
193
194                'allowed-auth'
195                       Authentication method to use. Given  as  a  MMBearerAl‐
196                       lowedAuth                  value                  (e.g.
197                       'none|pap|chap|mschap|mschapv2|eap'). Optional in 3GPP.
198
199                'user' User name (if any) required by the network. Optional in
200                       3GPP.
201
202                'password'
203                       Password  (if any) required by the network. Optional in
204                       3GPP.
205
206                'allow-roaming'
207                       Flag to tell whether connection is allowed during roam‐
208                       ing,  given  as  a  boolean  value (i.e 'yes' or 'no').
209                       Optional in 3GPP.
210
211                'rm-protocol'
212                       Protocol of the Rm interface, given as a MMModemCdmaRm‐
213                       Protocol  value (e.g. 'async', 'packet-relay', 'packet-
214                       network-ppp',    'packet-network-slip',     'stu-iii').
215                       Optional in CDMA.
216
217                'number'
218                       Telephone number to dial. Required in POTS.
219
220       --delete-bearer=PATH
221              Delete  bearer from a given modem. This option explicitly uses a
222              PATH to define the bearer, you  can  not  use  an  INDEX  to  be
223              deleted.
224
225       --set-allowed-modes=[MODE1|MODE2|...]
226              Set allowed modes for a given modem. For possible modes, see the
227              beginning of this section.
228
229       --set-bands=[BAND1|BAND2|...]
230              Set bands to be used for a  given  modem.  These  are  frequency
231              ranges  the  modem  should use. There are quite a number of sup‐
232              ported bands and listing them all here would be quite extensive.
233              For details, see the MMModemBand documentation.
234
235              An  example  would be: 'egsm|dcs|pcs|g850' to select all the GSM
236              frequency bands.
237
238       --set-preferred-mode=MODE
239              Set the preferred MODE for the given modem. The MODE MUST be one
240              of the allowed modes as set with the --set-allowed-modes option.
241              Possible MODE arguments are detailed at the  beginning  of  this
242              section.
243
244

3GPP OPTIONS

246       The  3rd  Generation  Partnership  Project  (3GPP)  is  a collaboration
247       between groups of telecommunications associations. These  options  per‐
248       tain to devices which support 3GPP.
249
250       Included  are  options to control USSD (Unstructured Supplementary Ser‐
251       vice Data) sessions.
252
253       All of the 3GPP options below make use of the --modem or -m  switch  to
254       specify the modem to act on.
255
256       --3gpp-scan
257              Scan for available 3GPP networks.
258
259       --3gpp-register-home
260              Request a given modem to register in its home network.
261
262              This  registers  with  the  default  network(s) specified by the
263              modem,
264
265       --3gpp-register-in-operator=MCCMNC
266              Request a given modem to register on the network  of  the  given
267              MCCMNC  (Mobile  Country Code, Mobile Network Code) based opera‐
268              tor. This code is used for GSM/LTE, CDMA, iDEN, TETRA  and  UMTS
269              public  land mobile networks and some satellite mobile networks.
270              The ITU-T Recommendation E.212 defines mobile country codes.
271
272       --3gpp-ussd-status
273              Request the status of ANY ongoing USSD session.
274
275       --3gpp-ussd-initiate=COMMAND
276              Request the given modem to initiate a USSD session with COMMAND.
277
278              For example, COMMAND could be '*101#' to give your current  pre-
279              pay balance.
280
281       --3gpp-ussd-respond=RESPONSE
282              When  initiating  an USSD session, a RESPONSE may be needed by a
283              network-originated request. This option allows for that.
284
285       --3gpp-ussd-cancel
286              Cancel an ongoing USSD session for a given modem.
287
288

CDMA OPTIONS

290       All CDMA (Code Division Multiple Access) options require the --modem or
291       -m option.
292
293
294       --cdma-activate=CARRIER
295              Activate  the given modem using OTA (Over the Air) settings. The
296              CARRIER is a code provided by the network for the  default  set‐
297              tings they provide.
298
299

SIMPLE OPTIONS

301       All simple options must be used with --modem or -m.
302
303
304       --simple-connect=['KEY1=VALUE1,KEY2=VALUE2,...']
305              Run a full connection sequence using KEY / VALUE pairs.  You can
306              use the --create-bearer options, plus any of the following ones:
307
308                'pin'  SIM-PIN unlock code.
309
310                'operator-id'
311                       ETSI MCC-MNC of a network to force registration.
312
313       --simple-disconnect
314              Disconnect ALL connected bearers for a given modem.
315
316       --simple-status
317              Display the status of the given modem.
318
319

LOCATION OPTIONS

321       These options detail how to discover your location using  Global  Posi‐
322       tioning  System  (GPS) or directly from your mobile network infrastruc‐
323       ture (either 3GPP or 3GPP2).
324
325       All location options must be used with --modem or -m.
326
327
328       --location-status
329              Show the current status for discovering our location.
330
331       --location-get
332              Show all location information available.
333
334       --location-enable-3gpp
335              Enable location discovery using the 3GPP network.
336
337       --location-disable-3gpp
338              Disable location discovery using the 3GPP network.
339
340       --location-get-3gpp
341              Show 3GPP based location information (MCC, MNC, LAC, CI).
342
343       --location-enable-gps-nmea
344              Enable location discovery  using  GPS  and  reported  with  NMEA
345              traces.
346
347       --location-disable-gps-nmea
348              Disable location discovery using GPS and NMEA traces.
349
350       --location-get-gps-nmea
351              Show GPS based location with NMEA trace information.
352
353       --location-enable-gps-raw
354              Enable  location discovery using GPS and reported with raw (i.e.
355              longitude/latitude) values.
356
357       --location-disable-gps-raw
358              Disable location discovery using GPS and raw values.
359
360       --location-get-gps-raw
361              Show GPS based location information with raw values (e.g.  lati‐
362              tude, longitude).
363
364       --location-enable-cdma-bs
365              Enable location discovery using the 3GPP2 network.
366
367       --location-disable-cdma-bs
368              Disable location discovery using the 3GPP2 network.
369
370       --location-get-cdma-bs
371              Show 3GPP2 based location information (location of the CDMA base
372              station).
373
374       --location-enable-gps-unmanaged
375              Enable location discovery using GPS but without  taking  control
376              of the NMEA tty port.
377
378       --location-disable-gps-unmanaged
379              Disable location discovery using GPS and unmanaged port.
380
381       --location-set-gps-refresh-rate=SEC
382              Set  the location refresh rate on the DBus interface to SEC sec‐
383              onds. If set to 0, the new location is  published  on  the  DBus
384              interface as soon as ModemManager detects it.
385
386

MESSAGING OPTIONS

388       All messaging options must be used with --modem or -m.
389
390
391       --messaging-status
392              Show the status of the messaging support.
393
394       --messaging-list-sms
395              List SMS messages available on a given modem.
396
397       --messaging-create-sms=['KEY1=VALUE1,...']
398              Create  a  new SMS on a given modem. KEYs can be any of the fol‐
399              lowing:
400
401                'number'
402                        Number to which the message is addressed.
403
404                'text' Message text, in UTF-8. When sending, if  the  text  is
405                       larger  than  the limit of the technology or modem, the
406                       message will be broken into multiple parts or messages.
407                       Note  that  text  and  data are never given at the same
408                       time.
409
410                'smsc' Indicates the SMS service center number.
411
412                'validity'
413                       Specifies when the SMS expires in the SMSC.
414
415                'class'
416                       3GPP message class (0..3).
417
418                'delivery-report-request'
419                       Specifies whether delivery  report  is  requested  when
420                       sending the SMS ('yes' or 'no')
421
422                'storage'
423                       Specifies the storage where this message is kept. Stor‐
424                       ages may be 'sm', 'me', 'mt', 'sr', 'bm', 'ta'.
425
426       --messaging-create-sms-with-data=PATH
427              Use PATH to a filename as the data to create a new SMS.
428
429       --messaging-delete-sms=PATH
430              Delete an SMS from a given modem. PATH indicates the SMS path.
431
432

TIME OPTIONS

434       All time operations require the --modem or -m option.
435
436
437       --time Display  the  current  network  time  from  the  operator.  This
438              includes the timezone which is usually of importance.
439
440

FIRMWARE OPTIONS

442       All firmware options require the --modem or -m option.
443
444
445       --firmware-list
446              List all the firmware images installed on a given modem.
447
448       --firmware-select=ID
449              Select a firmware image from those installed on a given modem. A
450              list  of  available  firmware  images  can  be  seen  using  the
451              --firmware-list option.
452
453              The ID provided is a UNIQUE identifier for the firmware.
454
455

OMA OPTIONS

457       All OMA options require the --modem or -m option.
458
459
460       --oma-status
461              Show the status of the OMA device management subsystem.
462
463       --oma-start-client-initiated-session=[SESSION TYPE]
464              Request to start a client initiated session.
465
466              The given session type must be one of:
467               'client-initiated-device-configure'
468               'client-initiated-prl-update'
469               'client-initiated-hands-free-activation'
470
471       --oma-accept-network-initiated-session=[SESSION ID]
472              Request to accept a network initiated session.
473
474       --oma-reject-network-initiated-session=[SESSION ID]
475              Request to reject a network initiated session.
476
477       --oma-cancel-session
478              Request to cancel current OMA session, if any.
479
480

SIM OPTIONS

482       --pin=PIN
483              Send PIN code to a given SIM card.
484
485       --puk=PUK
486              Send PUK code to a given SIM card. This must be used WITH --pin.
487
488       --enable-pin
489              Enable  PIN request for a given SIM card. This must be used WITH
490              --pin.
491
492       --disable-pin
493              Disable PIN request for a given SIM card. This must be used WITH
494              --pin.
495
496       --change-pin=PIN
497              Change the PIN for a given SIM card. It will be set to PIN. This
498              must be used WITH --pin to supply the old PIN number.
499
500

BEARER OPTIONS

502       All bearer options require the --bearer or -b option.
503
504
505       -c, --connect
506              Connect to a given bearer.
507
508       -x, --disconnect
509              Disconnect from a given bearer.
510
511

SMS OPTIONS

513       All SMS options require the --sms or -s option.
514
515
516       --send Send an SMS.
517
518       --store
519              This option will store the SMS in the default storage defined by
520              the  modem,  which  may be either modem-memory or SMS-memory. To
521              know what the existing default storage  is,  see  the  --messag‐
522              ing-status option.
523
524
525       --store-in-storage=STORAGE
526              This  option states which STORAGE to use for SMS messages.  Pos‐
527              sible values for STORAGE include:
528
529                'sm'   SIM card storage area.
530
531                'me'   Mobile equipment storage area.
532
533                'mt'   Sum of SIM and Mobile equipment storages
534
535                'sr'   Status report message storage area.
536
537                'bm'   Broadcast message storage area.
538
539                'ta'   Terminal adaptor message storage area.
540
541       --create-file-with-data=PATH
542              This option takes an SMS that has DATA (not TEXT) and will  cre‐
543              ate  a local file described by PATH and store the content of the
544              SMS there.
545
546

APPLICATION OPTIONS

548       -v, --verbose
549              Perform actions with more details reported and/or logged.
550
551       -V, --version
552              Returns the version of this program.
553
554       -a, --async
555              Use asynchronous methods. This is purely a development tool  and
556              has no practical benefit to most user operations.
557
558       --timeout=SECONDS
559              Use SECONDS for the timeout when performing operations with this
560              command. This option is useful when executing long running oper‐
561              ations, like --3gpp-scan.
562
563

EXAMPLES

565   Send the PIN to the SIM card
566       You'll need first to know which the proper path/index is for the SIM in
567       your modem:
568           $ mmcli -m 0 | grep SIM
569           SIM | path: '/org/freedesktop/ModemManager1/SIM/0'
570
571       And after that, you can just use the SIM index:
572           $ mmcli -i 0 --pin=1234
573           successfully sent PIN code to the SIM
574
575
576   Simple connect and disconnect
577       You can launch the simple connection process like:
578           $ mmcli -m 0 --simple-connect="pin=1234,apn=internet"
579           successfully connected the modem
580
581       Then, you can disconnect it like:
582           $ mmcli -m 0 --simple-disconnect
583           successfully disconnected all bearers in the modem
584
585
586   3GPP network scan
587       Scanning for 3GPP networks may really take a long time, so  a  specific
588       timeout must be given:
589           $ mmcli -m 0 --3gpp-scan --timeout=300
590
591           Found 4 networks:
592           21404 - Yoigo (umts, available)
593           21407 - Movistar (umts, current)
594           21401 - vodafone ES (umts, forbidden)
595           21403 - Orange (umts, forbidden)
596
597
598   Creating a new SMS message & storing it
599       Using the “sm” (SIM), you can do this using:
600
601           $   mmcli   -m  0  --messaging-create-sms="text='Hello  world',num‐
602       ber='+1234567890'"
603           Successfully created new SMS:
604               /org/freedesktop/ModemManager1/SMS/21 (unknown)
605
606           $ sudo mmcli -s 21 --store-in-storage="sm"
607           successfully stored the SMS
608
609           $ sudo mmcli -s 21
610           SMS '/org/freedesktop/ModemManager1/SMS/21'
611             -----------------------------------
612             Content    |              number: '+1234567890'
613                        |                text: 'Hello world'
614             -----------------------------------
615             Properties |            PDU type: 'submit'
616                        |               state: 'stored'
617                        |                smsc: 'unknown'
618                        |            validity: '0'
619                        |               class: '0'
620                        |             storage: 'sm'
621                        |     delivery report: 'not requested'
622                        |   message reference: '0'
623
624           $ sudo mmcli -m 0 --messaging-status
625           /org/freedesktop/ModemManager1/Modem/0
626             ----------------------------
627             Messaging | supported storages: 'sm, me'
628                       |    default storage: 'me'
629
630
631   Sending SMS messages from files
632       As you can see  below,  the  important  part  is  the  --messaging-cre‐
633       ate-sms-with-data and the PATH provided.
634
635           $ sudo mmcli -m 0 \
636                  --messaging-create-sms="number='+1234567890'" \
637                  --messaging-create-sms-with-data=/path/to/your/file
638           Successfully created new SMS:
639               /org/freedesktop/ModemManager1/SMS/22 (unknown)
640
641           $ sudo mmcli -s 22 --send
642           successfully sent the SMS
643
644
645   Listing SMS messages
646       When  the  receiver  gets  all  the  parts of the message, they can now
647       recover the sent file with another mmcli command in their  ModemManager
648       setup:
649
650           $> sudo mmcli -m 0 --messaging-list-sms
651           Found 1 SMS messages:
652               /org/freedesktop/ModemManager1/SMS/0 (received)
653
654           $> sudo mmcli -s 0 --create-file-with-data=/path/to/the/output/file
655
656
657   GPS location status
658       You  first  need  to  check whether the modem has GPS-specific location
659       capabilities. Note that we’ll assume the modem is exposed as  index  0;
660       if  you  have  more than one modem, just use --list-modems to check the
661       proper modem index:
662
663           $ mmcli -m 0 --location-status
664           /org/freedesktop/ModemManager1/Modem/0
665             ----------------------------
666             Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
667                      |      enabled: 'none'
668                      |      signals: 'no'
669
670       The output says that the modem supports 3GPP  Location  area  code/Cell
671       ID,  GPS  raw and GPS-NMEA location sources. None is enabled yet, as we
672       didn’t enable the modem, which we can do issuing:
673
674           $ sudo mmcli -m 0 --enable
675           successfully enabled the modem
676
677           $ mmcli -m 0 --location-status
678           /org/freedesktop/ModemManager1/Modem/0
679             ----------------------------
680             Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
681                      |      enabled: '3gpp-lac-ci'
682                      |      signals: 'no'
683
684
685   GPS location technology enabling
686       We can enable the RAW and NMEA GPS location sources using:
687
688           $ sudo mmcli -m 0 \
689                        --location-enable-gps-raw \
690                        --location-enable-gps-nmea
691           successfully setup location gathering
692
693       If we do check again the status, we’ll see the  GPS-specific  locations
694       are enabled:
695
696           $ mmcli -m 0 --location-status
697           /org/freedesktop/ModemManager1/Modem/0
698             ----------------------------
699             Location | capabilities: '3gpp-lac-ci, gps-raw, gps-nmea'
700                      |      enabled: '3gpp-lac-ci, gps-raw, gps-nmea'
701                      |      signals: 'no'
702
703
704   GPS location retrieval
705       You  can  query  location  source  specific  information  with  --loca‐
706       tion-get-3gpp, --location-get-gps-nmea and --location-get-gps-raw;  but
707       also for all at the same time:
708
709           $ sudo mmcli -m 0 --location-get
710           /org/freedesktop/ModemManager1/Modem/0
711             -------------------------
712             3GPP location   | Mobile country code: '214'
713                             | Mobile network code: '3'
714                             |  Location area code: '21071'
715                             |             Cell ID: '7033737'
716             -------------------------
717             GPS NMEA traces | $GPGGA,,,,,,0,,,,,,,,*66
718                             | $GPRMC,,V,,,,,,,,,,N*53
719                             | $GPGSA,A,1,,,,,,,,,,,,,,,*1E
720                             | $GPGSV,4,1,16,24,,,,29,,,,05,,,,18,,,*7A
721                             | $GPGSV,4,2,16,22,,,,14,,,,11,,,,17,,,*7B
722                             | $GPGSV,4,3,16,03,,,,12,,,,30,,,,13,,,*78
723                             | $GPGSV,4,4,16,23,,,,15,,,,27,,,,07,,,*79
724                             | $GPVTG,,T,,M,,N,,K,N*2C
725             -------------------------
726             Raw GPS         | Not available
727             -------------------------
728             CDMA BS         | Not available
729
730       An example of RAW GPS location information:
731
732           $ sudo mmcli -m 0 --location-get-gps-raw
733           /org/freedesktop/ModemManager1/Modem/0
734             -------------------------
735             Raw GPS         |  UTC time: '155142.2'
736                             | Longitude: '-3.513941'
737                             |  Latitude: '40.502603'
738                             |  Altitude: '18.000000'
739
740

AUTHOR

742       Martyn Russell <martyn@lanedo.com>
743
744

SEE ALSO

746       ModemManager(8), NetworkManager(8)
747
748       AT (http://en.wikipedia.org/wiki/AT_commands).
749
750       3GPP (http://en.wikipedia.org/wiki/3GPP).
751
752       MCCMNC (http://en.wikipedia.org/wiki/Mobile_Network_Code).
753
754       USSD      (http://en.wikipedia.org/wiki/Unstructured_Supplementary_Ser
755       vice_Data).
756
757       CDMA (http://en.wikipedia.org/wiki/Code_division_multiple_access).
758
759       OTA (http://en.wikipedia.org/wiki/Over-the-air_programming).
760
761       GPS (http://en.wikipedia.org/wiki/Global_Positioning_System)
762
763       NMEA (http://en.wikipedia.org/wiki/NMEA_0183)
764
765
766
767GNU                              October 2012                         mmcli(8)
Impressum