Cosc 5/4730

1. Cosc5/4730 GPS/Location Blackberry JSR-179: javax.microedition.location and android.location

2. Simulator notes • All the simulators can simulator GPS/location information • Blackberry (simulator) • Simulate-> gps location • Android • DDMS • commands (geo) to the emulator.

3. Blackberry

4. 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

5. 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

6. 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.

7. 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

8. 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 provider LocationProviderlp= LocationProvider.getInstance(cr); // Request the location, setting a one-minute timeout Location l = lp.getLocation(60); Coordinates c = l.getQualifiedCoordinates(); if(c != null ) { // Use coordinate information }

9. Criteria Note: NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM, POWER_USAGE_HIGH are field constants

10. 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.

11. Location methods • booleanisValid() • 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. • QualifiedCoordinatesgetQualifiedCoordinates() • Returns the coordinates of this location and their accuracy. • AddressInfogetAddressInfo() • 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.

12. Location methods (2) • intgetLocationMethod() • Returns information about the location method used. • String getExtraInfo(String mimetype) • Returns extra information about the location.

13. 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.

14. 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.

15. 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.

16. 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, intmaxAge) • Adds a LocationListener for updates at the defined interval.

17. Lastly • Get the last known location, wiout doing much. Note the data maybe out of date. • Location l = LocationProvider.getLastKnownLocation(); • intgetState(), provides the state of the location service • LocationProvider.AVAILABLE , OUT_OF_SERVICE TEMPORARILY_UNAVAILABLE

18. 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 change The points along a route.

19. Android

20. 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

21. 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.

22. 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.

23. 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.

24. 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 LocationProvidergetProvider(String name) • Providers are found in a couple of ways

25. Providers • List<string> getProviders(Boolean enabledOnly) • get a list of providers, true for ones that are working • String getBestProvider(Criteria criteria, booleanenabledOnly) • get a provider based on Criteria (similar what was already covered) • List<string> getAllProviders() • Returns a list of all providers • You can use booleanisProvidersEnabled(String) to determine if it is enabled or not.

26. LocationProvider • Information about the Provider • intgetAccuracy(), intgetPowerRequirement(), booleanhasMonetaryCost() • booleanmeetsCriteria(Criteria criteria) • booleanrequiresCell() • Returns true if the provider requires access to an appropriate cellular network (e.g., to make use of cell tower IDs), false otherwise. • booleanrequiresNetwork() • Returns true if the provider requires access to a data network (e.g., the Internet), false otherwise. • booleanrequiresSatellite() • Returns true if the provider requires access to a satellite-based positioning system (e.g., GPS), false otherwise. • booleansupportsAltitude() • Returns true if the provider is able to provide altitude information, false otherwise. • booleansupportsBearing() • Returns true if the provider is able to provide bearing information, false otherwise. • booleansupportsSpeed() • Returns true if the provider is able to provide speed information, false otherwise.

27. 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()

28. 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.

29. Example code get a location LocationManagermyL = (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 }

30. 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

31. LocationListener • added to your LocationManger • LocationManagermyL = (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.

32. 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.

33. 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

34. Q A &