Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Location APIs – Start to finish

by BlackBerry Development Advisor on ‎08-19-2010 09:18 PM - edited on ‎09-12-2012 04:12 PM by Administrator (28,413 Views)

Most BlackBerry® devices, including GSM, CDMA and iDEN based smartphones, have an embedded GPS chip. Depending on the type of the device, various GPS modes are supported. This article is a comprehensive guide to the supported GPS modes and APIs available for BlackBerry devices.

 

 

Supported Modes

A BlackBerry device, depending on the type and carrier, supports all or a subset of the following modes.

 

GSM based devices mostly support standalone mode. Some GSM carriers have enhanced their GPS service offering, supporting assisted GPS fixes on these devices. However, this requires BlackBerry® Device Software 4.6 or above and the carrier must have provisioned the device with this service.

 

In the CDMA world, BlackBerry devices support all the modes below. However, some carriers may not support some of these modes. Please check with your carrier to confirm.

iDEN devices support Standalone, Assisted and the Cellsite mode. However, availability of assisted and cellsite mode is dependent on the carrier.

  

Standalone (CDMA/GSM/iDEN)

  • Device computes a fix by communicating with satellites only
  • Supported on all devices with an internal GPS chip  
    • For BlackBerry devices operating on the Verizon network, requires BlackBerry Device Software 4.7 or greater
    • Requires a clear view of the sky
    • No data connectivity required
    • But cellular radio must be turned on
    • Relatively higher Average Time To First Fix (TTFF)
    • TTFF is improved by RIM’s ephemeris extension
    • Recommended for applications that require frequent fixes

Assisted (GSM/iDEN)

  • A PDE server, hosted by the carrier, periodically assists the device in getting a fix
  • Requires data connectivity
  • Operates outdoors and indoors with a partial view of the sky
  • Average Time To First Fix is faster than Standalone

Cellsite (GSM/CDMA/iDEN)

  • Retrieves a fix based on the location of the nearest cell towers
  • Extremely fast
  • Accuracy is very low
  • Recommended for applications where accuracy is not a concern

MS-Based (CDMA)

  • A PDE server, hosted by the carrier periodically assists the device in getting a fix
  • Requires data connectivity
  • Operates outdoors and indoors with a partial view of the sky
  • Average Time To First Fix is faster than Standalone
  • Recommended for applications that require frequent fixes

MS-Assisted (CDMA)

  • Device is assisted by the PDE server in every fix
  • Requires data connectivity
  • Can operate indoors and outdoors without any difficulty
  • Very fast Average Time To First Fix
  • Operates anywhere with a network connection
  • Not recommended for frequent fixes
  • Should not be used more than once every 10-15 minutes

The following three modes use a combination of MS-Based and MS-Assisted to achieve a location fix.

 

Speed optimal (CDMA)

  • Preferred mode: MS-Based
  • Initial mode attempted: MS-Based or MS-Assisted
  • Fallback mode: If MB-Based is attempted first, fallback is to MS-Assisted; if MS-Assisted is attempted first, fallback is to MS-Based

Accuracy optimal (CDMA)

  • Preferred mode: MS-Assisted
  • Initial mode attempted: MS-Assisted
  • Fallback mode: MS-Based, if MS-Assisted fails

Data optimal (CDMA)

  • Preferred mode: MS-Based
  • Initial mode attempted: MS-Based
  • Fallback mode: MS-Assisted, if MS-Based fails
  • Minimum PDE/network access is allowed

BlackBerry Geolocation Modes (BlackBerry Device Software 5.0 and later)

  • Free!
  • Available on all device and network types
  • Requires the device to be provisioned with this service
  • Requires Location Services enabled in device options
  • Requires Location Based Services IT Policy set to allowed for devices connected to a BlackBerry Enterprise Server
  • Very fast
  • Accuracy is low but is better than Cellsite
  • Three modes are supported
    • Cell Based – Computes location based on cell towers (since OS 5.0)
    • WLAN Based – Computes location based on WLAN access points (since OS 6.0)
    • Optimal – Uses both Cell and WLAN access points (since OS 6.0)

Acquiring GPS fixes

Once you have selected a mode that is best suited for your use case, acquiring the actual fixes is trivial. There are four basic steps involved:

  • Setup Criteria
  • Setup PDE - Only required for assisted modes on some CDMA networks
  • Obtain a LocationProvider
  • Retrieve Location Fixes
    • Multiple – via LocationListener
    • Single – via LocationProvider.getLocation(int timeout)

Setup Criteria

A Criteria object defines the GPS mode to be used. While setting up Criteria, you can choose to use the core Location API defined in javax.microedition.location (aka JSR-179) or APIs provided by RIM’s extension to the core Location API defined in net.rim.device.api.gps (aka JSR-179 extensions). In the following subsections, we will look in to both approaches.

 

Please note that all GPS modes cannot operate in both single and multiple fix sessions. We will learn more about single and multiple fix sessions when we discuss Retrieving Location Fixes.

  

Standalone (CDMA/GSM/iDEN)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(false); 
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_AUTONOMOUS); 
  • Fix frequency: Multiple and Single

 

Assisted (GSM/iDEN)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(200); 
    criteria.setVerticalAccuracy(200); 
    criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_ASSIST); 
  • Fix frequency: Single and Multiple

 

Cellsite (CDMA/iDEN)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT); 
    criteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT); 
    criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW); 
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_CELLSITE);
     
  • Fix frequency: Multiple and Single

 

MS-Assisted (CDMA)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(200); 
    criteria.setVerticalAccuracy(200); 
    criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_CDMA_MS_ASSIST); 
  • Fix frequency: Single

 

MS-Based (CDMA)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(200); 
    criteria.setVerticalAccuracy(200); 
    criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM); 
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_CDMA_MS_BASED);
     
  • Fix frequency: Multiple

 

Data Optimal (CDMA)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT); 
    criteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT); 
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_CDMA_DATA _OPTIMAL); 
  • Fix frequency: Multiple and Single

 

Speed Optimal (CDMA)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(200); 
    criteria.setVerticalAccuracy(200); 
    criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_HIGH); 
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_CDMA_SPEED_OPTIMAL); 
  • Fix frequency: Multiple

 

Accuracy Optimal (CDMA)

  • JSR-179 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(200); 
    criteria.setVerticalAccuracy(200); 
    criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_HIGH); 
  • JSR-179 extension (since OS 5.0) 
    BlackBerryCriteria bbCriteria = new BlackBerryCriteria(); 
    bbCriteria.setMode(GPSInfo.GPS_MODE_CDMA_ACCURACY_OPTIMAL); 
  • Fix frequency: Single

 

Geolocation (BlackBerry Device Software 5.0 and later)

  • JSR-179 (Same as Cellsite Criteria) 
    Criteria criteria = new Criteria(); 
    criteria.setCostAllowed(true); 
    criteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT); 
    criteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT); 
    criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW); 
    • On CDMA, Geolocation is used only if Cellsite mode fails
    • On GSM, Geolocation is used by default 
  • JSR-179 extension (since OS 6.0)
    • Geolocaiton Optimal  
      BlackBerryCriteria bbCriteria = = new BlackBerryCriteria(); 
      bbCriteria.setMode(LocationInfo.GEOLOCATION_MODE); 
    • Geolocation Cell 
      BlackBerryCriteria bbCriteria = = new BlackBerryCriteria(); 
      bbCriteria.setMode(LocationInfo.GEOLOCATION_MODE_CELL); 
    • Geolocation WLAN 
      BlackBerryCriteria bbCriteria = = new BlackBerryCriteria(); 
      bbCriteria.setMode(LocationInfo.GEOLOCATION_MODE_WLAN); 
  • Fix frequency: Multiple and Single

 
The following tables summarize how a
Criteria object maps to a GPS mode.

Criteria mapping for JSR-179 API

GPS Mode Supported on Horizontal Accuracy Vertical Accuracy Cost Allowed Preferred Power Consumption Preferred Response Time Fix Frequency
Standalone CDMA / GSM / iDEN Influences QoS Meters not allowed not applicable Any Single / multiple
Standalone CDMA / GSM / iDEN not required not required not allowed medium, high or no requirement Any Single / multiple
Assisted GSM / iDEN Influences QoS meters allowed medium or no requirement Influences QoS Single / multiple
Cell site / Geolocation CDMA / GSM / iDEN not required not required allowed Low Any Single / multiple
MS-Assisted CDMA Influences QoS meters allowed medium or no requirement Influences QoS Single
MS-based CDMA Influences QoS meters allowed medium or no requirement Influences QoS Multiple
Data optimal CDMA not required not required allowed medium, high or no requirement Any Single / multiple
Speed optimal CDMA Influences QoS meters allowed High Influences QoS Multiple
Accuracy optimal CDMA Influences QoS meters allowed High Influences QoS Single

 Note: QoS refers to the “Quality of Service” that determines the validity of a fix. 

 

 

 

Criteria mapping for JSR-179 extensions API

GPS Mode Supported on Mode constant Fix Frequency
Standalone CDMA / GSM / iDEN GPSInfo.GPS_MODE_AUTONOMOUS Single / multiple
Assisted GSM / iDEN GPSInfo.GPS_MODE_ASSIST Single / multiple
Cell site CDMA / GSM / iDEN GPSInfo.GPS_MODE_CELLSITE Single / multiple
Geolocation Optimal CDMA / GSM / iDEN LocationInfo.GEOLOCATION_MODE Single / multiple
Geolocation Cell CDMA / GSM / iDEN LocationInfo.GEOLOCATION_MODE_CELL Single / multiple
Geolocation WLAN CDMA / GSM / iDEN LocationInfo.GEOLOCATION_MODE_WLAN Single / multiple
MS-Assisted CDMA GPSInfo.GPS_MODE_CDMA_MS_ASSIST Single
MS-based CDMA GPSInfo.GPS_MODE_CDMA_MS_BASED Multiple
Data optimal CDMA GPSInfo.GPS_MODE_CDMA_DATA _OPTIMAL Single / multiple
Speed optimal CDMA GPSInfo.GPS_MODE_CDMA_SPEED_OPTIMAL Multiple
Accuracy optimal CDMA GPSInfo.GPS_MODE_CDMA_ACCURACY_OPTIMAL Single
 

 

Setup PDE

This section applies to CDMA carriers only. CDMA carriers host a Position Determining Entity (PDE) server that assists the device in getting an assisted GPS fix. Setting up PDE information is a required step for all assisted modes i.e. all modes except Standalone, Cellsite and Geolocation. Applications need to set the IP and Port address of the PDE server. Please note that each carrier has their own PDE server. If you are planning on deploying your application on multiple carriers, you need to use different PDE IP and Port for each carrier. It is also important to note that some carriers have decided to hardcode the PDE IP and Port information on the device itself. In those cases, you do not need to setup PDE information in your application. Please contact your target carriers for more details.

 

The following code shows how to set PDE IP and Port information.

 

GPSSettings.setPDEInfo(String ip, int port);

 

Setting up PDE information for Verizon® is a little different. Instead of Port and IP, Verizon requires a pair of ClientID and Password to access their PDE server. You need to join the Verizon Developer Program in order to get these credentials. Once you have the credentials from Verizon, you can set that information as shown below.

 

GPSSettings.setPDEInfo(";" + clientID + ";" + password, 0) 

  

Obtain a LocationProvider

Once the Criteria is setup and the PDE information is set (if required), we need to obtain an instance of the LocationProvider class. The LocationProvider class acts as the central piece of your GPS code and allow retrieving GPS fixes via its methods. The core LocationProvider (JSR-179) class provides basic methods to retrieve GPS fixes while the BlackBerryLocationProvider class (JSR-179 extension) which is extended from the core LocationProvider class, provides more details and control over a GPS fix. Here is how to obtain an instance of both.

 

JSR-179

LocationProvider provider = LocationProvider.getInstance(criteria);

 

JSR-179 extension (since OS 5.0) 

BlackBerryLocationProvider provider = (BlackBerryLocationProvider)LocationProvider.getInstance(bbCriteria);

  • You must use a BlackBerryCriteria to obtain a BlackBerryLocationProvider

 

Retrieve Location Fixes

There are two ways to obtain location fixes. In Multiple fix mode, fixes come via a listener interface at a specified interval. On the other hand, if you are interested in a single fix only, you can opt for Single fix mode.

 

Single Fix

If this method is used, a single fix will be returned. The following code snippets show how you can do it in your application.

Location LocationProvider.getLocation(int timeout);

The timeout value specifies how long the LocationProvider has - to return a fix. To use the default timeout value, please use -1 as the timeout.

 

Multiple Fix

To get continuous or multiple fixes at certain intervals, a LocationListener must be implemented which will be notified on each new location fix. Specifically we need to implement  

 
public void locationUpdated(LocationProvider  provider, Location location)

 

Once we have our LocationListener implementation, we need to set this listener to our LocationProvider or BlackBerryLocationProvider by calling

 

LocationProvider.setLocationListener(LocationListener, interval, timeout, maxAge)

 

Or

 

BlackBerryLocationProvider.setLocationListener(LocationListener, interval, timeout, maxAge)

 

Note that if you used a BlackBerryCriteria and obtained a BlackBerryLocationProvider, you will in fact receive a BlackBerryLocation object via LocationListener.locationUpdated() or LocationProvider.getLocation().

Both Location and BlackBerryLocation object contains information about the location fix including the longitude and latitude associated with it. The following sections explain the details of the content of these two Location objects. 

 

 

The Location Object

A basic Location object is obtained when you use the core Location API (JSR-179) for your Criteria and your LocationProvider. This object contains the following information that can be retrieved by calling the getter methods of this object.

 

  • Location.getLocationMethod()
    • Returns an integer mask of MTA_*, MTE_* and MTY_* constants in the Location class
    • Represents the GPS mode used to compute this Location
  • Location.getQualifiedCoordinates()
    • Returns a QualifiedCoordinate object from which longitude, latitude and altitude information can be extracted
  • Location.getSpeed()
    • Returns the current ground speed in meters/second at the time of measurement
  • Location.getCourse()
    • Returns the course made good in degrees relative to true north
  • Location.getTimeStamp()
    • Returns the timestamp at which the data was collected
  • Location.isValid
    • Returns the validity of the Location object. A failed fix usually results in an invalid fix.
  • Location.getExtraInfo(application/X-jsr179-location-nmea)
    • The raw location information in nmea format
    • Number of satellites can be parsed from this

 

The BlackBerryLocation Object

On the other hand if you used the RIM extension to the core Location API, you will receive a BlackBerryLocation object. This object has far more information regarding a location fix on top of what is available in a basic Location object and was introduced in OS 5.0.

 

  • BlackBerryLocation.getAverageSatelliteSignalQuality()
    • Returns the average satellite signal strength.
    • A good GPS fix ideally requires 4 or 5 satellites with good signal strength. Although the average signal strength gives us an idea about how good the GPS coverage is, it is important to ensure that the individual signal strength between the device and each satellite is good enough. More on this in the Best Practices section below.
  • BlackBerryLocation.getDataSource()
    • Returns the data source used to produce the location fix.
    • One of
      • GPSInfo.GPS_DEVICE_INTERNAL
      • GPSInfo.GPS_DEVICE_BLUETOOTH
      • LocationInfo.LOCATION_SOURCE_GEOLOCATION (since OS 6.0)
      • LocationInfo.LOCATION_SOURCE_GEOLOCATION_CELL (since OS 6.0)
      • LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN (since OS 6.0)
  • BlackBerryLocation.getGPSMode()
    • Returns the GPS mode used to compute the location fix
    • See GPSInfo.GPS_MODE_* and LocationInfo.GEOLOCATION_MODE constants
  • BlackBerryLocation.getSatelliteCount()
    • Returns the number of satellites used to compute this fix
  • BlackBerryLocation.getSatelliteInfo()
    • Returns an Enumeration of SatelliteInfo objects each representing a satellite that was in sight while computing this location.
    • SatelliteInfo contains azimuth, elevation, ID, signal quality and validity
  • BlackBerryLocation.getError()
    • Returns the error code (if any) of this location
    • Error codes are defined in GPSInfo class
    • More on error codes later in this article..
  • BlackBerryLocation.getStatus()
    • Returns the status of a location fix
    • More on status later in this article..

 

Bluetooth Data Source

Since BlackBerry Device Software 4.2.0, BlackBerry devices have support for Bluetooth® GPS. If you wish, you can use a Bluetooth GPS puck to be used as the default GPS data source. Nothing needs to change in your application. However,

  • The Bluetooth device needs to be paired with the BlackBerry
  • GPS source needs to be set to Bluetooth
    • Via GPS options on the device
    • Onboard GPS is default

 

Advanced API Features

Besides the features discussed so far, there are a lot more location related API features.

 

Concurrent Geolocation (BlackBerry Device Software 6.0 and later)

Concurrent Geolocation allows applications to keep getting Geolocation based fixes while waiting for fixes using other GPS modes. For example, an application may find it useful to show the BlackBerry device user an approximate location to work with while waiting for a fix that pinpoints the user with an accurate location fix. This feature can be enabled by calling:

 

bbCriteria.enableGeolocationWithGPS(BlackBerryCriteria.FASTEST_FIX_PREFERRED);

 

This means that the device will simultaneously try Geolocation mode and the mode defined in the BlackBerryCriteria. Fix is provided using whichever mode succeeds first i.e. Geolocation or the specified mode.

  

Geolocation fallback (BlackBerry Device Software 6.0 and later)

This feature enables applications to fallback to Geolocation mode whenever the desired mode defined in the criteria fails. This is an excellent feature for applications that can still work with an approximate location fix when a good fix is not available. Here is how to enable this in your BlackBerryCriteria:

 

bbCriteria.enableGeolocationWithGPS();

 

Geolocation mode is triggered only when the desired mode fails.

  

Failover mode (BlackBerry Device Software 5.0 and later)

At times a desired GPS mode might fail due to changing environmental conditions or other factors. Application can define a failover mode that the device may use in case the primary mode specified in the criteria fails. To enable this, you need to call 

 

bbCriteria.setFailoverMode(int mode, int retries, int timeout);

 

  • mode  
    A GPS mode supported on the BlackBerry device.

  

  • retries 
    T
    he maximum number of GPS retries (using the first mode) before a failover happens. A retry is triggered if a failure is reported. The retry value can only be between 0 and 3. If the value is less than 0 then a default of 0 (no retry) will be used.

  

  • timeout 
    The maximum wait time (in seconds) to get a fix before a failover occurs. The range of timeout value is between 30 to 300 seconds. A timeout value of less than 30 seconds will be adjusted to 30 seconds. Similarly, a timeout value of greater than 300 seconds will be adjusted to 300 seconds.

 

Note that Geolocation, Cellsite and MS-Assisted modes are not supported as failover modes. Also, it will only work for Internal GPS Data Source.

  

  

Subsequent mode (BlackBerry Device Software 5.0 and later)

An application may choose to use a mode for the first fix only and then use another mode for subsequent fixes. The classic case is where an application tries the first fix in an assisted mode and the subsequent fixes in autonomous or standalone mode. To set a subsequent mode we need to call 

 

bbCriteria.setSubsequentMode(int mode); 

 

Note that Geolocation and Cellsite is not supported as subsequent mode. 

  

GPS Restart Interval (BlackBerry Device Software 5.0 and later)

In certain circumstances, it is possible that the device went out of GPS coverage and hence failed to get any GPS fixes for a while. To preserve battery the GPS chip will timeout and go cold, i.e. your location provider is no longer capable of getting you any fixes even if the device comes back to GPS coverage. By setting, GPS Restart Interval we are essentially telling the API to restart the GPS at a certain interval of continuous invalid fixes. Here is how to do it. 

 

bbCriteria.setGPSRestartInterval(int interval, int maximumRetry); 

  

Fix Status (BlackBerry Device Software 5.0 and later)

Applications can check the status of a BlackBerryLocation object before parsing information from it. To get the status of a location fix we need to call 

 

BlackBerryLocation.getStatus();

 

The following status codes are supported:

  • GPS_ERROR
    • Call BlackBerryLocation.getError() for details on error (since OS 5.0)
  • GPS_FIX_COMPLETE
    • Complete GPS fix including satellite information
  • GPS_FIX_PARTIAL
    • Fix contains satellite information only
  • GPS_FIX_UNAVAILABLE
    • Fix is not available at all
  • FAILOVER_MODE_ON
    • Fix was computed using failover mode
  • SUBSEQUENT_MODE_ON
    • Fix was computed using subsequent mode

 

Fix Error

In cases where an error is thrown while getting a location fix, there are two ways to retrieve that error.

 

BlackBerry Device Software 4.7 and above 

GPSInfo.getLastGPSError() returns the error code of the last GPS fix.

  

BlackBerry Device Software 5.0 and above

BlackBerryLocation.getError() returns the error code associated with a BlackBerryLocation.

 

For a list of the error codes, please refer to GPSInfo.GPS_ERROR_* contants. The table below explains the defined error codes and in which cases they actually apply.

Error Code as defined in GPSInfo class GSM CDMA iDEN
GPS_ERROR_NONE GPS Fix is available without any error GPS Fix is available without any error GPS Fix is available without any error
GPS_ERROR_NO_FIX_IN_ALLOTTED_TIME No GPS fix could be obtained in allotted time. This is likely caused by poor GPS coverage. No GPS fix could be obtained in allotted time. This is likely caused by poor GPS coverage. No GPS fix could be obtained in allotted time. This is likely caused by poor GPS coverage.
GPS_ERROR_DEGRADED_FIX_IN_ALLOTTED_TIME Not Applicable Not Applicable Degraded fix; poor accuracy
GPS_ERROR_TIMEOUT_NO_FIX_NO_ASSIST_DATA Not Applicable No GPS fix could be obtained in allotted time as GPS assistance data request was rejected by the PDE. Not Applicable
GPS_ERROR_TIMEOUT_DEGRADED_FIX_NO_ASSIST_DATA Not Applicable Not Applicable Not Applicable
GPS_ERROR_LOW_BATTERY Not Applicable Not Applicable Not Applicable
GPS_ERROR_CHIPSET_DEAD Not Applicable Not Applicable Not Applicable
GPS_ERROR_INVALID_REQUEST GPS request is not valid. For example, any invalid parameters GPS request is not valid. For example, invalid GPS QoS  parameters GPS request is not valid. For example, any invalid parameters
GPS_ERROR_PRIVACY_ACCESS_DENIED Not Applicable Not Applicable Not Applicable
GPS_ERROR_ALMANAC_OUTDATED Not Applicable Not Applicable Not Applicable
GPS_ERROR_SERVICE_UNAVAILABLE Not Applicable GPS service is temporarily unavailable. Not Applicable
GPS_ERROR_GPS_LOCKED Not Applicable Mobile Originated GPS service is blocked. This implies that only control plane (e.g. 911) GPS service is available Not Applicable
GPS_ERROR_NO_SATELLITE_IN_VIEW Not Applicable Not Applicable Not Applicable
GPS_ERROR_AUTHENTICATION_FAILURE Not Applicable Assisted GPS session authentication failed with PDE. For example, application or device is not provisioned in the PDE Not Applicable
GPS_ERROR_NETWORK_CONNECTION_FAILURE Not Applicable PDE could not be reached for assisted GPS session due to a data connectivity issue Not Applicable
GPS_ERROR_INVALID_NETWORK_CREDENTIAL Not Applicable Assisted GPS session authentication parameter is invalid Not Applicable
 
  

Geocoding and Reverse Geocoding

Geocoding and Reverse Geocoding APIs essentially allow developers to send a freeform search string with a reference coordinate for searching and get an array of Landmark objects back. You can also pass a pair of latitude and longitude and get the best address match. And best of all, this service is free! This service is available via the net.rim.device.api.lbs.Locator class.

  

Geocoding

  • Free form text search (since OS 4.6)
    • Landmark[] geocode(String freeformString, Coordinates startCoords)
  • AddressInfo object search (since OS 5.0)
    • Landmark[] geocode(AddressInfo address, Coordinates startCoords)
  • startCoords is the starting point for the search

Reverse Geocoding

  • A latitude-longitude pair
    • Landmark[] reverseGeocode(int latitude, int longitude, int searchType) 
  • A Coordinates object
    • Landmark[] reverseGeocode(Coordinates coord, int searchType)
  • searchType can be one of
    • Locator.ADDRESS
    • Locator.COUNTRY
    • Locator.PROVINCE_STATE
    • Locator.CITY

  

Best Practices

We have covered all most all of the available APIs related to location based applications. It is mandatory that we look in to some best practices related to these APIs.  

  

Detect/Set Location Services On (BlackBerry Device software 6.0 and later)

Almost any location based operations require that the user have set the Location Services to ON in device options. Applications can also set this settings to ON programmatically.

 

  • LocationInfo.isLocationOn()
    • Determines if Location Services is set to ON
  • LocationInfo.setLocationOn()
    • Sets Location Services to ON

For BlackBerry devices that are activated with a BlackBerry® Enterprise Server, internal GPS and Geolocation can be blocked via IT Policies. To check for such scenarios, determine if the “Disable GPS” IT Policy is set to true, in which case, modes that require satellite communication will not work. Also, note that, the “Enable Geolocation” IT Policy must be enabled if you are planning on using Geolocation modes. The following snippet shows how to determine the assigned value for these policies.

 

  • ITPolicy.getBoolean(“Disable GPS”, false) – For GPS
  • ITPolicy.getBoolean(“Allow Geolocation Service”, true) – For Geolocation

 

Detect Location Sources (BlackBerry Device software 6.0 and later)

Before an application performs any GPS operations, it is important to detect what Location data sources are available on the device. This will help the application to stay ahead of the game by not attempting something that is bound to fail. A supported location source is what the device is capable of supporting however from an application’s perspective, it is more important to find out which of the supported sources are actually available. Both supported and available sources can be queried.

 

  • LocationInfo.getSupportedLocationSources();
    • Returns an integer mask representing the supported location data sources
  • LocationInfo.getAvailableLocationSources();
    • Returns an integer mask representing the available location data sources

Both methods returns an integer mask made of one or more of

  • GPSInfo.GPS_DEVICE_INTERNAL
  • GPSInfo.GPS_DEVICE_BLUETOOTH
  • LocationInfo.LOCATION_SOURCE_GEOLOCATION (since OS 6.0)
  • LocationInfo.LOCATION_SOURCE_GEOLOCATION_CELL (since OS 6.0)
  • LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN (since OS 6.0)

 

Detect Available Modes

Equally important is to detect the available GPS modes. To detect if a desired mode is available, applications can call

 

  • GPSInfo.isGPSModeAvailable(int mode)
    • Since OS 5.0
  • LocationInfo.isModeAvailable(int mode)
    • Since OS 6.0
    • Allows detection of Geolocation modes

 

Recovering from loss of GPS coverage

The LocationProvider is designed to retry for 3 times at the most to obtain a GPS fix. If all 3 attempts fail, it is determined that there is not enough GPS coverage and the LocationProvider becomes stale. In other words, the GPS chip simply stops and tries to preserve battery. Once in this state, your LocationProvider instance cannot be used to get any further location fixes. The only way to revive the LocationProvider from this state is to reset the LocationProvider and discard the current LocationProvider and LocationListener before initializing a new one as shown in the snippet below.

 

provider.setLocationListener(null, 0, 0, 0); 
provider.reset(); 
provider = null;

provider = LocationProvider.getInstance(...); 
provider.setLocationListener(...);

 

So how do we know when the LocationProvider is stale or more specifically, when to reset the provider? Before the LocationProvider becomes stale a LocationProvider.TEMPORARILY_UNAVAILABLE event is thrown via LocationListener.providerStateChanged(LocationProvider provider, int newState). When this happens, you may reset the provider as shown above if you want to trigger an immediate retry. But note that when there is no GPS coverage (e.g. indoor environment), continuously resetting the LocationProvider will only drain the battery without being able to return any location fix. Please find more on this in the Battery Usage section below.

 

Note: On some older BlackBerry Device Software versions, it was found that the TEMPORARILY_UNAVAILABLE is not always fired when expected. To handle that, you should keep track of the timestamp of the last valid fix and reset the provider after 3-5 minutes of continuous invalid fixes.

In BlackBerry Device Software 5.0 or above, instead of the technique mentioned here, please consider using GPS Restart Interval as discussed in this article. 

  

Handling low Satellite count

Quality or accuracy of fixes directly depends on the number of satellites and on the signal strength of each of those satellites. In general if you have at least 4 satellites in sight and each of their signal quality is approximately greater than 30, you should be getting a good fix. To ensure your fix meets these criteria, it is recommended that you check for both number of satellites in sight as well as the signal strength of each of those satellites.

In BlackBerry Device Software prior to 5.0, it is only possible to check for number of satellites for a given Location object. Please see code sample below.

 
protected String getNumSatellites(Location location) {

      String extra = location.getExtraInfo("application/X-jsr179-location-nmea");    

      for(int i=0; i<7; i++){

            extra = extra.substring(extra.indexOf(',')+1, extra.length());

      }    

      return extra.substring(0, extra.indexOf(','));     

}

 

On BlackBerry Device Software versions 5.0 and later, you can check both number of satellites used as well as their individual signal strength for a given BlackBerryLocation object. Here is how:

  • BlackBerryLocation.getSatelliteCount()
    • Returns the current number of satellites that are in view.
  • BlackBerryLocation.getSatelliteInfo()
    • Returns an Enumeration of SatelliteInfo objects representing each satellite in sight. A SatelliteInfo object includes ID, Azimuth, Elevation, Signal Quality as well as a validity flag that indicates whether the satellite info is valid.
  • BlackBerryLocation.getAverageSatelliteSignalQuality()
    • Returns the average signal quality of all satellites in view but note that having a great average signal quality does not guarantee that each of the satellite has a signal quality value greater than 30. It is the individual satellite signal quality value that directly influences the quality of fixes. 

Battery Usage 

Battery life is a critical part of user experience. Hence, applications should ensure that they are not unnecessarily draining the battery. Here are a few points you should consider.

 

  • Frequency of fixes directly correlates with battery consumption. The shorter your interval between fixes, the more battery you are consuming.
  • In general, assisted modes, take less battery than Standalone mode.
  • Geolocation/Cellsite based modes, on average, take least amount of battery.
  • Don’t reset blindly when the LocationProvider stops
    • The user might be indoors and out of GPS coverage.
    • Unless the user moves to an outdoor environment, resetting will not help and will unnecessarily cost battery.
    • Knowing whether the user has moved to an outdoor environment is a challenge. Following factors may indicate that the user has moved but it is not guaranteed. You may consider resetting in such situations:
      • A change in cellsite or geolocation coordinates can be a result of the user moving a significant distance.
      • Accelerometer activities may indicate that the user is moving to a different location.
      • Some heuristic data around fix success at different times of the day may help.
    • At the least, increase your reset interval exponentially every time a reset does not get you a valid fix.
  • Don’t reset too frequently
    • When the chip is in standby mode, it requires a rescan of the sky which can take up to 3-5 minutes although on an average it should not take more than ~20 seconds.
    • Resetting more than once (within a 3 minutes window) may interrupt a scan in progress and the chip has to start the scan from scratch, costing more battery than it should.

Geolocation

Geolocation mode has many practical use cases and if used correctly, can really enhance the user experience! Here are a few things to consider while leveraging the Geolocation service

  • Suitable for low accuracy use cases
  • Always keep the user well informed about the accuracy
  • Fixes not likely to change unless
    • User travels a significant distance
  • Should be requested less frequently
  • Consider using Geolocation mode for your initial fix
    • And then try other modes such as Standalone/Autonomous if higher accuracy is eventually required.

  

GPS Diagnostic Tool

To compliment this article, attached is sample code that implements almost all of the features and best practices described in this article. This application can be used to quickly test an API feature in case your application is not working and may serve as a reference implementation for almost all the features of the Location API.

Attached are the code samples for BlackBerry Device Software 5.0 and earlier (GPSDiagnostic.zip), and the code sample for BlackBerry Device Software 5.0 or later (GPSDiagnosticEX.zip).

Users Online
Currently online: 12 members 1,100 guests
Please welcome our newest community members: