Mobile Compass Plugin for Building Apps

1. 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 359.99 • 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 • CompassHeadingobject has 4 properties: • magneticHeading: • The heading in degrees from 0-359.99 at a single moment in time. (Number) • trueHeading: • The heading relative to the geographic North Pole in degrees 0-359.99 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.clearWatchmethod to stop watching the navigator.compass

7. navigator.compass.watchHeading $(document).on("deviceready", function() {var options = { frequency: 3000 }; // Update every 3 seconds varwatchID = 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: varwatchID = navigator.compass.watchHeading(onSuccess, onError, options); // ... later on ... navigator.compass.clearWatch(watchID);

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 • No support for filter

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