This post is an excerpt from a course developed by Anas Imtiaz, Ph.D. which is available within the Bluetooth Developer Academy.

In a previous post (Introduction to BLE Mobile Development for iOS), we covered:

  • Setting up Xcode for BLE development
  • Bluetooth permissions
  • Scanning for BLE peripherals
  • Connecting to a BLE peripheral

In today’s post, we will take this a step further and look at developing a UI-based iOS app (using SwiftUI) that can perform most of the previous functionalities, with some additional features:

  • Display the status of Bluetooth on the device (turned on or off)
  • Act as a Central to discover BLE Peripherals and display them as a list in the UI
  • Start and stop scanning by clicking dedicated buttons in the UI

Note: we will be using SwiftUI to develop the user interface which requires iOS13 and Xcode 11. If you are on previous versions you can still follow along since the Core Bluetooth APIs are exactly the same regardless of the method used to build the user interface.

For this tutorial, we’ll be using:

  • MacBook Pro 2017 
  • macOS Catalina (10.15.2) 
  • XCode version 11.3.1
  • iPhone 11 (iOS version 13.3.1)
  • Swift 5.1
  • Optional: Another iDevice (we’re using iPad Pro (1st generation, iPadOS 11.3))

The prerequisites for this tutorial include:

  • An Apple computer: Macbook, Mac Mini, iMac
  • macOS
  • XCode 11+
  • iPhone with BLE (iOS13+)
  • A BLE Peripheral device
  • Enrollment in the Apple Developer Program (Free, unless you want to deploy to the App Store in which case it is USD99 per year)
  • Basic understanding of Swift

Note: you can find the reference code for this tutorial towards the end of the post.

Setting up the Project

To start things off, fire up Xcode on your Mac and select Create a new Xcode Project. For the template select Single View App for iOS.

On the next screen, enter the app name and other details. Make sure to select SwiftUI for the user interface for this app.

Next, select the location where you want to save the project and the press Create.

On the left hand side you will see the list of files. The main file here that we will use for our UI is ContentView.swift.

On the right-hand side, you will see a live preview pane which will refresh every time the UI is being updated. It may be paused to start with, so hit the Resume button to build and preview the boilerplate code.

You should see the “Hello, World!” text on the preview.

Building the User Interface

(Note: We will keep this section brief in order to keep the focus of the tutorial on Core Bluetooth operations)

We are building an app that is able to scan for BLE peripherals. For its functionality, as a BLE scanner, we want to display a list of devices that we have found as well as the ability to start and stop scanning.

For operation as a BLE peripheral, we want our app to be able to start and stop advertising itself as a peripheral device (covered in the full course in the Bluetooth Developer Academy).

Finally, we also want our app to display the status of our Bluetooth hardware i.e. whether its switched on or off. The user interface we want will look something like this:

From top to bottom, we want some text for the title, a list of devices, status text, and a group of four buttons for control.

Before we move forward, let’s take a quick detour into the world of SwiftUI which is Apple’s latest way of building user interfaces in a declarative way. In SwiftUI, if we want to add a text label, we simply say:

If we want to make this text italic we add a modifier:

If we want to change its color to red, we add another modifier:

This is true for other UI elements as well where we simply add modifiers to achieve the desired look and functionality.

Another important concept is that of stacks. UI elements are organised in horizontal and vertical stacks (HStack and VStack). For example, two buttons laid side by side will be in HStack:

Two buttons laid vertically can be in a VStack:

And they can also be nested where there are groups of VStack inside HStack or vice versa.

Looking at our UI sketch above, we want a main VStack that holds all the elements inside starting with a Text object, a List object, a Text object saying STATUS following by another Text object which is showing the actual status, and finally a HStack with two VStacks each having a pair of Button objects. Additionally, for spacing between objects, we will use Spacer().

Adding all those UI elements in ContentView.swift, our starting point for the user interface will look like this.

And our ContentView.swift should have the following code:

We will continue to add to this initial UI code while we are exploring the CoreBluetooth framework in the next sections.

iPhone as a BLE Central Device

Setting Up

Since we are using SwiftUI for our user interface, we will create a separate class as an Observable Object to manage Bluetooth connections. This will be a class that will handle all Bluetooth operations that any View can subscribe to in order to get updates about the peripheral device.

The reason for having it as an observable object is to trigger a refresh and reload of the UI elements automatically whenever there is any data update.

Go to File –> New –> File

Choose iOS Swift File for the template. Click Next and save it as BLEManager.swift.

In this new file, define a new class BLEManager that conforms to NSObject and ObservableObject classes.

This is our empty class right now. We want to have our iOS device act as a BLE Central. So, we need to import the CoreBluetooth framework, define a variable of type CBCentralManager, and define the required CBCentralManagerDelegate methods. Add the CBCentralManagerDelegate to your class definition.

XCode will throw up an error saying: Type ‘BLEManager’ does not conform to protocol ‘CBCentralManagerDelegate’.

Use the auto-fix feature to get the stubs for the required methods that are currently missing in this class. In this case, the missing method is centralManagerDidUpdateState.

Xcode will add the following in your class:

Initialising CentralManager

When our BLEManager class is instantiated we want to initialise its myCentral instance variable and assign its delegate to self so that the delegate methods are called. This is done by overriding the default initializers init() method to perform the initialisation tasks.

Add the following function to your BLEManager class to initialise the central manager.

Note: If you followed the Introduction to Mobile Development for iOS tutorial, we used a single ViewController and included our BLE functionality as part of the same class.

In this tutorial, we are using a slightly different approach for the definition of BLE functions as we are creating a separate class object and observing it through the new SwiftUI framework. The APIs are exactly the same and the only difference is the initial setup. So what we are doing right now is exactly the same process as the other tutorial.

Before we finish the initial set up, let’s also add a boolean class variable that is set to true if Bluetooth is switched on BLEManager has been initialised, and false if it is switched off on our iPhone.

Since we want to display the status on our UI and automatically update the UI whenever the status changes, we will define it with the @Published attribute.

The @Published variable, as part of an @ObservableObject class will trigger an automatic UI refresh whenever its value changes and we can query the value to present the appropriate view. We will assign the values of isSwitchedOn in our didUpdateState delegate method as follows.

As a checkpoint, make sure your BLEManager class looks like the following at this time.

Finally, we need to instantiate this class in our ContentView, so go ahead to ContentView.swift, and add the following as the first line inside the ContentView definition.

To update the status, we will use a Text object that checks the value of isSwitchedOn variable. We can do it like this:

Copy the code above to replace the existing code for the status text in ContentView.swift.

Now our UI and initial BLEManager class is set up and ready for use. Go ahead to build and run the code on your phone to see it in action.

CoreBluetooth Central Permissions

At this point, our app builds successfully but crashes on launch. In your debug console, you will be shown an error as follows.

What just happened?

We forgot to add the right entitlement for Bluetooth usage in the Info.plist file. This is a mandatory requirement so that the users are presented with the right message when permission to access Bluetooth is being asked by the phone.

To fix this, go to your Info.plist file and add a new row. From the dropdown select “Privacy – Bluetooth Always Usage Description” and add a message that you want to be displayed.

Now let’s try again and this time everything should work well.

When you run the app you will see the user interface with the status that Bluetooth is not switched on. You will also be presented with the permissions dialog. Once you grant permission to use Bluetooth, the status should update as shown on the UI to indicate that it is now powered on as shown below.

(Note that the relevant key here is NSBluetoothAlwaysUsageDescription since iOS13. Prior to iOS13, the key for Bluetooth permissions was NSBluetoothPeripheralUsageDescription. Therefore, for compatibility it is recommended to have both these keys defined in the plist file.)

The UI looks good now, however, our list is empty since we haven’t scanned and found any peripheral devices yet.

Let’s now find devices to populate our list.

Scan for Peripheral Devices

As in the previous tutorial, we will use the scanForPeripherals method to start scanning. This will trigger callbacks to the didDiscoverPeripheral method where we will keep track of all the devices that we find and then populate our UI with them. 

The way we will tackle this is by creating an array where we can append the name and RSSI of every device we discover by scanning.

Let’s define a struct called Peripheral to hold this information on top of our BLEManager.swift file – after the import statements (we can do this in a separate file too but for convenience, we will do it here).

Our struct has three variables, with the name and rssi being the obvious ones. The id is of type Int which is added because we are subclassing from the Identifiable class.

The reason for doing this is purely for user interface purposes. We have a List view in our UI that will have several rows. Each row needs to have a separate identifier so that when we pass this our array of Peripheral objects as the data source of our List, it becomes super easy to display them. An excellent explanation of working with Identifiable items can be found here:

https://www.hackingwithswift.com/books/ios-swiftui/working-with-identifiable-items-in-swiftui

Now, declare an array for Peripheral objects in the BLEManager class. We will do this with the @Published attribute as well so that the UI is refreshed when new peripherals are discovered.

Now we will define the operation of the didDiscoverPeripheral delegate method. If you start typing didDiscover, Xcode will start showing a list of methods from where you can select the right method to autocomplete its definition.

Fill up this method as follows.

What we are doing here is that as soon as we discover a new peripheral, we define a new Peripheral object with its name as the name being advertised by the peripheral and its rssi as peripheral.rssi. Note that we are using CBAdvertisementDataLocalNameKey key to access the name being advertised. We can also use peripheral.name but this may return the name of the device that exists in its database as the GAP device name.

We also assign the id as the length of the array making the id unique. Finally, we append this newPeripheral to our peripherals array. What we are doing here is appending the name of every peripheral we find in our scan and the peripheral rssi to the array of structs. Since this array is @Published and is part of an @ObservableObject, any changes to it will trigger a UI refresh automatically.

We still haven’t fed this array as the data source, so go into your ContentView.swift file and replace the List object we had earlier with the following.

Briefly, what is happening here is that we have a List view with its data source as bleManager.peripherals array. For each element (peripheral) in this array, we define a row as HStack (horizontal stack of elements) where we display a Text view with the peripheral name, some space, and then a Text view with the peripheral RSSI. That’s pretty much it, our list view is ready to use.

One final piece of the puzzle left is that we still don’t have a method to start the scanning. We have a Button which we wish to use to do this. So let’s go to BLEManager and define a function called startScanning() as follows.

And another one called stopScanning() as follows.

Now we just need to add these functions as the corresponding Button actions in our user interface.

Make the following changes to the Start/Stop scanning buttons in ContentView.swift.

That was a bit of work there setting up everything on the UI and linking it to our BLEManager. Build and run on your phone, and press start scanning.

Keep an eye on your debug console as well to see which functions are being executed (the print statements have been added to help with that).

As you can see several devices are quickly shown on the list (which is scrollable) so you can move up and down to view the complete list.

Congratulations! You have set up the very basics of scanning as a Central Manager and displaying the list on your phone.

Source Code

ContentView.swift:

BLEManager.swift:

Summary & Closing

In this tutorial, we covered a lot, including:

  • Setting up an Xcode project
  • Setting up an iOS device as a BLE Central to scan for Peripherals
  • Designing a UI that supports starting the scanning process, stopping the scanning process, and listing the discovered Peripherals
  • Display the Bluetooth status on the iOS device (whether it’s on or off)

Take your BLE knowledge to the next level!

If you’ve found this tutorial useful, but you want to learn more about BLE development on iOS and further develop this basic app to cover:

  • Scanning for BLE peripherals in foreground and background
  • Scanning for an iPhone that is operating as a BLE peripheral
  • Differences between foreground and background scanning
  • Maintaining a connection with a peripheral in background
  • Setting up the iPhone as a BLE Peripheral
  • Advertising data in foreground and background
  • Limitations in background advertising
  • Setting up the iPhone as an iBeacon
  • Background iBeacon operation

then check out the Bluetooth Developer Academy.

As part of all the courses within the Academy, you’ll also be able to download the full source code to use as reference or use within your own application.

By joining the Bluetooth Developer Academy, you will get access to a growing library of courses and tutorials.

Here’s what one Academy member has to say:

If you’re developing a BLE project, you need two things, a good BLE sniffer and the Bluetooth Developer Academy. I am very happy to be part of this community and look forward to what comes next.

– Christopher Gates, Principal System Security Architect – Velentium

The current courses include:

  • The Basics of Bluetooth Low Energy
  • Analysis of BLE events using a BLE sniffer
  • Long-range mode (Coded PHY) using Bluetooth 5.0
  • Developing nRF52 applications using Visual Studio Code
  • Over the Air Device Firmware Update (OTA DFU) – nRF52 use case
  • Getting Started with Zephyr (including adding custom GATT Services and Characteristics)
  • The Developer’s Guide to what’s new in Bluetooth 5.2
  • SweynTooth: A Summary for BLE Developers
  • Introduction to BLE Security
  • Getting Started with BlueZ development
  • Introduction to BLE Development for iOS
  • …and more courses added each month!

For a full list of courses included, check out the Courses Library here:

Bluetooth Developer Academy Courses Library

The Academy also features a thriving community of Bluetooth experts, developers, and innovators. You’ll get to connect and interact with other experts in the Bluetooth space, learn from others’ experience and knowledge, and share yours.

Also included in the Academy is access to private support from me personally.

In the community, you will find:

  • Discussions around new features such as long-range mode (Bluetooth 5.0) and direction-finding (Bluetooth 5.1).
  • Discussions around the capabilities of different BLE sniffers.
  • Comparisons of BLE support and restrictions in iOS and Android.
  • Various technical questions and answers to these questions.
  • Listing of Bluetooth-related job openings.
  • And many more discussions!

Learn More About the Bluetooth Developer Academy