A BlackBerry phone is primarily a business phone with additional features like Email, Phone, Maps, GPS, Organizer, Social Networking and games. Developers can take advantage of various BlackBerry APIs to take the user experience to a new level. In this article, I am going to talk about BlackBerry and Location API,that allows you to develop Location based (LB) applications.
Compatibility
BlackBerry is packed with advanced features, but they are not supported in all models. Let us quickly have a glance at some of the models.
In general there are two options for using GPS with a BlackBerry. You either have a device with an internal GPS receiver, or you will need an external Bluetooth GPS receiver, which will provide the GPS data to your BlackBerry. Refer to this link to find out the models which support GPS http://na.blackberry.com/eng/devices/features/gps.jsp
Do not be disappointed if your preferred model is not the list, you can always download the simulator from https://www.blackberry.com/Downloads/entry.do
Though, the above list mentions about GPS support by default, it should also be noted that there will be existing applications developed based on JSR 179 java ME api even if the model doesn’t not have inbuilt GPS support. GPS capabilities could also be obtained by connecting to an external GPS device over Bluetooth, but this comes with its own set of challenges. Another option is for old blackberry models (RIM 857/957), which works with a serial GPS receiver attached via cable.
Overview
You must enable GPS on your device, for applications to retrieve the current location. The location is nothing but coordinates for latitude, longitude and altitude.
Additionally, support for JSR 179 Location API for Java ME comes with device software 4.0.2 and later. If you want BlackBerry extensions to JSR 179, you will need device software 5.0.0 and later.
To obtain a location via the GPS support in your device, your application has to do the following:
○ Specify the GPS mode
○ Get the location provider
○ Make GPS request
○ Retrieve the GPS location of a BlackBerry device
Code sample: Specifying the GPS mode
/* JSR 179 */
Criteria myCriteria = new Criteria();
/* JSR 179 extension */
BlackBerryCriteria myBlackBerryCriteria = new BlackBerryCriteria(…);
Dig Deep
There are three GPS modes and they have speficic properties that are described below. You will need to select one based on your application requirements.
○ Autonomous – relies on the GPS satellite only. This mode uses the GPS receiver on the BlackBerry device to retrieve location information. This mode cannot be used indoors or in close proximity to many physical obstructions, and it can take several minutes to fully synchronize with four or more satellites for the first GPS fix. An example application that can use this mode is a Car Parking Spot application.
○ Assisted Mode – GPS satellite and servers on the wireless network only. This mode uses the wireless network to retrieve satellite information. This mode can achieve a fast retrieval of the first GPS fix. An example application that can use this mode is a Nearby Restaurants application.
○ Cell site Mode – Geolocation service or the wireless network to provide on the location information of current base station. This mode uses the wireless network to achieve the first GPS fix, and is generally considered the fastest mode. This mode does not provide BlackBerry device tracking information such as the speed and the bearing. An example application that can use this mode is a Weather Application.
Let us look at the code samples to use the BlackBerry API to get location and satellite information. The code fragments are used to highlight the API rather than give a fully working GPS Application that also provides additional value added information.
First, let us look at a Java class GPSSatteliteInfo listed below. This is a utility class in which we will wrap all the GPS related sample code. The thread implementation is currently empty.
/* packages to import */
import java.util.*;
import java.lang.*;
import net.rim.device.api.gps.*;
/* create public class */
public class GPSSatelliteInfo {
/* member variables */
…
public GPSSatelliteInfo() {
gpsThread = new GPSThread(); //private thread class reference
gpsThread.start();
}
/* private thread class */
private static class GPSThread extends Thread
{
public void run()
{
//do something
}
}
}
○ Next, specify the GPSMode inside the run() method of Thread class
BlackBerryCriteria myCriteria = new BlackBerryCriteria(GPSInfo.GPS_MODE_AUTONOMOUS);
//OR to be on safer side
BlackBerryCriteria myCriteria = new BlackBerryCriteria();
if (GPSInfo.isGPSModeAvailable(GPSInfo.GPS_MODE_ASSIST))
myCriteria.setMode(GPSInfo.GPS_MODE_ASSIST);
else if (GPSInfo.isGPSModeAvailable(GPSInfo.GPS_MODE_AUTONOMOUS))
myCriteria.setMode(GPSInfo.GPS_MODE_AUTONOMOUS);
○ Next, get the LocationProvider and create a BlackBerryLocation object to retrieve the GPS fix including a 300 second timeout expiry.
BlackBerryLocationProvider myProvider;
myProvider = (BlackBerryLocationProvider) LocationProvider.getInstance(myCriteria);
BlackBerryLocation myLocation;
myLocation = (BlackBerryLocation) myProvider.getLocation(300);
○ Retrieve the satellite information
satCount = myLocation.getSatelliteCount();
signalQuality = myLocation.getAverageSatelliteSignalQuality();
dataSource = myLocation.getDataSource();
gpsMode = myLocation.getGPSMode();
SatelliteInfo si;
StringBuffer sb = new StringBuffer("[Id:SQ:E:A]\n");
String separator = ":";
for( Enumeration infoEnum = myLocation.getSatelliteInfo(); infoEnum != null; infoEnum.hasMoreElements();){
si = (SatelliteInfo)e.nextElement();
sb.append(si.getId() + separator);
sb.append(si.getSignalQuality() + separator);
sb.append(si.getElevation() + separator);
sb.append(si.getAzimuth());
sb.append('\n');
}
Note:The assisted mode can be used with BlackBerry devices that are associated with a CDMA network that utilizes PDE server technology. The assisted mode is designed to provide fast retrieval of a GPS fix. Assisted GPS capabilities are currently defined by wireless service providers. In many instances, you must enter into a formal relationship with wireless service providers before you can connect to their PDE server.
if ( !GPSInfo.isGPSModeAvailable(GPSInfo.GPS_MODE_ASSIST) || !GPSSettings.isPDEInfoRequired(GPSInfo.GPS_MODE_ASSIST))
return;
On similar lines, let us see how to retrieve location information.
static double lat, lon;
static float alt, spd, crs;
lat = myLocation.getQualifiedCoordinates().getLatitude();
lon = myLocation.getQualifiedCoordinates().getLongitude();
alt = myLocation.getQualifiedCoordinates().getAltitude();
spd = myLocation.getSpeed();
crs = myLocation.getCourse();
This covers how to retrieve satellite information and location coordinates.
However, there is a lot more that an application should do to provide a good user experience. Majority of times it is driven by the kind of application being developed. For example, if the application is designed to display my location on a map at a given time, then retrieving GPS location one time should suffice. But, at the same time, if the application is designed to keep retrieving the GPS coordinates as person moves some distance, then something more needs to be done. One way is to use the setLocationListener() by passing the interval value, timeout value, and maximum age as parameters to add a LocationListener.)
myProvider.setLocationListener(new handleGPSListener(), 10, -1, -1);
In the class, implement the LocationListener interface. Implement the basic framework for the locationUpdated () method, and the providerStateChanged() method.
public static class handleGPSListener implements LocationListener
{
public void locationUpdated(LocationProvider provider, Location location)
{
if (location.isValid())
{...}
else
{... }
}
public void providerStateChanged(LocationProvider provider, int newState)
{
if (newState == LocationProvider.AVAILABLE)
{...}
else if (newState == LocationProvider.OUT_OF_SERVICE)
{...}
else if (newState == LocationProvider.TEMPORARILY_UNAVAILABLE )
{...}
}
}
This gets invoked at a fixed interval to any location changes. This is ideal for application that is plotting user movement over a map. (Similar to the GPS navigation device to get directions).
We have now covered how to use the BlackBerry JSR 179 extension (aka GPS API) to get satellite and location coordinates. The code covered so far provides a basic working example to retrieve the satellite and location information. The same could be extended to make complex applications. There are other areas which are “good to know” like GPS error code, Location error codes, control the power consumption, preferred response time, manage cost allowed, setting the failover mode (fall back on other available options if one is not available), etc and the reader is advised to refer to the available documentation.
Location Based Services and applications are growing in importance. The BlackBerry platform provides good support for you to get started with building location based applications today. In future posts, we shall delve into deeper topics that help you to take advantage of the full range of BlackBerry location based APIs.
