Compass

Provides a consistent API to the compass on all platforms.

The compass provides 1D directional information of the device relative to magnetic north. The direction is an angular heading value rotating about the gravitational axis, measured in degrees. Heading equal to 0 represents magnetic north.

When motion events are not available on the device, Compass events are polyfilled with horizontal pan touch events.

Example

var compass = new MotionStack.Compass();

compass.start(function(e) {
  // log a single reading and
  // then stop further updates
  console.log(e.heading);
  compass.stop();
});

Constructor

new MotionStack.Compass([options])

Create a new Compass instance object.

Argument Type Description
options Object Options to pass in for the new Compass instance (optional)

  • fireOnAnimationFrame {Boolean}
  • Only emit the latest event within requestAnimationFrame intervals.


    Default: false

  • source {String}
  • The source used to calculate the reported data in order of approximation. If the specified source is not available, then the next available source is used.

    • "detectCompass" determines which is the best source estimate to use.
    • "rawOrientation" browser estimate.
    • "sensorFusion" sensor fusion via a Kalman filter.
    • "filteredOrientation" dynamic low-pass filter on the browser estimate.
    • "gravityPolyfill" accelerometer gravity estimate.
    • "touch" touch sensor.


    Default: "detectCompass"

var compass = new MotionStack.Compass();

Static Methods

isSupported()

Returns a Boolean value describing whether the device has a compass.

MotionStack.Compass.isSupported(); // true or false

Instance Methods

start(callback, [context])

Start receiving compass updates.

Argument Type Description
callback Function Callback function that receives an object as an argument

  • function(e)
  • e.heading {Number}
    Angular offset from magnetic north (degrees).
  • e.error {Number}
    Margin of error for compass measurement (degrees).
  • e.timeStamp {Number}
    The time in milliseconds when the data is collected.
  • e.source {String}
    The source used to calculate the reported data.

    • "rawOrientation" browser estimate.
    • "sensorFusion" sensor fusion via a Kalman filter.
    • "filteredOrientation" dynamic low-pass filter on the browser estimate.
    • "gravityPolyfill" accelerometer gravity estimate.
    • "touch" touch sensor.

context Object Context in which to invoke the callback (optional).
compass.start(function(e) {
  console.log(e.heading);
});

stop()

Stop compass updates.

compass.stop();

Source

src/interfaces/Compass.js