Motion Overview

Exposes Core Motion functionalities such as accessing the device’s accelerometer, gyroscope, and magnetometer data.

Tracking of motion metrics can impact performance and battery drain. Use this feature judiciously to avoid negatively affecting the user experience.

Motion

autoStart: boolean

If set, motion tracking will start automatically as soon as any attribute is read. Default is true.

Set to false if you want to control when motion is tracked manually using the start and stop functions.

motion.start(referenceFrame)

Start tracking motion metrics.

Parameters:

referenceFrame (number) – The reference frame in which to track motion metrics. Can be one of the following values:

  • motion.referenceFrame.XArbitraryZVertical (default): The X-axis is arbitrary and the Z-axis is vertical.

  • motion.referenceFrame.XArbitraryCorrectedZVertical: The X-axis is arbitrary and the Z-axis is vertical. If available, the magnetometer will be used to correct for accumulated yaw errors.

  • motion.referenceFrame.XMagneticNorthZVertical: The X-axis points toward the magnetic north and the Z-axis is vertical.

  • motion.referenceFrame.XTrueNorthZVertical: The X-axis points toward the true north and the Z-axis is vertical.

motion.stop()

Stop tracking motion metrics and set autoStart to false.

updateInterval: number

The interval, in seconds, at which motion data is updated. This value can be set to control the frequency of motion updates. A lower value means more frequent updates, which can provide smoother motion tracking but may consume more power. The default value is 1/30 second.

Note that the interval is clamped between limits defined by the system.

gravity: vec2

The gravity vector in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

acceleration: vec2

The acceleration vector in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

rotationRate: vec2

The rotation rate in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

sensorLocation: integer

The location of the device’s sensors.

The value can be one of the following:

  • motion.sensorLocation.default: The location of the device’s sensors is the default one.

  • motion.sensorLocation.headphoneLeft: The device’s sensors are located near the left headphone.

  • motion.sensorLocation.headphoneRight: The device’s sensors are located near the right headphone.

heading: number

The heading in degrees relative to the current reference frame.

Device Orientation

class motion.attitude

Represents a measurement of your device attitude. This orientation of a body relative to a given frame of reference.

You can set motion.attitude.referenceFrame to specify the frame of reference in which the attitude is expressed.

The value can be one of the following motion.referenceFrame.XArbitraryZVertical, motion.referenceFrame.XArbitraryCorrectedZVertical, motion.referenceFrame.XMagneticNorthZVertical, motion.referenceFrame.XTrueNorthZVertical.

Parameters:

  • pitch (number) – The pitch of the device, in radians.

  • yaw (number) – The yaw of the device, in radians.

  • roll (number) – The roll of the device, in radians.

  • rotationMatrix (mat3x3) – The rotation matrix that describes the device’s orientation.

  • quaternion (quat) – The quaternion that describes the device’s orientation.

  • referenceFrame (integer) – The reference frame in which motion metrics are tracked.

XArbitraryZVertical: integer

The X-axis is arbitrary and the Z-axis is vertical.

XArbitraryCorrectedZVertical: integer

The X-axis is arbitrary and the Z-axis is vertical. The system will attempt to correct for the device’s orientation.

XMagneticNorthZVertical: integer

The X-axis points toward the magnetic north and the Z-axis is vertical.

XTrueNorthZVertical: integer

The X-axis points toward the true north and the Z-axis is vertical.

Magnetic Field Data

class motion.magnetic
field: vec3

The magnetic field vector in the device’s reference frame.

accuracy: integer

The accuracy of the magnetic field data.

The value can be one of the following:

  • motion.magneticAccuracy.uncalibrated: The magnetic field data is uncalibrated.

  • motion.magneticAccuracy.low: The magnetic field data is of low accuracy.

  • motion.magneticAccuracy.medium: The magnetic field data is of medium accuracy.

  • motion.magneticAccuracy.high: The magnetic field data is of high accuracy.