CMDeviceMotion Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreMotion.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
CMDeviceMotion.h
Related sample code

Overview

An instance of CMDeviceMotion encapsulates measurements of the attitude, rotation rate, and acceleration of a device.

An application receives or samples CMDeviceMotion objects at regular intervals after calling the startDeviceMotionUpdatesUsingReferenceFrame:toQueue:withHandler: method, the startDeviceMotionUpdatesToQueue:withHandler: method, the startDeviceMotionUpdatesUsingReferenceFrame: method, or the startDeviceMotionUpdates method of the CMMotionManager class.

The accelerometer measures the sum of two acceleration vectors: gravity and user acceleration. User acceleration is the acceleration that the user imparts to the device. Because Core Motion is able to track a device’s attitude using both the gyroscope and the accelerometer, it can differentiate between gravity and user acceleration. A CMDeviceMotion object provides both measurements in the gravity and userAcceleration properties.

Tasks

Getting Attitude and Rotation Rate

Getting Acceleration Data

Getting the Calibrated Magnetic Field

Properties

attitude

The attitude of the device. (read-only)

@property(readonly, nonatomic) CMAttitude *attitude
Discussion

A CMAttitude object represents a measurement of attitude—that is, the orientation of a body relative to a given frame of reference.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMDeviceMotion.h

gravity

The gravity acceleration vector expressed in the device's reference frame. (read-only)

@property(readonly, nonatomic) CMAcceleration gravity
Discussion

The total acceleration of the device is equal to gravity plus the acceleration the user imparts to the device (userAcceleration).

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

magneticField

Returns the magnetic field vector with respect to the device. (read-only)

@property(readonly, nonatomic) CMCalibratedMagneticField magneticField
Discussion

The CMCalibratedMagneticField returned by this property gives you the total magnetic field in the device’s vicinity without device bias. Unlike the magneticField property of the CMMagnetometer class, these values reflect the earth’s magnetic field plus surrounding fields, minus device bias.

If the device does not have a magnetometer, the accuracy field of the property’s value (a CMCalibratedMagneticField structure) is CMMagneticFieldCalibrationAccuracyUncalibrated.

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

rotationRate

The rotation rate of the device. (read-only)

@property(readonly, nonatomic) CMRotationRate rotationRate
Discussion

A CMRotationRate structure contains data specifying the device’s rate of rotation around three axes. The value of this property contains a measurement of gyroscope data whose bias has been removed by Core Motion algorithms. The identically name property of CMGyroData, on the other hand, gives the raw data from the gyroscope. The structure type is declared in CMGyroData.h.

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

userAcceleration

The acceleration that the user is giving to the device. (read-only)

@property(readonly, nonatomic) CMAcceleration userAcceleration
Discussion

The total acceleration of the device is equal to gravity plus the acceleration the user imparts to the device.

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

Constants

CMCalibratedMagneticField

Calibrated magnetic field data and an estimate of the accuracy of the calibration.

typedef struct {
   CMMagneticField field;
   CMMagneticFieldCalibrationAccuracy accuracy;
} CMCalibratedMagneticField;
Fields
field

A structure containing 3-axis calibrated magnetic field data. See the description of the CMMagneticField structure.

accuracy

An enum-constant value that indicates the accuracy of the magnetic field estimate. See “CMMagneticFieldCalibrationAccuracy.”

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

CMMagneticFieldCalibrationAccuracy

Indicates the calibration accuracy of a magnetic field estimate

typedef enum {     CMMagneticFieldCalibrationAccuracyUncalibrated = -1,
   CMMagneticFieldCalibrationAccuracyLow,
   CMMagneticFieldCalibrationAccuracyMedium,
   CMMagneticFieldCalibrationAccuracyHigh } CMMagneticFieldCalibrationAccuracy;
Constants
CMMagneticFieldCalibrationAccuracyUncalibrated

The magnetic field estimate is not calibrated.

Available in iOS 5.0 and later.

Declared in CMDeviceMotion.h.

CMMagneticFieldCalibrationAccuracyLow

The accuracy of the magnetic field calibration is low.

Available in iOS 5.0 and later.

Declared in CMDeviceMotion.h.

CMMagneticFieldCalibrationAccuracyMedium

The accuracy of the magnetic field calibration is medium.

Available in iOS 5.0 and later.

Declared in CMDeviceMotion.h.

CMMagneticFieldCalibrationAccuracyHigh

The accuracy of the magnetic field calibration is high.

Available in iOS 5.0 and later.

Declared in CMDeviceMotion.h.

Discussion

One of the enum constants of the CMMagneticFieldCalibrationAccuracy type is the value of the accuracy field of the CMCalibratedMagneticField structure returned from the magneticField property.

Declared In
CMDeviceMotion.h