Location Manager, Delegate, and Authorization

Use of Core Location requires a location manager object, an instance of CLLocationManager. This object needs to be created on the main thread and retained thereafter. A standard strategy is to pick an instance that persists throughout the life of your app — your app delegate, or your root view controller, for example — and initialize an instance property with a location manager:

let locman = CLLocationManager()

Your location manager will generally be useless without a delegate (CLLocationManagerDelegate). You don’t want to change a location manager’s delegate, so you’ll want to set it once, early in the life of the location manager. This delegate will need to be an instance that persists together with the location manager. For example, if locman is a constant property of our root view controller, then we can set the root view controller as its delegate in the root view controller’s initializer:

required init?(coder aDecoder: NSCoder) {
    super.init(coder:aDecoder)
    self.locman.delegate = self
}

You must also explicitly request authorization from the user when you first start tracking the device’s location. There are two types of authorization (starting in iOS 8):

When In Use

When In Use authorization allows your app to perform basic location determination.

Always

Always authorization gives your app use of all Core Location modes and features. (I’ll describe later what these are.)

You’ll need to decide which level of authorization you need. Do not blithely pick Always authorization just because it is broader! On the contrary, you should pick When In Use authorization unless you need Always authorization for some feature of your app.

A further complication is that the user can turn off location services as a whole. If location services are off, and if you proceed to try to use Core Location anyway, the system may put up an alert on your behalf offering to switch to the Settings app so that the user can turn location services on. The CLLocationManager class method locationServicesEnabled reports whether location services as a whole are switched off. If so, a possible strategy is to call startUpdatingLocation on your location manager anyway. The attempt to learn the device’s location will fail, but this failure may also cause the user to see the system alert:

if !CLLocationManager.locationServicesEnabled() {
    self.locman.startUpdatingLocation()
    return
}

Once location services are enabled, you’ll call the CLLocationManager class method authorizationStatus to learn your app’s actual authorization status. There are two types of authorization, so there are two status cases reporting that you have authorization: .authorizedWhenInUse and .authorizedAlways. If the status is .notDetermined, you can request that the system put up the authorization request alert on your behalf by calling one of two instance methods, either requestWhenInUseAuthorization or requestAlwaysAuthorization; you must also have a corresponding entry in your app’s Info.plist, either “Privacy — When In Use Description” (NSLocationWhenInUseUsageDescription) or “Privacy — Location Always Usage Description” (NSLocationAlwaysUsageDescription), providing the body of the authorization request alert.

Oddly, neither requestWhenInUseAuthorization nor requestAlwaysAuthorization takes a completion function. Your code just continues blithely on. If you call requestWhenInUseAuthorization and then attempt to track the device’s location by calling startUpdatingLocation, you might succeed if the user grants authorization, but you might fail. The Core Location API provides no simple way for you to proceed only when you know the outcome of the authorization request.

On the other hand, when the user changes your authorization status — either granting authorization in the authorization request alert, or switching to the Settings app and providing authorization there — your location manager delegate’s locationManager(_:didChangeAuthorization:) is called. Thus, if you were to store whatever action you want to perform before obtaining authorization, you could perform that action after obtaining authorization.

Here’s a strategy for doing that. Instead of making our CLLocationManager a property of the root view controller, we have a utility class, ManagerHolder; it creates the location manager, asks for authorization if needed, and stores the function we want to call when we have authorization (for the structure of checkForLocationAccess, compare the discussion under “Music Library Authorization”):

class ManagerHolder {
    let locman = CLLocationManager()
    var doThisWhenAuthorized : (() -> ())?
    func checkForLocationAccess(always:Bool = false,
        andThen f: (()->())? = nil) {
            // no services? try to get alert
            guard CLLocationManager.locationServicesEnabled() else {
                self.locman.startUpdatingLocation()
                return
            }
            let status = CLLocationManager.authorizationStatus()
            switch status {
            case .authorizedAlways, .authorizedWhenInUse:
                f?()
            case .notDetermined:
                self.doThisWhenAuthorized = f
                always ?
                    self.locman.requestAlwaysAuthorization() :
                    self.locman.requestWhenInUseAuthorization()
            case .restricted:
                // do nothing
                break
            case .denied:
                // do nothing, or beg the user to authorize us in Settings
                break
            }
    }
}

Our utility class encapsulates management and authorization of the location manager. This gives us flexibility. With my utility class, I can instantiate a location manager anywhere and it will be managed correctly. My current plan is to attach a ManagerHolder instance to the root view controller; but it would be trivial to attach a ManagerHolder to the app delegate instead, or to both.

So now I do attach a ManagerHolder instance to the root view controller. The root view controller initializes and stores a ManagerHolder instance as an instance property, thus bringing the location manager to life as early as possible. For convenience, I’ll still give our root view controller a locman property, but this will be a computed property that bounces to the ManagerHolder’s location manager instance:

class ViewController: UIViewController, CLLocationManagerDelegate {
    let managerHolder = ManagerHolder()
    var locman : CLLocationManager {
        return self.managerHolder.locman
    }
    required init?(coder aDecoder: NSCoder) {
        super.init(coder:aDecoder)
        self.locman.delegate = self
    }
    // ...
}

Acting as the location manager delegate, the root view controller can now implement locationManager(_:didChangeAuthorizationStatus:) to call the function stored in the ManagerHolder:

func locationManager(_ manager: CLLocationManager,
    didChangeAuthorization status: CLAuthorizationStatus) {
        switch status {
        case .authorizedAlways, .authorizedWhenInUse:
            self.managerHolder.doThisWhenAuthorized?()
            self.managerHolder.doThisWhenAuthorized = nil
        default: break
        }
}

If we now call our ManagerHolder’s checkForLocationAccess before tracking location, everything will work correctly.

Location Tracking

To use the location manager to track the user’s location, configure the location manager (I’ll go into more detail in a moment) and then tell the location manager to startUpdatingLocation.

The location manager will begin calling the delegate’s locationManager(_:didUpdateLocations:) delegate method repeatedly. You’ll deal with each such call as it arrives. In this way, you will be kept more or less continuously informed of where the device is — until you call stopUpdatingLocation. Don’t forget to call it when you no longer need location tracking!

Your delegate should also implement locationManager(_:didFailWithError:) to receive error messages.

The pattern here is common to virtually all uses of the location manager. The location manager can do various kinds of tracking, but they all work the same way: you’ll tell it to start, a corresponding delegate method will be called repeatedly, and ultimately you’ll tell it to stop.

Here are some location manager configuration properties that are useful to set before you start location tracking:

desiredAccuracy

Your choices are:

• kCLLocationAccuracyBestForNavigation

• kCLLocationAccuracyBest

• kCLLocationAccuracyNearestTenMeters

• kCLLocationAccuracyHundredMeters

• kCLLocationAccuracyKilometer

• kCLLocationAccuracyThreeKilometers

It might be sufficient for your purposes to know very quickly but very roughly the device’s location. Highest accuracy may also cause the highest battery drain; indeed, kCLLocationAccuracyBestForNavigation is supposed to be used only when the device is connected to external power. The accuracy setting is not a filter: the location manager will send you whatever location information it has, even if it isn’t as accurate as you asked for, and checking a location’s horizontalAccuracy is then up to you.

distanceFilter

Perhaps you don’t need a location report unless the device has moved a certain distance since the previous report. This property can help keep you from being bombarded with events you don’t need.

activityType

Your choices are (CLActivityType):

• .fitness

• .automotiveNavigation

• .otherNavigation

• .other

This affects how persistently and frequently updates will be sent, based on the movement of the device. Think of it as an autopause setting. The more we are willing to accept pauses in the sending of updates, the less power we will use. Thus, .automotiveNavigation uses more power than .fitness, but there’s a hope that in the former case the device may be connected to a source of power. You could go even further and set pausesLocationUpdatesAutomatically to false — but don’t.

Here’s a basic example, taking advantage of the authorization strategy described in the previous section:

func doFindMe () {
    self.managerHolder.checkForLocationAccess {
        self.locman.desiredAccuracy = kCLLocationAccuracyBest
        self.locman.activityType = .fitness
        self.locman.startUpdatingLocation()
    }
}

We have a location manager, we are set as the location manager’s delegate, we have requested authorization if needed, and if we have or can get authorization, we have started tracking location. All we have to do now is sit back and wait for our implementation of locationManager(_:didUpdateLocations:) to be called. The second parameter is an array of CLLocation, a value class that encapsulates the notion of a location. Its properties include:

coordinate

A CLLocationCoordinate2D, a struct consisting of two Doubles representing latitude and longitude.

altitude

A CLLocationDistance, which is a Double representing a number of meters.

speed

A CLLocationSpeed, which is a Double representing meters per second.

course

A CLLocationDirection, which is a Double representing degrees (not radians) clockwise from north.

horizontalAccuracy

A CLLocationAccuracy, which is a Double representing meters.

timestamp

A Date.

In this situation, the array that we receive is likely to contain just one CLLocation — and even if it contains more than one, the last CLLocation in the array is guaranteed to be the newest. Thus, it is sufficient for our locationManager(_:didUpdateLocations:) implementation to extract the last element of the array:

let REQ_ACC : CLLocationAccuracy = 10
func locationManager(_ manager: CLLocationManager,
    didUpdateLocations locations: [CLLocation]) {
        let loc = locations.last!
        let acc = loc.horizontalAccuracy
        print(acc)
        if acc < 0 || acc > REQ_ACC {
            return // wait for the next one
        }
        let coord = loc.coordinate
        print("You are at (coord.latitude) (coord.longitude)")
}

It’s instructive to see, from the console logs, how the accuracy improves as the sensors warm up and the GPS obtains a fix:

1285.19869645162
1285.19869645172
1285.19869645173
65.0
65.0
30.0
30.0
30.0
10.0
You are at ...

Where Am I?

A common desire is, rather than tracking location continuously, to get one location once. To do that, a common beginner mistake is to call startUpdatingLocation and implement locationManager(_:didUpdateLocations:) to stop updating as soon as it is called:

func locationManager(_ manager: CLLocationManager,
    didUpdateLocations locations: [CLLocation]) {
        let loc = locations.last!
        let coord = loc.coordinate
        print("You are at (coord.latitude) (coord.longitude)")
        manager.stopUpdatingLocation() // this won't work!
}

That’s unlikely to work. As I demonstrated in the preceding section, the sensors take time to warm up, and many calls to locationManager(_:didUpdateLocations:) may be made before a reasonably accurate CLLocation arrives. The correct strategy is to do just what I did in the preceding section — and then call stopUpdatingLocation at the very end, when a sufficiently accurate location has in fact been received. It’s a lot of work to get just one reading, but it’s what you have to do.

Or rather, it’s what you had to do. Starting in iOS 9, instead of calling startUpdatingLocation, you can call requestLocation:

self.locman.desiredAccuracy = kCLLocationAccuracyBest
self.locman.requestLocation()

Your locationManager(_:didUpdateLocations:) will be called once with a good location, based on the desiredAccuracy you’ve already set:

func locationManager(manager: CLLocationManager,
    didUpdateLocations locations: [CLLocation]) {
        let loc = locations.last!
        let coord = loc.coordinate
        print("You are at (coord.latitude) (coord.longitude)")
}

Keep in mind, however, that calling requestLocation will not magically cause an accurate location to arrive any faster! It’s a great convenience that locationManager(_:didUpdateLocations:) will be called just once, but some considerable time may elapse before that call arrives.

You do not have to call stopUpdatingLocation, though you can do so if you change your mind and decide before the location arrives that it is no longer needed.

Background Location

You can use Core Location when your app is not in the foreground. There are two quite different ways to do this:

Continuous background location

This is an extension of basic location tracking. You tell the location manager to startUpdatingLocation, and updates are permitted to continue even if the app goes into the background. Your app runs in the background in order to receive these updates.

Location monitoring

Your app does not run in the background! Rather, the system monitors location for you. If a significant location event occurs, your app may be awakened in the background (or launched in the background, if it is not running) and notified.

Heading

For appropriately equipped devices, Core Location supports use of the magnetometer to determine which way the device is facing (its heading). Although this information is accessed through a location manager, you do not need location services to be turned on merely to use the magnetometer to report the device’s orientation with respect to magnetic north; you do need location services to be turned on in order to report true north, as this depends on the device’s location.

As with location, you’ll first check that the desired feature is available (headingAvailable); then you’ll configure the location manager, and call startUpdatingHeading. The delegate will be sent locationManager(_:didUpdateHeading:) repeatedly until you call stopUpdatingHeading (or else locationManager(_:didFailWithError:) will be called).

A heading object is a CLHeading instance; its magneticHeading and trueHeading properties are CLLocationDirection values, which report degrees (not radians) clockwise from the reference direction (magnetic or true north, respectively). If the trueHeading is not available, it will be reported as -1. The trueHeading will not be available unless both of the following are true in the Settings app:

• Location services are turned on (Privacy → Location Services).

• Compass calibration is turned on (Privacy → Location Services → System Services).

Beyond that, explicit user authorization is not needed in order to get the device’s heading with respect to true north.

Implement the delegate method locationManagerShouldDisplayHeadingCalibration(_:) to return true if you want the system’s compass calibration dialog to be permitted to appear if needed.

In this example, I’ll use the device as a compass. The headingFilter setting is to prevent us from being bombarded constantly with readings. For best results, the device should probably be held level (like a tabletop, or a compass); we are setting the headingOrientation so that the reported heading will be the direction in which the top of the device (the end away from the Home button) is pointing:

guard CLLocationManager.headingAvailable() else {return} // no hardware
self.locman.headingFilter = 5
self.locman.headingOrientation = .portrait
self.locman.startUpdatingHeading()

In the delegate, I’ll display our heading as a rough cardinal direction in a label in the interface (self.lab). If we have a trueHeading, I’ll use it; otherwise I’ll use the magneticHeading:

func locationManager(_ manager: CLLocationManager,
    didUpdateHeading newHeading: CLHeading) {
        var h = newHeading.magneticHeading
        let h2 = newHeading.trueHeading // -1 if no location info
        if h2 >= 0 {
            h = h2
        }
        let cards = ["N", "NE", "E", "SE", "S", "SW", "W", "NW"]
        var dir = "N"
        for (ix, card) in cards.enumerated() {
            if h < 45.0/2.0 + 45.0*Double(ix) {
                dir = card
                break
            }
        }
        if self.lab.text != dir {
            self.lab.text = dir
        }
}

Shake Events

A shake event is a UIEvent (Chapter 5). Receiving shake events involves the notion of the first responder. To receive shake events, your app must contain a UIResponder which:

• Returns true from canBecomeFirstResponder

• Is in fact first responder

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

motionBegan(_:with:)

Something has started to happen that might or might not turn out to be a shake.

motionEnded(_:with:)

The motion reported in motionBegan is over and has turned out to be a shake.

motionCancelled(_:with:)

The motion reported in motionBegan wasn’t a shake after all.

It might be sufficient to implement motionEnded(_:with:), 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 .motionShake, 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:

override var canBecomeFirstResponder : Bool {
    return true
}
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    self.becomeFirstResponder()
}
override func motionEnded(_ motion: UIEventSubtype, with e: UIEvent?) {
    print("hey, you shook me!")
}

By default, if some other object is first responder, and is of a type that supports undo (such as a UITextField), and if motionBegan(_:with:) is sent up the responder chain, and if you have not set the shared UIApplication’s applicationSupportsShakeToEdit property to false, 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:

override func motionEnded(_ motion: UIEventSubtype, with e: UIEvent?) {
    if self.isFirstResponder {
        print("hey, you shook me!")
    } else {
        super.motionEnded(motion, with: e)
    }
}

Raw Acceleration

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:

With a low-pass filter

A low-pass filter will damp out user acceleration so as to report gravity only.

With a high-pass filter

A high-pass filter will damp out the effect of gravity so as to detect user acceleration only, reporting a motionless device as having zero acceleration.

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:

• It’s up to you to apply the filters; you have to implement boilerplate code and hope that you don’t make a mistake.

• Filters mean latency. Your response to the accelerometer values will lag behind what the device is actually doing; this lag may be noticeable.

Reading raw accelerometer values with Core Motion 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:

1. You start by instantiating CMMotionManager; retain the instance somewhere, typically as an instance property. There is no reason not to initialize the property directly:

   let motman = CMMotionManager()

2. Confirm that the desired hardware is available.

3. Set the interval at which you wish the motion manager to update itself with new sensor readings.

4. Call the appropriate start method.

5. You probably expect me to say now that the motion manager will call into a delegate. Surprise! A motion manager has no delegate. You have two choices:

   • Poll the motion manager whenever you want data, asking for the appropriate data property. The polling interval doesn’t have to be the same as the motion manager’s update interval; when you poll, you’ll obtain the motion manager’s current data — that is, the data generated by its most recent update, whenever that was.

   • If your app’s purpose is to collect all the data, then instead of calling a start method, you can call a start...Updates(to:withHandler:) method with a function that will be called back, preferably on a background thread managed by an OperationQueue (Chapter 24).

6. Don’t forget to call the corresponding stop method when you no longer need data.

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

guard self.motman.isAccelerometerAvailable else { return }
self.motman.accelerometerUpdateInterval = 1.0 / 30.0
self.motman.startAccelerometerUpdates()
self.timer = Timer.scheduledTimer(
    timeInterval:self.motman.accelerometerUpdateInterval,
    target: self, selector: #selector(pollAccel),
    userInfo: nil, repeats: true)

My pollAccel method is now being called repeatedly. In it, I ask the motion manager for its accelerometer data. This arrives as a CMAccelerometerData object, 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 the front of the screen.

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 property (self.state) starts out at .unknown, and then switches between .lyingDown (device on its back) and .notLyingDown (device not on its back), and we update the interface only when there is a state change:

guard let data = self.motman.accelerometerData else {return}
let acc = data.acceleration
let x = acc.x
let y = acc.y
let z = acc.z
let accu = 0.08
if abs(x) < accu && abs(y) < accu && z < -0.5 {
    if self.state == .unknown || self.state == .notLyingDown {
        self.state = .lyingDown
        self.label.text = "I'm lying on my back... ahhh..."
    }
} else {
    if self.state == .unknown || self.state == .lyingDown {
        self.state = .notLyingDown
        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 properties:

func add(acceleration accel:CMAcceleration) {
    let 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:

guard let data = self.motman.accelerometerData else {return}
self.add(acceleration: data.acceleration)
let x = self.oldX
let y = self.oldY
let z = self.oldZ
// ... and the rest is as before ...

As I mentioned earlier, instead of polling, you can receive callbacks to a function. This approach is useful particularly if your goal is to receive every update or to receive updates on a background thread (or both). To illustrate, I’ll rewrite the previous example to use this technique; to keep things simple, I’ll ask for my callbacks on the main thread (the documentation advises against this, but Apple’s own sample code does it). We now start our accelerometer updates like this:

self.motman.startAccelerometerUpdates(to: .main) { data, err in
    guard let data = data else {
        print(err)
        self.stopAccelerometer()
        return
    }
    self.receive(acceleration:data)
}

receive(acceleration:) is just like our earlier pollAccel, except that we already have the accelerometer data:

func receive(acceleration data:CMAccelerometerData) {
    self.add(acceleration: data.acceleration)
    let x = self.oldX
    let y = self.oldY
    let z = self.oldZ
    // ... and the rest is as before ...
}

In this next example, the user is allowed to slap the side of the device into 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):

func add(acceleration accel:CMAcceleration) {
    let 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 a property 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:

func pollAccel(_: Any!) {
    guard let data = self.motman.accelerometerData else {return}
    self.add(acceleration: data.acceleration)
    let x = self.oldX
    let thresh = 1.0
    if x < -thresh {
        if data.timestamp - self.oldTime > 0.5 || self.lastSlap == .right {
            self.oldTime = data.timestamp
            self.lastSlap = .left
            self.canceltimer?.invalidate()
            self.canceltimer = .scheduledTimer(
                withTimeInterval:0.5, repeats: false) { _ in
                    print("left")
            }
        }
    } else if x > thresh {
        if data.timestamp - self.oldTime > 0.5 || self.lastSlap == .left {
            self.oldTime = data.timestamp
            self.lastSlap = .right
            self.canceltimer?.invalidate()
            self.canceltimer = .scheduledTimer(
                withTimeInterval:0.5, repeats: false) { _ in
                    print("right")
            }
        }
    }
}

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.

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.

Gyroscope

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:

• The accelerometer can be supplemented by the gyroscope to detect quickly the difference between gravity and user-induced acceleration.

• The gyroscope can observe pure rotation, where little or no acceleration is involved and so the accelerometer would not have been helpful. The extreme case is constant attitudinal rotation around the gravity axis, which the accelerometer alone would be completely unable to detect (because there is no user-induced force, and gravity remains constant).

It is possible to track the raw gyroscope data: make sure the device has a gyroscope (isGyroAvailable), 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 3-9.) 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 gradually increasing (or decreasing) over time 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):

gravity

A CMAcceleration expressing a vector with value 1 pointing to the center of the earth, measured in Gs.

userAcceleration

A CMAcceleration describing user-induced acceleration, with no gravity component, measured in Gs.

rotationRate

A CMRotationRate describing how the device is rotating around its own center. This is essentially the CMGyroData rotationRate with scale and bias accounted for.

magneticField

A CMCalibratedMagneticField describing (in its field, a CMMagneticField) the magnetic forces acting on the device, measured in microteslas. The sensor’s internal bias has already been factored out. The accuracy is one of the following (CMMagneticFieldCalibrationAccuracy):

• .uncalibrated

• .low

• .medium

• .high

attitude

A CMAttitude, descriptive of the device’s instantaneous attitude in space. When you ask the motion manager to start generating updates, you can specify a reference frame (CMAttitudeReferenceFrame) for the attitude (having first called the class method availableAttitudeReferenceFrames to ascertain that the desired reference frame is available on this device). In every case, the negative z-axis points at the center of the earth:

.xArbitraryZVertical

The x-axis and y-axis, though orthogonal to the other axes, could be pointing anywhere.

.xArbitraryCorrectedZVertical

The same as in the previous option, but the magnetometer is used to maintain accuracy (preventing drift of the reference frame over time).

.xMagneticNorthZVertical

The x-axis points toward magnetic north.

.xTrueNorthZVertical

The x-axis points toward true north. This value will be inaccurate unless you are also using Core Location to obtain the device’s location.

The attitude value’s numbers can be accessed through various CMAttitude properties corresponding to three different systems, each being convenient for a different purpose:

pitch, roll, yaw

The device’s angle of offset from the reference frame, in radians, around the device’s natural x-axis, y-axis, and z-axis respectively.

rotationMatrix

A CMRotationMatrix struct embodying a 3×3 matrix expressing a rotation in the reference frame.

quaternion

A CMQuaternion describing an attitude. (Quaternions are commonly used in OpenGL.)

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, intended to allow the runtime to prompt the user if the magnetometer needs calibration:

guard self.motman.isDeviceMotionAvailable else { return }
let ref = CMAttitudeReferenceFrame.xMagneticNorthZVertical
let avail = CMMotionManager.availableAttitudeReferenceFrames()
guard avail.contains(ref) else { return }
self.motman.showsDeviceMovementDisplay = true
self.motman.deviceMotionUpdateInterval = 1.0 / 30.0
self.motman.startDeviceMotionUpdates(using: ref)
let t = self.motman.deviceMotionUpdateInterval * 10
self.timer = Timer.scheduledTimer(timeInterval:t,
    target:self, selector:#selector(pollAttitude),
    userInfo:nil, repeats:true)

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

guard let mot = self.motman.deviceMotion else {return}
let acc = mot.magneticField.accuracy.rawValue
if acc <= CMMagneticFieldCalibrationAccuracy.low.rawValue {
    return // not ready yet
}
let att = mot.attitude
let to_deg = 180.0 / .pi
print("(att.pitch * to_deg), (att.roll * to_deg), (att.yaw * to_deg)")

The values are all close to zero when the device is level (flat on its back) with its x-axis (right edge) 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 north has a yaw approaching -90.

There are some quirks in the way Euler angles operate mathematically:

• roll and yaw increase with counterclockwise rotation from 0 to π (180 degrees) and then jump to -π (-180 degrees) and continue to increase to 0 as the rotation completes a circle; but pitch increases to π/2 (90 degrees) and then decreases to 0, then decreases to -π/2 (-90 degrees) and increases to 0. This means that attitude alone, if we are exploring it through pitch, roll, and yaw, is insufficient to describe the device’s attitude, since a pitch value of, say, π/4 (45 degrees) could mean two different things. To distinguish those two things, we can supplement attitude with the z-component of gravity:

  let g = mot.gravity
  let whichway = g.z > 0 ? "forward" : "back"
  print("pitch is tilted (whichway)")

• Values become inaccurate in certain orientations. In particular, when pitch is ±90 degrees (the device is upright or inverted), roll and yaw become erratic. (You may see this effect referred to as “the singularity” or as “gimbal lock.”) I believe that, depending on what you are trying to accomplish, you can solve this by using a different expression of the attitude, such as the rotationMatrix, which does not suffer from this limitation.

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 .xArbitraryCorrectedZVertical; 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 property, self.ref:

guard let mot = self.motman.deviceMotion else {return}
let att = mot.attitude
if self.ref == nil {
    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 instance method multiply(byInverseOf:), which transforms our attitude so that it is relative to the stored initial attitude:

att.multiply(byInverseOf: 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 matrix constitute its rotation component, so we start with an identity matrix and set those entries directly:

let r = att.rotationMatrix
var t = CATransform3DIdentity
t.m11 = CGFloat(r.m11)
t.m12 = CGFloat(r.m12)
t.m13 = CGFloat(r.m13)
t.m21 = CGFloat(r.m21)
t.m22 = CGFloat(r.m22)
t.m23 = CGFloat(r.m23)
t.m31 = CGFloat(r.m31)
t.m32 = CGFloat(r.m32)
t.m33 = CGFloat(r.m33)
let lay = // whatever
CATransaction.setAnimationDuration(1.0/10.0)
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 .xArbitraryCorrectedZVertical is designed to help mitigate, by bringing the magnetometer into play.

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

• Your app should create only one CMMotionManager instance.

• Use of Core Motion is legal while your app is running in the background. To take advantage of this, however, your app would need to be running in the background for some other reason; there is no Core Motion UIBackgroundModes setting in an Info.plist. For example, you might run in the background because you’re using Core Location, and take advantage of this to employ Core Motion as well.

• Core Motion requires that various sensors be turned on, such as the magnetometer and the gyroscope. This can result in some increased battery drain, so try not to use any sensors you don’t have to, and remember to stop generating updates as soon as you no longer need them.

Motion Activity

Some devices have a motion coprocessor chip with the ability to detect, analyze, and keep a record of device motion even while the device is asleep and with very little drain on power. This is not, in and of itself, a form of location determination; it is an analysis of the device’s physical motion and attitude in order to draw conclusions about what the user has been doing while carrying or wearing the device. You can learn that the user is walking, or walked for an hour, but not where the user was walking.

Interaction with the motion coprocessor is through a CMMotionActivityManager instance. There is no reason not to initialize an instance property with it:

let actman = CMMotionActivityManager()

The device must actually have a motion coprocessor; call the class method isActivityAvailable. The user must also grant authorization, and, having granted it, can later deny it (in the Settings app, under Privacy → Motion & Fitness). Like location services, the user can turn off this feature in general (Fitness Tracking) as well as denying it to your app in particular. There are no authorization methods; the technique is to “tickle” the activity manager by trying to query it and seeing if you get an error. In this example, I have a Bool property, self.authorized, which I set based on the outcome of trying to query the activity manager:

guard CMMotionActivityManager.isActivityAvailable() else { return }
let now = Date()
self.actman.queryActivityStarting(from:now, to:now, to:.main) { arr, err in
    let notauth = Int(CMErrorMotionActivityNotAuthorized.rawValue)
    if err != nil && (err! as NSError).code == notauth {
        self.isAuthorized = false
    } else {
        self.isAuthorized = true
    }
}

On the first run of that code, the system puts up the authorization request alert. The completion function is not called until the user deals with the alert, so the outcome tells you what the user decided. On subsequent runs, that code reports the current authorization status.

There are two approaches to querying the activity manager:

Real-time updates

This is similar to getting motion manager updates with a callback function. You call this method:

• startActivityUpdates(to:withHandler:)

Your callback function is called periodically. When you no longer need updates, call stopActivityUpdates.

Historical data

The motion coprocessor records about a week’s-worth of data. You ask for a chunk of that recorded data by calling this method:

• queryActivityStarting(from:to:to:withHandler:)

I’ll illustrate querying for historical data. In this example, I fetch the data for the past 24 hours. I have prepared an OperationQueue property, self.queue:

let now = Date()
let yester = now - (60*60*24)
self.actman.queryActivityStarting(
    from: yester, to: now, to: self.queue) { arr, err in
        guard var acts = arr else {return}
        // ...
}

We now have an array of CMMotionActivity objects representing every change in the device’s activity status. This is a value class. It has a startDate, a confidence (a CMMotionActivityConfidence, .low, .medium, or .high) ranking the activity manager’s faith in its own categorization of what the user was doing, and a bunch of Bool properties actually categorizing the activity:

• stationary

• walking

• running

• automotive

• cycling

• unknown

A common first response to the flood of data is to pare it down (sometimes referred to as smoothing). To help with this, I’ve extended CMMotionActivity with a utility method that summarizes its Bool properties as a string:

extension CMMotionActivity {
    private func tf(_ b:Bool) -> String {
        return b ? "t" : "f"
    }
    func overallAct() -> String {
        let s = tf(self.stationary)
        let w = tf(self.walking)
        let r = tf(self.running)
        let a = tf(self.automotive)
        let c = tf(self.cycling)
        let u = tf(self.unknown)
        return "(s) (w) (r) (a) (c) (u)"
    }
}

So, as a straightforward way of paring down the data, I remove every CMMotionActivity with no definite activity, with a low degree of confidence, or whose activity is the same as its predecessor. Then I set a property, and my data are ready for use:

let blank = "f f f f f f"
acts = acts.filter {act in act.overallAct() != blank}
acts = acts.filter {act in act.confidence == .high}
for i in (1..<acts.count).reversed() {
    if acts[i].overallAct() == acts[i-1].overallAct() {
        acts.remove(at:i)
    }
}
DispatchQueue.main.async {
    self.data = acts
}

There is also a CMPedometer class; before using it, check the isStepCountingAvailable class method. Some devices can deduce the size of the user’s stride and compute distance (isDistanceAvailable); some devices can use barometric data to estimate whether the user mounted a flight of stairs (isFloorCountingAvailable). Starting in iOS 9, you can also ask for instantaneous cadence (isCadenceAvailable) and pace (isPaceAvailable). Pedometer data is queried just like motion activity data; you can either ask for constant updates or you can ask for the stored history. Each bit of data arrives as a CMPedometerData object. The pedometer may work reliably under circumstances where Core Location doesn’t.