Bluetooth Logo

Writing an SDK With Core Bluetooth – 07 – Properties

This entry is part 10 of 24 in the series Writing an SDK With Core Bluetooth

WHAT DOES THE USER NEED?

One of the biggest issues that I have with many SDKs, is that they slavishly model the system they are representing. This is often not the most optimal way to present functionality to the user.

Bluetooth is a highly flexible system. It is used by millions of devices that each may have a very different dynamic from other devices, and Bluetooth needs to serve them all, so it is rather complex and flexible. Core Bluetooth does a relatively good job of simplifying the standard, but it is still fairly byzantine.

I like to start with the user; ask them what they want, and then make the SDK an interpreter between them and the interface. Hide that Bluetooth complexity, and boil it down to the basics for the user.

PROPERTIES

Let’s start by examining the properties (the variables and states) of the system, and see how we can map between what the user expects, and what we can get from Bluetooth.

We now understand our system very well, indeed. We just spent a boatload of time studying it, and we didn’t think about the Bluetooth mechanism much.

That’s exactly how this kind of thing should go. Apple’s approach to Bluetooth is solid, well-documented and stable. It’s sorted. We don’t need to worry about it, and we can’t make any changes. We can defer worrying about it for now.

The properties, as I see them, are thus:

CENTRAL

  • List of Discovered Devices
    • Each Device:
      • Name of Device
      • Device Error State
      • Question
      • Answer
  • App State
    • Core Bluetooth Powered On State
    • Core Bluetooth Error State
    • Core Bluetooth Is Scanning

PERIPHERAL

  • App State
    • Core Bluetooth Powered On State
    • Core Bluetooth Error State
    • Core Bluetooth is Advertising

That’s about it. Under the hood, there will be a number of other things, like bespoke UUIDs for the Service and Characteristics, but the user doesn’t care about that.

“App State” is not really the SDK’s problem (That’s about whether or not we have an answer screen up, or whatnot). The SDK is all about presenting the remote device’s information to the user (the app). There is, however, one exception. The Core Bluetooth state. Things like whether or not it is powered on, and if there is some kind of error, matter to the app, and the SDK will be responsible for that.

In fact, the SDK doesn’t even need to worry about maintaining a list of devices (but we will, as that allows us to abstract the device identity from the user), or which device is selected. That’s really the app’s domain.

Note that I have “Error States” mentioned. That’s critically important; especially for a “messy” standard, like BLE. All kinds of ugliness can happen in the system, and we should be prepared to deal with it.

NOTE: In Peripherals, we don’t actually need to maintain a reference or persistent model to the Central device. We only care about it long enough to get asked a question, and respond. Nevertheless, I will maintain a reference to the Central device for convenience.

DETAILED EXAMINATION OF THE PROPERTIES

Now that we know what properties we are looking at, let’s figure out how we will package them up for use in the SDK.

GLOBAL PROPERTIES

Core Bluetooth State

This is the state of Core Bluetooth. Quite simply, it is whether or not it is powered on, and if there is some error.

Operational State

Just whether we are a Central or Peripheral. Other states are the domain of the app, itself.

CENTRAL PROPERTIES

List of Discovered Peripheral Devices

If we were doing a “pure” stateless approach, then this would not be necessary. However, I want to do it in the SDK, simply because each device has a unique, very ugly, UUID. I don’t want to expose that to the user. The user doesn’t need the UUID to identify the device. If I keep the list in the SDK, then there’s no need to expose the UUID.

Each Device:

  • Name of Device
    Each device will have a name. This is not necessarily unique to the device. If it does not have one, the SDK should assign one.
  • Device Error State
    If the device is experiencing an error, the error state should be reflected here.
  • Question
    The text of the question that was asked of the device. If no question has been asked, this can be empty.
  • Answer
    The text of any answer from the device. If there was no answer, this can be empty.

Core Bluetooth State

Is the device scanning?

PERIPHERAL PROPERTIES

Core Bluetooth State

Is the device advertising?

That pretty much wraps up the properties. Let’s move on to how we will be modeling the system to the user.