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.