The compass API allows a developer to read the mobile device’s heading (using the device compass if available). The API works almost the same as the Accelerometer API; you can either query the heading value once or define a watch to periodically measure the heading value. The only differences between the two are in the results object, which is passed to the onSuccess function, and options that can be set when creating a watch.
To enable an application to read the heading, you must first add the device orientation plugin to your project by opening a terminal window and issuing the following CLI command from the Cordova project folder:
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device- orientation.git
Like the Accelerator API, the Compass API exposes three methods:
▪
compass.getCurrentHeading▪
compass.watchHeading▪
compass.clearWatchThe getCurrentHeading method allows an application to query the compass’s current orientation. The
watchHeading and clearWatch methods are used to allow an application to capture compass headings over a period of time, taking repeated measurements from the compass at a specific time interval. To measure the compass’s orientation, you use something like the following in your application:
navigator.compass.getCurrentHeading(onSuccess, onFailure);
In this example, the call to getCurrentHeading includes the names of two functions: onSuccess is executed when the heading has been successfully measured, and onFailure is executed when an error occurs; following are examples of some functions that can be used for this purpose:
ptg11524036
function onSuccess(res) {
magneticHeading = res.magneticHeading; trueHeading =res. res.trueHeading; headingAccuracy = res.headingAccuracy var d = new Date(res.timestamp); timestamp = d.toLocaleString(); }
function onFailure(err) { alert("Error: " + err.code); }
The heading object (res in the example) returned to the onSuccess function has the properties described in Table 12.2.
Table 12.2 CCoommppaassss RReessuullttss VVaalluueess
PPrrooppeerrttyy DDeessccrriippttiioonn
magneticHeading The compass heading in degrees from 0 to 359.
trueHeading The compass heading relative to the geographic North Pole in degrees from 0 to 259. A negative value indicates that the true heading cannot be determined.
headingAccuracy The difference in degrees between the magnetic heading and the true heading values. timestamp The date and time that the measurement was made (number of milliseconds since midnight January 1, 1970)
When an error occurs, the onFailure function is passed an error code, which can be queried to determine the cause of the error. Possible values are CompassError.COMPASS_INTERNAL_ERR and
CompassError.COMPASS_NOT_SUPPORTED.
To use compass.watchHeading, an application sets up a watch using the following code:
var options = {frequency : 1000};
watchID = navigator.compass.watchHeading(onSuccess, onFailure, options);
In this particular example, the code uses the same onSuccess and onFailure functions from the previous example. The options object defines the frequency of the accelerator measurement in milliseconds. So, to measure the current heading values every 1 second, you would use 1000, as shown in the example. To measure every half second, use a frequency of 500. You can also specify a filter
value, which defines a minimum degree value change, which must occur before the watch is fired. Because compass values fluctuate pretty rapidly, you will want to set a filter to reduce the number of times heading measurement is made (and returned to your program) so your program can respond only to more dramatic changes in heading.
In the code, the result of the call to watchHeading is assigned to a variable called watchID, which is used later to cancel the watch, as shown in here:
ptg11524036 With all of this in place, the application will read the compass every second and pass the values to the
onSuccess function to process the results. To see a complete application using the Compass API, refer to Chapter 14.
G
Geeoollooccaattiioonn
The Cordova Geolocation API allows an application to determine the physical location of the device running an application. The API is based on the W3C’s Geolocation API and works almost the same as the Accelerometer and Compass APIs; you can either query the location once or define a watch to periodically calculate the location. The only differences between them are in the results object, which is passed to the onSuccess function, and options that can be set when creating a watch. To enable an application to determine the device’s location, you must first add the Geolocation plugin to your project by opening a terminal window and issuing the following CLI command from the Cordova project folder:
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git
The Geolocation API exposes three methods:
▪
compass.getCurrentPosition▪
compass.watchPosition▪
compass.clearWatchThe getCurrentPosition method allows an application to determine the device’s current location. The watchPosition and clearWatch methods are used to allow an application to periodically calculate the device’s location over a period of time, making repeated calculations at a specific time interval.
When the Geolocation API returns a location object, the object exposes coordinates and timestamp
properties. The timestamp property contains the date and time that the measurement was made in number of milliseconds since midnight January 1, 1970. The coordinates property is another object that includes the properties described in Table 12.3.
Table 12.3 CCoooorrddiinnaatteess PPrrooppeerrttiieess
PPrrooppeerrttyy DDeessccrriippttiioonn
accuracy The accuracy of the latitude and longitude coordinates in meters. altitude The device’s height in meters above the ellipsoid (http://tinyurl.com/nje9d2o).
altitudeAccuracy The accuracy of the altitude coordinate in meters. heading The device heading (direction of travel) in degrees. latitude The latitude portion of the location in decimal degrees. longitude The longitudinal portion of the location in decimal degrees. speed The device’s current speed in meters per second.
ptg11524036