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);
SetPrimarySimSlot      (IN  u     sim_slot);
Command                (IN  s     cmd,
                        IN  u     timeout,
                        OUT s     response);

Signals

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

Properties

Sim                           readable   o
SimSlots                      readable   ao
PrimarySimSlot                readable   u
Bearers                       readable   ao
SupportedCapabilities         readable   au
CurrentCapabilities           readable   u
MaxBearers                    readable   u
MaxActiveBearers              readable   u
Manufacturer                  readable   s
Model                         readable   s
Revision                      readable   s
CarrierConfiguration          readable   s
CarrierConfigurationRevision  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.

This interface will always be available as long a the modem is considered valid.

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

Deprecated: 1.10.0. Use "Bearers" property instead.

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"

Number to dial for the data connection, given as a string value (signature "s"). Deprecated since version 1.10.0.

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:

Dictionary of properties needed to get the bearer connected.

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.

The given bitmask should be supported by the modem, as specified in the "SupportedCapabilities" property.

This command may power-cycle the device.

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 SetPrimarySimSlot() method

SetPrimarySimSlot (IN  u sim_slot);

Selects which SIM slot to be considered as primary, on devices that expose multiple slots in the "SimSlots" property.

When the switch happens the modem may require a full device reprobe, so the modem object in DBus will get removed, and recreated once the selected SIM slot is in use.

There is no limitation on which SIM slot to select, so the user may also set as primary a slot that doesn't currently have any valid SIM card inserted.

IN u sim_slot:

SIM slot number to set as primary.


The Command() method

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

Send an arbitrary AT command to a modem and get the response.

Note that using this interface call is only allowed when running ModemManager in debug mode or if the project was built using the with-at-command-via-dbus configure option.

IN s cmd:

The command string, e.g. "AT+GCAP" or "+GCAP" (leading AT is inserted if necessary).

IN u timeout:

The number of seconds to wait for a response.

OUT s response:

The modem'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 primary active SIM object available in this device, if any.

This SIM object is the one used for network registration and data connection setup.

If multiple org.freedesktop.ModemManager1.Modem.SimSlots are supported, the org.freedesktop.ModemManager1.Modem.PrimarySimSlot index value specifies which is the slot number where this SIM card is available.


The "SimSlots" property

SimSlots  readable   ao

The list of SIM slots available in the system, including the SIM object paths if the cards are present. If a given SIM slot at a given index doesn't have a SIM card available, an empty object path will be given.

The length of this array of objects will be equal to the amount of available SIM slots in the system, and the index in the array is the slot index.

This list includes the SIM object considered as primary active SIM slot (org.freedesktop.ModemManager1.Modem.Sim) at index org.freedesktop.ModemManager1.Modem.ActiveSimSlot.


The "PrimarySimSlot" property

PrimarySimSlot  readable   u

The index of the primary active SIM slot in the org.freedesktop.ModemManager1.Modem.SimSlots array, given in the [1,N] range.

If multiple SIM slots aren't supported, this property will report value 0.

In a Multi SIM Single Standby setup, this index identifies the only SIM that is currently active. All the remaining slots will be inactive.

In a Multi SIM Multi Standby setup, this index identifies the active SIM that is considered primary, i.e. the one that will be used when a data connection is setup.


The "Bearers" property

Bearers  readable   ao

The list of bearer object paths (EPS Bearers, PDP Contexts, or CDMA2000 Packet Data Sessions) as requested by the user.

This list does not include the initial EPS bearer details (see "InitialEpsBearer").


The "SupportedCapabilities" property

SupportedCapabilities  readable   au

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

If the modem doesn't allow changing the current capabilities, the list will report one single entry with the same bitmask as in "CurrentCapabilities".

Only multimode devices implementing both 3GPP (GSM/UMTS/LTE/5GNR) and 3GPP2 (CDMA/EVDO) specs will report more than one combination of capabilities.


The "CurrentCapabilities" property

CurrentCapabilities  readable   u

Bitmask of MMModemCapability values, specifying the currently used generic family of access technologies.

This bitmask will be one of the ones listed in "SupportedCapabilities".


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 MM_BEARER_TYPE_DEFAULT bearers that may be explicitly enabled by the user.

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 "CarrierConfiguration" property

CarrierConfiguration  readable   s

The description of the carrier-specific configuration (MCFG) in use by the modem.


The "CarrierConfigurationRevision" property

CarrierConfigurationRevision  readable   s

The revision identification of the carrier-specific configuration (MCFG) in use 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.