Titanium Mobile # Modules.CoreMotion
Allows Titanium client applications to access Apple's CoreMotion APIs.
3.3.0# Overview
The Core Motion module provides access to Apple's CoreMotion APIs. The Core Motion module provides support for monitoring various hardware sensors on iOS devices, such as the accelerometer, gyroscope, and magnetometer. The Core Motion module allows you to access the metrics provided by these sensors.
For instruction and examples of using the Core Motion Module, see the Core Motion Module guide (opens new window).
# Requirements
This module only works with devices running iOS 7 and later. Not all devices have the same hardware sensors, so all features may not be available for all devices. Be sure to use the API to check the device for the existence of a feature.
You can only test the Core Motion module on a device. The Core Motion API cannot be tested on the iOS simulator.
Some features may require permission to use "Motion Activity". iOS requires the user's approval to use the "Motion Activity" permission. When the application uses the Core Motion API for the first time, iOS prompts the user to either approve or deny access to the Core Motion features of the device. The user can change the permission settings with Settings > Privacy.
# Getting Started
Once you have installed the module and added it as a depedency,
use require() to access it from JavaScript:
var CoreMotion = require("ti.coremotion");
// The `CoreMotion` variable is a reference to the Module object. Use this reference to make
// subsequent calls to the CoreMotion Module API. The following example shows the step counting
// API of `CoreMotion`.
var pedometer = CoreMotion.createPedometer();
// This code checks to see if the device can gather step counting data
if (pedometer.isStepCountingAvailable()) {
// If it can, it starts the step counter and outputs the data to the console
pedometer.startPedometerUpdates(function(e) {
Ti.API.info(JSON.stringify(e));
});
} else {
Ti.API.warn('This device does not support counting steps.');
}
# Sample Application
The module ZIP file contains a Core Motion sample applications in example/app.js.
# Further Reading
- iOS Developer Library: Core Motion Framework Reference (opens new window)
- iOS Developer Library: Motion Events (opens new window)
# Constants
# ATTITUDE_REFERENCE_FRAME_X_ARBITRARY_CORRECTED_Z_VERTICAL
3.3.0Describes the same reference frame as ATTITUDE_REFERENCE_FRAME_X_ARBITRARY_Z_VERTICAL except that the magnetometer, when available and calibrated, is used to improve long-term yaw accuracy. Using this constant instead of ATTITUDE_REFERENCE_FRAME_X_ARBITRARY_Z_VERTICAL results in increased CPU usage.
# ATTITUDE_REFERENCE_FRAME_X_ARBITRARY_Z_VERTICAL
3.3.0Describes a reference frame in which the Z axis is vertical and the X axis points in an arbitrary direction in the horizontal plane.
# ATTITUDE_REFERENCE_FRAME_X_MAGNETIC_NORTH_Z_VERTICAL
3.3.0Describes a reference frame in which the Z axis is vertical and the X axis points toward magnetic north. Note that using this reference frame may require device movement to calibrate the magnetometer.
# ATTITUDE_REFERENCE_FRAME_X_TRUE_NORTH_Z_VERTICAL
3.3.0Describes a reference frame in which the Z axis is vertical and the X axis points toward true north. Note that using this reference frame may require device movement to calibrate the magnetometer. It also requires the location to be available in order to calculate the difference between magnetic and true north.
# AUTHORIZATION_STATUS_AUTHORIZED
8.3.0Access is authorized by the user.
# AUTHORIZATION_STATUS_DENIED
8.3.0Access is denied by the user.
# AUTHORIZATION_STATUS_NOT_DETERMINED
8.3.0The user has not been prompted yet.
# AUTHORIZATION_STATUS_RESTRICTED
8.3.0Access is denied due to system-wide restrictions.
# ERROR_DEVICE_REQUIRES_MOVEMENT
3.3.0The device must move for a sampling of motion data to occur.
# ERROR_MOTION_ACTIVITY_NOT_AUTHORIZED
3.3.0The app is not currently authorized to use motion activity support.
# ERROR_MOTION_ACTIVITY_NOT_AVAILABLE
3.3.0Motion activity support is not available on the current device.
# ERROR_MOTION_ACTIVITY_NOT_ENTITLED
3.3.0The app is missing a required entitlement.
# ERROR_TRUE_NORTH_NOT_AVAILABLE
3.3.0True north is not available on this device. This usually indicates that the device's location is not yet available.
# MAGNETIC_FIELD_CALIBRATION_ACCURACY_HIGH
3.3.0The accuracy of the magnetic field calibration is high.
# MAGNETIC_FIELD_CALIBRATION_ACCURACY_LOW
3.3.0The accuracy of the magnetic field calibration is low.
# MAGNETIC_FIELD_CALIBRATION_ACCURACY_MEDIUM
3.3.0The accuracy of the magnetic field calibration is medium.
# MAGNETIC_FIELD_CALIBRATION_ACCURACY_UNCALIBRATED
3.3.0The magnetic field estimate is not calibrated.
# MOTION_ACTIVITY_CONFIDENCE_MEDIUM
3.3.0Confidence is good.