1. Cosc 5/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 LocationProvider lp= 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 UnitsDefault ValueSetterAccessor Horizontal accuracy Meters NO_REQUIREMENT setHorizontalAccura cy getHorizontalAccur acy Vertical accuracyMeters NO_REQUIREMENT setVerticalAccuraygetVerticalAccuracy Preferred response time Milliseconds NO_REQUIREMENT setPreferredRespon seTime getPreferredRespon seTime Power consumption int NO_REQUIREMENT setPreferredPowerC onsumption getPreferredPower Consumption Cost allowedboolean true (allowed to cost) setCostAllowedisAllowedToCost Speed and course required boolean false (not required) setSpeedAndCourse Required getSpeedAndCours eRequired Altitude requiredboolean false (not required) setAltitudeRequiredgetAltitudeRequire d Address requiredboolean false (not required) setAddressInfoRequ ired getAddressInfoRequ ired 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 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.

12. Location methods (2) int getLocationMethod() – 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, int maxAge) – 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(); int getState(), 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 – Maybe needed for some things, but needed the mapactivity. – GPS 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_SERVIC E) – 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

25. Providers List 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 getAllProviders() – Returns a list of all providers – You can use boolean isProvidersEnabled(String) to determine if it is enabled or not.

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

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 LocationManager 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 }

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

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 &