Chris' Blog.

In this post, I'd like to explain how to get your app to pair with a Bluetooth LE peripheral, reconnect on subsequent app launches, and stay connected as the devices comes in and out of range - handle all the realistic scenarios. I'll also talk about the gotchas when working with CoreBluetooth, and outline a good example that you can build on.

Important things to know

• Bluetooth Low Energy is basically what you want to be using - not old-style Bluetooth. If you want the latter, this article won't be much help.
• CoreBluetooth is the iOS framework for dealing with bluetooth. It's probably worth a read: Core Bluetooth Guide and Core Bluetooth API.
• BLE devices have 'services', and those services have 'characteristics'.
• A 'profile' is something you may have read about. It's basically an informal grouping of 'services'. Don't worry too much about profiles, especially for your own devices.
• BLE is all about reading and writing values (raw byte arrays) to characteristics.
• If you want to send/receive messages (eg JSON), commonly people build something custom on top of a pair of characteristics.
• You can subscribe to changes to a characteristic, allowing a peripheral to 'push' data to you when it wants.

High-level

Before delving into the nitty gritty, I'll explain what needs to happen at a high level.

Here's how pairing with a new device works:

1 Wait for CoreBluetooth to get to the poweredOn state. 1 Scan for peripherals (that have the services you're interested in). 1 Connect to a peripheral. 1 Discover its services. 1 Discover the services' characteristics. 1 Done!

And here's how connecting to that device on subsequent launches of your app:

1 Wait for CoreBluetooth to get to the 'poweredOn' state. 1 Retrieve the previously-connected peripheral 1 Connect, discover, etc.

And here's how you re-connect when the device goes out of range:

1 You're connected normally... 1 didDisconnect is called with error .connectionTimeout 1 Call 'connect' and never timeout 1 didConnect is called later on when the device comes into range.

Project Setup

Firstly, you'll need to include CoreBluetooth into your app. In Xcode, go into your target settings > General > Linked Frameworks and Libraries, click '+' and select CoreBluetooth.

Next, you should consider enabling background mode if your use-case requires it. If so, head for target settings > Capabilities > Background Modes > Uses Bluetooth LE accessories.

Go to your Info.plist, and add a key named 'Privacy - Bluetooth Peripheral Usage Description' and set the value to something like 'MyAwesomeApp connects to your MyBrilliantPeripheral via Bluetooth'. This is shown to the user by iOS.

App Startup

At app startup, create a CBCentralManager instance. Typically you'll do this in some kind of singleton. Since it requires the delegate passed to the initialiser, you can't use the same singleton as the delegate due to Swift's init rules. You must also pass in a restore ID for reconnects across app launches to work. Hopefully you're only pairing to one device, and thus can use a constant for this id. If you pass 'nil' for the queue, all the central/peripheral delegates will be called on the main thread, which is probably reasonable.

class MyBluetoothLEManager {
    static let shared = MyBluetoothLEManager()

    private let central = CBCentralManager(
        delegate: MyCBCentralManagerDelegate.shared, 
        queue: nil, 
        options: [
            // Alert the user if BT is turned off.
            CBCentralManagerOptionShowPowerAlertKey: true,

            // ID to allow restoration.
            CBCentralManagerOptionRestoreIdentifierKey: "MyRestoreIdentifierKey",
        ])

This 'central' will initially be unusable, you must wait for it to call your delegate's centralManagerDidUpdateState with central.state == poweredOn before you can do anything. This can be tricky, which is why I recommend using a State Machine for dealing with Core Bluetooth. I've written in the past about State Machines before, I recommend reading about it to get a background. In the case here, I'm not going the whole hog with an Event handler, I'm basically just using an enum with associated values, which I think is a good balance.

Before the poweredOn state, however, Core Bluetooth may call willRestoreState and give you one or more CBPeripherals. This occurs when your app is relaunched into the background to handle some Bluetooth task, eg a subscribed characteristic value has changed. The given peripheral's state should be connected, however I've seen it as connecting only when running with Xcode's debugger attached. The trick is to store that peripheral somewhere, then wait for the poweredOn state, and then use it. I'll show you later how to do this neatly with a state machine.

Once you're reached the powered on state, there is a multitude of options ahead:

• If willRestoreState was called before, and the peripheral is in connecting state, call connect.
• If willRestoreState was called before, and the peripheral is in connected state, and its services and their characteristics are filled in, you're ready to use it!
• If willRestoreState was called before, and the peripheral is in connected state, but services and/or characteristics are not filled in, call discoverServices then discoverCharacteristics.
• Try central.retrievePeripherals(withIdentifiers: to find a previously-paired peripheral, and then connect to it.
• Try central.retrieveConnectedPeripherals(withServices: to find your previously-paired peripheral that is connected to iOS but not your app, and connect to it.
• Failing all that, you're likely in a situation where your app has simply not been paired before.

Scanning

Once you are in poweredOn state but aren't connected, and your user has selected to initiate pairing, you need to call central.scanForPeripherals(withServices: [CBUUID(string: "SOME-UUID")], options: nil).

The UUID is used as a battery-saving measure for you to tell iOS to filter the peripherals to only the ones with the service(s) you're interested in. Your hardware team will be able to give you this ID, otherwise you can use Apple Hardware IO Tools > Bluetooth Explorer to find it.

Core Bluetooth will never timeout when scanning, so you'll probably want to create some timeout of your own (10s is a good starting point), and call central.stopScan() at that point. Again, the State Machine is a great way to handle these timeouts neatly, which I will explain further below.

When it finds something, it will call the didDiscover:advertisementData:rssi: delegate with the discovered peripheral. Your hardware team may want to put some custom data in the advertising packets, which will be given to you here as advertisementData[CBAdvertisementDataManufacturerDataKey] as? Data.

Connecting

If this is the peripheral you want, you must call central.stopScan(), then myCentral.connect(peripheral, options: []), and retain the CBPeripheral somewhere otherwise Core Bluetooth will drop it before the connection completes.

connect will not timeout (which is handy for out-of-range reconnections), so you must implement your own timeout. I like to embed a timeout in the State Machine's as an enum associated value. This way the timeout gets automatically cancelled when the state progresses. To do this, I use Countdown from an earlier post I wrote called 'Timers without circular references'.

Creating the timeout looks like this:

let timeout = Countdown(seconds: 10, closure: {
    peripheral.cancelPeripheralConnection(central: self.myCentral)
    self.state = .disconnected
})

And embedding it in the state machine looks like this:

state = .connecting(peripheral, timeout)

In this way the state enum retains the peripheral for us too, which is essential to keep Core Bluetooth happy.

After a call to connect, your delegate will be called with either didConnect: or didFailToConnect:error:.

Upon didConnect, you should save the peripheral.identifier UUID somewhere (eg UserDefaults) so it can be reused at next app launch to reconnect.

Out-of-range

Once paired, one thing you'll need to deal with is the peripheral coming in and out of range, and reconnecting when that happens.

Your CBCentralManagerDelegate will be told via didDisconnectPeripheral:error: that something's gone wrong. At this point some heuristics is involved to figure out of this is an out-of-range issue, as opposed to the peripheral deliberately unpairing from you at the user's selection. Here's what has worked for me:

• If the error is nil, it's a disconnection initiated by your own code, so simply go to 'disconnected' state.
• Check if the error is a CB error with: if (error as NSError).domain == CBErrorDomain
• Cast the error code to a CB enum like so: if let code = CBError.Code(rawValue: (error as NSError).code)
• Make a set of errors that are probably out-of-range, here's what I found worked: let outOfRangeHeuristics: Set<CBError.Code> = [.unknown, .connectionTimeout, .peripheralDisconnected, .connectionFailed]
• Check if the error is one of the above: if outOfRangeHeuristics.contains(code), and if so, try to reconnect (explained below).
• After all those checks, at this point it's up to you if you want to try reconnect or not. I don't try, personally.

If you've decided it's probably an out-of-range and it's worth trying to reconnect, the trick is to simply call central.connect(peripheral, options:[]) and never set your own timeout. What you're doing here is effectively telling iOS 'I'm interested in connecting, let me know if you ever see this peripheral again'. This works because connect never times out.

Sending

TODO

Receiving

TODO

Messaging

TODO

Unpairing

This is easy! When the user requests that you unpair, simply call: central.cancelPeripheralConnection(peripheral), then dereference the peripheral, then erase the peripheral identifier you stored in your UserDefaults.

Gotchas

• You can't use the central manager immediately - it must change its state to poweredOn
• Calls to connect never timeout. This is very useful for when a device goes out of range: Simply call connect, and you'll get notified when it comes back in range, however long that may take.
• When connecting to a peripheral, you must retain the CBPeripheral for the duration or iOS will cancel the connection.
• It's hard to know the maximum size of a characteristic's value. As best I can tell, iOS negotiates it with the peripheral behind the scenes based on which BT version is being used, and tries to push it higher than the lowest-common-denominator that the standard officially supports. In any case, you don't really need to know the size when setting a value: just set it to as big a Data as you like (within reason), and Core Bluetooth will automatically 'chunk' it for you and set the characteristic's value to those chunks, one Bluetooth packet at a time. This is very useful for the common case where you're using characteristics for sending JSON messages.

Framework

TODO

Thanks for reading, and have a great week!

Photo by Joel Filipe on Unsplash

Every now and again, an iOS app will have cause to hide some information such that it's very difficult to find by looking at the binary. Be it some form of DRM key, or crypto keys, or API keys, or whatever - sometimes you simply must hide data in your binary. Below I'll tell you my latest favourite trick to do so (I wrote years ago a separate technique, but I think this is simpler and more flexible).

Before I continue, be aware you should authenticate users, not authenticate an app. It's mathematically impossible to hide data perfectly yet still be able to access it from your code. A determined hacker will be able to find it. However, this technique will help prevent the bots that are running scripts over your binaries from easily stealing your API keys. I recommend talking to a security consultant about potentially re-architecting your systems so that it isn't necessary to rely on eg a hidden API key. This article is provided with no warranties!

Ok so that out of the way, here's the gist: Your data (C for cleartext) is converted to data, and a same-length amount of random data R is generated. The two are XORed to produce X. R and X are then stored in your app. Thus someone running 'strings' on your app won't find anything valuable, it'll simply look like a bunch of random garbage. Unfortunately it'll still be vulnerable to anyone capable of attaching a debugger, but there's no technique that can solve for that - what you're doing here is raising the bar.

Here's a Playground for generating R and X:

import Foundation

// You can specify your data as bytes like so:
//let clear: [UInt8] = [1, 2, 3, 4...]

// Or convert it from a string like so:
let clear: [UInt8] = [UInt8]("My_API_Key_Here".data(using: .utf8)!)

// Generate the random data.
let random: [UInt8] = (0..<clear.count).map { _ in UInt8(arc4random_uniform(256)) }

// Xor them together.
let obfuscated: [UInt8] = zip(clear, random).map(^)

print(obfuscated + random)

Run this a few times, and check that you're getting different random gibberish each time. Copy the output to your app like so:

let obfuscatedApiKey: [UInt8] = [1, 2, 3, 4...]

And use the following in your app to de-obfuscate the key:

extension Array where Element == UInt8 {
    var deobfuscated: [UInt8] {
        let a = prefix(count / 2)
        let b = suffix(count / 2)
        return zip(a, b).map(^)
    }
}

Some convenience accessors for your obfuscated keys might look like so:

struct MyConstants {
    private static let obfuscatedKey: [UInt8] =
        [135, 89, 20, 175...]

    /// My API key! Obfuscated so won't be too easy for hackers to find.
    static var key: String {
        return String(bytes: obfuscatedKey.deobfuscated, 
            encoding: .utf8)!
    }
}

Thanks for reading, and have a great week!

Photo by Dayne Topkin on Unsplash

Finite State Machines are one of those things you don't use very often, but occasionally they can rescue a codebase from turning into a huge mess. But they don't have to be difficult and complicated. In this post I will show how to leverage Swift's powerful enums to build a simple and type-safe state machine, without needing to bring in an external library as a dependency to your app.

Recently I was working on an iOS app that could be controlled from multiple sources: from the UI (of course), remotely from the server, and via bluetooth. We needed a way to ensure that events from these sources couldn't take the app into a strange state. Eg we can't have the app presenting a login page if you're already logged in. A FSM will also make your app more unit-test-friendly which is no bad thing.

There are two parts to a State Machine: State and Events. For this example, pretend we're creating a simple game. State can be modelled neatly as a Swift enum:

enum State {
    case introduction // On the first page of the game
    case help // In the help screen
    case choosingEpisode // Choosing an episode
    case choosingLevel(Episode) // After choosing an episode, player is now choosing
        // a level
    case playingLevel(Episode, Level) // Now playing the chosen level
    case finishedLevel(Episode, Level, Int) // Finished a level, displaying their
        // score.
}

You'll notice that the last few cases have associated values:

• choosingLevel(Episode) is used to store the previously-selected episode when on the level selection page.
• playingLevel(Episode, Level) is used to store the details of the current level whilst playing it.
• finishedLevel(Episode, Level, Int) stores the level that was just finished, and the score the player achieved.

If you're unfamiliar with enums with associated values, you can read more about that here: https://docs.swift.org/swift-book/LanguageGuide/Enumerations.html#ID148

Events are similarly modelled using an enum:

enum Event {
    case displayHelp // Takes the user from the intro to the help screen.
    case dismissHelp // Takes the user back to the intro from help.
    case startPlaying // Takes the user from the intro to the episode chooser.
    case chooseEpisode(Episode) // The user selected an episode, so take
        // the user from the episode chooser to the level chooser.
    case chooseLevel(Level) // The user selected a level, so take the user
        // from the level chooser to the gameplay.
    case completeLevel(Int) // Takes the user from gameplay to the completed
        // level screen, displaying their achieved score.
    case dismissFinishedLevel // Takes the user from the completed level
        // screen back to the level chooser to play again.
}

Your current state needs to be stored somewhere. A singleton is a simple way to do this:

class FiniteStateMachine {
    static let shared = FiniteStateMachine()

    var state = State.introduction // Initial app-startup state.
    ...

Next we need a mechanism for selecting appropriate transitions given the 'before' state. For example, a 'return home' event might perform a different state transition if you are in a game (eg many view controllers to pop) vs only in the help screen (eg only one modal VC to dismiss). I call this mechanism the transition selector.

An important feature of the transition selector is that it throws if the incoming event isn't valid for the given state. This is key to the state machine's ability to prevent you getting into an invalid state. Here is the transition selector:

    ...
    /// A transition is a closure that, once run, leaves you in a new state.
    typealias Transition = () throws -> (State)

    /// This selects the appropriate transition to handle the event.
    /// The choice of transition may depend upon the old state.
    func transition(forEvent event: Event) throws -> Transition {
        switch (state, event) {
            case (.introduction, .displayHelp): return presentHelp()
            case (.help, .dismissHelp): return dismissHelp()
            case (.introduction, .startPlaying): return presentEpisodeChooser()

            // Here we pull a value out of the event using `let episode`:
            case (.choosingEpisode, .chooseEpisode(let episode)):
                return presentLevelChooser(episode: episode)

            // Here is how we can pull the episode out of the 'before' state.
            case (.choosingLevel(let episode), .chooseLevel(let level)):
                return presentGamePlay(level: level)

            ... further transitions as per your app ...

            default: throw Errors.transitionNotFound
        }
    }

    enum MyErrors: Error {
        case transitionNotFound
    }
    ...

You may notice that transition(forEvent:) returns a closure (of type Transition), but to return said closure it calls functions, rather than returning those functions themselves. This is because those functions are curried. Now currying is one of those CompSci terms that can be super-complicated, but don't fear, the gist of it is that these functions return closures with the parameters baked in. It turns out to simply be some boilerplate that you don't really need to worry too much about. Bear with me please!

Here's what those transition functions look like:

    static func presentLevelChooser(episode: Episode) -> Transition {
        return {
            // Perform the transition.
            let levelChooser = ...create level chooser view controller...
            levelChooser.levels = episode.levels
            NavigationManager.shared.rootNavController
                .pushViewController(levelChooser, animated: true)

            // Return the new state
            return State.choosingLevel(episode)
        }
    }

Finally you need a mechanism for handling events. This is the function that the rest of your app will call:

    func handle(event: Event) throws {
        let transition = try transition(forEvent: event)
        state = try transition()
    }

And so, here's how to use this state machine. In your various event-sources in your app (UI, network, perhaps bluetooth) you'd call the state machine like so:

    try? FiniteStateMachine.shared.handle(event: .startPlaying)
    try? FiniteStateMachine.shared.handle(event: .chooseEpisode(myEpisode))
    try? FiniteStateMachine.shared.handle(event: .chooseLevel(myLevel))
    try? FiniteStateMachine.shared.handle(event: .completeLevel(100))
    try? FiniteStateMachine.shared.handle(event: .dismissFinishedLevel)     

As always, feel free to use this framework as a starting point and modify until you get something that best suits your use-case.

PS: A handy trick I like - you can easily store a Countdown Timer in one of your state enum associated values, to create a timeout for that state that is automatically invalidated when leaving that state.

Thanks for reading, and have a great week!

Photo by Malcolm Lightbody on Unsplash