A shake event is a UIEvent (Chapter 18). Receiving shake events is rather like receiving remote events (Chapter 27), involving the notion of the first responder. To receive shake events, your app must contain a UIResponder which:

This responder, or a UIResponder further up the responder chain, should implement some or all of these methods:

Thus, it might be sufficient to implement motionEnded:withEvent:, because this arrives if and only if the user performs a shake gesture. The first parameter will be the event subtype, but at present this is guaranteed to be UIEventSubtypeMotionShake, so testing it is pointless.

The view controller in charge of the current view is a good candidate to receive shake events. Thus, a minimal implementation might look like this:

- (BOOL) canBecomeFirstResponder {
    return YES;
}

- (void) viewDidAppear: (BOOL) animated {
    [super viewDidAppear: animated];
    [self becomeFirstResponder];
}

- (void)motionEnded:(UIEventSubtype)motion withEvent:(UIEvent *)event {
    NSLog(@"hey, you shook me!");
}

By default, if the first responder is of a type that supports undo (such as an NSTextField), and if motionBegan:withEvent: is sent up the responder chain, and if you have not set the shared UIApplication’s applicationSupportsShakeToEdit property to NO, a shake will be handled through an Undo or Redo alert. Your view controller might not want to rob any responders in its view of this capability. A simple way to prevent this is to test whether the view controller is itself the first responder; if it isn’t, we call super to pass the event on up the responder chain:

- (void)motionEnded:(UIEventSubtype)motion withEvent:(UIEvent *)event {
    if ([self isFirstResponder])
        NSLog(@"hey, you shook me!");
    else
        [super motionEnded:motion withEvent:event];
}

If the device has an accelerometer but no gyroscope, you can learn about the forces being applied to it, but some compromises will be necessary. The chief problem is that, even if the device is completely motionless, its acceleration values will constitute a normalized vector pointing toward the center of the earth, popularly known as gravity. The accelerometer is thus constantly reporting a combination of gravity and user-induced acceleration. This is good and bad. It’s good because it means that, with certain restrictions, you can use the accelerometer to detect the device’s attitude in space. It’s bad because gravity values and user-induced acceleration values are mixed together. Fortunately, there are ways to separate these values mathematically:

In some situations, it is desirable to apply both a low-pass filter and a high-pass filter, so as to learn both the gravity values and the user acceleration values. A common additional technique is to run the output of the high-pass filter itself through a low-pass filter to reduce noise and small twitches. Apple provides some nice sample code for implementing a low-pass or a high-pass filter; see especially the AccelerometerGraph example, which is also very helpful for exploring how the accelerometer behaves.

The technique of applying filters to the accelerometer output has some serious downsides, which are inevitable in a device that lacks a gyroscope:

There are actually two ways to read the raw accelerometer values: UIAccelerometer and Core Motion. UIAccelerometer is slated for deprecation, and its delegate method is in fact deprecated, so I’ll describe how to read the raw accelerometer values with Core Motion. The technique is really a subset of how you read any values with Core Motion; in some ways it is similar to how you use Core Location:

In this example, I will simply report whether the device is lying flat on its back. I start by creating and configuring my motion manager, and I launch a repeating timer to trigger polling:

self.motman = [CMMotionManager new];
if (!self.motman.accelerometerAvailable) {
    NSLog(@"oh well");
    return;
}
self.motman.accelerometerUpdateInterval = 1.0 / 30.0;
[self.motman startAccelerometerUpdates];
self.timer =
    [NSTimer
        scheduledTimerWithTimeInterval:self.motman.accelerometerUpdateInterval
        target:self selector:@selector(pollAccel:) userInfo:nil repeats:YES];

My pollAccel: method is now being called repeatedly. In pollAccel:, I ask the motion manager for its accelerometer data. This arrives as a CMAccelerometerData, which is a timestamp plus a CMAcceleration; a CMAcceleration is simply a struct of three values, one for each axis of the device, measured in Gs. The positive x-axis points to the right of the device. The positive y-axis points toward the top of the device, away from the Home button. The positive z-axis points out of the screen toward the user.

The two axes orthogonal to gravity, which are the x and y axes when the device is lying more or less on its back, are much more accurate and sensitive to small variation than the axis pointing toward or away from gravity. So our approach is to ask first whether the x and y values are close to zero; only then do we use the z value to learn whether the device is on its back or on its face. To keep from updating our interface constantly, we implement a crude state machine; the state (an instance variable) starts out at -1, and then switches between 0 (device on its back) and 1 (device not on its back), and we update the interface only when there is a state change:

CMAccelerometerData* dat = self.motman.accelerometerData;
CMAcceleration acc = dat.acceleration;
CGFloat x = acc.x;
CGFloat y = acc.y;
CGFloat z = acc.z;
CGFloat accu = 0.08; // feel free to experiment with this value
if (fabs(x) < accu && fabs(y) < accu && z < -0.5) {
    if (state == -1 || state == 1) {
        state = 0;
        self.label.text = @"I'm lying on my back... ahhh...";
    }
} else {
    if (state == -1 || state == 0) {
        state = 1;
        self.label.text = @"Hey, put me back down on the table!";
    }
}

This works, but it’s sensitive to small motions of the device on the table. To damp this sensitivity, we can run our input through a low-pass filter. The low-pass filter code comes straight from Apple’s own examples, and involves maintaining the previously filtered reading as a set of instance variables:

-(void)addAcceleration:(CMAcceleration)accel {
    double alpha = 0.1;
    self->oldX = accel.x * alpha + self->oldX * (1.0 - alpha);
    self->oldY = accel.y * alpha + self->oldY * (1.0 - alpha);
    self->oldZ = accel.z * alpha + self->oldZ * (1.0 - alpha);
}

Our polling code now starts out by passing the data through the filter:

CMAccelerometerData* dat = self.motman.accelerometerData;
CMAcceleration acc = dat.acceleration;
[self addAcceleration: acc];
CGFloat x = self->oldX;
CGFloat y = self->oldY;
CGFloat z = self->oldZ;
// ... and the rest is as before ...

In this next example, the user is allowed to slap the side of the device against an open hand — perhaps as a way of telling it to go to the next or previous image or whatever it is we’re displaying. We pass the acceleration input through a high-pass filter to eliminate gravity (again, the filter code comes straight from Apple’s examples):

-(void)addAcceleration:(CMAcceleration)accel {
    double alpha = 0.1;
    self->oldX = accel.x - ((accel.x * alpha) + (self->oldX * (1.0 - alpha)));
    self->oldY = accel.y - ((accel.y * alpha) + (self->oldY * (1.0 - alpha)));
    self->oldZ = accel.z - ((accel.z * alpha) + (self->oldZ * (1.0 - alpha)));
}

What we’re looking for, in our polling routine, is a high positive or negative x value. A single slap is likely to consist of several consecutive readings above our threshold, but we want to report each slap only once, sο we take advantage of the timestamp attached to a CMAccelerometerData, maintaining the timestamp of our previous high reading as an instance variable and ignoring readings that are too close to one another in time. Another problem is that a sudden jerk involves both an acceleration (as the user starts the device moving) and a deceleration (as the device stops moving); thus a left slap might be preceded by a high value in the opposite direction, which we might interpret wrongly as a right slap. We can compensate crudely, at the expense of some latency, with delayed performance (the report: method simply logs to the console):

CMAccelerometerData* dat = self.motman.accelerometerData;
CMAcceleration acc = dat.acceleration;
[self addAcceleration: acc];
CGFloat x = self->oldX;
CGFloat thresh = 1.0;
if ((x < -thresh) || (x > thresh))
    NSLog(@"%f", x);
if (x < -thresh) {
    if (dat.timestamp - self->oldTime > 0.5 || self->lastSlap == 1) {
        self->oldTime = dat.timestamp;
        self->lastSlap = -1;
        [NSObject cancelPreviousPerformRequestsWithTarget:self];
        [self performSelector:@selector(report:)
                   withObject:@"left" afterDelay:0.5];
    }
}
if (x > thresh) {
    if (dat.timestamp - self->oldTime > 0.5 || self->lastSlap == -1) {
        self->oldTime = dat.timestamp;
        self->lastSlap = 1;
        [NSObject cancelPreviousPerformRequestsWithTarget:self];
        [self performSelector:@selector(report:)
                   withObject:@"right" afterDelay:0.5];
    }
}

The gesture we’re detecting is a little tricky to make: the user must slap the device into an open hand and hold it there; if the device jumps out of the open hand, that movement may be detected as the last in the series, resulting in the wrong report (left instead of right, or vice versa). And the latency of our gesture detection is very high; here’s a typical successful detection of a leftward slap:

2012-02-13 12:03:18.673 p724p742smackMe[4024:707] -1.204655
2012-02-13 12:03:18.743 p724p742smackMe[4024:707] -1.153451
2012-02-13 12:03:18.775 p724p742smackMe[4024:707] 1.168514
2012-02-13 12:03:18.809 p724p742smackMe[4024:707] -1.426584
2012-02-13 12:03:18.875 p724p742smackMe[4024:707] -1.297352
2012-02-13 12:03:18.942 p724p742smackMe[4024:707] -1.072046
2012-02-13 12:03:19.316 p724p742smackMe[4024:707] left

The gesture started with an involuntary shake; then the rapid acceleration to the left was detected as a positive value; finally, the rapid deceleration was detected as a negative value, and it took several tenths of a second for our delayed performance to decide that this was the end of the gesture and report a leftward slap. Of course we might try tweaking some of the magic numbers in this code to improve accuracy and performance, but a more sophisticated analysis would probably involve storing a stream of all the most recent CMAccelerometerData objects and studying the entire stream to work out the overall trend.

The inclusion of an electronic gyroscope in the panoply of onboard hardware in some devices has made a huge difference in the accuracy and speed of gravity and attitude reporting. A gyroscope has the property that its attitude in space remains constant; thus it can detect any change in the attitude of the containing device. This has two important consequences for accelerometer measurements:

It is possible to track the raw gyroscope data: make sure the device has a gyroscope, and then call startGyroUpdates. What we get from the motion manager is a CMGyroData object, which combines a timestamp with a CMRotationRate that reports the rate of rotation around each axis, measured in radians per second, where a positive value is counterclockwise as seen by someone whose eye is pointed to by the positive axis. (This is the opposite of the direction graphed in Figure 16.7.) The problem, however, is that the gyroscope values are scaled and biased. This means that the values are based on an arbitrary scale and are increasing (or decreasing) at a roughly constant rate. Thus there is very little merit in the exercise of dealing with the raw gyroscope data.

What you are likely to be interested in is a combination of at least the gyroscope and the accelerometer. The mathematics required to combine the data from these sensors can be daunting. Fortunately, there’s no need to know anything about that. Core Motion will happily package up the calculated combination of data as a CMDeviceMotion instance, with the effects of the sensors’ internal bias and scaling already factored out. CMDeviceMotion consists of the following properties, all of which provide a triple of values corresponding to the device’s natural 3D frame (x increasing to the right, y increasing to the top, z increasing out the front):

In this example, we turn the device into a simple compass/clinometer, merely by asking for its attitude with reference to magnetic north and taking its pitch, roll, and yaw. We begin by making the usual preparations; notice the use of the showsDeviceMovementDisplay property, which will allow the runtime to prompt the user to move the device in a figure-of-eight if the magnetometer needs calibration:

self.motman = [CMMotionManager new];
if (!self.motman.deviceMotionAvailable) {
    NSLog(@"oh well");
    return;
}
CMAttitudeReferenceFrame f = CMAttitudeReferenceFrameXMagneticNorthZVertical;
if (([CMMotionManager availableAttitudeReferenceFrames] & f) == 0) {
    NSLog(@"darn");
    return;
}
self.motman.showsDeviceMovementDisplay = YES;
self.motman.deviceMotionUpdateInterval = 1.0 / 30.0;
[self.motman startDeviceMotionUpdatesUsingReferenceFrame:f];
NSTimeInterval t = self.motman.deviceMotionUpdateInterval * 10;
self.timer =
    [NSTimer scheduledTimerWithTimeInterval:t target:self
    selector:@selector(pollAttitude:) userInfo:nil repeats:YES];

In pollAttitude:, we wait until the magnetometer is ready, and then we start taking attitude readings (converted to degrees):

CMDeviceMotion* mot = self.motman.deviceMotion;
if (mot.magneticField.accuracy <= CMMagneticFieldCalibrationAccuracyLow)
    return; // not ready yet
CMAttitude* att = mot.attitude;
CGFloat to_deg = 180.0 / M_PI; // I like degrees
NSLog(@"%f %f %f", att.pitch * to_deg, att.roll * to_deg, att.yaw * to_deg);

The values are all close to zero when the device is level with its top pointing to magnetic north, and each value increases as the device is rotated counterclockwise with respect to an eye that has the corresponding positive axis pointing at it. So, for example, a device held upright (top pointing at the sky) has a pitch approaching 90; a device lying on its right edge has a roll approaching 90; and a device lying on its back with its top pointing west has a yaw approaching 90.

There are some quirks to be aware of in the way that Euler angles operate mathematically:

This next (simple and very silly) example illustrates a use of CMAttitude’s rotationMatrix property. Our goal is to make a CALayer rotate in response to the current attitude of the device. We start as before, except that our reference frame is CMAttitudeReferenceFrameXArbitraryZVertical; we are interested in how the device moves from its initial attitude, without reference to any particular fixed external direction such as magnetic north. In pollAttitude, our first step is to store the device’s current attitude in a CMAttitude instance variable, ref:

CMDeviceMotion* mot = self.motman.deviceMotion;
CMAttitude* att = mot.attitude;
if (!self.ref) {
    self.ref = att;
    return;
}

That code works correctly because on the first few polls, as the attitude-detection hardware warms up, att is nil, so we don’t get past the return call until we have a valid initial attitude. Our next step is highly characteristic of how CMAttitude is used: we call the CMAttitude method multiplyByInverseOfAttitude:, which transforms our attitude so that it is relative to the stored initial attitude:

[att multiplyByInverseOfAttitude:self.ref];

Finally, we apply the attitude’s rotation matrix directly to a layer in our interface as a transform. Well, not quite directly: a rotation matrix is a 3×3 matrix, whereas a CATransform3D, which is what we need in order to set a layer’s transform, is a 4×4 matrix. However, it happens that the top left nine entries in a CATransform3D’s 4×4 matrix constitute its rotation component, so we start with an identity matrix and set those entries directly:

CMRotationMatrix r = att.rotationMatrix;
CATransform3D t = CATransform3DIdentity;
t.m11 = r.m11;
t.m12 = r.m12;
t.m13 = r.m13;
t.m21 = r.m21;
t.m22 = r.m22;
t.m23 = r.m23;
t.m31 = r.m31;
t.m32 = r.m32;
t.m33 = r.m33;
CALayer* lay = // whatever;
[CATransaction setDisableActions:YES];
lay.transform = t;

The result is that the layer apparently tries to hold itself still as the device rotates. The example is rather crude because we aren’t using OpenGL to draw a three-dimensional object, but it illustrates the principle well enough.

There is a quirk to be aware of in this case as well: over time, the transform has a tendency to drift. Thus, even if we leave the device stationary, the layer will gradually rotate. That is the sort of effect that CMAttitudeReferenceFrameXArbitraryCorrectedZVertical is designed to help mitigate, by bringing the magnetometer into play.

Here are some additional considerations to be aware of when using Core Motion: