Please find attached a proposal for both a DBUS and Modem API for AGPS support.
There are some minor changes compared to the proposal from May 14, 2010.
This proposal introduces two AGPS features:
1) Fine time injection - the cellular modem has access to accurate timing
information that can help a GPS device to get a quicker fix. If the modem and
GPS device are separate components a handshake mechanism is required to forward
the timing information from the modem to the GPS. A typical approach is to have
a hardware signal between the modem and GPS device that can carry a timing
pulse. In addition signalling through software is required to request such
timing pulse and to associate the correct Universal Time with the generated
pulse.
2) Control Plane Assistance Data and Position Requests - The Mobile Network is
able to provide assistance data for GPS devices through the control plane. This
assistance data can help a GPS device to get a quicker fix. In addition the
control plane can be used by the Mobile Network to request a GPS enabled
Mobile Device for its location. This latter functionality is needed to meet
E911 requirements [1]. A typical sequence looks as follow:
Mobile Network Mobile Device
--- Assistance Data --->
--- Position Request -->
<-- Position Response --
[1] http://en.wikipedia.org/wiki/Enhanced_911
Cheers,
Waldo
Proposed DBUS API:
AgpsManager hierarchy
=====================
Service org.ofono
Interface org.ofono.AgpsManager
Object path [variable prefix]/{modem0,modem1,...}
Methods dict GetProperties()
Returns properties for the modem object. See
the properties section for available properties.
Possible Errors: [service].Error.InvalidArguments
void SetProperty(string name, variant value)
Changes the value of the specified property. Only
properties that are listed as read-write are
changeable. On success a PropertyChanged signal
will be emitted.
Possible Errors: [service].Error.InvalidArguments
[service].Error.DoesNotExist
void SendLCSFrame(string frametype, string framedata)
Send a LCS position protocol frame to the Mobile
Network. The LCS frame typically represents a
Position Response.
Valid frametypes are:
rrlp_measure_position_response
rrc_measurement_report
The raw frame data is formatted as the concatenated
sequence of the two digit hexadecimal representation
of each of its octets. Example: "00FC2345"
void RequestFineTimeInjection(string rat, uint16 pulselength)
Request modem to generate a fine time injection
pulse. pulselength is the duration of the pulse
expressed in radio frames.
rat specifies the access technology used to derive
the pulse from and can be "gsm" or "umts".
If the requested access technology is not currently
in use an error is returned.
Signals PropertyChanged(string name, variant value)
This signal indicates a changed value of the given
property.
IncomingLCSFrame(string frametypes, string framedata)
LCS positioning protocol frame received from the
Mobile Network.
Valid frametypes for the LCS frame are:
rrlp_assistance_data
rrlp_measure_position_request
rrc_assistance_data_delivery
rrc_measurement_control
Note that position/measurement requests can include
assistance data as well.
The raw frame data is formatted as the concatenated
sequence of the two digit hexadecimal representation
of each of its octets. Example: "00FC2345"
FineTimeInjectionNotification(dict radioframenumber)
Notification about fine time injection pulse
generated by modem. The radioframenumber dict
is defined as follow:
string AccessTechnology
"gsm" or "umts"
uint32 TdmaFrameNumber (gsm only)
range 0 - 2715647 (2048*26*51)
uint16 TdmaTimeslot (gsm only)
range 0 - 7
uint16 TimeslotBit (gsm only)
range 0 - 156
uint16 TimingAdvance (gsm only)
range 0 - 63
uint16 BcchArfcn (gsm only)
range 0 - 1023
uint16 Bsic (gsm only)
range 0 - 64
uint16 Sfn (umts only)
range 0 - 4095
string RrcState (umts only)
"cell_dch", "cell_fach", "cell_pch" or
"ura_pch"
uint16 RoundTripTime (umts only)
range 0 - 32766
Properties boolean LcsEnabled [readwrite]
If LcsEnabled is False, then no LCS positioning
protocol frames are received.
Proposed Modem driver API:
/*
*
* oFono - Open Source Telephony
*
* Copyright (C) 2008-2010 Intel Corporation. All rights reserved.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*
*/
#ifndef __OFONO_AGPS_H
#define __OFONO_AGPS_H
#ifdef __cplusplus
extern "C" {
#endif
#include <ofono/types.h>
struct ofono_agps;
enum ofono_lcs_frame_type {
RRLP_ASSISTANCE_DATA = 0, /* from modem */
/* Position request can include assistance data as well */
RRLP_MEASURE_POSITION_REQUEST = 1, /* from modem */
RRLP_MEASURE_POSITION_RESPONSE = 2, /* from GPS */
RRC_ASSISTANCE_DATA_DELIVERY = 3, /* from modem */
/* Measurement control can include assistance data as well */
RRC_MEASUREMENT_CONTROL = 4, /* from modem */
RRC_MEASUREMENT_REPORT = 5, /* frop GPS */
};
enum ofono_rrc_state {
RRC_CELL_PCH = 0,
RRC_CELL_FACH = 1,
RRC_CELL_DCH = 2,
RRC_URA_PCH = 3,
};
struct ofono_lcs_frame {
enum ofono_lcs_frame_type lcs_frame_type;
int frame_length; /* size of raw_frame in bytes */
unsigned char* raw_frame;
};
struct ofono_lcs_gsm_fn {
int TDMA_frame_number; /* range 0 - 2715647 (2048*26*51) */
int TDMA_timeslot; /* range 0 - 7 */
int timeslot_bit; /* range 0 - 156 */
int timing_advance; /* range 0 - 63 */
int bcch_arfcn; /* range 0 - 1023 */
int bsic; /* range 0 - 64 */
};
struct ofono_lcs_utran_fn {
int sfn; /* range 0 - 4095 */
int rrc_state; /* enum ofono_rrc_state */
int round_trip_time; /* range 0 - 32766 */
};
struct ofono_lcs_radio_fn {
int radio_access_technology; /* enum access_technology */
union {
struct ofono_lcs_gsm_fn gsm_frame_number;
struct ofono_lcs_utran_fn utran_frame_number;
};
};
typedef void (*ofono_agps_send_lcs_frame_cb_t)(const struct ofono_error *error,
void *data);
typedef void (*ofono_agps_inject_time_cb_t)(const struct ofono_error *error,
struct ofono_lcs_radio_fn *radio_frame_number,
void *data);
/* AGPS related functions, including LCS frame forwarding and fine time
injection
*/
struct ofono_agps_driver {
const char *name;
int (*probe)(struct ofono_agps *agps, unsigned int vendor,
void *data);
void (*remove)(struct ofono_agps *agps);
void (*receive_lcs_frames)(struct ofono_agps *agps, int enabled);
/* Assistance Data and Position Requests from the Mobile Network are
* signalled via the ofono_agps_lcs_frame_notify function and the
* oFono core to an external GPS manager. This GPS manager can reply
* to Position Requests with one or more Position Responses which
* are then send back to the modem via the send_lcs_frame function.
*/
void (*send_lcs_frame)(struct ofono_agps *agps,
struct ofono_lcs_frame *frame,
ofono_agps_send_lcs_frame_cb_t cb, void *data);
/* The GPS manager can ask the modem to generate a HW pulse (time
* stamp) with a defined length and the modem replies indicates when
* it generates the pulse. But as the modem has no precise idae of
* Universal Time, it indicates at which radio frame number it
* generated the pulse. The GPS manager which knows the link between
* Universal Time and the Radio Frame number knows very precisely at
* what time the pulse was generated and its duration.
*
* Timing accuracy is typically a few microseconds.
*/
void (*inject_time)(struct ofono_agps *agps,
int radio_access_technology, /* enum access_technology
*/
int pulse_length, /* duration of pulse in radio slots */
ofono_agps_inject_time_cb_t cb, void *data);
};
void ofono_agps_lcs_frame_notify(struct ofono_agps *agps,
struct ofono_lcs_frame frame);
int ofono_agps_driver_register(const struct ofono_agps_driver *d);
void ofono_agps_driver_unregister(const struct ofono_agps_driver *d);
struct ofono_agps *ofono_agps_create(struct ofono_modem *modem,
unsigned int vendor,
const char *driver,
void *data);
void ofono_agps_register(struct ofono_agps *agps);
void ofono_agps_remove(struct ofono_agps *agps);
void ofono_agps_set_data(struct ofono_agps *agps, void *data);
void *ofono_agps_get_data(struct ofono_agps *agps);
#ifdef __cplusplus
}
#endif
#endif /* __OFONO_AGPS_H */
AgpsManager hierarchy
=====================
Service org.ofono
Interface org.ofono.AgpsManager
Object path [variable prefix]/{modem0,modem1,...}
Methods dict GetProperties()
Returns properties for the modem object. See
the properties section for available properties.
Possible Errors: [service].Error.InvalidArguments
void SetProperty(string name, variant value)
Changes the value of the specified property. Only
properties that are listed as read-write are
changeable. On success a PropertyChanged signal
will be emitted.
Possible Errors: [service].Error.InvalidArguments
[service].Error.DoesNotExist
void SendLCSFrame(string frametype, string framedata)
Send a LCS position protocol frame to the Mobile
Network. The LCS frame typically represents a
Position Response.
Valid frametypes are:
rrlp_measure_position_response
rrc_measurement_report
The raw frame data is formatted as the concatenated
sequence of the two digit hexadecimal representation
of each of its octets. Example: "00FC2345"
void RequestFineTimeInjection(string rat, uint16 pulselength)
Request modem to generate a fine time injection
pulse. pulselength is the duration of the pulse
expressed in radio frames.
rat specifies the access technology used to derive
the pulse from and can be "gsm" or "umts".
If the requested access technology is not currently
in use an error is returned.
Signals PropertyChanged(string name, variant value)
This signal indicates a changed value of the given
property.
IncomingLCSFrame(string frametypes, string framedata)
LCS positioning protocol frame received from the
Mobile Network.
Valid frametypes for the LCS frame are:
rrlp_assistance_data
rrlp_measure_position_request
rrc_assistance_data_delivery
rrc_measurement_control
Note that position/measurement requests can include
assistance data as well.
The raw frame data is formatted as the concatenated
sequence of the two digit hexadecimal representation
of each of its octets. Example: "00FC2345"
FineTimeInjectionNotification(dict radioframenumber)
Notification about fine time injection pulse
generated by modem. The radioframenumber dict
is defined as follow:
string AccessTechnology
"gsm" or "umts"
uint32 TdmaFrameNumber (gsm only)
range 0 - 2715647 (2048*26*51)
uint16 TdmaTimeslot (gsm only)
range 0 - 7
uint16 TimeslotBit (gsm only)
range 0 - 156
uint16 TimingAdvance (gsm only)
range 0 - 63
uint16 BcchArfcn (gsm only)
range 0 - 1023
uint16 Bsic (gsm only)
range 0 - 64
uint16 Sfn (umts only)
range 0 - 4095
string RrcState (umts only)
"cell_dch", "cell_fach", "cell_pch" or
"ura_pch"
uint16 RoundTripTime (umts only)
range 0 - 32766
Properties boolean LcsEnabled [readwrite]
If LcsEnabled is False, then no LCS positioning
protocol frames are received.
/*
*
* oFono - Open Source Telephony
*
* Copyright (C) 2008-2010 Intel Corporation. All rights reserved.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*
*/
#ifndef __OFONO_AGPS_H
#define __OFONO_AGPS_H
#ifdef __cplusplus
extern "C" {
#endif
#include <ofono/types.h>
struct ofono_agps;
enum ofono_lcs_frame_type {
RRLP_ASSISTANCE_DATA = 0, /* from modem */
/* Position request can include assistance data as well */
RRLP_MEASURE_POSITION_REQUEST = 1, /* from modem */
RRLP_MEASURE_POSITION_RESPONSE = 2, /* from GPS */
RRC_ASSISTANCE_DATA_DELIVERY = 3, /* from modem */
/* Measurement control can include assistance data as well */
RRC_MEASUREMENT_CONTROL = 4, /* from modem */
RRC_MEASUREMENT_REPORT = 5, /* frop GPS */
};
enum ofono_rrc_state {
RRC_CELL_PCH = 0,
RRC_CELL_FACH = 1,
RRC_CELL_DCH = 2,
RRC_URA_PCH = 3,
};
struct ofono_lcs_frame {
enum ofono_lcs_frame_type lcs_frame_type;
int frame_length; /* size of raw_frame in bytes */
unsigned char* raw_frame;
};
struct ofono_lcs_gsm_fn {
int TDMA_frame_number; /* range 0 - 2715647 (2048*26*51) */
int TDMA_timeslot; /* range 0 - 7 */
int timeslot_bit; /* range 0 - 156 */
int timing_advance; /* range 0 - 63 */
int bcch_arfcn; /* range 0 - 1023 */
int bsic; /* range 0 - 64 */
};
struct ofono_lcs_utran_fn {
int sfn; /* range 0 - 4095 */
int rrc_state; /* enum ofono_rrc_state */
int round_trip_time; /* range 0 - 32766 */
};
struct ofono_lcs_radio_fn {
int radio_access_technology; /* enum access_technology */
union {
struct ofono_lcs_gsm_fn gsm_frame_number;
struct ofono_lcs_utran_fn utran_frame_number;
};
};
typedef void (*ofono_agps_send_lcs_frame_cb_t)(const struct ofono_error *error,
void *data);
typedef void (*ofono_agps_inject_time_cb_t)(const struct ofono_error *error,
struct ofono_lcs_radio_fn *radio_frame_number,
void *data);
/* AGPS related functions, including LCS frame forwarding and fine time
injection
*/
struct ofono_agps_driver {
const char *name;
int (*probe)(struct ofono_agps *agps, unsigned int vendor,
void *data);
void (*remove)(struct ofono_agps *agps);
void (*receive_lcs_frames)(struct ofono_agps *agps, int enabled);
/* Assistance Data and Position Requests from the Mobile Network are
* signalled via the ofono_agps_lcs_frame_notify function and the
* oFono core to an external GPS manager. This GPS manager can reply
* to Position Requests with one or more Position Responses which
* are then send back to the modem via the send_lcs_frame function.
*/
void (*send_lcs_frame)(struct ofono_agps *agps,
struct ofono_lcs_frame *frame,
ofono_agps_send_lcs_frame_cb_t cb, void *data);
/* The GPS manager can ask the modem to generate a HW pulse (time
* stamp) with a defined length and the modem replies indicates when
* it generates the pulse. But as the modem has no precise idae of
* Universal Time, it indicates at which radio frame number it
* generated the pulse. The GPS manager which knows the link between
* Universal Time and the Radio Frame number knows very precisely at
* what time the pulse was generated and its duration.
*
* Timing accuracy is typically a few microseconds.
*/
void (*inject_time)(struct ofono_agps *agps,
int radio_access_technology, /* enum access_technology
*/
int pulse_length, /* duration of pulse in radio slots */
ofono_agps_inject_time_cb_t cb, void *data);
};
void ofono_agps_lcs_frame_notify(struct ofono_agps *agps,
struct ofono_lcs_frame frame);
int ofono_agps_driver_register(const struct ofono_agps_driver *d);
void ofono_agps_driver_unregister(const struct ofono_agps_driver *d);
struct ofono_agps *ofono_agps_create(struct ofono_modem *modem,
unsigned int vendor,
const char *driver,
void *data);
void ofono_agps_register(struct ofono_agps *agps);
void ofono_agps_remove(struct ofono_agps *agps);
void ofono_agps_set_data(struct ofono_agps *agps, void *data);
void *ofono_agps_get_data(struct ofono_agps *agps);
#ifdef __cplusplus
}
#endif
#endif /* __OFONO_AGPS_H */
_______________________________________________
ofono mailing list
ofono@ofono.org
http://lists.ofono.org/listinfo/ofono
