freesmartphone.org GSM Network Interface

Description

The Network interface is used to give information about the GSM service providers and this device’s status with regards to to network registration and connectivity. Taxonomy note: We think in terms of (service) providers rather than (network) operators, since multiple (service) providers can use the networks from operators, however what actually matters most is the provider name, not the actual network operator the provider is using.

Namespace

org.freesmartphone.GSM.Network

Methods

• Register
• Unregister
• GetStatus
• GetSignalStrength
• GetTimeReport
• ListProviders
• RegisterWithProvider
• SetCallingIdentification
• GetCallingIdentification
• SendUssdRequest

Signals

• Status
• SignalStrength
• TimeReport
• IncomingUssd
• CipherStatus

Properties

None

Errors

None

Methods

Register ( )

Description: Register with any available service provider.

Implementation Note

This maps to the GSM 07.07 command +COPS=0, see 3GPP TS 07.07 Chapter 7.3.

Unregister ( )

Description: Unregister from service provider.

GetStatus ( ) → a{sv}

Description: Get Network Status.

Returns:

a{sv}: status Network status information. Mandatory tuples are:

• ( “registration”, string ):
  The telephony registration status. Expected values are:
  • “unregistered” = not registered, not trying,
  • “home” = registered to home network,
  • “busy” = not registered, but currently trying,
  • “denied” = no permitted network available,
  • “unknown” = no idea,
  • “roaming” = registered to foreign network.
• ( “mode”, string ):
  The registration mode. Expected values are:
  • “automatic” = automatic selection,
  • “manual” = manual selection,
  • “manual;automatic” = manual first, then automatic,
  • “unregister” = manual unregister,
  • “unknown” = unknown (this should never occur in production).
• ( “act”, string ):
  The network access type. Will default to “GSM” if a modem doesn’t support reporting. Expected values are:
  • “GSM” = GPRS access
  • “Compact GSM” =
  • “UMTS” = UMTS access
  • “EDGE” = Enhanced Data Rates for GSM Evolution
  • “HSDPA” = High Speed Downlink Packet Access
  • “HSUPA” = High Speed Uplink Packet Access
  • “HSDPA/HSUPA” = High Speed Packet Access (both downlink and uplink)

Optional tuples are:

• ( “display”, string ): The display name of the network provider (if registered or roaming).
• ( “provider”, string ): The full name of the network provider (if registered or roaming).
• ( “code”, string ): MCC and MNC of the network provider (if registered or roaming).
• MCC: first three characters starting from the left.
• MNC: remaining characters.
• ( “strength”, int ): The signal strength in percentage (0-100).
• ( “lac”, string ): The location area code string (if available).
• ( “cid”, string ): The cell id string (if available).
• ( “pdp.registration”, string ): The PDP access registration; values same as telephony registration.
• ( “pdp.lac”, string ): The PDP location area code string (if available).
• ( “pdp.cid”, string ): The PDP cell id string (if available).

GetSignalStrength ( ) → i

Description: Query the current signal strength, if registered with a service provider.

Returns:

i: signal_strength The signal strength in percent (0-100).

GetTimeReport ( ) → iiii

Description: Query the last received time report.

Returns:

i: time The current time in seconds since UNIX epoch. 0, if no time has been received.

i: timestamp Timestamp indicating when the time report has been received from the network.

i: zone The time zone offset in minutes based on UTC. This value is only valid, if within the interval ( -1440, 1440 ).

i: zonestamp Timestamp indicating when the time report has been received from the network.

ListProviders ( ) → a(sssss)

Description: List available service providers.

Returns:

a(sssss): providers An array of four-tuples with the following structure:

• Unique operator code,
• Status (“unknown”, “available”, “current”, “forbidden”),
• Long Name,
• Short Name (optional, may be empty).
• Network access type (defaults to “GSM”).

RegisterWithProvider ( s )

Description: Register to a dedicated service provider.

Parameters:*

s: operator_code The operator code.

SetCallingIdentification ( s )

Description: Set whether your subscriber number is visible during a call.

Parameters:*

s: status One of the following values:

• “on”, if your subscriber number should always be visible to other parties.
• “off”, if your subscriber number should never be visible to other parties.
• “network”, if you want to use the network default.

GetCallingIdentification ( ) → s

Description: Get whether your subscriber number is visible during a call.

Returns:

s: status One of the following values:

• “on”, if your subscriber number is always visible to other parties.
• “off”, if your subscriber number is never visible to other parties.
• “network”, if visibility depends on the network settings.

SendUssdRequest ( s )

Description: Send an Unstructured Supplementary Service Data (USSD) request to the network. Responses will be delivered via the signal IncomingUssd

Implementation Note

This can map to the GSM 07.07 command +CUSD=1,”(request)”,(code), see 3GPP TS 07.07 Chapter 7.14.

Parameters:*

s: request The request to be sent to the network.

Signals

Status ( a{sv} )

Description: Sent, when the network registration status changes.

Parameters:

a{sv}: status The registration status. See GetStatus for expected values.

SignalStrength ( i )

Description: (OPTIONAL) Sent, when registered with a service provider and the network signal strength changes.

Parameters:

i: signal_strength The signal strength in percent (0-100).

TimeReport ( ii )

Description: Sent upon receiving a network time and/or zone report.

Parameters:

i: time The current time in seconds since UNIX epoch. 0, if no time has been received.

i: zone The time zone offset in minutes based on UTC. This value is only valid, if within the interval ( -1440, 1440 ).

IncomingUssd ( ss )

Description: Sent, when an USSD result or a network initiated request arrives. This signal is usually sent in response to the method SendUssdRequest

Parameters:

s: mode The message mode. Valid values are:

• “completed”, if the last user-initiated request has been successfully completed,
• “useraction”, if this is a network-initiated request and further user action is necessary,
• “terminated”, if the network terminated the request,
• “localclient”, if another local client on the network has responded,
• “unsupported”, if the last user-inititated request is unsupported,
• “timeout”, if the network has not answered in time.

s: message The message. Only set if mode is “completed” or “useraction”. “”, otherwise.

CipherStatus ( ss )

Description: Sent, when the network reports a change in telephony or PDP cipher indication.

Parameters:

s: telephony The telephony cipher: “enabled”, “disabled”, or “unknown”

s: pdp The PDP cipher cipher: “enabled”, “disabled”, or “unknown”