org.freedesktop.ModemManager1.Modem: ModemManager Reference Manual

org.freedesktop.ModemManager1.Modem

org.freedesktop.ModemManager1.Modem — The ModemManager Modem interface.

Methods

Enable                 (IN  b     enable);
ListBearers            (OUT ao    bearers);
CreateBearer           (IN  a{sv} properties,
                        OUT o     path);
DeleteBearer           (IN  o     bearer);
Reset                  ();
FactoryReset           (IN  s     code);
SetPowerState          (IN  u     state);
SetCurrentCapabilities (IN  u     capabilities);
SetCurrentModes        (IN  (uu)  modes);
SetCurrentBands        (IN  au    bands);
Command                (IN  s     cmd,
                        IN  u     timeout,
                        OUT s     response);

Signals

StateChanged (i old,
              i new,
              u reason);

Properties

Sim                    readable   o
Bearers                readable   ao
SupportedCapabilities  readable   au
CurrentCapabilities    readable   u
MaxBearers             readable   u
MaxActiveBearers       readable   u
Manufacturer           readable   s
Model                  readable   s
Revision               readable   s
HardwareRevision       readable   s
DeviceIdentifier       readable   s
Device                 readable   s
Drivers                readable   as
Plugin                 readable   s
PrimaryPort            readable   s
Ports                  readable   a(su)
EquipmentIdentifier    readable   s
UnlockRequired         readable   u
UnlockRetries          readable   a{uu}
State                  readable   i
StateFailedReason      readable   u
AccessTechnologies     readable   u
SignalQuality          readable   (ub)
OwnNumbers             readable   as
PowerState             readable   u
SupportedModes         readable   a(uu)
CurrentModes           readable   (uu)
SupportedBands         readable   au
CurrentBands           readable   au
SupportedIpFamilies    readable   u

Description

The Modem interface controls the status and actions in a given modem object.

Method Details

The Enable() method

Enable (IN  b enable);

Enable or disable the modem.

When enabled, the modem's radio is powered on and data sessions, voice calls, location services, and Short Message Service may be available.

When disabled, the modem enters low-power state and no network-related operations are available.

IN b enable:

TRUE to enable the modem and FALSE to disable it.

The ListBearers() method

ListBearers (OUT ao bearers);

List configured packet data bearers (EPS Bearers, PDP Contexts, or CDMA2000 Packet Data Sessions).

OUT ao bearers:

The list of bearer object paths.

The CreateBearer() method

CreateBearer (IN  a{sv} properties,
              OUT o     path);

Create a new packet data bearer using the given characteristics.

This request may fail if the modem does not support additional bearers, if too many bearers are already defined, or if properties are invalid.

Allowed properties are:

`"apn"`	Access Point Name, given as a string value (signature `"s"`). Required in 3GPP.
`"ip-type"`	Addressing type, given as a MMBearerIpFamily value (signature `"u"`). Optional in 3GPP and CDMA.
`"allowed-auth"`	The authentication method to use, given as a MMBearerAllowedAuth value (signature `"u"`). Optional in 3GPP.
`"user"`	User name (if any) required by the network, given as a string value (signature `"s"`). Optional in 3GPP.
`"password"`	Password (if any) required by the network, given as a string value (signature `"s"`). Optional in 3GPP.
`"allow-roaming"`	Flag to tell whether connection is allowed during roaming, given as a boolean value (signature `"b"`). Optional in 3GPP.
`"rm-protocol"`	Protocol of the Rm interface, given as a MMModemCdmaRmProtocol value (signature `"u"`). Optional in CDMA.
`"number"`	Telephone number to dial, given as a string value (signature `"s"`). Required in POTS.

Some properties are only applicable to a bearer of certain access technologies, for example the "apn" property is not applicable to CDMA2000 Packet Data Session bearers.

`IN a{sv} properties`:	List of properties to assign to the bearer after creating it.
`OUT o path`:	On success, the object path of the newly created bearer.

The DeleteBearer() method

DeleteBearer (IN  o bearer);

Delete an existing packet data bearer.

If the bearer is currently active and providing packet data server, it will be disconnected and that packet data service will terminate.

IN o bearer:

Object path of the bearer to delete.

The Reset() method

Reset ();

Clear non-persistent configuration and state, and return the device to a newly-powered-on state.

This command may power-cycle the device.

The FactoryReset() method

FactoryReset (IN  s code);

Clear the modem's configuration (including persistent configuration and state), and return the device to a factory-default state.

If not required by the modem, code may be ignored.

This command may or may not power-cycle the device.

IN s code:

Carrier-supplied code required to reset the modem.

The SetPowerState() method

SetPowerState (IN  u state);

Set the power state of the modem. This action can only be run when the modem is in MM_MODEM_STATE_DISABLED state.

IN u state:

A MMModemPowerState value, to specify the desired power state.

The SetCurrentCapabilities() method

SetCurrentCapabilities (IN  u capabilities);

Set the capabilities of the device. A restart of the modem may be required.

IN u capabilities:

Bitmask of MMModemCapability values, to specify the capabilities to use.

The SetCurrentModes() method

SetCurrentModes (IN  (uu) modes);

Set the access technologies (e.g. 2G/3G/4G preference) the device is currently allowed to use when connecting to a network.

The given combination should be supported by the modem, as specified in the "SupportedModes" property.

IN (uu) modes:

A pair of MMModemMode values, where the first one is a bitmask of allowed modes, and the second one the preferred mode, if any.

The SetCurrentBands() method

SetCurrentBands (IN  au bands);

Set the radio frequency and technology bands the device is currently allowed to use when connecting to a network.

IN au bands:

List of MMModemBand values, to specify the bands to be used.

The Command() method

Command (IN  s cmd,
         IN  u timeout,
         OUT s response);

`IN s cmd`:
`IN u timeout`:
`OUT s response`:

Signal Details

The "StateChanged" signal

StateChanged (i old,
              i new,
              u reason);

The modem's state (see "State") changed.

`i old`:	A MMModemState value, specifying the new state.
`i new`:	A MMModemState value, specifying the new state.
`u reason`:	A MMModemStateChangeReason value, specifying the reason for this state change.

Property Details

The "Sim" property

Sim  readable   o

The path of the SIM object available in this device, if any.

The "Bearers" property

Bearers  readable   ao

The list of bearer object paths (EPS Bearers, PDP Contexts, or CDMA2000 Packet Data Sessions).

The "SupportedCapabilities" property

SupportedCapabilities  readable   au

List of MMModemCapability values, specifying the combinations of generic family of access technologies the modem supports.

If the modem doesn't allow changing the current capabilities, a single entry with MM_MODEM_CAPABILITY_ANY will be given.

The "CurrentCapabilities" property

CurrentCapabilities  readable   u

Bitmask of MMModemCapability values, specifying the generic family of access technologies the modem currently supports without a firmware reload or reinitialization.

The "MaxBearers" property

MaxBearers  readable   u

The maximum number of defined packet data bearers the modem supports.

This is not the number of active/connected bearers the modem supports, but simply the number of bearers that may be defined at any given time. For example, POTS and CDMA2000-only devices support only one bearer, while GSM/UMTS devices typically support three or more, and any LTE-capable device (whether LTE-only, GSM/UMTS-capable, and/or CDMA2000-capable) also typically support three or more.

The "MaxActiveBearers" property

MaxActiveBearers  readable   u

The maximum number of active packet data bearers the modem supports.

POTS and CDMA2000-only devices support one active bearer, while GSM/UMTS and LTE-capable devices (including LTE/CDMA devices) typically support at least two active bearers.

The "Manufacturer" property

Manufacturer  readable   s

The equipment manufacturer, as reported by the modem.

The "Model" property

Model  readable   s

The equipment model, as reported by the modem.

The "Revision" property

Revision  readable   s

The revision identification of the software, as reported by the modem.

The "HardwareRevision" property

HardwareRevision  readable   s

The revision identification of the hardware, as reported by the modem.

The "DeviceIdentifier" property

DeviceIdentifier  readable   s

A best-effort device identifier based on various device information like model name, firmware revision, USB/PCI/PCMCIA IDs, and other properties.

This ID is not guaranteed to be unique and may be shared between identical devices with the same firmware, but is intended to be "unique enough" for use as a casual device identifier for various user experience operations.

This is not the device's IMEI or ESN since those may not be available before unlocking the device via a PIN.

The "Device" property

Device  readable   s

The physical modem device reference (ie, USB, PCI, PCMCIA device), which may be dependent upon the operating system.

In Linux for example, this points to a sysfs path of the usb_device object.

This value may also be set by the user using the MM_ID_PHYSDEV_UID udev tag (e.g. binding the tag to a specific sysfs path).

The "Drivers" property

Drivers  readable   as

The Operating System device drivers handling communication with the modem hardware.

The "Plugin" property

Plugin  readable   s

The name of the plugin handling this modem.

The "PrimaryPort" property

PrimaryPort  readable   s

The name of the primary port using to control the modem.

The "Ports" property

Ports  readable   a(su)

The list of ports in the modem, given as an array of string and unsigned integer pairs. The string is the port name or path, and the integer is the port type given as a MMModemPortType value.

The "EquipmentIdentifier" property

EquipmentIdentifier  readable   s

The identity of the device.

This will be the IMEI number for GSM devices and the hex-format ESN/MEID for CDMA devices.

The "UnlockRequired" property

UnlockRequired  readable   u

Current lock state of the device, given as a MMModemLock value.

The "UnlockRetries" property

UnlockRetries  readable   a{uu}

A dictionary in which the keys are MMModemLock flags, and the values are integers giving the number of PIN tries remaining before the code becomes blocked (requiring a PUK) or permanently blocked. Dictionary entries exist only for the codes for which the modem is able to report retry counts.

The "State" property

State  readable   i

Overall state of the modem, given as a MMModemState value.

If the device's state cannot be determined, MM_MODEM_STATE_UNKNOWN will be reported.

The "StateFailedReason" property

StateFailedReason  readable   u

Error specifying why the modem is in MM_MODEM_STATE_FAILED state, given as a MMModemStateFailedReason value.

The "AccessTechnologies" property

AccessTechnologies  readable   u

Bitmask of MMModemAccessTechnology values, specifying the current network access technologies used by the device to communicate with the network.

If the device's access technology cannot be determined, MM_MODEM_ACCESS_TECHNOLOGY_UNKNOWN will be reported.

The "SignalQuality" property

SignalQuality  readable   (ub)

Signal quality in percent (0 - 100) of the dominant access technology the device is using to communicate with the network. Always 0 for POTS devices.

The additional boolean value indicates if the quality value given was recently taken.

The "OwnNumbers" property

OwnNumbers  readable   as

List of numbers (e.g. MSISDN in 3GPP) being currently handled by this modem.

The "PowerState" property

PowerState  readable   u

A MMModemPowerState value specifying the current power state of the modem.

The "SupportedModes" property

SupportedModes  readable   a(uu)

This property exposes the supported mode combinations, given as an array of unsigned integer pairs, where:

	The first integer is a bitmask of MMModemMode values, specifying the allowed modes.
	The second integer is a single MMModemMode, which specifies the preferred access technology, among the ones defined in the allowed modes.

The "CurrentModes" property

CurrentModes  readable   (uu)

A pair of MMModemMode values, where the first one is a bitmask specifying the access technologies (eg 2G/3G/4G) the device is currently allowed to use when connecting to a network, and the second one is the preferred mode of those specified as allowed.

The pair must be one of those specified in "SupportedModes".

The "SupportedBands" property

SupportedBands  readable   au

List of MMModemBand values, specifying the radio frequency and technology bands supported by the device.

For POTS devices, only the MM_MODEM_BAND_ANY mode will be returned.

The "CurrentBands" property

CurrentBands  readable   au

List of MMModemBand values, specifying the radio frequency and technology bands the device is currently using when connecting to a network.

It must be a subset of "SupportedBands".

The "SupportedIpFamilies" property

SupportedIpFamilies  readable   u

Bitmask of MMBearerIpFamily values, specifying the IP families supported by the device.