Tinkering Down Under - bluetooth

The waste that was COVIDSafe

Thu, 11 Aug 2022 19:55:00 +1000

It’s challenging to advocate for digital civil liberties in Australia. Every time the federal government tries to do something authoritarian, they make such a mess that it’s unclear whether it’s better to argue against it on moral grounds or because their harebrained scheme doesn’t actually deliver the dystopian outcome they wanted. Previous attempts include Stephen Conroy’s “clean feed” internet filter and Tony Abbott’s mandatory ISP data retention, the latter of which remains active law. Australia’s two major political parties contributed each of these ideas, enjoying broad electoral support all the while, which goes to show how doomed we are on this particular front.

Fast-forward to COVID. Reverting to instinct and precedent, the Australian populace sat and waited to see what the government thought we should do in the face of this new challenge. Prime Minister Scott Morrison had an answer: install this wonderful new app COVIDSafe, available on the Apple and Google app stores. Everybody’s phones will emit Bluetooth pings, and by tracking everyone who’s been nearby for 15+ minutes, all the close contacts of a positive case can be notified and we will quickly stop the spread of this virus. It was sold as the ticket to getting back to normal. (To be fair, this sounded somewhat logical before Omicron.)

Naturally, Australia’s implementation of this concept involved sending all of this proximity information to a big government database. Could it be a problem to create a central record of which citizens have been near which other citizens at particular dates and times? Surely not! At the time, Google and Apple were collaborating on a system which enabled Android and iOS users to exchange these Bluetooth pings in an anonymous way until they were actually found to be positive, sidestepping most of the privacy concerns and most of the technical concerns which I’ll get to in a minute.

If this Google/Apple system was adopted then the app would probably have provided some benefits. We could entertain ourselves rehashing familiar arguments about whether this level of data collection is justified for the public good and call it a day. Alas. The Australian government chose not to adopt this technology.

This meant COVIDSafe was functioning as a plain old Bluetooth LE app without special support for exposure notifications. In regular apps, Bluetooth Low Energy functionality is severely limited for reasons of privacy and battery life, particularly when the app is not running in the foreground or if the device is locked. So it was that COVIDSafe became another potential surveillance project foiled by its own rubbish implementation.

Having committed to this course of action they inevitably faced a number of problems, all of which were foreseeable had they bothered to ask an independent subject matter expert. Transmission and reception of Bluetooth LE advertisements is heavily restricted when the relevant app is not actively running. iOS is the worst: when your app is backgrounded you get only a single notification the first time you detect another device. You don’t get to find out whether they moved closer, or when they moved away. I demonstrated this in a video at the time.

Then there is the general unreliability of rangefinding using Bluetooth LE. In the general case this is considered a fool’s errand, particularly on Android when there are lots of different manufacturers of wireless chipsets with their own sensitivity scales. It correlates with distance from the other device, certainly, but it also depends heavily on transmission power and antenna orientation and environmental factors. A colleague at a former employer spent days collecting Android calibration data for a client who wanted a one metre cutoff for an unrelated app. We could kind of do it but it was rather rough.

A couple of years later, COVIDSafe is finally being decommissioned, having been an abject failure from beginning to end. Take-up was poor, efficacy was terrible, and the costs were high. This to say nothing of the public trust lost in having the Prime Minister spruik another boondoggle that runs down your phone battery and doesn’t actually work. (Actually, a distrust of government apps might prove useful if Peter Dutton ever becomes Prime Minister.)

What this debacle indicates to me most is that the federal government needs a solid internal app development team. Making good-quality and privacy-respecting apps is nowadays a core responsibility of governments and we need people in the bureaucracy who will call it how it is when a minister wants something, and do the ongoing maintenance without costing tens of millions of dollars.

My wish for WWDC: a Bluetooth 5 API

Thu, 27 May 2021 13:00:00 +1000

Apple’s CoreBluetooth is pretty good. The implementation is high quality and it performs well. The consistent hardware and software means that you don’t get different behaviour from different models. It’s not perfect—the flow control delegates are ugly and the advertisement configuration is limited—but it’s basically nice to use. Android is generally the opposite: buggy, slow, and devices from different manufacturers work differently. There is an eyebrow-raising list on SweetBlue’s old wiki page.

One area Android is way ahead is Bluetooth 5. In case you missed it, Bluetooth 5 has several useful improvements over 4.2. The most interesting to me are the alternative PHYs, or modulation schemes. Traditional Bluetooth LE transmits at a rate of 1 Mbps. Bluetooth 5 adds a 2 Mbps PHY, so you can go twice as fast provided your signal is strong enough. There is also a Coded PHY, which includes forward error correction. This can operate at an effective rate of 500 kbps or 125 kbps, trading off speed for seriously improved range—reportedly over 1 km. In one video Nordic Semi put one of their chips on a drone and were receiving data at 750 metres with room to spare.

Way back in 2017 Google released Android Oreo with new APIs to configure your PHYs and simultaneously support both “legacy” and extended advertisement sets. Things are not so peachy on the hardware side. You can have a device certified for Bluetooth 5 without supporting those new PHYs, meaning that Android phones produced in the last few years are all over the place in their support. The situation finally seems to be improving. In my testing, the Samsung Galaxy S9 doesn’t support all the BT5 features but the S10 does.

Meanwhile, Apple hasn’t given us any control over Bluetooth 5 at all. Developers like me want to choose our PHYs. We want to use extended advertisements to transmit hundreds of bytes of data instead of ~23 plus a service UUID. We want to use periodic advertisements to avoid unnecessarily establishing connections. Hopefully, surely, finally this year we will see some updates on this at WWDC?

While I’m dreaming, hopefully they’ll fix News+ too. I want to like it but I just can’t countenance publishers pushing ads in the middle of content I’m paying for.

Bluetooth LE for Mobile - 4. Android Peripheral

Mon, 02 Jul 2018 15:30:00 +1000

The story so far:

An Overview
iOS Peripheral
iOS Central
Android Peripheral

Next our discussion turns to Android. Android has had complete support for BLE/GATT for a while. It offers slightly more configurability than iOS in options such as power levels and advertisement data.

There are some gotchas. Support for acting as a central was introduced in Android 4.3 (API level 18). Support for acting as a peripheral didn’t arrive until Android 5.0 (API level 21). I hope that you, dear reader, don’t need to support KitKat. If you do, it won’t be able to broadcast BLE advertisements in any case.

There is also a significant number of bugs and performance problems. Some of this can be attributed to Android; much to poor implementations in specific hardware models. There is some voodoo involved in trying to keep the widest range of hardware happy. It involves things like judicious use of the main thread and attempting to gracefully work around the notorious error 133. These problems afflict centrals more than peripherals so I’ll address them in the next post.

While I can’t speak for the latest versions, matters seem to be improving with time. I’ve had the most trouble with Android 5.0 devices and somewhat less with 6.0. The difficulty with the Android ecosystem is that so many devices in the wild are stuck on old versions. At the time of writing 5.x still has a 22.4% market share and 6.0 has 25.5% (source).

I wasn’t able to find any official walkthroughs of Android peripheral code and I don’t want to get into the Java here. For code examples I’ll refer a couple of times to a nice blog post on nilhcem.com.

Android Permissions for Bluetooth LE

To use the full range of BLE functions an app must have the BLUETOOTH and BLUETOOTH_ADMIN privileges. See this documentation for a manifest example.

More surprisingly, scanning on Android 6.0+ requires ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION. The rationale for this is that BLE peripherals are often iBeacons representing particular locations. If the app happens to identify one then it knows where the user is. It… makes sense I suppose? Communicating this requirement effectively to users is left as an exercise for the reader.

Configuring a GATT Server

The process of setting up a tree of services and characteristics is conceptually very similar to on iOS. There is a class representing a single characteristic, another representing a single service, and another representing the overall GATT server (peripheral). You instantiate the “small” ones and add them to the bigger ones until the entire data model is defined.

A BluetoothGattCharacteristic is initialised with a UUID, plus some properties and permissions flags. There are many possible flags but the most important ones concern reading and writing. If it’s readable it should have PROPERTY_READ and PERMISSION_READ; if it’s writable it should PROPERTY_WRITE and PERMISSION_WRITE. If it needs to support both reading and writing the flags can be bitwise-ORed together: PERMISSION_READ | PERMISSION_WRITE.

The service is represented by a BluetoothGattService. Initialise one with the service UUID, and you will probably want to use the primary service type unless you already know otherwise. The corresponding characteristics can then be added to it with addCharacteristic().

Finally, implement BluetoothGattServerCallback and open a BluetoothGattServer, providing your callback. Services can be added to it with addService(). It won’t actually broadcast any advertisements – we’ll get to that in a moment. Your callback implementation is what does all the work of handling connected devices and responding to read and write requests.

See the nilhcem.com blog post for a code example of configuring characteristics and services, as well as handling read and write requests. Note that they are also using a feature called characteristic descriptors which I haven’t discussed. It isn’t critical if you’re writing both the central and peripheral app which means you know exactly what the characteristics represent.

Advertising with BluetoothLeAdvertiser

A separate class called BluetoothLeAdvertiser does the specific job of broadcasting advertisements. You obtain one via BluetoothAdapter.

To call startAdvertising() you need to prepare an AdvertiseSettings using AdvertiseSettings.Builder, AdvertiseData using AdvertiseData.Builder, and implement the AdvertiseCallback interface. This callback class will find out whether startAdvertising() was successful or not. Like iOS, this is an asynchronous process and you should wait for the callback rather than assume it worked.

The “Start Advertising” section of the nilhcem blog post has a good example of preparing typical parameters.

Extra Advertisement Data with Scan Response

Android provides considerably more control over how advertisement packets are structured than iOS does. As seen above, an AdvertiseData.Builder is used to construct the contents of the advertisement packet. This can include arbitrary “manufacturer data”, which is really cool. The trouble is that you can only have 31 total bytes of data in the packet. This is really tight and every field you add has overhead. Service UUIDs are really big unless your company can obtain a short UUID allocation.

One solution is an active scan request followed by a scan response. If a central hears a peripheral’s advertisement it can essentially call out “hey can I have a bit more info please?” The peripheral will oblige by broadcasting a second advertising packet. This scan response can contain another 31 bytes, separate from the original. These content of these two packets is merged when you receive it on a central.

On Android you provide the scanResponse packet as a second instance of AdvertiseData. There is a corresponding version of startAdvertising() that takes two AdvertiseData parameters. Conceptually:

Advertising Rate and Power

Android offers the developer control over the rate at which advertisements are broadcast – and it defaults to a low rate, which could take centrals a relatively long time to detect. This behaviour is controlled by the “mode” in AdvertiseSettings. There are three constants corresponding to “low power” (the default), “balanced”, and “low latency”.

The exact rates are not specified in the documentation. I have always used the highest “low latency” rate. Anecdotally this produces a stream of advertisements at around 10 Hz. The others are reported to go down to ~4 Hz and 1 Hz. For comparison, iOS apps advertise at a steady 20 Hz.

What rate does your peripheral actually need? If the central user is going to open and interact with your app in order to locate nearby peripherals, their receiving radio will be fully powered. They will probably pick up even a 1 Hz advertisement within a second or two depending on ambient interference. If you’re relying on longer-term background scanning where the OS will be cutting corners to save power, more frequent advertisements means a better chance of being detected promptly.

The power level can also be adjusted using the AdvertiseSettings. If it only makes sense for your app to communicate at short distances consider using a low power level. This will save energy, help to reduce interference with other Bluetooth devices, and require your centrals to get closer before they detect the peripheral.

Summary

This post has been a quick introduction to BLE on Android, the basic steps to act as a peripheral, and a look at some more advanced configuration options.

In the next post I will describe using the central role on Android, along with some guidelines for reducing the number of problems on older devices.

Bluetooth LE for Mobile - 3. iOS Central

Wed, 21 Mar 2018 10:15:00 +1100

The story so far:

The last post focused on how to make an iOS device become a BLE peripheral. This one will discuss being a central. There were some general tips for iOS too so if you’re jumping in here I’d recommend at least reading the previous post.

iPhones and iPads make fantastic centrals. It doesn’t matter so much what the peripheral is – as centrals they are reliable, fast, and in most cases recover cleanly from error conditions. My first time doing BLE was on iOS communicating with a LightBlue Bean and I thought this level of reliability was normal. How naive I was. Android does generally work but if you have the opportunity to make a BLE app that’s iOS-only then you’ll have an awesome time.

The Apple documentation Performing Common Central Role Tasks hasn’t been updated for a few years. It does have some Objective-C snippets relevant to this topic.

Scanning for advertisements

The starting point for an iOS central is CBCentralManager.

Initialise a new instance, passing in your own class that implements CBCentralManagerDelegate.
Wait until the delegate receives centralManagerDidUpdateState() to confirm BLE is available.
Call scanForPeripherals(), optionally filtering by the service UUID.
Wait until the delegate receives the didDiscover method, which includes an instance of CBPeripheral, advertisement data and an indication of signal strength. This method will be called for each peripheral that is discovered.
If you wish, establish a connection to a peripheral. Assign a delegate to the CBPeripheral and call connect() on the CBCentralManager. (More about this shortly)
When finished scanning, call stopScan().

Do pay close attention to the CBCentralManager’s state notifications – if it’s not poweredOn (and this transition takes time) then you can’t scan. The user is also free to switch off Bluetooth at any time and the app has to deal with the consequences.

When starting the scan there are a couple of important choices to make. The first is whether you want your app to get a callback for every advertisement that a peripheral transmits, or to just get notified once when a peripheral first comes into range. If you have no special need for the continuous stream of advertisements then it will be better for your users’ batteries to stick with just one callback.

The second choice is whether to filter peripherals by the service UUIDs they include in their advertisements. If you are trying to connect to a particular kind of device then this is a good idea because it means you won’t be notified about every set of wireless headphones and iBeacon you come across. This simplifies your programming and again saves battery. If on the other hand you’re making a utility that scans for all BLE peripherals in range, then you would choose not to have any filtering.

Accessing advertised data

I’ve previously suggested that if an application can get away with using only broadcast advertisement data, without establishing connections, then it should. This process is fast and reliable.

In the delegate method where advertisements are delivered to your app you get a dictionary of values that may or may not be present depending on what the peripheral chose to include. (As far as I can tell iOS automatically performs a Scan Request/Response to capture extra data when it’s split over two advertisement packets.)

If the other peripheral is an iOS app then they have have limited control over the content of the advertisements. They can set only the local name and the service UUIDs and the name can’t be very long. The other keys may be of interest if you’re communicating with non-iOS peripherals.

One more warning: Android peripherals can in certain situations transmit a previous, out-of-date local name for one or two advertisements before the new name takes effect. It’s bizarre but true and this may be an issue as an iOS central if you act on the first name you see.

Connecting to a peripheral

Often advertisements are not enough and we need to establish a stateful connection to the peripheral. Before you can connect to a peripheral you have must received an advertisement from it. The advertisement delegate method will receive the CBPeripheral that you need – hold onto it and you can use it to make a connection either immediately or later, assuming they’re still in range.

The opening and closing of connections is done by calling methods on the CBCentralManager, passing the CBPeripheral as a parameter. Once connected, all service and characteristic operations are initiated directly on that CBPeripheral.

So establishing a connection is an “outer” process that involves the manager. Since it’s the CBCentralManager doing it, success or failure of that connection will go to the CBCentralManagerDelegate.

Notice that the delegate will also get a notification when we have finished disconnecting from a peripheral. Don’t try connecting to that peripheral again until we get that notification. As mentioned in the last post, all BLE things take time and iOS will tell you when it’s ready.

Once the connection is established there is more work to do – discovery. First you must discover the service you want, then you must discover characteristics within that service to which you want to read, write or subscribe. It is necessary to go through the motions even if you’ve connected before, and even if you know exactly what kind of device it is based on the advertisement.

This may seem tedious but it’s worthwhile – it gives you the opportunity to specify exactly which service UUIDs and characteristic UUIDs you want. If this is a relatively small number of characteristics it will be extremely fast, because it won’t bother retrieving anything else.

Once you have a CBPeripheral that’s connected and has a CBPeripheralDelegate configured, you can go ahead and do things like readValue() and writeValue(), passing in the CBCharacteristic you want to work with. Each of these operations will result in a corresponding success or failure delegate method.

Unless you have a lot of idle time in your connections I would recommend only trying to do one thing at a time – i.e., connect to only one peripheral and do only one read/write before doing the next one.

Rangefinding with RSSI

RSSI numbers are essentially made up. The “I” stands for “indication”. No BLE devices can compensate for the physical layout of the space they’re in. There can be enormous variation in RSSI values between different devices when they are the same distance apart. The advantage of iOS is that all devices are made by the same manufacturer so there is consistency in the Bluetooth hardware and RSSI algorithms.

That said, you can estimate distance approximately. Apple offers it with iBeacons – see their CLProximity enum. If “The beacon is relatively close to the user” sounds vague… well, yes it is. I don’t recommend it.

Scanning and connecting in the background

iOS doesn’t let us have a lot of fun when our apps are in the background so BLE is a pleasant surprise. Your app can’t start scanning from the background – for example, when the user first turns on their phone. However if your app is launched and it has the right background mode, scanning will continue after the user switches to another app – even after the iPhone is locked. Just be aware that scanning happens at a much reduced rate so it will take longer to detect advertisements.

What’s more, when a peripheral is detected your app’s code will be called and will have the opportunity to establish a connection and read characteristics, all without any user interaction. Depending on what you discover you might choose to launch a local notification, or simply do nothing.

Summary

This post introduced CBCentralManager and CBPeripheral and the things you can do with each to implement a full-featured BLE central in iOS. If you’re following along the series, you now have a pretty complete idea of how the iOS Core Bluetooth API hangs together. That means Android next time!

Bluetooth LE for Mobile - 2. iOS Peripheral

Thu, 01 Mar 2018 21:00:00 +1100

The story so far:

Core Bluetooth and iOS

In the last post I described Bluetooth Low Energy (BLE) at a high level and explained roughly how it works on iOS and Android phones. Now I want to talk about the iOS API; in particular how to be a peripheral. I’m not going to go into heaps of detail – that’s what the documentation is for – but in this post I’ll introduce the key classes, describe what coding you’ll need to do, and highlight quirks that are interesting and/or dangerous.

The framework for Bluetooth LE communication on iOS and macOS is called Core Bluetooth. Despite the broad name it is almost entirely for GATT communication, which is all about the services and characteristics mentioned previously.

Prerequisites

Your device must have Bluetooth turned on. Obviously. If you want your app to be able to act as a Central or Peripheral when it is not in the foreground you must enable the bluetooth-central or bluetooth-peripheral Background Modes in Xcode.

Being a Peripheral

To turn your iPhone or iPad or Mac into a Bluetooth LE peripheral you need an instance of CBPeripheralManager. You will need to provide it a delegate of type CBPeripheralManagerDelegate. Implement this in your class and pass it in when you initialise the CBPeripheralManager.

The required steps are described pretty well in the Apple documentation Performing Common Peripheral Role Tasks (albeit in Objective-C) so I won’t bore you with code snippets. Here’s a diagram though.

First you need to allocate UUIDs for your services and characteristics. To create a CBMutableCharacteristic you need to specify its UUID and its permissions such as whether it is readable or writable. Then you create a CBMutableService and assign an array of characteristics to it. If you’re unsure you probably want to create a primary service.

Once you’ve built up a CBMutableService, add it to the CBPeripheralManager with add(). Finally, when all your services are added, call startAdvertising() on that manager, providing the device name and the array of advertised service UUIDs. Your delegate will be called with peripheralManagerDidStartAdvertising(). If the error parameter is nil, congratulations, your peripheral is now live.

Tip: It’s all async

When using CBPeripheralManager or CBCentralManager look closely at their respective delegate methods, implement all of them, and understand when they are called and why.

Error handling is critical because in BLE errors happen all the damn time. It may be due to lack of permissions, Bluetooth being switched off, or congestion on 2.4 GHz. It is way less reliable than just about any other API. It’s not Apple’s fault; it’s just the nature of things and if an app doesn’t pay attention and manage its state properly it will have a bad time.

Virtually every action that you can take with the BLE API takes a certain amount of time to complete and it will tell the delegate when it succeeds or fails. It’s important to wait for these notifications before doing the next thing. For example, disconnecting from a device takes time. If you attempt to reconnect before receiving didDisconnectPeripheral then it will not end well.

It is somewhat unfortunate that iOS wound up with a “massive delegate” design for this API. There’s an argument to be made for farming off particular tasks and responsibilities to multiple smaller classes. You’re forced into writing a big stateful class that can handle an arbitrary number of characteristics for an arbitrary number of connecting peripherals. Recognise that this is going to happen and do your best to move complexity out to helper classes.

Handling read and write requests

Surprisingly, if you are an iOS peripheral the operating system will not tell you when a central connects or disconnects. It just isn’t part of the API. So your app will be advertising merrily away and suddenly it will be interrupted by a read or write request. (It could be also be a subscription event – more about those shortly.)

There are two delegate methods for responding to read and write requests. For a read you must provide a Data (NSData) containing the bytes to return. In a write request are provided with a CBAttRequest that contains the bytes that were written by the central.

In both cases the delegate is given two pieces of information – a CBCentral, who has a UUID identifier that tracks a particular device for the duration of its connection, and the CBCharacteristic that was targeted, which contains the UUID you assigned to it earlier on.

There is no rule that you have to give every central the same value for a particular characteristic. There is no rule that you have to provide the same value every time a central reads a given characteristic. Let your imagination run wild – but realise that if you rely on a series of reads or writes, the longer your process goes, the lower the probability that it will fully succeed.

However there are two important things that the iOS peripheral does not know:

If a central reads a value and you provide it, you don’t know for sure if they ever got it.
If a central writes a value and you use it, you don’t know for sure they got the acknowledgement that the write was successful.

This is not especially limiting but it’s something to keep in mind if you want your app to be fault tolerant.

The trouble with subscriptions

Have you ever written an app that gummed up iOS so badly that the entire device needs a reboot to start working again? I’ve done it only once and it was using BLE subscriptions.

A connected central can choose to subscribe to a characteristic. Your app will receive delegate calls when they subscribe and unsubscribe. When the characteristic notionally “changes value”, or perhaps you just want to send a bunch of chunks of data in a row, you can invoke updateValue() to tell iOS that it should transmit a new value to the relevant subscribers.

But sometimes updateValue() returns false, indicating failure. Have a look at this crazy method.

You have to wait for this mysterious queue to empty out a bit, at which point you receive this call on your delegate. You can then do more updateValue()s until one of them returns false. Then you have to wait again.

Okay so this is kind of clunky and state-heavy but you can work with it to get the data through – unless the connection to the device fails abruptly. In that case iOS sometimes gets stuck trying to communicate with devices that don’t exist, the queue never empties, and it all goes to hell in a handbasket.

I should mention that I did most of this testing on iOS 9 which is now a little dated. All the same I would recommend avoiding the subscription API unless you specifically need sporadic realtime updates from peripheral to central – i.e., exactly what it was designed for.

For everything else, such as sending larger chunks of data, you are far better off to have the central do just one read or write at a time, wait for the success result, then do the next one. This way you never pile up on any queues and failures can be handled far more gracefully.

Big Data with iOS BLE

Under normal circumstances BLE characteristic values are limited to 20 bytes in length. When the central and peripheral are both running iOS the rules can be bent a little.

CBCentral has a maximumValueLength parameter which indicates how many bytes you’re allowed to send it at once. I have seen iPad centrals reporting values of around 160 bytes. I don’t have measurements but this may speed things up for you if you’re trying to send a lot of data via characteristic reads.

Next steps

In the next post I will describe being a BLE central in iOS. Originally I was going to cover all of iOS in this post but it was getting way too long.

Part 3: iOS Central

Bluetooth LE for Mobile - 1. An Overview

Tue, 20 Feb 2018 22:00:00 +1100

Introduction

This is the first in a series of posts introducing Bluetooth Low Energy (BLE). The target audience is iOS and Android mobile developers who want to use BLE to communicate with external hardware, or with another device running their app.

In the last couple of years I’ve spent a bunch of time building cross-platform apps that use Bluetooth LE – in other words, using CoreBluetooth and the Android Bluetooth API in apps that can reliably advertise, scan, and transfer different kinds of data to each other.

In this introduction I want to bring the main features together in some detail and describe how to use them on both platforms. Basically it’s the things I wish I knew when I started out with cross-platform BLE.

I should point out up front that I am not an expert on the Bluetooth protocol, the hardware or the RF behaviour – I haven’t even read much of the spec. I’m just a guy who spent a long time banging his head against the APIs that these platforms provide.

This first post is a high level overview of what it’s like to use BLE, what the words mean and what it has to offer your app.

A Cross-Platform Radio Protocol

Bluetooth Low Energy lets modern iOS and Android devices and various gadgets communicate without needing WiFi or Internet access. It’s an industry standard and all supported devices are compatible with each other. It works reliably over a range of tens of metres.

It’s effectively a client/server protocol. A peripheral is the server – it announces itself by transmitting a regular stream of advertisements. These advertisements are received by a client, which is called a central. The central may choose to establish a temporary connection to the peripheral. Using that connection the central can request to read or write data. The peripheral plays a generally passive role and responds to requests from the central.

When you think about Bluetooth gadgets in the real world – smart light bulbs, iBeacons, and so on – these are all peripherals. They advertise continuously and your phone acts as a central, detecting them when they’re in range, pulling data off them and letting the user control them.

Once granted the right app-level permissions, iOS and Android devices can scan and connect to arbitrary peripherals without requiring any user interaction. This is very different from ordinary Bluetooth where there is a heavyweight pairing procedure.

Conceptually the peripheral is a simple key/value datastore. It hosts services, each of which is a list of one or more characteristics. Each characteristic is a chunk of binary data up to 20 bytes (normally). Every service and characteristic is identified by its own UUID. When a central is reading or writing data, it is doing it with a particular characteristic.

When an iOS or Android device acts a peripheral – advertising, and accepting connections from other devices – it generally supports connections from multiple centrals simultaneously. The app developer may choose to present the same or different data to each central.

Advertising and Scanning

The first step in any BLE communication is to have a peripheral broadcast an advertisement. This is a packet that is repeatedly transmitted typically around 10 or 20 times per second. These packets will normally include two pieces of information: a service UUID and a device name.

The service UUID is how you identify a particular type of device or a particular app. A peripheral may host multiple services but it should pick at least one to mention in its advertisement.

Imagine you’re writing an app that talks to your brand of smart light bulb. You want your app to only detect your light bulbs, not every single BLE device in range. The light bulb will advertise a service UUID that is unique. When you scan in your app you can specify this target UUID and the OS will only bother to tell you when it hears a device that matches.

The device name is just a string and normally human readable. If you have multiple smart light bulbs you might give them different names like “Lounge”, “Kitchen”, and so on. This way you can identify a specific device by its advertisement data alone.

On the central side, your app can choose to be be notified either every time it hears a matching advertisement, or just once per device that comes into range.

Power Saving and BLE Performance

Even though it’s called Bluetooth Low Energy, if you’re advertising or scanning all the time this will use an appreciable amount of energy from your phone battery. As a result operating systems will pretend to do what you asked but don’t guarantee that they will run the radio all the time. iOS is particularly tough about this when your app goes into the background and when the phone is locked.

The exact algorithms are not public but anecdotally it seems that when the OS wants to save power it operates the BLE radio for brief spurts at a time. The theory goes that if some device out there is transmitting an advertisement 10 times per second, if you listen for 100 ms out of every second (10% of the time), you will probably notice that device within one second and this is fast enough.

Ultimately there are trade-offs between power and performance. Android gives the programmer slightly more control over this than iOS. If you are building a device that needs to be detected by locked iPhones it is important that the advertising rate is nice and high.

Establishing Connections

First let us be clear: BLE does not offer much bandwidth. It is not designed for streaming data. If you do it anyway, speeds are around a few hundred bytes per second under good conditions. (It totally does work though.)

A central that has detected a peripheral by its advertisements may or may not want to connect. In some cases the information contained in the advertisement along with the received signal strength (RSSI) may be all its needs to do its job. Compared with everything else in mobile BLE, transmitting and receiving advertisements is super reliable. If this is enough information to get the job done then I’d highly recommend not even bothering with connections. Unfortunately that’s pretty rare and you will normally need to connect to read data of your choice, or to write any data at all.

From the API’s point of view there are several phases:

Establishing an initial connection
Discovering the services that are available
Discovering the characteristics that are available for a given service
Finally, using those discovered characteristics to read and write data

Even when you know that a particular device is offering certain services and characteristics you still have to go through the rigmarole of discovering them every time you connect.

In Android steps 2 and 3 are handled by a single request that goes ahead and discovers every service and characteristic available on a given device. This is easy to use but the downside is that it’s very slow. On Android 5 and below it takes around 6 or 7 seconds to interrogate a typical iOS device. This was substantially sped up in Android 6+ but it’s still slow. Caching does help if you make multiple connections to the same device.

In iOS there are two distinct stages. First you discover services, which you can specify by UUID, then you discover characteristics, which you can also specify by UUID. iOS connects really dang fast.

Reading and Writing Data

Both iOS and Android offer a lot of control over the reading and writing of data.

Centrals can:

Initiate a read request or a write request
Get a callback indicating whether a given read or write request succeeded or failed

Peripherals can:

Respond to each read and write request individually, knowing the identity of the central that requested it
Choose which data to send dynamically in response to each read request
Choose what to do with the data received in each write request

With this level of control it is straightforward to build up interesting application level protocols using these operations as building blocks.

It is also possible for a connected central to subscribe or unsubscribe to a particular characteristic. When a central has subscribed, the peripheral can transmit updates to this characteristic and as long as the central remains connected they will receive those updates asynchronously.

You might assume (as one Apple sample project does) that this is a great way to create a data channel from peripheral to central. In practice the iOS subscription API has some major issues. In a later post about iOS I will explain why I think it’s silly.

GATT

I should mention that a lot of what I am describing in this post is technically GATT, which is just one part of Bluetooth Low Energy. GATT is basically all you get in iOS and Android so all the documentation just calls it “Bluetooth LE”. I won’t try to explain any more because as I mentioned at the start, I only know about what the APIs provide.

Conclusion

In this post I’ve introduced the main concepts of Bluetooth Low Energy – what you can use it for, the general lifecycle of the API, and the main terms such as peripheral, central, service and characteristic.

Even though they provide almost the same functionality, the iOS and Android APIs wound up being fairly different. In the next few posts I’m going to briefly describe the architecture of each one and highlight some of the interesting parts.

Part 2: iOS Peripheral