CMMotionManager Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/CoreMotion.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Event Handling Guide for iOS
Declared in
CMError.h
CMErrorDomain.h
CMMotionManager.h
Related sample code

Overview

A CMMotionManager object is the gateway to the motion services provided by iOS. These services provide an app with accelerometer data, rotation-rate data, magnetometer data, and other device-motion data such as attitude. These types of data originate with a device’s accelerometers and (on some models) its magnetometer and gyroscope.

After creating an instance of CMMotionManager, an app can use it to receive four types of motion: raw accelerometer data, raw gyroscope data, raw magnetometer data, and processed device-motion data (which includes accelerometer, rotation-rate, and attitude measurements). The processed device-motion data provided by Core Motion’s sensor fusion algorithms gives the device’s attitude, rotation rate, calibrated magnetic fields, the direction of gravity, and the acceleration the user is imparting to the device.

An app can take one of two approaches when receiving motion data, by handling it at specified update intervals or periodically sampling the motion data. With both of these approaches, the app should call the appropriate stop method (stopAccelerometerUpdates, stopGyroUpdates, stopMagnetometerUpdates, and stopDeviceMotionUpdates) when it has finished processing accelerometer, rotation-rate, magnetometer, or device-motion data.

Handling Motion Updates at Specified Intervals

To receive motion data at specific intervals, the app calls a “start” method that takes an operation queue (instance of NSOperationQueue) and a block handler of a specific type for processing those updates. The motion data is passed into the block handler. The frequency of updates is determined by the value of an “interval” property.

Periodic Sampling of Motion Data

To handle motion data by periodic sampling, the app calls a “start” method taking no arguments and periodically accesses the motion data held by a property for a given type of motion data. This approach is the recommended approach for apps such as games. Handling accelerometer data in a block introduces additional overhead, and most game apps are interested only the latest sample of motion data when they render a frame.

Hardware Availability and State

If a hardware feature (for example, a gyroscope) is not available on a device, calling a start method related to that feature has no effect. You can find out whether a hardware feature is available or active by checking the appropriate property; for example, for gyroscope data, you can check the value of the gyroAvailable or gyroActive properties.

Tasks

Managing Accelerometer Updates

Determining Whether the Accelerometer Is Active and Available

Accessing Accelerometer Data

Managing Gyroscope Updates

Determining Whether the Gyroscope Is Active and Available

Accessing Gyroscope Data

Managing Magnetometer Updates

Determining Whether the Magnetometer Is Active and Available

Accessing Magnetometer Data

Managing the Device Movement Display

Managing Device Motion Updates

Accessing Attitude Reference Frames

Determining Whether the Device Motion Hardware Is Active and Available

Accessing Device Motion Data

Properties

accelerometerActive

A Boolean value that indicates whether accelerometer updates are currently happening. (read-only)

@property(readonly, nonatomic, getter=isAccelerometerActive) BOOL accelerometerActive
Discussion

This property indicates whether startAccelerometerUpdatesToQueue:withHandler: or startAccelerometerUpdates has been called since the last time stopAccelerometerUpdates was called. (If the start methods hadn’t been called, the app could be getting updates from the accelerometer after calling, for example, startDeviceMotionUpdates, but this property would return NO.)

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

accelerometerAvailable

A Boolean value that indicates whether an accelerometer is available on the device. (read-only)

@property(readonly, nonatomic, getter=isAccelerometerAvailable) BOOL accelerometerAvailable
Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

accelerometerData

The latest sample of accelerometer data. (read-only)

@property(readonly) CMAccelerometerData *accelerometerData
Discussion

If no accelerometer data is available, the value of this property is nil. An app that is receiving accelerometer data after calling startAccelerometerUpdates periodically checks the value of this property and processes the acceleration data.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

accelerometerUpdateInterval

The interval, in seconds, for providing accelerometer updates to the block handler.

@property(assign, nonatomic) NSTimeInterval accelerometerUpdateInterval
Discussion

The system supplies accelerometer updates to the block handler specified in startAccelerometerUpdatesToQueue:withHandler: at regular intervals determined by the value of this property. The interval units are in seconds. The value of this property is capped to minimum and maximum values; the maximum value is determined by the maximum frequency supported by the hardware. If your app is sensitive to the intervals of acceleration data, it should always check the timestamps of the delivered CMAccelerometerData instances to determine the true update interval.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

attitudeReferenceFrame

Returns either the reference frame currently being used or the default attitude reference frame (read-only)

@property(readonly, nonatomic) CMAttitudeReferenceFrame attitudeReferenceFrame
Discussion

If device motion is active, this property returns the reference frame currently in use. If device motion is not active but has been active since the app was last launched, this property returns the last frame used. If device motion has not been active since the app was last launched, this property returns the default attitude reference frame for the device. If device motion is not available on the device, the value is undefined.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

deviceMotion

The latest sample of device-motion data. (read-only)

@property(readonly) CMDeviceMotion *deviceMotion
Discussion

If no device-motion data is available, the value of this property is nil. An app that is receiving device-motion data after calling startDeviceMotionUpdates periodically checks the value of this property and processes the device-motion data.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

deviceMotionActive

A Boolean value that determines whether the app is receiving updates from the device-motion service. (read-only)

@property(readonly, nonatomic, getter=isDeviceMotionActive) BOOL deviceMotionActive
Discussion

This property indicates whether startDeviceMotionUpdatesToQueue:withHandler: or startDeviceMotionUpdates has been called since the last time stopDeviceMotionUpdates was called.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

deviceMotionAvailable

A Boolean value that indicates whether the device-motion service is available on the device. (read-only)

@property(readonly, nonatomic, getter=isDeviceMotionAvailable) BOOL deviceMotionAvailable
Discussion

The device-motion service is available if a device has both an accelerometer and a gyroscope. Because all devices have accelerometers, this property is functionally equivalent to gyroAvailable.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

deviceMotionUpdateInterval

The interval, in seconds, for providing device-motion updates to the block handler.

@property(assign, nonatomic) NSTimeInterval deviceMotionUpdateInterval
Discussion

The system supplies device-motion updates to the block handler specified in startDeviceMotionUpdatesToQueue:withHandler: at regular intervals determined by the value of this property. The interval units are in seconds. The value of this property is capped to minimum and maximum values; the maximum value is determined by the maximum frequency supported by the hardware. If your app is sensitive to the intervals of device-motion data, it should always check the timestamps of the delivered CMDeviceMotion instances to determine the true update interval.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

gyroActive

A Boolean value that determines whether gyroscope updates are currently happening. (read-only)

@property(readonly, nonatomic, getter=isGyroActive) BOOL gyroActive
Discussion

This property indicates whether startGyroUpdatesToQueue:withHandler: or startGyroUpdates has been called since the last time stopGyroUpdates was called. (If the start methods hadn’t been called, the app could be getting updates from the gyroscope after calling, for example, startDeviceMotionUpdates, but this property would return NO.)

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

gyroAvailable

A Boolean value that indicates whether a gyroscope is available on the device. (read-only)

@property(readonly, nonatomic, getter=isGyroAvailable) BOOL gyroAvailable
Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

gyroData

The latest sample of gyroscope data. (read-only)

@property(readonly) CMGyroData *gyroData
Discussion

If no gyroscope data is available, the value of this property is nil. An app that is receiving gyroscope data after calling startGyroUpdates periodically checks the value of this property and processes the gyroscope data.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

gyroUpdateInterval

The interval, in seconds, for providing gyroscope updates to the block handler.

@property(assign, nonatomic) NSTimeInterval gyroUpdateInterval
Discussion

The system supplies gyroscope (that is, rotation rate) updates to the block handler specified in startGyroUpdatesToQueue:withHandler: at regular intervals determined by the value of this property. The interval units are in seconds. The value of this property is capped to minimum and maximum values; the maximum value is determined by the maximum frequency supported by the hardware. If your app is sensitive to the intervals of gyroscope data, it should always check the timestamps of the delivered CMGyroData instances to determine the true update interval.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

magnetometerActive

A Boolean value that determines whether magnetometer updates are currently happening. (read-only)

@property(readonly, nonatomic, getter=isMagnetometerActive) BOOL magnetometerActive
Discussion

This property indicates whether the startMagnetometerUpdatesToQueue:withHandler: or startMagnetometerUpdates method has been called since the last time the stopMagnetometerUpdates method was called. (If the start methods hadn’t been called, the app could be getting updates from the magnetometer after calling, for example, startDeviceMotionUpdates, but this property would return NO.)

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

magnetometerAvailable

A Boolean value that indicates whether a magnetometer is available on the device. (read-only)

@property(readonly, nonatomic, getter=isMagnetometerAvailable) BOOL magnetometerAvailable
Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

magnetometerData

The latest sample of magnetometer data. (read-only)

@property(readonly) CMMagnetometerData *magnetometerData
Discussion

If no magnetometer data is available, the value of this property is nil. An app that is receiving magnetometer data after calling startMagnetometerUpdates periodically checks the value of this property and processes the gyroscope data.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

magnetometerUpdateInterval

The interval, in seconds, at which the system delivers magnetometer data to the block handler.

@property(assign, nonatomic) NSTimeInterval magnetometerUpdateInterval
Discussion

The supplies magnetometer data to the block handler specified in startMagnetometerUpdatesToQueue:withHandler: at regular intervals determined by the value of this property. The interval unit are in seconds. The value of this property is capped to minimum and maximum values; the maximum value is determined by the maximum frequency supported by the hardware. If your app is sensitive to the intervals of magnetometer data, it should always check the timestamps of the delivered CMMagnetometerData instances to determine the true update interval.

Availability
  • Available in iOS 5.0 and later.
Declared In
CMMotionManager.h

showsDeviceMovementDisplay

Controls whether the device-movement display is shown.

@property(assign, nonatomic) BOOL showsDeviceMovementDisplay
Discussion

When a device requires movement (for example, to calibrate the compass), the value of this property indicates if the system’s device-movement display should be shown. When a device requires movement, the block handler of type CMDeviceMotionHandler reports the CMErrorDeviceRequiresMovement error once. By default, this property is NO.

Availability
  • Available in iOS 5.0 and later.
Declared In
CMMotionManager.h

Class Methods

availableAttitudeReferenceFrames

Returns a bitmask specifying the available attitude reference frames on the device.

+ (NSUInteger)availableAttitudeReferenceFrames
Return Value

A bitmask that you can bitwise-AND with the enum constants of the CMAttitudeReferenceFrame type.

Discussion

For example, to determine whether CMAttitudeReferenceFrameXMagneticNorthZVertical is available on the device, you would perform the following test:

if ([CMMotionManager availableAttitudeReferenceFrames] & CMAttitudeReferenceFrameXMagneticNorthZVertical) {
    // do something appropriate here
}
Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

Instance Methods

startAccelerometerUpdates

Starts accelerometer updates without a handler.

- (void)startAccelerometerUpdates
Discussion

You can get the latest accelerometer data through the accelerometerData property. You must call stopAccelerometerUpdates when you no longer want your app to process accelerometer updates.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

startAccelerometerUpdatesToQueue:withHandler:

Starts accelerometer updates on an operation queue and with a specified handler.

- (void)startAccelerometerUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMAccelerometerHandler)handler
Parameters
queue

An operation queue provided by the caller. Because the processed events might arrive at a high rate, using the main operation queue is not recommended.

handler

A block that is invoked with each update to handle new accelerometer data. The block must conform to the CMAccelerometerHandler type.

Discussion

You must call stopAccelerometerUpdates when you no longer want your app to process accelerometer updates.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
CMMotionManager.h

startDeviceMotionUpdates

Starts device-motion updates without a block handler.

- (void)startDeviceMotionUpdates
Discussion

You can get the latest device-motion data through the deviceMotion property. You must call stopDeviceMotionUpdates when you no longer want your app to process device-motion updates. This method uses the reference frame returned by attitudeReferenceFrame for device-motion updates.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

startDeviceMotionUpdatesToQueue:withHandler:

Starts device-motion updates on an operation queue and using a specified block handler.

- (void)startDeviceMotionUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMDeviceMotionHandler)handler
Parameters
queue

An operation queue provided by the caller. Because the processed events might arrive at a high rate, using the main operation queue is not recommended.

handler

A block that is invoked with each update to handle new device-motion data. The block must conform to the CMDeviceMotionHandler type.

Discussion

This method uses the reference frame returned by attitudeReferenceFrame for device-motion updates. You must call stopDeviceMotionUpdates when you no longer want your app to process device-motion updates.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

startDeviceMotionUpdatesUsingReferenceFrame:

Starts device-motion updates using a reference frame but without a block handler.

- (void)startDeviceMotionUpdatesUsingReferenceFrame:(CMAttitudeReferenceFrame)referenceFrame
Parameters
referenceFrame

A constant identifying the reference frame to use for device-motion updates.

Discussion

You can get the latest device-motion data through the deviceMotion property. You must call stopDeviceMotionUpdates when you no longer want your app to process device-motion updates.

Availability
  • Available in iOS 5.0 and later.
Declared In
CMMotionManager.h

startDeviceMotionUpdatesUsingReferenceFrame:toQueue:withHandler:

Starts device-motion updates on an operation queue and using a specified reference frame and block handler.

- (void)startDeviceMotionUpdatesUsingReferenceFrame:(CMAttitudeReferenceFrame)referenceFrame toQueue:(NSOperationQueue *)queue withHandler:(CMDeviceMotionHandler)handler
Parameters
referenceFrame

A constant identifying the reference frame to use for device-motion updates.

queue

An operation queue provided by the caller. Because the processed events might arrive at a high rate, using the main operation queue is not recommended.

handler

A block that is invoked with each update to handle new device-motion data. The block must conform to the CMDeviceMotionHandler type.

Discussion

You must call stopDeviceMotionUpdates when you no longer want your app to process device-motion updates.

Availability
  • Available in iOS 5.0 and later.
Declared In
CMMotionManager.h

startGyroUpdates

Starts gyroscope updates without a handler.

- (void)startGyroUpdates
Discussion

You can get the latest gyroscope data through the gyroData property. You must call stopGyroUpdates when you no longer want your app to process gyroscope updates.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
CMMotionManager.h

startGyroUpdatesToQueue:withHandler:

Starts gyroscope updates on an operation queue and with a specified handler.

- (void)startGyroUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMGyroHandler)handler
Parameters
queue

An operation queue provided by the caller. Because the processed events might arrive at a high rate, using the main operation queue is not recommended.

handler

A block that is invoked with each update to handle new gyroscope data. The block must conform to the CMGyroHandler type.

Discussion

You must call stopGyroUpdates when you no longer want your app to process gyroscope updates.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
CMMotionManager.h

startMagnetometerUpdates

Starts magnetometer updates without a block handler.

- (void)startMagnetometerUpdates
Discussion

You can get the latest magnetometer data through the magnetometerData property. You must call stopMagnetometerUpdates when you no longer want your app to process magnetometer updates.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

startMagnetometerUpdatesToQueue:withHandler:

Starts magnetometer updates on an operation queue and with a specified handler.

- (void)startMagnetometerUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMMagnetometerHandler)handler
Parameters
queue

An operation queue provided by the caller. Because the processed events might arrive at a high rate, using the main operation queue is not recommended.

handler

A block that is invoked with each update to handle new magnetometer data. The block must conform to the CMMagnetometerHandler type.

Discussion

You must call stopMagnetometerUpdates when you no longer want your app to process magnetometer updates.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

stopAccelerometerUpdates

Stops accelerometer updates.

- (void)stopAccelerometerUpdates
Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
CMMotionManager.h

stopDeviceMotionUpdates

Stops device-motion updates.

- (void)stopDeviceMotionUpdates
Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
CMMotionManager.h

stopGyroUpdates

Stops gyroscope updates.

- (void)stopGyroUpdates
Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
CMMotionManager.h

stopMagnetometerUpdates

Stops magnetometer updates.

- (void)stopMagnetometerUpdates
Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
CMMotionManager.h

Constants

CMAccelerometerHandler

The type of block callback for handling accelerometer data.

typedef void (^CMAccelerometerHandler)(CMAccelerometerData *accelerometerData, NSError *error);
Discussion

Blocks of type CMAccelerometerHandler are called when there is accelerometer data to process. You pass the block into startAccelerometerUpdatesToQueue:withHandler: as the second argument. Blocks of this type return no value but take two arguments:

accelerometerData

An object that encapsulates a CMAcceleration structure with fields holding acceleration values for the three axes of movement.

error

An error object representing an error encountered in providing accelerometer updates. If an error occurs, you should stop accelerometer updates and inform the user of the problem. If there is no error, this argument is nil. Core Motion errors are of the CMErrorDomain domain and the CMError type.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

CMGyroHandler

The type of block callback for handling gyroscope data. 

typedef void (^CMGyroHandler)(CMGyroData *gyroData, NSError *error);
Discussion

Blocks of type CMGyroHandler are called when there is gyroscope data to process. You pass the block into startGyroUpdatesToQueue:withHandler: as the second argument. Blocks of this type return no value but take two arguments:

gyroData

An object that encapsulates a CMRotationRate structure with fields holding rotation-rate values for the three axes of movement.

error

An error object representing an error encountered in providing gyroscope data. If an error occurs, you should stop gyroscope updates and inform the user of the problem. If there is no error, this argument is nil. Core Motion errors are of the CMErrorDomain domain and the CMError type.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

CMMagnetometerHandler

The type of block callback for handling magnetometer data.

typedef void (^CMMagnetometerHandler)(CMMagnetometerData *magnetometerData, NSError *error);
Discussion

Blocks of type CMMagnetometerHandler are called when there is magnetometer data to process. You pass the block into the startMagnetometerUpdatesToQueue:withHandler: method as the second argument. Blocks of this type return no value but take two arguments:

magnetometerData

An object that encapsulates a CMMagneticField structure with fields holding magnetic-field values for the three axes of movement.

error

An error object representing an error encountered in providing magnetometer data. If an error occurs, you should stop magnetometer updates and inform the user of the problem. If there is no error, this argument is nil. Core Motion errors are of the CMErrorDomain domain and the CMError type.

Availability
  • Available in iOS 5.0 and later.
Declared In
CMMotionManager.h

CMDeviceMotionHandler

The type of block callback for handling device-motion data. 

typedef void (^CMDeviceMotionHandler)(CMDeviceMotion *motion, NSError *error);
Discussion

Blocks of type CMDeviceMotionHandler are called when there is device-motion data to process. You pass the block into startDeviceMotionUpdatesToQueue:withHandler: as the second argument. Blocks of this type return no value but take two arguments:

motion

A CMDeviceMotion object, which encapsulates other objects and a structure representing attitude, rotation rate, gravity, and user acceleration.

error

An error object representing an error encountered in providing gyroscope data. If an error occurs, you should stop gyroscope updates and inform the user of the problem. If there is no error, this argument is nil. Core Motion errors are of the CMErrorDomain domain and the CMError type.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMMotionManager.h

Core Motion Error Domain

The error domain for Core Motion.

extern NSString *const CMErrorDomain;
Constants
CMErrorDomain

Identifies the domain of NSError objects returned from Core Motion.

Available in iOS 4.0 and later.

Declared in CMErrorDomain.h.

Declared In
CMErrorDomain.h

CMError

The type for Core Motion errors.

typedef enum {
   CMErrorNULL = 100,
   CMErrorDeviceRequiresMovement,
   CMErrorTrueNorthNotAvailable
} CMError;
Constants
CMErrorNULL

No error.

Available in iOS 4.0 and later.

Declared in CMError.h.

CMErrorDeviceRequiresMovement

The device must move for a sampling of motion data to occur.

Available in iOS 5.0 and later.

Declared in CMError.h.

CMErrorTrueNorthNotAvailable

True north is not available on this device. This usually indicates that the device’s location is not yet available.

Available in iOS 5.0 and later.

Declared in CMError.h.

Declared In
CMError.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)

Did this document help you? Yes It's good, but... Not helpful...