iOS Developer Library — Prerelease

Developer

Core Motion Framework Reference CMMotionManager Class Reference

Options
Deployment Target:

On This Page
Language:

CMMotionManager

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.

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

    Declaration

    Swift

    var accelerometerData: CMAccelerometerData? { get }

    Objective-C

    @property(readonly, nullable) 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.

  • 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.)

    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

    Availability

    Available in iOS 4.0 and later.

    See Also

    gyroActive

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

    Declaration

    Swift

    var gyroData: CMGyroData? { get }

    Objective-C

    @property(readonly, nullable) 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.

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

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var deviceMotion: CMDeviceMotion? { get }

    Objective-C

    @property(readonly, nullable) 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.

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 : RawRepresentable { init(_ rawValue: UInt32) init(rawValue rawValue: UInt32) var rawValue: 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.