Documentation/Maemo 5 Developer Guide/Using Connectivity Components/Using Location API

m (Liblocation signals and callbacks)
(wiify slightly)
 
(9 intermediate revisions not shown)
Line 1: Line 1:
-
=Using Location API=
+
Location framework provides a library called liblocation which is used for developing location aware applications in [[Open development/Maemo roadmap/Fremantle|Fremantle]]. Liblocation supports internal GPS, network based methods and external bluetooth GPS.
-
Location framework provides a library called liblocation which is used for developing location aware applications in Fremantle. Liblocation supports internal GPS, network based methods and external bluetooth GPS.
+
-
 
+
==Using liblocation==
==Using liblocation==
-
To start implementing applications using liblocation API, you have to include the following headers.
 
-
#include <location/location-gps-device.h>
 
-
#include <location/location-gpsd-control.h>
 
-
Liblocation has two public ''GObjects''. ''LocationGPSDControl'' is used for starting and stopping of location services, setting location method and interval, and listening for errors. ''LocationGPSDevice'' has information about device status and contains the actual fix when one exists. The two ''GObjects'' are initiated as follows.
+
To start implementing applications using liblocation API, you have to include the following headers:
-
LocationGPSDControl *control = location_gpsd_control_get_default();
+
 
-
LocationGPSDevice *device = g_object_new(LOCATION_TYPE_GPS_DEVICE, NULL);
+
<source lang="c">
 +
#include <location/location-gps-device.h>
 +
#include <location/location-gpsd-control.h>
 +
</source>
 +
 
 +
Liblocation has two public <code>GObject</code>s. <code>LocationGPSDControl</code> is used for starting and stopping of location services, setting location method and interval, and listening for errors. <code>LocationGPSDevice</code> has information about device status and contains the actual fix when one exists. The two <code>GObject</code>s are initiated as follows:
 +
<source lang="c">
 +
LocationGPSDControl *control = location_gpsd_control_get_default();
 +
LocationGPSDevice *device = g_object_new(LOCATION_TYPE_GPS_DEVICE, NULL);
 +
</source>
==Location methods==
==Location methods==
-
Liblocation supports the following location methods which are defined in location-gpsd-control.h.
 
-
*'''LOCATION_METHOD_USER_SELECTED:''' Liblocation will choose the best possible location method based on location settings in control panel. You can think of it as asking all the methods CWP+ACWP+GNSS+AGNSS. Choose this method if you don't have any special needs.
 
-
*'''LOCATION_METHOD_CWP - Complementary Wireless Positioning:''' This method provides either coordinates for center of current country with horizontal accuracy equalling radius of the country (MCC fix), or coordinates based on currently used GSM base station. Latter is used if such information exists in device's cache, which is updated when ACWP method is used. SIM card is needed for CWP method.
 
-
*'''LOCATION_METHOD_ACWP - Assisted Complementary Wireless Positioning:''' A method where device is located based on cellular base station to which device is registered to. SIM card and a network connection is needed for ACWP method. If no network connection is available, this equals to CWP. Application might receive MCC fixes before base station information from external location server is fetched and as a fallback if e.g. network is temporary unavailable.
 
-
*'''LOCATION_METHOD_GNSS - Global Navigation Satellite System:''' A method for using GPS receiver. Typically time for the first fix is significantly longer than with AGNSS. Neither SIM card nor network connection is needed for GNSS method, and GNSS can even be used in offline mode.
 
-
*'''LOCATION_METHOD_AGNSS - Assisted Global Navigation Satellite System''' A method for using GPS receiver with assistance data from external location server. A SIM card and a network connection is needed for AGNSS method. If no network connection or SIM card is available, this equals to GNSS.
 
-
Location resources are shared between applications, and applications can request different location methods. Fixes for all requested methods are sent for all applications listening to liblocation "changed" signal, therefore application should judge whether fix it is receiving, is one that it needs. See [[#LocationGPSDevice and LocationGPSDeviceFix|LocationGPSDeviceFix]] section for discussion.
+
Liblocation supports the following location methods which are defined in <code>location-gpsd-control.h</code>.
 +
* <code>LOCATION_METHOD_USER_SELECTED</code>: Liblocation will choose the best possible location method based on location settings in control panel. You can think of it as asking all the methods CWP+ACWP+GNSS+AGNSS. Choose this method if you don't have any special needs.
 +
* <code>LOCATION_METHOD_CWP</code> - Complementary Wireless Positioning: This method provides either coordinates for center of current country with horizontal accuracy equalling radius of the country (MCC fix), or coordinates based on currently used GSM base station. Latter is used if such information exists in device's cache, which is updated when ACWP method is used. SIM card is needed for CWP method.
 +
* <code>LOCATION_METHOD_ACWP</code> - Assisted Complementary Wireless Positioning: A method where device is located based on cellular base station to which device is registered to. SIM card and a network connection is needed for ACWP method. If no network connection is available, this equals to CWP. Application might receive MCC fixes before base station information from external location server is fetched and as a fallback if e.g. network is temporary unavailable.
 +
* <code>LOCATION_METHOD_GNSS</code> - Global Navigation Satellite System: A method for using GPS receiver. Typically time for the first fix is significantly longer than with AGNSS. Neither SIM card nor network connection is needed for GNSS method, and GNSS can even be used in offline mode.
 +
* <code>LOCATION_METHOD_AGNSS</code> - Assisted Global Navigation Satellite System. A method for using GPS receiver with assistance data from external location server. A SIM card and a network connection is needed for AGNSS method. If no network connection or SIM card is available, this equals to GNSS.
-
If device is set for bluetooth GPS from control panel, it can used for locationing via USER_SELECTED, AGNSS and GNSS methods. In this case AGNSS and GNSS do not differ, because assistance server cannot be utilized.
+
Location resources are shared between applications, and applications can request different location methods. Fixes for all requested methods are sent for all applications listening to liblocation <code>changed</code> signal, therefore application should judge whether fix it is receiving, is one that it needs. See [[#LocationGPSDevice and LocationGPSDeviceFix|LocationGPSDeviceFix]] section for discussion.
 +
 
 +
If device is set for bluetooth GPS from control panel, it can used for locationing via <code>USER_SELECTED</code>, <code>AGNSS</code> and <code>GNSS</code> methods. In this case AGNSS and GNSS do not differ, because assistance server cannot be utilized.
Device caches cell information for ACWP and satellite information for AGNSS. Hence if a non-assisted location method is used immediately after it's assisted counterpart, it will probably work as the assisted one.
Device caches cell information for ACWP and satellite information for AGNSS. Hence if a non-assisted location method is used immediately after it's assisted counterpart, it will probably work as the assisted one.
-
Location method is set as ''LocationGPSDControl'''s "preferred-method" property. Several methods can be given by bitwise or'ing the method identifiers:
+
Location method is set as <code>LocationGPSDControl</code>'s <code>preferred-method</code> property. Several methods can be given by bitwise or'ing the method identifiers:
 +
<source lang="c">
  g_object_set(G_OBJECT(control), "preferred-method", LOCATION_METHOD_GNSS | LOCATION_METHOD_AGNSS, NULL);
  g_object_set(G_OBJECT(control), "preferred-method", LOCATION_METHOD_GNSS | LOCATION_METHOD_AGNSS, NULL);
 +
</source>
-
ACWP and AGNSS methods require network positioning and GNSS and AGNSS require GPS to be enabled in location settings. If requirements for asked methods are not enabled when starting location, user is prompted a dialog to enable them. After that all the possible preferred-methods are started. If there isn't any, an error to application is signalled.
+
ACWP and AGNSS methods require network positioning and GNSS and AGNSS require GPS to be enabled in location settings. If requirements for asked methods are not enabled when starting location, user is prompted a dialog to enable them. After that all the possible preferred-methods are started. If there is not any, an error to application is signalled.
-
USER_SELECTED method makes expection to dialog rule. Albeit it uses all of the methods: CWP+ACWP+GNSS+AGNSS, dialog is shown only if both networking and gps are disabled.
+
<code>USER_SELECTED</code> method makes exception to dialog rule. Albeit it uses all of the methods: CWP+ACWP+GNSS+AGNSS, dialog is shown only if both networking and gps are disabled.
If user changes location settings during location session, then used location method is modified to best available accordingly, and error signalled if none is available.
If user changes location settings during location session, then used location method is modified to best available accordingly, and error signalled if none is available.
Line 39: Line 46:
Here is table that summarizes differences between the methods. Accuracy refers to horizontal accuracy of the fix.
Here is table that summarizes differences between the methods. Accuracy refers to horizontal accuracy of the fix.
-
{| class="wikitable" style="margin: 1em auto 1em auto"
+
{| class="wikitable"
-
! Method !! Typ Accuracy !! Req SIM !! Req NW !! Drains Bat
+
|+
 +
Available location methods
|-
|-
-
| CWP || 1km-1000km || Yes || No || No
+
! Method !! Typical Accuracy !! Requires SIM !! Requires Network !! Drains Battery
|-
|-
-
| ACWP || 1km-10km || Yes || Yes || No
+
| CWP || 1-1000 km || Yes || No || No
|-
|-
-
| GNSS || 1m-100m || No || No || Yes
+
| ACWP || 1-10 km || Yes || Yes || No
|-
|-
-
| AGNSS || 1m-100m || Yes || Yes || Yes
+
| GNSS || 5-100m || No || No || Yes
 +
|-
 +
| AGNSS || 5-100m || Yes || Yes || Yes
|}
|}
==Location intervals==
==Location intervals==
-
Liblocation supports a default interval (equals to one second) and intervals of 1, 2, 5, 10, 20, 30, 60 and 120 seconds between fixes. These are defined in location-gpsd-control.h. Due to performance and power consumption reasons, all the intervals provide fixes only if position of the device has changed. Therefore the interval reflects more how often device checks for coordinate changes, than the actual interval between fixes. Nature of GPS fixes being constantly changing guarantees that GPS fixes are provided with requested interval. However, if there are several applications using different intervals, then the used interval is the minimum of intervals requested by all applications.
 
-
Location interval is set as ''LocationGPSDControl'''s "preferred-interval" property:
+
Liblocation supports a default interval (equals to one second) and intervals of 1, 2, 5, 10, 20, 30, 60 and 120 seconds between fixes. These are defined in <code>location-gpsd-control.h</code>. Due to performance and power consumption reasons, all the intervals provide fixes only if position of the device has changed. Therefore the interval reflects more how often device checks for coordinate changes, than the actual interval between fixes. Nature of GPS fixes being constantly changing guarantees that GPS fixes are provided with requested interval. However, if there are several applications using different intervals, then the used interval is the minimum of intervals requested by all applications.
-
g_object_set(G_OBJECT(control), "preferred-interval", LOCATION_INTERVAL_60S, NULL);
+
Location interval is set as <code>LocationGPSDControl</code>'s "preferred-interval" property:
 +
 
 +
<source lang="c">
 +
g_object_set(G_OBJECT(control), "preferred-interval", LOCATION_INTERVAL_60S, NULL);
 +
</source>
==LocationGPSDevice and LocationGPSDeviceFix==
==LocationGPSDevice and LocationGPSDeviceFix==
-
LocationGPSDevice object has the following public fields:
 
-
*gboolean online: Whether there is a connection to the hardware
 
-
*LocationGPSDeviceStatus status: Status of the device
 
-
*LocationGPSDeviceFix *fix: The actual fix (latitude, longitude, etc)
 
-
*int satellites_in_view: Number of satellites in view
 
-
*int satellites_in_use: Number of satellites in use
 
-
*GPtrArray *satellites: Array of satellites
 
-
*LocationCellInfo *cell_info: Information about cell the device is connected to
 
 +
<code>LocationGPSDevice</code> object has the following public fields:
 +
* <code>gboolean online</code>: Whether there is a connection to the hardware
 +
* <code>LocationGPSDeviceStatus status</code>: Status of the device
 +
* <code>LocationGPSDeviceFix *fix</code>: The actual fix (latitude, longitude, etc)
 +
* <code>int satellites_in_view</code>: Number of satellites in view
 +
* <code>int satellites_in_use</code>: Number of satellites in use
 +
* <code>GPtrArray *satellites</code>: Array of satellites
 +
* <code>LocationCellInfo *cell_info</code>: Information about cell the device is connected to
-
The most useful field is naturally "fix" which contains position and movement of the device and accuracies for them. ''LocationGPSDeviceFix'' fields are listed below. In parenthesis there is a identifier which can be bitwisely anded with "fields" field, to see whether corresponding field is set.
+
The most useful field is naturally "fix" which contains position and movement of the device and accuracies for them. "<code>LocationGPSDeviceFix</code>" fields are listed in the table below. In "Fields Flag" column there is a identifier which can be bitwisely anded with "fields" field, to see whether corresponding field is set.
 +
{| class="wikitable"
 +
|+LocationGPSDeviceFix
 +
! Variable !! colspan="3" | Description
 +
|-
 +
| <code>mode</code> || colspan="3" | Mode of the fix (2D, 3D, not seen or no fix)
 +
|-
 +
| <code>fields</code> || colspan="3" | Bitfield representing what fields contain valid data
 +
|-
 +
! Variable !! Unit !! Description !! Fields Flag
 +
|-
 +
| <code>time</code> || s || Timestamp of the update || <code>LOCATION_GPS_DEVICE_TIME_SET</code>
 +
|-
 +
| <code>ept</code> || s || Time accuracy ||
 +
|-
 +
| <code>latitude</code> || degrees || Fix latitude || <code>LOCATION_GPS_DEVICE_LATLONG_SET</code>
 +
|-
 +
| <code>longitude</code> || degrees || Fix longitude || <code>LOCATION_GPS_DEVICE_LATLONG_SET</code>
 +
|-
 +
| <code>eph</code> || cm || Horizontal position accuracy ||
 +
|-
 +
| <code>altitude</code> || m || Fix altitude || <code>LOCATION_GPS_DEVICE_ALTITUDE_SET</code>
 +
|-
 +
| <code>epv</code> || m ||  Altitude accuracy ||
 +
|-
 +
| <code>track</code> || degrees || Direction of motion || <code>LOCATION_GPS_DEVICE_TRACK_SET</code>
 +
|-
 +
| <code>epd</code> || degrees || Track accuracy ||
 +
|-
 +
| <code>speed</code> || km/h || Current speed || <code>LOCATION_GPS_DEVICE_SPEED_SET</code>
 +
|-
 +
| <code>eps</code> || km/h || Speed accuracy ||
 +
|-
 +
| <code>climb</code> || m/s || Current rate of climb || <code>LOCATION_GPS_DEVICE_CLIMB_SET</code>
 +
|-
 +
| <code>epc || m/s || Climb accuracy ||
 +
|}
-
*LocationGPSDeviceMode mode: The mode of the fix
+
The units for epv, epd, eps and epc might be different in liblocation version 0.99-1 and older.
-
*guint32 fields: A bitfield representing what fields contain valid data
+
-
*double time: The timestamp of the update (LOCATION_GPS_DEVICE_TIME_SET)
+
-
*double ept: Time accuracy
+
-
*double latitude: Fix latitude (LOCATION_GPS_DEVICE_LATLONG_SET)
+
-
*double longitude: Fix longitude (LOCATION_GPS_DEVICE_LATLONG_SET)
+
-
*double eph: Horizontal position accuracy
+
-
*double altitude: Fix altitude in meters (LOCATION_GPS_DEVICE_ALTITUDE_SET)
+
-
*double epv: Vertical position accuracy
+
-
*double track: Direction of motion in degrees (LOCATION_GPS_DEVICE_TRACK_SET)
+
-
*double epd: Track accuracy
+
-
*double speed: Current speed in km/h (LOCATION_GPS_DEVICE_SPEED_SET)
+
-
*double eps: Speed accuracy
+
-
*double climb: Current rate of climb in m/s (LOCATION_GPS_DEVICE_CLIMB_SET)
+
-
*double epc: Climb accuracy
+
 +
An application receiving a fix cannot know if the fix is a result from location method it requested. Therefore application should study whether fix is accurate enough to satisfy application's needs. This can be done by inspecting "eph" field, which is fix's horizontal accuracy in centimeters. Typical values for horizontal accuracies can be seen in the location methods table. If accuracy is not known, it has a value of <code>NaN</code>.
-
An application receiving a fix cannot know if the fix is a result from location method it requested. Therefore application should study whether fix is accurate enough to satisfy application's needs. This can be done by inspecting "eph" field, which is fix's horizontal accuracy in centimeters. Typical values for horizontal accuracies can be seen in the location methods table. If accuracy is not known, it has a value of NaN.
+
==Liblocation signals and callbacks==
-
 
+
The most useful signal in liblocation is <code>LocationGPSDevice</code>'s <code>changed</code> signal, which is emitted everytime a new fix is received. <code>LocationGPSDControl</code> has an <code>error-verbose</code> signal which is emitted in case of an error. There is also a legacy signal <code>error</code>, which doesn't give a reason for error.
-
==Liblocation signals and callbacks==
+
-
The most useful signal in liblocation is ''LocationGPSDevice'''s "changed" signal, which is emitted everytime a new fix is received. ''LocationGPSDControl'' has an "error-verbose" signal which is emitted in case of an error. There is also a legacy signal "error", which doesn't give a reason for error.
+
You can connect to these signals in the usual way:
You can connect to these signals in the usual way:
-
g_signal_connect(control, "error-verbose", G_CALLBACK(on_error), user_data);
+
<source lang="c">
-
g_signal_connect(device,  "changed", G_CALLBACK(on_changed), user_data);
+
g_signal_connect(control, "error-verbose", G_CALLBACK(on_error), user_data);
 +
g_signal_connect(device,  "changed", G_CALLBACK(on_changed), user_data);
 +
</source>
-
Below are examples for these signals' callbacks.
+
Below are examples for these signals' callbacks:
-
static void on_error(LocationGPSDControl *control, LocationGPSDControlError error, gpointer user_data)
+
-
{
+
-
  switch (error) {
+
-
  case LOCATION_ERROR_USER_REJECTED_DIALOG:
+
-
    g_debug("User didn't enable requested methods");
+
-
    break;
+
-
  case LOCATION_ERROR_USER_REJECTED_SETTINGS:
+
-
    g_debug("User changed settings, which disabled location");
+
-
    break;
+
-
  case LOCATION_ERROR_BT_GPS_NOT_AVAILABLE:
+
-
    g_debug("Problems with BT GPS");
+
-
    break;
+
-
  case LOCATION_ERROR_METHOD_NOT_ALLOWED_IN_OFFLINE_MODE:
+
-
    g_debug("Requested method is not allowed in offline mode");
+
-
    break;
+
-
  case LOCATION_ERROR_SYSTEM:
+
-
    g_debug("System error");
+
-
    break;
+
-
  }
+
-
}
+
-
static void on_changed(LocationGPSDevice *device, gpointer user_data)
+
<source lang="c">
-
{
+
static void on_error(LocationGPSDControl *control, LocationGPSDControlError error, gpointer user_data)
-
  if (!device)
+
{  
-
    return;
+
  switch (error) {
-
+
  case LOCATION_ERROR_USER_REJECTED_DIALOG:
-
  if (device->fix) {
+
    g_debug("User didn't enable requested methods");
-
    if (device->fix->fields & LOCATION_GPS_DEVICE_LATLONG_SET)
+
    break;
-
      g_debug("lat = %f, long = %f", device->fix->latitude, device->fix->longitude);
+
  case LOCATION_ERROR_USER_REJECTED_SETTINGS:
-
+
    g_debug("User changed settings, which disabled location");
-
    if (device->fix->fields & LOCATION_GPS_DEVICE_ALTITUDE_SET)
+
    break;
-
      g_debug("alt = %f", device->fix->altitude);
+
  case LOCATION_ERROR_BT_GPS_NOT_AVAILABLE:
-
   
+
    g_debug("Problems with BT GPS");
-
    g_debug("horizontal accuracy: %f meters", device->fix->eph/100);
+
    break;
-
  }
+
  case LOCATION_ERROR_METHOD_NOT_ALLOWED_IN_OFFLINE_MODE:
-
+
    g_debug("Requested method is not allowed in offline mode");
-
  if (device && device->cell_info) {
+
    break;
-
    if (device->cell_info->flags & LOCATION_CELL_INFO_GSM_CELL_INFO_SET)
+
  case LOCATION_ERROR_SYSTEM:
-
      g_debug("Mobile Country Code GSM: %d", device->cell_info->gsm_cell_info.mcc);
+
    g_debug("System error");
-
+
    break;
-
    if (device->cell_info->flags & LOCATION_CELL_INFO_WCDMA_CELL_INFO_SET)
+
  }
-
      g_debug("Mobile Country Code WCDMA: %d", device->cell_info->wcdma_cell_info.mcc);
+
}
-
  }
+
-
 
+
-
  g_debug("Satellites in view: %d, in use: %d", device->satellites_in_view, device->satellites_in_use);
+
-
}  
+
-
Liblocation sends a "changed" signal also after locationing is started or stopped, in which case a last known fix is sent if such exists. Application can differentiate these fixes from real ones by inspecting device->status field which equals LOCATION_GPS_DEVICE_STATUS_NO_FIX if the fix is not real.
+
static void on_changed(LocationGPSDevice *device, gpointer user_data)
 +
{
 +
  if (!device)
 +
    return;
 +
 
 +
  if (device->fix) {
 +
    if (device->fix->fields & LOCATION_GPS_DEVICE_LATLONG_SET)
 +
      g_debug("lat = %f, long = %f", device->fix->latitude, device->fix->longitude);
 +
 
 +
    if (device->fix->fields & LOCATION_GPS_DEVICE_ALTITUDE_SET)
 +
      g_debug("alt = %f", device->fix->altitude);
 +
 
 +
    g_debug("horizontal accuracy: %f meters", device->fix->eph/100);
 +
  }
 +
 
 +
  if (device && device->cell_info) {
 +
    if (device->cell_info->flags & LOCATION_CELL_INFO_GSM_CELL_INFO_SET)
 +
      g_debug("Mobile Country Code GSM: %d", device->cell_info->gsm_cell_info.mcc);
 +
 
 +
    if (device->cell_info->flags & LOCATION_CELL_INFO_WCDMA_CELL_INFO_SET)
 +
      g_debug("Mobile Country Code WCDMA: %d", device->cell_info->wcdma_cell_info.mcc);
 +
  }
 +
 
 +
  g_debug("Satellites in view: %d, in use: %d", device->satellites_in_view, device->satellites_in_use);
 +
}
 +
</source>
 +
 
 +
Liblocation sends a <code>changed</code> signal also after locationing is started or stopped, in which case a last known fix is sent if such exists. Application can differentiate these fixes from real ones by inspecting <code>device->status</code> field which equals <code>LOCATION_GPS_DEVICE_STATUS_NO_FIX</code> if the fix is not real.
==Starting and stopping locationing==
==Starting and stopping locationing==
 +
Finally after everything above has been done, locationing can be started.
Finally after everything above has been done, locationing can be started.
-
location_gpsd_control_start(control);
+
<source lang="c">
 +
location_gpsd_control_start(control);
 +
</source>
If the chosen location method violates control panel location settings, then a dialog is shown to user. Dialogs ask user to enable necessary services. On user's refusal an error to application is sent. If no error is seen, fixes should be coming after a while. When locationing is no longer needed, it can be stopped.
If the chosen location method violates control panel location settings, then a dialog is shown to user. Dialogs ask user to enable necessary services. On user's refusal an error to application is sent. If no error is seen, fixes should be coming after a while. When locationing is no longer needed, it can be stopped.
-
location_gpsd_control_stop(control);
 
 +
<source lang="c">
 +
location_gpsd_control_stop(control);
 +
</source>
==Complete example==
==Complete example==
 +
Here is a complete standalone example using liblocation. It starts location services after program is started, then when first fix arrives, prints it, stops services, and shutdowns.
Here is a complete standalone example using liblocation. It starts location services after program is started, then when first fix arrives, prints it, stops services, and shutdowns.
-
#include <location/location-gps-device.h>
+
 
-
#include <location/location-gpsd-control.h>
+
<source lang="c">
-
+
#include <location/location-gps-device.h>
-
static void on_error(LocationGPSDControl *control, gpointer data)
+
#include <location/location-gpsd-control.h>
-
{  
+
 
-
g_debug("location error... quitting");
+
static void on_error(LocationGPSDControl *control, LocationGPSDControlError error, gpointer data)
-
g_main_loop_quit((GMainLoop *) data);
+
{  
-
}
+
g_debug("location error: %d... quitting", error);
-
+
g_main_loop_quit((GMainLoop *) data);
-
static void on_changed(LocationGPSDevice *device, gpointer data)
+
}
-
{
+
 
-
if (!device)
+
static void on_changed(LocationGPSDevice *device, gpointer data)
-
return;
+
{
-
+
if (!device)
-
if (device->fix) {
+
return;
-
if (device->fix->fields & LOCATION_GPS_DEVICE_LATLONG_SET) {
+
 
-
g_debug("lat = %f, long = %f", device->fix->latitude, device->fix->longitude);
+
if (device->fix) {
-
location_gpsd_control_stop((LocationGPSDControl *) data);
+
if (device->fix->fields & LOCATION_GPS_DEVICE_LATLONG_SET) {
-
}
+
g_debug("lat = %f, long = %f", device->fix->latitude, device->fix->longitude);
-
}
+
location_gpsd_control_stop((LocationGPSDControl *) data);
-
}  
+
}
-
+
}
-
static void on_stop(LocationGPSDControl *control, gpointer data)
+
}  
-
{
+
 
-
g_debug("quitting");
+
static void on_stop(LocationGPSDControl *control, gpointer data)
-
g_main_loop_quit((GMainLoop *) data);
+
{
-
}  
+
g_debug("quitting");
-
+
g_main_loop_quit((GMainLoop *) data);
-
static gboolean start_location(gpointer data)
+
}  
-
{
+
 
-
location_gpsd_control_start((LocationGPSDControl *) data);
+
static gboolean start_location(gpointer data)
-
return FALSE;
+
{
-
}
+
location_gpsd_control_start((LocationGPSDControl *) data);
-
+
return FALSE;
-
int main(int argc, char *argv[])
+
}
-
{
+
 
-
LocationGPSDControl *control;
+
int main(int argc, char *argv[])
-
LocationGPSDevice *device;
+
{
-
GMainLoop *loop;
+
LocationGPSDControl *control;
-
+
LocationGPSDevice *device;
-
g_type_init();
+
GMainLoop *loop;
-
+
 
-
loop = g_main_loop_new(NULL, FALSE);
+
g_type_init();
-
+
 
-
control = location_gpsd_control_get_default();
+
loop = g_main_loop_new(NULL, FALSE);
-
device = g_object_new(LOCATION_TYPE_GPS_DEVICE, NULL);
+
 
-
+
control = location_gpsd_control_get_default();
-
g_object_set(G_OBJECT(control),
+
device = g_object_new(LOCATION_TYPE_GPS_DEVICE, NULL);
-
"preferred-method", LOCATION_METHOD_USER_SELECTED,
+
 
-
"preferred-interval", LOCATION_INTERVAL_DEFAULT,
+
g_object_set(G_OBJECT(control),
-
NULL);
+
"preferred-method", LOCATION_METHOD_USER_SELECTED,
-
+
"preferred-interval", LOCATION_INTERVAL_DEFAULT,
-
g_signal_connect(control, "error", G_CALLBACK(on_error), loop);
+
NULL);
-
g_signal_connect(device, "changed", G_CALLBACK(on_changed), control);
+
 
-
g_signal_connect(control, "gpsd-stopped", G_CALLBACK(on_stop), loop);
+
g_signal_connect(control, "error-verbose", G_CALLBACK(on_error), loop);
-
+
g_signal_connect(device, "changed", G_CALLBACK(on_changed), control);
-
g_idle_add(start_location, control);
+
g_signal_connect(control, "gpsd-stopped", G_CALLBACK(on_stop), loop);
-
+
 
-
g_main_loop_run(loop);
+
g_idle_add(start_location, control);
-
+
 
-
g_object_unref(device);
+
g_main_loop_run(loop);
-
g_object_unref(control);
+
 
-
+
g_object_unref(device);
-
return 0;
+
g_object_unref(control);
-
}
+
 
 +
return 0;
 +
}
 +
</source>
You can compile this example with following command:
You can compile this example with following command:
-
  gcc -Wall `pkg-config --cflags gl
+
  gcc -Wall `pkg-config --cflags --libs liblocation` -o test test.c
 +
 
 +
[[Category:Development]]
 +
[[Category:Documentation]]
 +
[[Category:Fremantle]]

Latest revision as of 13:42, 1 March 2011

Location framework provides a library called liblocation which is used for developing location aware applications in Fremantle. Liblocation supports internal GPS, network based methods and external bluetooth GPS.

Contents

[edit] Using liblocation

To start implementing applications using liblocation API, you have to include the following headers:

#include <location/location-gps-device.h>
#include <location/location-gpsd-control.h>

Liblocation has two public GObjects. LocationGPSDControl is used for starting and stopping of location services, setting location method and interval, and listening for errors. LocationGPSDevice has information about device status and contains the actual fix when one exists. The two GObjects are initiated as follows:

LocationGPSDControl *control = location_gpsd_control_get_default();
LocationGPSDevice *device = g_object_new(LOCATION_TYPE_GPS_DEVICE, NULL);

[edit] Location methods

Liblocation supports the following location methods which are defined in location-gpsd-control.h.

  • LOCATION_METHOD_USER_SELECTED: Liblocation will choose the best possible location method based on location settings in control panel. You can think of it as asking all the methods CWP+ACWP+GNSS+AGNSS. Choose this method if you don't have any special needs.
  • LOCATION_METHOD_CWP - Complementary Wireless Positioning: This method provides either coordinates for center of current country with horizontal accuracy equalling radius of the country (MCC fix), or coordinates based on currently used GSM base station. Latter is used if such information exists in device's cache, which is updated when ACWP method is used. SIM card is needed for CWP method.
  • LOCATION_METHOD_ACWP - Assisted Complementary Wireless Positioning: A method where device is located based on cellular base station to which device is registered to. SIM card and a network connection is needed for ACWP method. If no network connection is available, this equals to CWP. Application might receive MCC fixes before base station information from external location server is fetched and as a fallback if e.g. network is temporary unavailable.
  • LOCATION_METHOD_GNSS - Global Navigation Satellite System: A method for using GPS receiver. Typically time for the first fix is significantly longer than with AGNSS. Neither SIM card nor network connection is needed for GNSS method, and GNSS can even be used in offline mode.
  • LOCATION_METHOD_AGNSS - Assisted Global Navigation Satellite System. A method for using GPS receiver with assistance data from external location server. A SIM card and a network connection is needed for AGNSS method. If no network connection or SIM card is available, this equals to GNSS.

Location resources are shared between applications, and applications can request different location methods. Fixes for all requested methods are sent for all applications listening to liblocation changed signal, therefore application should judge whether fix it is receiving, is one that it needs. See LocationGPSDeviceFix section for discussion.

If device is set for bluetooth GPS from control panel, it can used for locationing via USER_SELECTED, AGNSS and GNSS methods. In this case AGNSS and GNSS do not differ, because assistance server cannot be utilized.

Device caches cell information for ACWP and satellite information for AGNSS. Hence if a non-assisted location method is used immediately after it's assisted counterpart, it will probably work as the assisted one.

Location method is set as LocationGPSDControl's preferred-method property. Several methods can be given by bitwise or'ing the method identifiers:

 g_object_set(G_OBJECT(control), "preferred-method", LOCATION_METHOD_GNSS | LOCATION_METHOD_AGNSS, NULL);

ACWP and AGNSS methods require network positioning and GNSS and AGNSS require GPS to be enabled in location settings. If requirements for asked methods are not enabled when starting location, user is prompted a dialog to enable them. After that all the possible preferred-methods are started. If there is not any, an error to application is signalled.

USER_SELECTED method makes exception to dialog rule. Albeit it uses all of the methods: CWP+ACWP+GNSS+AGNSS, dialog is shown only if both networking and gps are disabled.

If user changes location settings during location session, then used location method is modified to best available accordingly, and error signalled if none is available.

Here is table that summarizes differences between the methods. Accuracy refers to horizontal accuracy of the fix.

Available location methods
Method Typical Accuracy Requires SIM Requires Network Drains Battery
CWP 1-1000 km Yes No No
ACWP 1-10 km Yes Yes No
GNSS 5-100m No No Yes
AGNSS 5-100m Yes Yes Yes

[edit] Location intervals

Liblocation supports a default interval (equals to one second) and intervals of 1, 2, 5, 10, 20, 30, 60 and 120 seconds between fixes. These are defined in location-gpsd-control.h. Due to performance and power consumption reasons, all the intervals provide fixes only if position of the device has changed. Therefore the interval reflects more how often device checks for coordinate changes, than the actual interval between fixes. Nature of GPS fixes being constantly changing guarantees that GPS fixes are provided with requested interval. However, if there are several applications using different intervals, then the used interval is the minimum of intervals requested by all applications.

Location interval is set as LocationGPSDControl's "preferred-interval" property:

g_object_set(G_OBJECT(control), "preferred-interval", LOCATION_INTERVAL_60S, NULL);

[edit] LocationGPSDevice and LocationGPSDeviceFix

LocationGPSDevice object has the following public fields:

  • gboolean online: Whether there is a connection to the hardware
  • LocationGPSDeviceStatus status: Status of the device
  • LocationGPSDeviceFix *fix: The actual fix (latitude, longitude, etc)
  • int satellites_in_view: Number of satellites in view
  • int satellites_in_use: Number of satellites in use
  • GPtrArray *satellites: Array of satellites
  • LocationCellInfo *cell_info: Information about cell the device is connected to

The most useful field is naturally "fix" which contains position and movement of the device and accuracies for them. "LocationGPSDeviceFix" fields are listed in the table below. In "Fields Flag" column there is a identifier which can be bitwisely anded with "fields" field, to see whether corresponding field is set.

LocationGPSDeviceFix
Variable Description
mode Mode of the fix (2D, 3D, not seen or no fix)
fields Bitfield representing what fields contain valid data
Variable Unit Description Fields Flag
time s Timestamp of the update LOCATION_GPS_DEVICE_TIME_SET
ept s Time accuracy
latitude degrees Fix latitude LOCATION_GPS_DEVICE_LATLONG_SET
longitude degrees Fix longitude LOCATION_GPS_DEVICE_LATLONG_SET
eph cm Horizontal position accuracy
altitude m Fix altitude LOCATION_GPS_DEVICE_ALTITUDE_SET
epv m Altitude accuracy
track degrees Direction of motion LOCATION_GPS_DEVICE_TRACK_SET
epd degrees Track accuracy
speed km/h Current speed LOCATION_GPS_DEVICE_SPEED_SET
eps km/h Speed accuracy
climb m/s Current rate of climb LOCATION_GPS_DEVICE_CLIMB_SET
epc m/s Climb accuracy

The units for epv, epd, eps and epc might be different in liblocation version 0.99-1 and older.

An application receiving a fix cannot know if the fix is a result from location method it requested. Therefore application should study whether fix is accurate enough to satisfy application's needs. This can be done by inspecting "eph" field, which is fix's horizontal accuracy in centimeters. Typical values for horizontal accuracies can be seen in the location methods table. If accuracy is not known, it has a value of <code>NaN.

[edit] Liblocation signals and callbacks

The most useful signal in liblocation is LocationGPSDevice's changed signal, which is emitted everytime a new fix is received. LocationGPSDControl has an error-verbose signal which is emitted in case of an error. There is also a legacy signal error, which doesn't give a reason for error.

You can connect to these signals in the usual way:

g_signal_connect(control, "error-verbose", G_CALLBACK(on_error), user_data);
g_signal_connect(device,  "changed", G_CALLBACK(on_changed), user_data);

Below are examples for these signals' callbacks:

static void on_error(LocationGPSDControl *control, LocationGPSDControlError error, gpointer user_data)
{ 
  switch (error) {
  case LOCATION_ERROR_USER_REJECTED_DIALOG:
    g_debug("User didn't enable requested methods");
    break;
  case LOCATION_ERROR_USER_REJECTED_SETTINGS:
    g_debug("User changed settings, which disabled location");
    break;
  case LOCATION_ERROR_BT_GPS_NOT_AVAILABLE:
    g_debug("Problems with BT GPS");
    break;
  case LOCATION_ERROR_METHOD_NOT_ALLOWED_IN_OFFLINE_MODE:
    g_debug("Requested method is not allowed in offline mode");
    break;
  case LOCATION_ERROR_SYSTEM:
    g_debug("System error");
    break;
  }
}
 
static void on_changed(LocationGPSDevice *device, gpointer user_data)
{
  if (!device)
    return;
 
  if (device->fix) {
    if (device->fix->fields & LOCATION_GPS_DEVICE_LATLONG_SET)
      g_debug("lat = %f, long = %f", device->fix->latitude, device->fix->longitude);
 
    if (device->fix->fields & LOCATION_GPS_DEVICE_ALTITUDE_SET)
      g_debug("alt = %f", device->fix->altitude);
 
    g_debug("horizontal accuracy: %f meters", device->fix->eph/100);
  }
 
  if (device && device->cell_info) {
    if (device->cell_info->flags & LOCATION_CELL_INFO_GSM_CELL_INFO_SET)
      g_debug("Mobile Country Code GSM: %d", device->cell_info->gsm_cell_info.mcc);
 
    if (device->cell_info->flags & LOCATION_CELL_INFO_WCDMA_CELL_INFO_SET)
      g_debug("Mobile Country Code WCDMA: %d", device->cell_info->wcdma_cell_info.mcc);
  }
 
  g_debug("Satellites in view: %d, in use: %d", device->satellites_in_view, device->satellites_in_use);
}

Liblocation sends a changed signal also after locationing is started or stopped, in which case a last known fix is sent if such exists. Application can differentiate these fixes from real ones by inspecting device->status field which equals LOCATION_GPS_DEVICE_STATUS_NO_FIX if the fix is not real.

[edit] Starting and stopping locationing

Finally after everything above has been done, locationing can be started.

location_gpsd_control_start(control);

If the chosen location method violates control panel location settings, then a dialog is shown to user. Dialogs ask user to enable necessary services. On user's refusal an error to application is sent. If no error is seen, fixes should be coming after a while. When locationing is no longer needed, it can be stopped.

location_gpsd_control_stop(control);

[edit] Complete example

Here is a complete standalone example using liblocation. It starts location services after program is started, then when first fix arrives, prints it, stops services, and shutdowns.

#include <location/location-gps-device.h>
#include <location/location-gpsd-control.h>
 
static void on_error(LocationGPSDControl *control, LocationGPSDControlError error, gpointer data)
{ 
	g_debug("location error: %d... quitting", error);
	g_main_loop_quit((GMainLoop *) data);
}
 
static void on_changed(LocationGPSDevice *device, gpointer data)
{
	if (!device)
		return;
 
	if (device->fix) {
		if (device->fix->fields & LOCATION_GPS_DEVICE_LATLONG_SET) {
			g_debug("lat = %f, long = %f", device->fix->latitude, device->fix->longitude);
			location_gpsd_control_stop((LocationGPSDControl *) data);
		}
	}
} 
 
static void on_stop(LocationGPSDControl *control, gpointer data)
{
	g_debug("quitting");
	g_main_loop_quit((GMainLoop *) data);
} 
 
static gboolean start_location(gpointer data)
{
	location_gpsd_control_start((LocationGPSDControl *) data);
	return FALSE;
}
 
int main(int argc, char *argv[])
{
	LocationGPSDControl *control;
	LocationGPSDevice *device;
	GMainLoop *loop;
 
	g_type_init();
 
	loop = g_main_loop_new(NULL, FALSE);
 
	control = location_gpsd_control_get_default();
	device = g_object_new(LOCATION_TYPE_GPS_DEVICE, NULL);
 
	g_object_set(G_OBJECT(control),
		"preferred-method", LOCATION_METHOD_USER_SELECTED,
		"preferred-interval", LOCATION_INTERVAL_DEFAULT,
		NULL);
 
	g_signal_connect(control, "error-verbose", G_CALLBACK(on_error), loop);
	g_signal_connect(device, "changed", G_CALLBACK(on_changed), control);
	g_signal_connect(control, "gpsd-stopped", G_CALLBACK(on_stop), loop);
 
	g_idle_add(start_location, control);
 
	g_main_loop_run(loop);
 
	g_object_unref(device);
	g_object_unref(control);
 
	return 0;
}

You can compile this example with following command:

gcc -Wall `pkg-config --cflags --libs liblocation` -o test test.c