Cosc 5/4730

GPS/LocationBlackberry JSR-179: javax.microedition.location

andandroid.location

Simulator notes

• All the simulators can simulator GPS/location information– Blackberry (simulator)• Simulate-> gps location

– Android• DDMS• commands (geo) to the emulator.

BLACKBERRY

java.microedition.Location API• Provides Latitude and Longitude coordinates in a position response,

along with the time it was determined and measure of accuracy.– If possible in hardware may include

• orientation (compass, pitch, roll) of the device• the speed at which the device is traveling• Street address

– provides additional feature• access to a system-wide database of landmarks and positions of those landmarks.

– User specified.

• Blackberry uses the same package– and extends with net.rim.device.api.gps

• BlackBerryCriteria, BlackBerryLocation, BlackBeryLocationProvider

javax.microedition.location package

• LocationProvider – Hardware or software module, which provides a static factory method to return a specific

LocationProvider– This is the starting point for applications using this API and represents a source of the location

information.• Criteria

– The criteria used for the selection of the location provider is defined by the values in this class.• desired accuracy and cost to the user

• Location– The Location class represents the standard set of basic location information, includes timestamp,

coordinates, accuracy, etc…• Coordinates

– The Coordinates class represents coordinates as latitude-longitude-altitude values. Provides methods to interconvert between floating-point and human-readable textual representations of coordinates.

• QualifiedCoordinates– The QualifiedCoordinates class represents coordinates as latitude-longitude-altitude values that are

associated with an accuracy value. Subclass of Coordinates

javax.microedition.location package(2)

• AddressInfo– The AddressInfo class holds textual address information about a

location.• Orientation

– The Orientation class represents the physical orientation of the device.• Landmark

– The Landmark class represents a landmark, i.e. a known location with a name. User's landmarks, but there is always a default landmark store.

• LandmarkStore – The LandmarkStore class provides methods to store, delete and

retrieve landmarks from a persistent landmark store.

javax.microedition.location package(3)

• There are also two listeners• LocationListener

– The LocationListener represents a listener that receives events associated with a particular LocationProvider.

– Gives your application a means to regularly receive position reports– implement the locationUpdated and providerStateChanged method

• ProximityListener– This interface represents a listener to events associated with

detecting proximity to some registered coordinates.– Called when the device is within/reached a predetermined location– implement proximityEvent and monitoringStateChanged method

Using the Location API

• Establish the criteria for the location request• Obtain a LocationProvider instance that meets your

criteria• Determine the positions location.Criteria cr= new Criteria();// Get an instance of the providerLocationProvider lp= LocationProvider.getInstance(cr);// Request the location, setting a one-minute timeoutLocation l = lp.getLocation(60);Coordinates c = l.getQualifiedCoordinates();if(c != null ) {

// Use coordinate information}

CriteriaCriteria Units Default Value Setter Accessor

Horizontal accuracy

Meters NO_REQUIREMENT setHorizontalAccuracy

getHorizontalAccuracy

Vertical accuracy Meters NO_REQUIREMENT setVerticalAccuray getVerticalAccuracy

Preferred response time Milliseconds NO_REQUIREMENT

setPreferredResponseTime

getPreferredResponseTime

Power consumption int NO_REQUIREMENT

setPreferredPowerConsumption

getPreferredPowerConsumption

Cost allowed boolean true (allowed to cost) setCostAllowed isAllowedToCost

Speed and course required boolean false (not required)

setSpeedAndCourseRequired

getSpeedAndCourseRequired

Altitude required boolean false (not required) setAltitudeRequired getAltitudeRequired

Address required boolean false (not required) setAddressInfoRequired

getAddressInfoRequired

Note: NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM, POWER_USAGE_HIGH are field constants

BlackBerryCriteria

• Inherits everything from Criteria – Adds GPS modes, and failover in case the GPS

mode spec’d fails. – Adds requires Requirements for number of

satellites, signal quality, etc.• GPSINFO, GPSettings, SatelliteInfo

– These three classes require a signed app.

Location methods• boolean isValid()

– Returns whether this Location instance represents a valid location with coordinates or an invalid one where all the data, especially the latitude and longitude coordinates, may not be present.

• QualifiedCoordinates getQualifiedCoordinates()– Returns the coordinates of this location and their accuracy.

• AddressInfo getAddressInfo()– Returns the AddressInfo associated with this Location object.

• long getTimestamp()– Returns the time stamp at which the data was collected.

• float getCourse()– Returns the heading in degrees relative to true north.

• float getSpeed()– Returns the terminal's current ground speed in meters per second at the time of

measurement.

Location methods (2)

• int getLocationMethod()– Returns information about the location method

used.• String getExtraInfo(String mimetype)– Returns extra information about the location.

Coordinates • float getAltitude()

– Returns the altitude component of this coordinate.• double getLatitude()

– Returns the latitude component of this coordinate.• double getLongitude()

– Returns the longitude component of this coordinate.• void setAltitude(float altitude)

– Sets the geodetic altitude for this point.• void setLatitude(double latitude)

– Sets the geodetic latitude for this point.• void setLongitude(double longitude)

– Sets the geodetic longitude for this point.

Coordinates (2)

• static double convert(String coordinate)– Converts a String representation of a coordinate

into the float representation as used in this API.• float distance(Coordinates to)– Calculates the geodetic distance between the two

points according to the ellipsoid model of WGS84.

AddressInfo

• String getField(int field)– Returns the value of an

address field.• void setField(int field,

String value)– Sets the value of an

address field.– Mostly for use with

landmarks

• fields:– BUILDING_FLOOR, BUILDING_NAME,

BUILDING_ROOM, BUILDING_ZONE– STREET, CITY, COUNTRY, POSTAL_CODE– STATE, COUNTY, DISTRICT,

PHONE_NUMBER– EXTENSION

• like an apartment or house number.– COUNTRY_CODE

• Address field denoting country as a two-letter ISO 3166-1 code.

– CROSSING1• Address field denoting a street in a

crossing.– CROSSING2

• Address field denoting a street in a crossing.

– URL• Address field denoting a URL for this place.

listener • For the LocationProvider• addProximityListener(ProximityListener listener,

Coordinates coordinates, float proximityRadius)– Adds a ProximityListener for updates when proximity to the

specified coordinates is detected.• removeProximityListener(ProximityListener listener)

– Removes a ProximityListener from the list of recipients for updates.

• setLocationListener(LocationListener listener, int interval, int timeout, int maxAge)– Adds a LocationListener for updates at the defined interval.

Lastly

• Get the last known location, wiout doing much. Note the data maybe out of date.– Location l =

LocationProvider.getLastKnownLocation();• int getState(), provides the state of the

location service– LocationProvider.AVAILABLE , OUT_OF_SERVICE

TEMPORARILY_UNAVAILABLE

Example code

• The example code on the website is very simple to provide a feel for the location.– You can use default locations to test

– Default Route will also changeThe points along a route.

ANDROID

Android

• Very similar to JSR-179• Get a LocationManger from the system• Choose a provider with Criteria or just a

provider– providers: gps, network, etc…

• get the Location and use the data.• There is a LocationListener

Permissions

• Add them to the AndroidManifest.xml<uses-permission android:name="android.permission.INTERNET" />

– Maybe needed for some things, but needed the mapactivity.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />– GPS location

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />– Cell_ID or WiFI location

• There maybe other needed as well– ACCESS_LOCATION_EXTRA_COMMANDS, ACCESS_MOCK_LOCATION– See http://developer.android.com/intl/zh-CN/reference/android/Manifest.permission.html

for all permissions.

android.location package• Address

– A class representing an Address, i.e, a set of Strings describing a location. • Criteria

– A class indicating the application criteria for selecting a location provider. • Geocoder

– A class for handling geocoding and reverse geocoding. • GpsSatellite

– This class represents the current state of a GPS satellite. • GpsStatus

– This class represents the current state of the GPS engine. • Location

– A class representing a geographic location sensed at a particular time (a "fix"). • LocationManager

– This class provides access to the system location services. • LocationProvider

– An abstract superclass for location providers.

android.location package (2)• Listeners• GpsStatus.Listener

– Used for receiving notifications when GPS status has changed. • GpsStatus.NmeaListener

– Used for receiving NMEA sentences from the GPS. • LocationListener

– Used for receiving notifications from the LocationManager when the location has changed.

• A addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent) can be added to the LocationManger– Sets a proximity alert for the location given by the position (latitude, longitude)

and the given radius.

LocationManager

• This is the factory class to get location information– You do not instantiate this class directly, retrieve it

through Context.getSystemService(Context.LOCATION_SERVICE)

– Now you can get a Location information with getLastKnownLocation(String Provider);

– and more information about the provider with LocationProvider getProvider(String name)

• Providers are found in a couple of ways

Providers

• List<string> getProviders(Boolean enabledOnly)– get a list of providers, true for ones that are working

• String getBestProvider(Criteria criteria, boolean enabledOnly)– get a provider based on Criteria (similar what was

already covered)• List<string> getAllProviders()– Returns a list of all providers– You can use boolean isProvidersEnabled(String) to

determine if it is enabled or not.

LocationProvider• Information about the Provider• int getAccuracy(), int getPowerRequirement(), boolean hasMonetaryCost()• boolean meetsCriteria(Criteria criteria)• boolean requiresCell()

– Returns true if the provider requires access to an appropriate cellular network (e.g., to make use of cell tower IDs), false otherwise.

• boolean requiresNetwork()– Returns true if the provider requires access to a data network (e.g., the Internet), false otherwise.

• boolean requiresSatellite()– Returns true if the provider requires access to a satellite-based positioning system (e.g., GPS), false

otherwise.• boolean supportsAltitude()

– Returns true if the provider is able to provide altitude information, false otherwise.• boolean supportsBearing()

– Returns true if the provider is able to provide bearing information, false otherwise.• boolean supportsSpeed()

– Returns true if the provider is able to provide speed information, false otherwise.

Location• Has a standard set of getters you would expect– double getLatitude(), double getLongitude(), float getSpeed(),

double getAltitude()– long getTime()

• Returns the UTC time of this fix, in milliseconds since January 1, 1970.– float getAccuracy()

• Returns the accuracy of the fix in meters.– float getBearing()

• Returns the direction of travel in degrees East of true North.– Returns true if has X

• hasAltitude(), hasBearing(), hasSpeed(), hasAccuracy()

Location (2)• float bearingTo(Location dest)

– Returns the approximate initial bearing in degrees East of true North when traveling along the shortest path between this location and the given location.

• static void distanceBetween(double startLatitude, double startLongitude, double endLatitude, double endLongitude, float[] results)– Computes the approximate distance in meters between two locations,

and optionally the initial and final bearings of the shortest path between them.

• float distanceTo(Location dest)– Returns the approximate distance in meters between this location and

the given location.

Example code get a locationLocationManager myL = (LocationManager)

getBaseContext().getSystemService(Context.LOCATION_SERVICE);//or use (LocationManager) getContext().getSystemService(Context.LOCATION_SERVICE);

Location loc = myL.getLastKnownLocation("gps");if (loc != null ) { double sLatitude = loc.getLatitude(); double sLongitude = loc.getLongitude(); String location = sLatitude+","+sLongitude; } else { //No location can be found with gps}

LocationListener• Create a LocationListener or implement LocationListener in a

class• The following methods must be implemented

– void onLocationChanged(Location location)• Called when the location has changed.

– void onProviderDisabled(String provider)• Called when the provider is disabled by the user.

– void onProviderEnabled(String provider)• Called when the provider is enabled by the user.

– void onStatusChanged(String provider, int status, Bundle extras)• Called when the provider status changes.• Status can be OUT_OF_SERVICE, TEMPORARILY_UNAVAILABLE, AVAILABLE

LocationListener

• added to your LocationManger• LocationManager myL = (LocationManager)

getBaseContext().getSystemService(Context.LOCATION_SERVICE);• myL.requestLocationUpdates(LocationManager.GPS_PROVIDER, 0, 0,

myLocationListener);– here Use a GPS provider, could be NETWORK_PROVIDER– minTime the minimum time interval for notifications, in milliseconds. This field is only

used as a hint to conserve power, and actual time between location updates may be greater or lesser than this value. Here set to 0

– minDistance the minimum distance interval for notifications, in meters. Again set to 0 here.

– myLocationListener is a the LocationListener to be called.

Example code

• A simple android program is provided on the website. It will display location information in a TextView. It also has a LocationListener.

• Use the ddms.bat in the tools directory to change the location info.

References• JavaDocs

– http://mobilezoo.biz/jsr/179/index.html– http://www.blackberry.com/developers/docs/5.0.0api/index.html

• Select location in the packages window

• J2ME and Location-Based Services– http://developers.sun.com/mobility/apis/articles/location/

• Course Book, Chapter 17 Finding Your Way• Android (many links have mapactivity as well, skipped in lecture)

– http://developer.android.com/intl/zh-CN/guide/topics/location/index.html– http://foo.jasonhudgins.com/2007/12/cruising-around-with-android.html– http://www.androidcompetencycenter.com/2009/01/android-location-api/http://

www.vogella.de/articles/Android/article.html#locationapi– http://www.damonkohler.com/2009/02/android-recipes.html

• Controlling the android emulator– http://developer.android.com/intl/zh-CN/guide/developing/tools/ddms.html#emulator-

control

QA&