Aleksander Morgado
091bf4dbd8
Sometimes SUPL-server based A-GPS is not possible, e.g. if the module doesn't have Internet connectivity. In such cases, the modem may support injecting additional "assistance data" that may be downloaded from the Internet using external means (e.g. WiFi), in order to keep having a quick time to first fix. We now support using this location assistance data, with the following new API elements: * A new mask of supported assistance data types is provided in the SupportedAssistanceData property. * A new list of URLs from where the aassistance data may be downloaded is also provided in a new AssistanceDataServers property. * A new InjectAssistanceData() method is provided, to perform the data injection in the module once it's been downloaded to the host system.
358 lines
17 KiB
XML
358 lines
17 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
|
|
<!--
|
|
ModemManager 1.0 Interface Specification
|
|
|
|
Copyright (C) 2008 Novell, Inc.
|
|
Copyright (C) 2008-2013 Red Hat, Inc.
|
|
Copyright (C) 2011-2013 Google, Inc.
|
|
Copyright (C) 2011-2013 Lanedo GmbH
|
|
-->
|
|
|
|
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
|
|
|
|
<!--
|
|
org.freedesktop.ModemManager1.Modem.Location:
|
|
@short_description: The ModemManager Location interface.
|
|
|
|
The Location interface allows devices to provide location information to
|
|
client applications. Not all devices can provide this information, or even
|
|
if they do, they may not be able to provide it while a data session is
|
|
active.
|
|
-->
|
|
<interface name="org.freedesktop.ModemManager1.Modem.Location">
|
|
|
|
<!--
|
|
Setup:
|
|
@sources: Bitmask of <link linkend="MMModemLocationSource">MMModemLocationSource</link> flags, specifying which sources should get enabled or disabled. <link linkend="MM-MODEM-LOCATION-SOURCE-NONE:CAPS">MM_MODEM_LOCATION_SOURCE_NONE</link> will disable all location gathering.
|
|
@signal_location: Flag to control whether the device emits signals with the new location information. This argument is ignored when disabling location information gathering.
|
|
|
|
Configure the location sources to use when gathering location
|
|
information. Also enable or disable location information gathering.
|
|
This method may require the client to authenticate itself.
|
|
|
|
When signals are emitted, any client application (including malicious
|
|
ones!) can listen for location updates unless D-Bus permissions restrict
|
|
these signals from certain users. If further security is desired, the
|
|
@signal_location argument can be set to %FALSE to disable location
|
|
updates via D-Bus signals and require applications to call
|
|
authenticated APIs (like
|
|
<link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Location.GetLocation">GetLocation()</link>
|
|
) to get
|
|
location information.
|
|
|
|
The optional
|
|
<link linkend="MM-MODEM-LOCATION-SOURCE-AGPS:CAPS">MM_MODEM_LOCATION_SOURCE_AGPS</link>
|
|
allows to request A-GPS operation, and it must be given along with either
|
|
<link linkend="MM-MODEM-LOCATION-SOURCE-GPS-RAW:CAPS">MM_MODEM_LOCATION_SOURCE_GPS_RAW</link>
|
|
or
|
|
<link linkend="MM-MODEM-LOCATION-SOURCE-GPS-NMEA:CAPS">MM_MODEM_LOCATION_SOURCE_GPS_NMEA</link>.
|
|
|
|
-->
|
|
<method name="Setup">
|
|
<arg name="sources" type="u" direction="in" />
|
|
<arg name="signal_location" type="b" direction="in" />
|
|
</method>
|
|
|
|
<!--
|
|
GetLocation:
|
|
@location: Dictionary of available location information when location information gathering is enabled.
|
|
|
|
Return current location information, if any. If the modem supports
|
|
multiple location types it may return more than one. See the
|
|
#org.freedesktop.ModemManager1.Modem.Location:Location property
|
|
for more information on the dictionary returned at @location.
|
|
|
|
This method may require the client to authenticate itself.
|
|
-->
|
|
<method name="GetLocation">
|
|
<arg name="Location" type="a{uv}" direction="out" />
|
|
</method>
|
|
|
|
<!--
|
|
SetSuplServer:
|
|
@supl: SUPL server configuration, given either as IP:PORT or with a full URL.
|
|
|
|
Configure the SUPL server for A-GPS.
|
|
-->
|
|
<method name="SetSuplServer">
|
|
<arg name="supl" type="s" direction="in" />
|
|
</method>
|
|
|
|
<!--
|
|
InjectAssistanceData:
|
|
@data: assistance data to be injected to the GNSS module.
|
|
|
|
Inject assistance data to the GNSS module.
|
|
The data files should be downloaded using external means from the URLs specified in
|
|
the <link linkend="AssistanceDataServers">AssistanceDataServers</link> property.
|
|
|
|
The user does not need to specify the assistance data type being given.
|
|
|
|
There is no maximum @data size limit specified, default DBus system bus limits apply.
|
|
-->
|
|
<method name="InjectAssistanceData">
|
|
<arg name="data" type="ay" direction="in">
|
|
<annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/>
|
|
</arg>
|
|
</method>
|
|
|
|
<!--
|
|
SetGpsRefreshRate:
|
|
@rate: Rate, in seconds.
|
|
|
|
Set the refresh rate of the GPS information in the API. If not explicitly
|
|
set, a default of 30s will be used.
|
|
|
|
The refresh rate can be set to 0 to disable it, so that every update reported by
|
|
the modem is published in the interface.
|
|
-->
|
|
<method name="SetGpsRefreshRate">
|
|
<arg name="rate" type="u" direction="in" />
|
|
</method>
|
|
|
|
<!--
|
|
Capabilities:
|
|
|
|
Bitmask of <link linkend="MMModemLocationSource">MMModemLocationSource</link>
|
|
values, specifying the supported location sources.
|
|
-->
|
|
<property name="Capabilities" type="u" access="read" />
|
|
|
|
<!--
|
|
SupportedAssistanceData:
|
|
|
|
Bitmask of <link linkend="MMModemLocationAssistanceDataType">MMModemLocationAssistanceDataType</link>
|
|
values, specifying the supported types of assistance data.
|
|
-->
|
|
<property name="SupportedAssistanceData" type="u" access="read" />
|
|
|
|
<!--
|
|
Enabled:
|
|
|
|
Bitmask specifying which of the supported
|
|
<link linkend="MMModemLocationSource">MMModemLocationSource</link>
|
|
location sources is currently enabled in the device.
|
|
-->
|
|
<property name="Enabled" type="u" access="read" />
|
|
|
|
<!--
|
|
SignalsLocation:
|
|
|
|
%TRUE if location updates will be emitted via D-Bus signals, %FALSE if
|
|
location updates will not be emitted.
|
|
|
|
See the
|
|
<link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Location.Setup">Setup()</link>
|
|
method for more information.
|
|
-->
|
|
<property name="SignalsLocation" type="b" access="read" />
|
|
|
|
<!--
|
|
Location:
|
|
|
|
Dictionary of available location information when location information
|
|
gathering is enabled. If the modem supports multiple location types it
|
|
may return more than one here.
|
|
|
|
Note that if the device was told not to emit updated location
|
|
information when location information gathering was initially enabled,
|
|
this property may not return any location information for security reasons.
|
|
|
|
This dictionary is composed of a
|
|
<link linkend="MMModemLocationSource">MMModemLocationSource</link>
|
|
key, with an associated data which contains type-specific location
|
|
information:
|
|
|
|
<variablelist>
|
|
<varlistentry><term><link linkend="MM-MODEM-LOCATION-SOURCE-3GPP-LAC-CI:CAPS">MM_MODEM_LOCATION_SOURCE_3GPP_LAC_CI</link></term>
|
|
<listitem>
|
|
<para>
|
|
Devices supporting this
|
|
capability return a string in the format <literal>"MCC,MNC,LAC,CI,TAC"</literal> (without the
|
|
quotes of course) where the following applies:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry><term><literal>MCC</literal></term>
|
|
<listitem>
|
|
This is the three-digit ITU E.212 Mobile Country Code of the
|
|
network provider to which the mobile is currently registered.
|
|
e.g. <literal>"310"</literal>.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>MNC</literal></term>
|
|
<listitem>
|
|
This is the two- or three-digit GSM Mobile Network Code of the
|
|
network provider to which the mobile is currently registered.
|
|
e.g. <literal>"26"</literal> or <literal>"260"</literal>.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>LAC</literal></term>
|
|
<listitem>
|
|
This is the two-byte Location Area Code of the GSM/UMTS base
|
|
station with which the mobile is registered, in upper-case
|
|
hexadecimal format without leading zeros, as specified in
|
|
3GPP TS 27.007. E.g. <literal>"84CD"</literal>.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>CI</literal></term>
|
|
<listitem>
|
|
This is the two- or four-byte Cell Identifier with which the mobile
|
|
is registered, in upper-case hexadecimal format without leading
|
|
zeros, as specified in 3GPP TS 27.007.
|
|
e.g. <literal>"2BAF"</literal> or <literal>"D30156"</literal>.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>TAC</literal></term>
|
|
<listitem>
|
|
This is the two-byte Location Area Code of the LTE base
|
|
station with which the mobile is registered, in upper-case
|
|
hexadecimal format without leading zeros, as specified in
|
|
3GPP TS 27.007. E.g. <literal>"6FFE"</literal>.
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
The entire string may only be composed of the ASCII digits <literal>[0-9]</literal>,
|
|
the alphabetical characters <literal>[A-F]</literal>, and the comma (<literal>,</literal>) character.
|
|
No other characters are allowed. For example: <literal>"310,260,8BE3,2BAF"</literal> or
|
|
<literal>"250,40,CE00,1CEAD8F0"</literal>.
|
|
</para>
|
|
<para>
|
|
If any of these four items (<literal>MCC</literal>, <literal>MNC</literal>,
|
|
<literal>LAC</literal>, <literal>CI</literal>) is unknown or the
|
|
mobile is not registered with a network, then the
|
|
<link linkend="MM-MODEM-LOCATION-SOURCE-3GPP-LAC-CI:CAPS">MM_MODEM_LOCATION_SOURCE_3GPP_LAC_CI</link>
|
|
location
|
|
information item should not be provided as a returned value from the
|
|
<link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Location.GetLocation">GetLocation()</link>
|
|
method or in the #org.freedesktop.ModemManager1.Modem.Location:Location property.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><link linkend="MM-MODEM-LOCATION-SOURCE-GPS-RAW:CAPS">MM_MODEM_LOCATION_SOURCE_GPS_RAW</link></term>
|
|
<listitem>
|
|
<para>
|
|
Devices supporting this
|
|
capability return a D-Bus dictionary (signature <literal>"a{sv}"</literal>) mapping well-known
|
|
keys to values with defined formats.
|
|
</para>
|
|
<para>
|
|
The allowed key/value pairs and their formats are:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry><term><literal>"utc-time"</literal></term>
|
|
<listitem>
|
|
(Required) UTC time in ISO 8601 format, given as a string value (signature <literal>"s"</literal>). e.g. <literal>203015</literal>.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>"latitude"</literal></term>
|
|
<listitem>
|
|
(Required) Latitude in Decimal Degrees (positive numbers mean N quadrasphere, negative mean S quadrasphere), given as a double value (signature <literal>"d"</literal>). e.g. <literal>38.889722</literal>, meaning 38d 53' 22" N.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>"longitude"</literal></term>
|
|
<listitem>
|
|
(Required) Longitude in Decimal Degrees (positive numbers mean E quadrasphere, negative mean W quadrasphere), given as a double value (signature <literal>"d"</literal>). e.g. <literal>-77.008889</literal>, meaning 77d 0' 32" W.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>"altitude"</literal></term>
|
|
<listitem>
|
|
(Optional) Altitude above sea level in meters, given as a double value (signature <literal>"d"</literal>). e.g. <literal>33.5</literal>.
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><link linkend="MM-MODEM-LOCATION-SOURCE-GPS-NMEA:CAPS">MM_MODEM_LOCATION_SOURCE_GPS_NMEA</link></term>
|
|
<listitem>
|
|
<para>
|
|
Devices supporting this capability return
|
|
a string containing one or more NMEA sentences (D-Bus signature <literal>'s'</literal>).
|
|
The manager will cache the most recent NMEA sentence of each type for
|
|
a period of time not less than 30 seconds. When reporting multiple
|
|
NMEA sentences, sentences shall be separated by an ASCII Carriage
|
|
Return and Line Feed (<literal><CR><LF></literal>) sequence.
|
|
</para>
|
|
<para>
|
|
For example, if the device sends a <literal>$GPRMC</literal> sentence immediately
|
|
followed by a <literal>$GPGGA</literal> sentence, the reported location string would be
|
|
(where of course the <literal><CR><LF></literal> is replaced with the actual
|
|
ASCII <literal>CR</literal> (0x0D) and <literal>LF</literal> (0x0A) control characters):
|
|
<para><literal>
|
|
$GPRMC,134523.92,V,,,,,,,030136,,,N*73<CR><LF>$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45
|
|
</literal></para>
|
|
If the device sends a new <literal>$GPRMC</literal> three seconds later, the new <literal>$GPRMC</literal>
|
|
replaces the previously received <literal>$GPRMC</literal> sentence, and the updated
|
|
string would be:
|
|
<para><literal>
|
|
$GPRMC,134526.92,V,,,,,,,030136,,,N*76<CR><LF>$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45
|
|
</literal></para>
|
|
If the device then sends a <literal>$GPGSA</literal> sentence about 5 seconds later, the
|
|
<literal>$GPGSA</literal> sentence is added to the string (since no <literal>$GPGSA</literal> sentence was
|
|
obviously received in this session), the updated string would be:
|
|
<para><literal>
|
|
$GPRMC,134526.92,V,,,,,,,030136,,,N*76<CR><LF>$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45<CR><LF>$GPGSA,A,1,,,,,,,,,,,,,1.1,0.5,1.0*34
|
|
</literal></para>
|
|
The manager may discard any cached sentences older than 30 seconds.
|
|
</para>
|
|
<para>
|
|
This allows clients to read the latest positioning data as soon as
|
|
possible after they start, even if the device is not providing
|
|
frequent location data updates.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><link linkend="MM-MODEM-LOCATION-SOURCE-CDMA-BS:CAPS">MM_MODEM_LOCATION_SOURCE_CDMA_BS</link></term>
|
|
<listitem>
|
|
<para>
|
|
Devices supporting this
|
|
capability return a D-Bus dictionary (signature <literal>"a{sv}"</literal>) mapping well-known
|
|
keys to values with defined formats.
|
|
</para>
|
|
<para>
|
|
The allowed key/value pairs and their formats are:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry><term><literal>"latitude"</literal></term>
|
|
<listitem>
|
|
(Required) Latitude in Decimal Degrees (positive numbers mean N quadrasphere, negative mean S quadrasphere), given as a double value (signature <literal>"d"</literal>). e.g. <literal>38.889722</literal>, meaning 38d 53' 22" N.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>"longitude"</literal></term>
|
|
<listitem>
|
|
(Required) Longitude in Decimal Degrees (positive numbers mean E quadrasphere, negative mean W quadrasphere), given as a double value (signature <literal>"d"</literal>). e.g. <literal>-77.008889</literal>, meaning 77d 0' 32" W.
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
-->
|
|
<property name="Location" type="a{uv}" access="read" />
|
|
|
|
<!--
|
|
SuplServer:
|
|
|
|
SUPL server configuration for A-GPS, given either as IP:PORT or with a full URL.
|
|
-->
|
|
<property name="SuplServer" type="s" access="read" />
|
|
|
|
<!--
|
|
AssistanceDataServers:
|
|
|
|
URLs from where the user can download assistance data files to inject with
|
|
<link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Location.InjectAssistanceData">InjectAssistanceData()</link>.
|
|
-->
|
|
<property name="AssistanceDataServers" type="as" access="read" />
|
|
|
|
<!--
|
|
GpsRefreshRate:
|
|
|
|
Rate of refresh of the GPS information in the interface.
|
|
-->
|
|
<property name="GpsRefreshRate" type="u" access="read" />
|
|
|
|
</interface>
|
|
</node>
|