1mmcli(8) User Commands mmcli(8)
3
7 mmcli - Control and monitor the ModemManager
8
11 mmcli [OPTION...]
12
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
25 -h, --help
26 Show summary of options by group.
27 --help-all
29 Show all groups and options.
30 --help-manager
32 Show manager specific options.
33 --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 --help-modem
40 Show modem specific options.
41 --help-3gpp
43 Show 3GPP specific options.
44 --help-cdma
46 Show CDMA specific options.
47 --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 --help-location
54 Show location or positioning specific options.
55 --help-messaging
57 Show messaging specific options. See also --help-sms which is
58 related.
59 --help-time
61 Show time specific options.
62 --help-firmware
64 Show firmware specific options.
65 --help-oma
67 Show OMA specific options.
68 --help-sim
70 Show SIM card specific options.
71 --help-bearer
73 Show bearer specific options.
74 --help-sms
76 Show SMS specific options. See also --help-messaging which is
77 related.
78
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 The default mode is ERR.
88 -L, --list-modems
90 List available modems.
91 -M, --monitor-modems
93 List available modems and monitor modems added or removed.
94 -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
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 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 Found 1 modems:
111 /org/freedesktop/ModemManager1/Modem/4
112 In this case, the INDEX is 4 and the PATH is the entire string above.
114 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 /org/freedesktop/ModemManager1/Bearer/4
120 -m, --modem=[PATH|INDEX]
123 Specify a modem.
124 -b, --bearer=[PATH|INDEX]
126 Specify a bearer.
127 -i, --sim=[PATH|INDEX]
129 Specify a SIM card.
130 -s, --sms=[PATH|INDEX]
132 Specify an SMS.
133
136 All of the modem options below make use of the --modem or -m switch to
137 specify the modem to act on.
138 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 '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 -w, --monitor-state
149 Monitor the state of a given modem.
150 -e, --enable
152 Enable a given modem.
153 This powers the antenna, starts the automatic registration
155 process and in general prepares the modem to be connected.
156 -d, --disable
158 Disable a given modem.
159 This disconnects the existing connection(s) for the modem and
161 puts it into a low power mode.
162 -r, --reset
164 Resets the modem to the settings it had when it was power
165 cycled.
166 --factory-reset=CODE
168 Resets the modem to its original factory default settings.
169 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 --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 --list-bearers
181 List packet data bearers that are available for the given modem.
182 --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 'apn' Access Point Name. Required in 3GPP.
188 'ip-type'
190 Addressing type. Given as a MMBearerIpFamily value
191 (e.g. 'ipv4', 'ipv6', 'ipv4v6'). Optional in 3GPP and
192 CDMA.
193 '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 'user' User name (if any) required by the network. Optional in
200 3GPP.
201 'password'
203 Password (if any) required by the network. Optional in
204 3GPP.
205 '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 '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 'number'
218 Telephone number to dial. Required in POTS.
219 --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 --set-allowed-modes=[MODE1|MODE2|...]
226 Set allowed modes for a given modem. For possible modes, see the
227 beginning of this section.
228 --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 An example would be: 'egsm|dcs|pcs|g850' to select all the GSM
236 frequency bands.
237 --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
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 Included are options to control USSD (Unstructured Supplementary Ser‐
251 vice Data) sessions.
252 All of the 3GPP options below make use of the --modem or -m switch to
254 specify the modem to act on.
255 --3gpp-scan
257 Scan for available 3GPP networks.
258 --3gpp-register-home
260 Request a given modem to register in its home network.
261 This registers with the default network(s) specified by the
263 modem,
264 --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 --3gpp-ussd-status
273 Request the status of ANY ongoing USSD session.
274 --3gpp-ussd-initiate=COMMAND
276 Request the given modem to initiate a USSD session with COMMAND.
277 For example, COMMAND could be '*101#' to give your current pre-
279 pay balance.
280 --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 --3gpp-ussd-cancel
286 Cancel an ongoing USSD session for a given modem.
287
290 All CDMA (Code Division Multiple Access) options require the --modem or
291 -m option.
292 --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
301 All simple options must be used with --modem or -m.
302 --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 'pin' SIM-PIN unlock code.
309 'operator-id'
311 ETSI MCC-MNC of a network to force registration.
312 --simple-disconnect
314 Disconnect ALL connected bearers for a given modem.
315 --simple-status
317 Display the status of the given modem.
318
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 All location options must be used with --modem or -m.
326 --location-status
329 Show the current status for discovering our location.
330 --location-get
332 Show all location information available.
333 --location-enable-3gpp
335 Enable location discovery using the 3GPP network.
336 --location-disable-3gpp
338 Disable location discovery using the 3GPP network.
339 --location-get-3gpp
341 Show 3GPP based location information (MCC, MNC, LAC, CI).
342 --location-enable-gps-nmea
344 Enable location discovery using GPS and reported with NMEA
345 traces.
346 --location-disable-gps-nmea
348 Disable location discovery using GPS and NMEA traces.
349 --location-get-gps-nmea
351 Show GPS based location with NMEA trace information.
352 --location-enable-gps-raw
354 Enable location discovery using GPS and reported with raw (i.e.
355 longitude/latitude) values.
356 --location-disable-gps-raw
358 Disable location discovery using GPS and raw values.
359 --location-get-gps-raw
361 Show GPS based location information with raw values (e.g. lati‐
362 tude, longitude).
363 --location-enable-cdma-bs
365 Enable location discovery using the 3GPP2 network.
366 --location-disable-cdma-bs
368 Disable location discovery using the 3GPP2 network.
369 --location-get-cdma-bs
371 Show 3GPP2 based location information (location of the CDMA base
372 station).
373 --location-enable-gps-unmanaged
375 Enable location discovery using GPS but without taking control
376 of the NMEA tty port.
377 --location-disable-gps-unmanaged
379 Disable location discovery using GPS and unmanaged port.
380 --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
388 All messaging options must be used with --modem or -m.
389 --messaging-status
392 Show the status of the messaging support.
393 --messaging-list-sms
395 List SMS messages available on a given modem.
396 --messaging-create-sms=['KEY1=VALUE1,...']
398 Create a new SMS on a given modem. KEYs can be any of the fol‐
399 lowing:
400 'number'
402 Number to which the message is addressed.
403 '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 'smsc' Indicates the SMS service center number.
411 'validity'
413 Specifies when the SMS expires in the SMSC.
414 'class'
416 3GPP message class (0..3).
417 'delivery-report-request'
419 Specifies whether delivery report is requested when
420 sending the SMS ('yes' or 'no')
421 'storage'
423 Specifies the storage where this message is kept. Stor‐
424 ages may be 'sm', 'me', 'mt', 'sr', 'bm', 'ta'.
425 --messaging-create-sms-with-data=PATH
427 Use PATH to a filename as the data to create a new SMS.
428 --messaging-delete-sms=PATH
430 Delete an SMS from a given modem. PATH indicates the SMS path.
431
434 All time operations require the --modem or -m option.
435 --time Display the current network time from the operator. This
438 includes the timezone which is usually of importance.
439
442 All firmware options require the --modem or -m option.
443 --firmware-list
446 List all the firmware images installed on a given modem.
447 --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 The ID provided is a UNIQUE identifier for the firmware.
454
457 All OMA options require the --modem or -m option.
458 --oma-status
461 Show the status of the OMA device management subsystem.
462 --oma-start-client-initiated-session=[SESSION TYPE]
464 Request to start a client initiated session.
465 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 --oma-accept-network-initiated-session=[SESSION ID]
472 Request to accept a network initiated session.
473 --oma-reject-network-initiated-session=[SESSION ID]
475 Request to reject a network initiated session.
476 --oma-cancel-session
478 Request to cancel current OMA session, if any.
479
482 --pin=PIN
483 Send PIN code to a given SIM card.
484 --puk=PUK
486 Send PUK code to a given SIM card. This must be used WITH --pin.
487 --enable-pin
489 Enable PIN request for a given SIM card. This must be used WITH
490 --pin.
491 --disable-pin
493 Disable PIN request for a given SIM card. This must be used WITH
494 --pin.
495 --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
502 All bearer options require the --bearer or -b option.
503 -c, --connect
506 Connect to a given bearer.
507 -x, --disconnect
509 Disconnect from a given bearer.
510
513 All SMS options require the --sms or -s option.
514 --send Send an SMS.
517 --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 --store-in-storage=STORAGE
526 This option states which STORAGE to use for SMS messages. Pos‐
527 sible values for STORAGE include:
528 'sm' SIM card storage area.
530 'me' Mobile equipment storage area.
532 'mt' Sum of SIM and Mobile equipment storages
534 'sr' Status report message storage area.
536 'bm' Broadcast message storage area.
538 'ta' Terminal adaptor message storage area.
540 --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
548 -v, --verbose
549 Perform actions with more details reported and/or logged.
550 -V, --version
552 Returns the version of this program.
553 -a, --async
555 Use asynchronous methods. This is purely a development tool and
556 has no practical benefit to most user operations.
557 --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
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 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 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 Then, you can disconnect it like:
582 $ mmcli -m 0 --simple-disconnect
583 successfully disconnected all bearers in the modem
584 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 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 Creating a new SMS message & storing it
599 Using the “sm” (SIM), you can do this using:
600 $ 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 $ sudo mmcli -s 21 --store-in-storage="sm"
607 successfully stored the SMS
608 $ 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 $ sudo mmcli -m 0 --messaging-status
625 /org/freedesktop/ModemManager1/Modem/0
626 ----------------------------
627 Messaging | supported storages: 'sm, me'
628 | default storage: 'me'
629 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 $ 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 $ sudo mmcli -s 22 --send
642 successfully sent the SMS
643 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 $> sudo mmcli -m 0 --messaging-list-sms
651 Found 1 SMS messages:
652 /org/freedesktop/ModemManager1/SMS/0 (received)
653 $> sudo mmcli -s 0 --create-file-with-data=/path/to/the/output/file
655 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 $ 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 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 $ sudo mmcli -m 0 --enable
675 successfully enabled the modem
676 $ 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 GPS location technology enabling
686 We can enable the RAW and NMEA GPS location sources using:
687 $ sudo mmcli -m 0 \
689 --location-enable-gps-raw \
690 --location-enable-gps-nmea
691 successfully setup location gathering
692 If we do check again the status, we’ll see the GPS-specific locations
694 are enabled:
695 $ 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 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 $ 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 An example of RAW GPS location information:
731 $ 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
742 Martyn Russell <martyn@lanedo.com>
743
746 ModemManager(8), NetworkManager(8)
747 AT (http://en.wikipedia.org/wiki/AT_commands).
749 3GPP (http://en.wikipedia.org/wiki/3GPP).
751 MCCMNC (http://en.wikipedia.org/wiki/Mobile_Network_Code).
753 USSD (http://en.wikipedia.org/wiki/Unstructured_Supplementary_Ser‐
755 vice_Data).
756 CDMA (http://en.wikipedia.org/wiki/Code_division_multiple_access).
758 OTA (http://en.wikipedia.org/wiki/Over-the-air_programming).
760 GPS (http://en.wikipedia.org/wiki/Global_Positioning_System)
762 NMEA (http://en.wikipedia.org/wiki/NMEA_0183)
764GNU October 2012 mmcli(8)