1. CIS 136 Building Mobile Apps
Compass
CIS 136 Building Mobile Apps

2. Compass Plug-in provides access to the device's compass
a sensor that detects the direction or heading that the device is pointed
measures the heading in degrees from 0 to
0 is north
navigator.compass is the global object

3. navigator.compass navigator.compass object has 3 methods
getCurrentHeading
watchHeading
clearWatch
Exposes 1 object
Heading

4. navigator.compass.getCurrentHeading()
Get the current compass heading
If successful, the heading is returned in a CompassHeading object
CompassHeading object has 4 properties:
magneticHeading:
The heading in degrees from at a single moment in time. (Number)
trueHeading:
The heading relative to the geographic North Pole in degrees at a single moment in time
A negative value indicates that the true heading can't be determined. (Number)
headingAccuracy:
The deviation in degrees between the reported heading and the true heading. (Number)
timestamp:
The time at which this heading was determined. (milliseconds)

5. navigator.compass.getCurrentHeading()
$(document).on("deviceready", function()
{ navigator.compass.getCurrentHeading(success,error); }
function success(heading) {
// gets compass heading object $(‘#heading‘).html=heading.magneticHeading);
function error(error)
//gets error object

6. navigator.compass.watchHeading
Gets the device's current heading at a regular interval
Can accept options
compass Options may contain the following keys:
frequency: How often to retrieve the compass heading in milliseconds. (Number) (Default: 100)
filter: The change in degrees required to initiate a watchHeading success callback (Number)
When this value is set, frequency is ignored
Each time the heading is retrieved, the success function (aka callback function ) is executed
Returns data – in this example an object named watchID
returned watch ID references the compass watch interval
The watch ID can be used with navigator.compass.clearWatch method to stop watching the navigator.compass

7. navigator.compass.watchHeading
$(document).on("deviceready", function()
{ var options = { frequency: 3000 }; // Update every 3 seconds
var watchID = navigator.compass.watchHeading(success,error,options);
});
function success(heading) {
$(‘#heading’).html = 'Heading: ' + heading.magneticHeading; }
function error(compassError)
$(‘#msg’).html = 'Compass error: ' + compassError.code

8. navigator.compass.clearWatch()
Stops watching the compass referenced by the watch ID parameter
watchID: The ID returned by navigator.compass.watchHeading
navigator.compass.clearWatch(watchID);
Full example:
var watchID = navigator.compass.watchHeading(onSuccess, onError, options);
// ... later on ...

9. navigator.compass quirkiness
Quirks
IOS
Only one watchHeading can be in effect at one time
The trueHeading property is only returned for location services enabled via navigator.geolocation.watchLocation()
heading factors in the device's current orientation
It does not reference its absolute position (for apps that supports that orientation).
Windows Phone
No support for filter
Android
The trueHeading property is not supported, but reports the same value as magneticHeading
The headingAccuracy property is always 0 because there is no difference between the magneticHeading and trueHeading

10. navigator.compass Compass Error object function error(compassError){
$(‘#msg’).html = 'Compass error: ' + compassError.code }
Compass Error object
A CompassError object is returned to the error function (i.e. compassError callback function) when an error occurs
Provides 1 property:
Code: predefined per these constants
CompassError.COMPASS_INTERNAL_ERR
CompassError.COMPASS_NOT_SUPPORTED