Developers

Local Navigation

Home > Developers > Developers Knowledge Base

Back

What Is - Best practices for designing GPS applications for BlackBerry smartphones operating on CDMA networks

Last Updated: 22 December 2008
Article Number: DB-00671

Summary

This article applies to the following:

  • BlackBerry® Device Software 4.2.2 and later
  • BlackBerry® Pearl™ 8130 smartphone
  • BlackBerry® Curve™ 8330 smartphone
  • BlackBerry® 8830 World Edition smartphone

Details

Description

The BlackBerry 8130 smartphone, BlackBerry 8330 smartphone and BlackBerry 8830 smartphone use the Qualcomm® gpsOne® chipset. This chip can operate in several modes, some of which are quite different than the modes supported by BlackBerry smartphones operating on the Global System for Mobile communications® (GSM®) network.

This article explains the modes supported by BlackBerry smartphones operating on the Code Division Multiple Access (CDMA) network and the best practices for writing location-based services applications for the Qualcomm gpsOne chip.

Modes

Depending on the criteria set by an application, a Qualcomm gpsOne chip can be in any of the following modes:

Standalone

  • MS (Mobile Station or Device) operates in standalone-only mode
  • No network or Position Determination Entity (PDE) for position-location-related activity
  • Data demodulation (if required) occurs without an ephemeris download from the PDE
  • Recommended for outdoor use only; requires a clear view of the sky
  • Time To First Fix (TTFF) can be affected by cloud cover and/or urban canyons

MS-based

  • MS-operation in MS-based mode
  • Only seed position is calculated using MS-assisted mode
  • Suitable for applications requiring frequent fixes
  • Operates outdoors and indoors with a partial view of the sky

MS-assisted

  • MS operates in MS-assisted/PDE-based position calculation mode only
  • No MS-based position location fixes for the active sessions
  • No ephemeris downloads from PDE and no data demodulation
  • Suitable for single fixes

    • Note: Applications that need frequent fixes should not operate in this mode because this may result in data charges from the wireless service provider

  • Operates anywhere with a network connection

There are three more modes that use a combination of MS-Based and MS-Assisted to achieve a location fix.

Speed optimal

  • MS-based position calculation is preferred
  • PDE-based fix/MS-assisted mode is done only if MS-based position calculation fix fails
  • Ephemeris download from PDE is preferred as compared with data demodulation

Accuracy optimal

  • PDE-based position calculation/MS-assisted mode is a preferred option MS-based position calculation only if PDE-based fix failsEphemeris download from PDE is preferred as compared with data demodulation

Data optimal

  • Standalone mode is the preferred option and minimum PDE/network access is allowed
  • Data demodulation is preferred as compared with ephemeris download from PDE
  • MS-assisted position fix if MS-based position calculation fails to generate a fix
  • Data optimal mode disables SA download

Finally, another mode that simply returns the location of the cellular transmission site in contact with the BlackBerry smartphone is known as CellSite. This mode is not part of Qualcomm gpsOne but is worth mentioning. Accuracy of this mode is obviously low: 400m to 2500m in urban areas and will vary by location. CellSite is recommended when accuracy is of least concern.

Java Specification Request (JSR) 179 and Qualcomm gpsOne

JSR179 (also know as Location application programming interface [API]) includes the necessary APIs to use location-based services capabilities of a BlackBerry smartphone. The most important class in JSR179 is the LocationProvider, which is used to obtain location data from the Global Positioning System (GPS) module. An instance is obtained by calling LocationProvider.getInstance(Criteria c). Depending on the Criteria object, the API returns a LocationProvider in one of the above-mentioned modes. It is important to understand what criteria results in which mode. The following table can be used as a reference to determine the mapping between different sets of criteria and Qualcomm gpsOne modes.


Set Horizontal Accuracy() Set Vertical Accuracy() Is Allowed To Cost() set Preferred Power Consumption() set Preferred Response Time() Frequency of fix in set Location Listener() Resulting Qualcomm gpsOne Mode
Mapped to QOS > Accuracy threshold meters not allowed not applicable any single/multiple Standalone
not required not required not allowed medium, high or no requirement any single/multiple Standalone
not required not required allowed medium, high or no requirement any single/multiple Data optimal
Mapped to QOS > Accuracy threshold meters allowed High Mapped to QOS > performance multiple Speed optimal
Mapped to QOS > Accuracy threshold meters allowed medium or no requirement Mapped to QOS > performance multiple MS-based
Mapped to QOS > Accuracy threshold meters allowed High Mapped to QOS > performance Single Accuracy optimal
Mapped to QOS > Accuracy threshold meters allowed medium or no requirement Mapped to QOS > performance Single PDE calculate
Mapped to QOS > Accuracy threshold meters allowed medium or no requirement QOS == Zero Single AFLT
not required not required allowed low any any cell site

Based on the preceding table, the following algorithm is used in the BlackBerry smartphone API implementation:

-if costAllowed = FALSE, mode is standalone
-else if costAllowed=TRUE,
       -if (Sprint or Bell), mode is MS-Based
       -if horizontalAccuracy = 0, mode is Data Optimal
       -if horizontalAccuracy > 0,
             -if multipled fixes requested,
                   -if Telus, mode is MS-based
                   -otherwise,
                         -if powerUsage = HIGH, mode is Speed Optimal;
                         -if powerUsage != HIGH, mode is MS-based
             -else if single fix requested,
                   -if powerUsage = HIGH, mode is Accuracy Optimal;
                  -if powerUsage != HIGH, mode is PDE Calculate
                   -if powerUsage = MEDIUM and preferredResponseTime = 0,
                         mode is AFLT
                   -if powerUsage = LOW mode is Cellsite

Note: Verizon does not support the Standalone mode. For BlackBerry Device Software 4.7 and later, Standalone mode is open to applications that are signed by Research In Motion.

The following is an example obtaining a LocationProvider instance in Standalone mode:

Criteria c = new Criteria();
c.setCostAllowed(false);
LocationProvider provider = LocationProvider.getInstance(c);

DB-00671

Once a LocationProvider instance is obtained, read the location information from the BlackBerry smartphone. There are two ways to read location information from the BlackBerry smartphone:

  1. Call LocationProvider.getLocation(int timeout). If this method is used, a single fix will be returned. The timeout parameter is specified in seconds. A value of -1 indicates that the implementation should use its default timeout value for this provider.

    2. Location loc = provider.getLocation(100);

    DB-00671_02.jpg

    This method is strongly recommended when frequent fixes are not required.

  2. Implement a LocationListener. To obtain multiple fixes at fixed intervals, implement the LocationListener interface of JSR179. This interface has the following two methods:

    1. locationUpdated(LocationProvider provider,Location location)

      2. Called by the LocationProvider that this listener is registered to. This method will be called periodically according to the interval defined when registering the listener to provide updates of the current location. The provider parameter is the source of the event. The location parameter is the Location object that contains location information of the new fix.

    2. providerStateChanged(LocationProvider provider, int newState)

      3. Called by the LocationProvider that this listener is registered to, if the state of the LocationProvider has changed. The value of the newState parameter can be xLocationProvider.AVAILABLE, LocationProvider.OUT_OF_SERVICE or LocationProvider.TEMPORARILY_UNAVAILABLE.

    After implementing a LocationListener , an instance must be created and registered with a LocationProvider object. To register a LocationListener instance, call LocationProvider.setLocationListener(LocationListener listener, int interval, int timeout, int maxAge). The parameters are defined as follows:

    • listener - The LocationListener instance to register
    • interval - The interval in seconds to obtain location data
    • timeout - The timeout value in seconds
    • maxAge - The maximum age of the returned location in seconds

    -1 can be passed to use the default value for the interval, maxAge and timeout parameters. The following code demonstrates how to register a LocationListener with default values:

    LocationListener locListener = new LocationListenerImpl();
    provider.setLocationListener(locListener, -1, -1, -1);

    Once a LocationListener is registered, the locationUpdated method should be called automatically at the defined interval.

Provider states

As stated in the preceding text, the system automatically updates the state of a LocationProvider by calling the providerStateChanged() method of the registered LocationListener. The following description indicates how these status codes are interpreted in the BlackBerry smartphone API implementation:

  • TEMPORARILY_UNAVAILABLE - The GPS chipset has stopped looking for a fix. LocationProvider will no longer provide a fix to the application.
  • OUT_OF_SERVICE - Indicates when there is an IT Policy sent to the BlackBerry smartphone to disable GPS.
  • AVAILABLE - Never sent to the application.

Setting up PDE information

CDMA wireless service providers usually provide a PDE server which helps the BlackBerry smartphone in obtaining and computing location information.

Note: All Qualcomm gpsOne modes, except StandAlone and Cellsite, require a connection to a PDE server. To enable a connection to a PDE server, the Internet Protocol (IP) address and the port of the server must be configured using GPSSettings.setPDEInfo(String ip, int port). The following is an example:

// You must replace these values with values provided by your carrier.
GPSSettings.setPDEInfo("127.0.0.1", 80);

Resetting the LocationProvider

A LocationProvider may stop returning fixes when network coverage deteriorates or the BlackBerry smartphone is in an environment that is not suitable for receiving GPS data (for example, indoors). In these scenarios, the GPS chip will go completely cold to preserve battery power and throw a TEMPORARILY_UNAVAILABLE event by calling providerStateChanged()of the registered LocationListener instance. If this event is triggered, an application can reset the provider to restore the GPS chip. The following code demonstrates how to reset a LocationProvider:

provider.setLocationListener(null, 0, 0, 0);
provider.reset();
provider = null;
provider = LocationProvider.getInstance(criteria);
provider.setLocationListener(new LocationListenerImpl(),interval, timeout, maxAge);

After a reset, the application can try to get a fix again; however, if the GPS chip fails to get a fix (if the network coverage or environment has not improved), it will again go cold and will stop getting fixes. It is expected that the application will decide when to reset the provider. It is strongly recommended not to reset the provider at an interval less than three minutes since it can take up to three minutes to get a fix from a cold start.

Note: In some BlackBerry Device Software versions, the TEMPORARILY_UNAVAILABLE state was not always triggered as appropriate. In these cases, it is a good practice to keep track of the timestamp of the last valid fix and to reset the provider if the last valid fix is more than three minutes old.

Keeping the GPS chip ‘hot’

The GPS chip is considered ‘hot’ when it has an active connection with the satellites. A fix can be obtained almost instantly when the chip is hot. To preserve battery power, the chip is configured to go cold if the application does not ask for fixes for some time. From a cold start it may take much longer to get a fix. For applications that require frequent fixes, it is recommended that the application queries for fixes every 10 seconds. Therefore, the LocationListener should be registered with an interval of less than or equal to 10 seconds.

Setting up Verizon credentials

Verizon requires third-party applications to have a valid Client ID and Password for their Location Proxy Server (LPS) to access the Location API. To obtain these credentials, contact Verizon. Verizon credentials can be set in an application by calling GPSSettings.setPDEInfo(String ip, int port) as follows:

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

A sample application that implements all the recommendations of this article can be found here.

Keywords

GPS, LBS, Location Based Services, gpsOne, CDMA, JSR 179, PDE, Criteria, LPS, Verizon

By downloading, accessing or otherwise using the Knowledge Base documents you agree: (a) that the terms of use for the documents found at http://www.blackberry.com/support/knowledgebase/disclaimer.shtml apply to your use or reference to these documents; and (b) not to copy, distribute, disclose or reproduce, in full or in part any of the documents without the express written consent of RIM.