iOS Developer Library

Developer

CoreMotion Framework Reference CMMotionManager Class Reference

Options
Deployment Target:

On This Page
Language:

CMMotionManager

Inheritance


Conforms To


Import Statement


Swift

import CoreMotion

Objective-C

@import CoreMotion;

Availability


Available in iOS 4.0 and later.

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.

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

    Declaration

    Swift

    var accelerometerActive: Bool { get }

    Objective-C

    @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 NOfalse.)

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var accelerometerAvailable: Bool { get }

    Objective-C

    @property(readonly, nonatomic, getter=isAccelerometerAvailable) BOOL accelerometerAvailable

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var accelerometerData: CMAccelerometerData! { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var gyroUpdateInterval: NSTimeInterval

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func startGyroUpdatesToQueue(_ queue: NSOperationQueue!, withHandler handler: CMGyroHandler!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

  • Starts gyroscope updates without a handler.

    Declaration

    Swift

    func startGyroUpdates()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

  • Stops gyroscope updates.

    Declaration

    Swift

    func stopGyroUpdates()

    Objective-C

    - (void)stopGyroUpdates

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var gyroActive: Bool { get }

    Objective-C

    @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 NOfalse.)

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

    See Also

    gyroAvailable

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

    Declaration

    Swift

    var gyroAvailable: Bool { get }

    Objective-C

    @property(readonly, nonatomic, getter=isGyroAvailable) BOOL gyroAvailable

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

    See Also

    gyroActive

  • gyroData gyroData Property

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

    Declaration

    Swift

    var gyroData: CMGyroData! { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var magnetometerActive: Bool { get }

    Objective-C

    @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 NOfalse.)

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var magnetometerAvailable: Bool { get }

    Objective-C

    @property(readonly, nonatomic, getter=isMagnetometerAvailable) BOOL magnetometerAvailable

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var magnetometerData: CMMagnetometerData! { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later.

  • Controls whether the device-movement display is shown.

    Declaration

    Swift

    var showsDeviceMovementDisplay: Bool

    Objective-C

    @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 NOfalse.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var attitudeReferenceFrame: CMAttitudeReferenceFrame { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    class func availableAttitudeReferenceFrames() -> CMAttitudeReferenceFrame

    Objective-C

    + (CMAttitudeReferenceFrame)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
    • }

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var deviceMotionActive: Bool { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var deviceMotionAvailable: Bool { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var deviceMotion: CMDeviceMotion! { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

Data Types

  • The type of block callback for handling accelerometer data.

    Declaration

    Swift

    typealias CMAccelerometerHandler = (CMAccelerometerData!, NSError!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

  • The type of block callback for handling gyroscope data.

    Declaration

    Swift

    typealias CMGyroHandler = (CMGyroData!, NSError!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

  • The type of block callback for handling magnetometer data.

    Declaration

    Swift

    typealias CMMagnetometerHandler = (CMMagnetometerData!, NSError!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    typealias CMDeviceMotionHandler = (CMDeviceMotion!, NSError!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.

  • The error domain for Core Motion.

    Declaration

    Swift

    let CMErrorDomain: String

    Objective-C

    extern NSString *const CMErrorDomain;

    Constants

    • CMErrorDomain

      CMErrorDomain

      Identifies the domain of NSError objects returned from Core Motion.

      Available in iOS 4.0 and later.

  • The type for Core Motion errors.

    Declaration

    Swift

    struct CMError { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { CMErrorNULL = 100, CMErrorDeviceRequiresMovement, CMErrorTrueNorthNotAvailable, CMErrorUnknown, CMErrorMotionActivityNotAvailable, CMErrorMotionActivityNotAuthorized, CMErrorMotionActivityNotEntitled, CMErrorInvalidParameter } CMError;

    Constants

    • CMErrorNULL

      CMErrorNULL

      No error.

      Available in iOS 4.0 and later.

    • CMErrorDeviceRequiresMovement

      CMErrorDeviceRequiresMovement

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

      Available in iOS 5.0 and later.

    • CMErrorTrueNorthNotAvailable

      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.

    • CMErrorUnknown

      CMErrorUnknown

      An unknown error occurred.

      Available in iOS 7.0 and later.

    • CMErrorMotionActivityNotAvailable

      CMErrorMotionActivityNotAvailable

      Motion activity support is not available on the current device.

      Available in iOS 7.0 and later.

    • CMErrorMotionActivityNotAuthorized

      CMErrorMotionActivityNotAuthorized

      The app is not currently authorized to use motion activity support.

      Available in iOS 7.0 and later.

    • CMErrorMotionActivityNotEntitled

      CMErrorMotionActivityNotEntitled

      The app is missing a required entitlement.

      Available in iOS 7.0 and later.

    • CMErrorInvalidParameter

      CMErrorInvalidParameter

      An invalid parameter was specified.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later.