Enabling Background BLE Scanning on iPhone


A previous post shows how to create a simple BLE (Bluetooth Low Energy) scanner app for iPhone. The app can detect BLE devices while the app is in foreground. The goal of this post is to create an app that scans even it goes to the background.

 

Prerequisites (parentheses indicate my environment)

  • Xcode (10.0) ruining on Mac (10.14)
  • iPhone (iPhone 8 with iOS 12.0.1)
    * An actual iOS device is required since Bluetooth is not supported in Xcode simulator.
  • A BLE peripheral device to be scanned (Galaxy S7 running BLE Peripheral Simulator app [1])

 

Steps
1. Launch Xcode and create a Single View App.

2. Select Info.plist in Project navigator.

3. Click on “+” button next to “Information Property List” and select “Required Background Modes”.

4. Expand “Required Background Modes” by clicking on the triangle icon.

5. Add “App communicates using CoreBluetooth” as the value.

6. Open ViewController.swift file and import CoreBluetooth framework.

7. Add CBCentralManagerDelegate protocol to ViewController class.

8. Then, Xcode will prompt an error. Click on “Fix” button and it will create  centralManagerDidUpdateState() method which will be called when the central manager’s state is changed. At startup, this method is called after instantiating CBCentralManager.

9. Declare a variable for CBCentralManager in ViewController class.

10. Instantiate CBCentralManager in viewDidLoad().

11. In centralManagerDidUpdateState() method, start scanning when the state is poweredOn.

In order to scan in background, service UUIDs need to be specified [2]. In this post, the app will scan for Battery Service [3] for testing purpose (Line 3).

8. Define centralManager didDiscover method. It will be called when any advertising device is discovered. Inside the method, it prints the device name, RSSI, and advertising data.

9. Open AppDelegate.swift file and add print statements in applicationDidEnterBackground method and applicationWillEnterForeground method to output the app state transitions.

 

Test
1. Background Scan
1-1. Make sure below conditions before start.

  • The peripheral device is not advertising yet.
  • Bluetooth is ON on the iPhone.

1-2. Connect iPhone to Mac.

1-3. Build and run the program.

1-4. Lock the iPhone screen by pressing the side button.

1-5. Start advertising on the peripheral device. In case of BLE Peripheral Simulator, launch the app and tap on “Battery”.

Below is the example of the result of background scan.

Notice that the Bluetooth device name is not detected. Let’s scan in foreground and compare the results.

 

2. Foreground Scan
2-1. Stop advertising on the peripheral device by tapping Back button.

2-2. Cancel screen lock on iPhone.

2-3. Restart advertising on the peripheral device.

In above, didDiscover peripheral callback was called twice (Line 3-7 and Line 9-14). AD Data of the first result is same as the background scan result. The second result additionally has a device name in AD Data (Line 11).
According to an Apple Developer Forum post [4], the first result is from the initial Advertising packet and the second is from Scan Response packet. And the second packet is not guaranteed when the iOS app is running in background. That explains why the background scan result didn’t have the second packet.
So, when scanning in background, some data may not be available (e.g. in this case, the device name).

 

Takeaway
BLE scan while app is in background (even when screen is locked) is possible. However, there are some limitations need to be consider when writing an app.

  • Service UUIDs need to be specified when starting BLE scan.
  • Some data may not be received. (i.e. Data in Scan Response)
  • Other limitations are describe in Apple’s official document [5].

 

References
[1] BLE Peripheral Simulator – Google Play Store
[2] scanForPeripherals(with Services: options:) – Apple Developer
[3] GATT Specifications Battery Service – Bluetooth SIG
[4] Apple Developer Forums – Apple Developer
[5] Core Bluetooth Background Execution Modes – Apple Developer

 

 

 

Creating a Simple BLE Scanner on iPhone


Here are steps to create a simple BLE (Bluetooth Low Energy) scanner app for iPhone (for my own learning purpose). The goal is to enable below features.

  • Scan for all advertising devices around.
  • Print the device name, RSSI (signal strength), and advertising data [1] for each discovered device in the debug console output [2].

* It doesn’t filter any specific UUID, doesn’t connect to any peripheral device, and doesn’t show anything on app screen.

 

 

Prerequisites (parentheses indicate my environment)

  • Xcode (10.0) ruining on Mac (10.14)
  • iPhone (iPhone 8 with iOS 12.0.1)
    * An actual iOS device is required since Bluetooth is not supported in Xcode simulator.

 

Steps
1. Launch Xcode and create a Single View App.

2. Open ViewController.swift file and import CoreBluetooth framework.

3. In order to scan, iPhone need to be BLE central. So, add CBCentralManagerDelegate protocol to ViewController class.

4. Then, Xcode will prompt an error. Click on “Fix” button and it will create  centralManagerDidUpdateState method which will be called when the central manager’s state is changed. At startup, this method is called after instantiating CBCentralManager.

5. Declare a variable for CBCentralManager in ViewController class.

6. Instantiate CBCentralManager in viewDidLoad method.

7. In centralManagerDidUpdateState method, start scanning when the state is poweredOn.

8. Define centralManager didDiscover method in ViewController class. It will be called when any advertising device is discovered. Inside the method, it prints the device name, RSSI, and advertising data.

 

 

Test
1. Connect iPhone to Mac.

2. Make sure Bluetooth setting is ON on the connected iPhone.

3. Build and run the program, and check the console output on Xcode. Below is an example of the output.

In the example above, it detected my Fitbit Flex (Line 3-14) and some other devices. All possible advertising data type on CoreBluetooth are listed here.

 

References
[1] Advertising Data Type – Bluetooth SIG
[2] Console output in Xcode – Apple Developer

 

 

Setting Up Bluetooth OOB Pairing with NFC on Raspberry Pi

This post shows steps to setup Bluetooth Out-Of-Band (OOB) pairing using NFC [1] on Raspberry Pi using nfcpy [2]. The goal is to pair a phone and Raspberry Pi by just touching each other.

 

Prerequisites (parentheses indicate my environment)

 

Steps
1. Installation
1-1. Install nfcpy.

1-2. Verify installation by running the module.

The output should be like this:

1-3. As the output suggests, copy line 11 above and execute it.

1-4. Reboot the system.

1-5. After reboot, run the module again.

This time, the output should be like this:

 

2. Setting up Bluetooth OOB Pairing
2-1. Download example code [3].

2-2. Create NDEF data [4] for Bluetooth OOB pairing [5].

Note: Replace “XX:XX:XX:XX:XX:XX” with your Raspberry Pi’s Bluetooth device address.

2-3. Write NDEF data to NFC adapter [6].

2-4. Open another terminal and launch Bluetooth command line interface.

2-5. Enable the pairing agent.

2-6. Set the agent as default agent.

2-7. Enable discoverable mode.

 

3. Test
3-1. Enable NFC on the phone.

3-2. Move the phone close to the NFC adapter.

3-3. Allow the pairing request on the phone.

3-4. Allow the service authorization on Raspberry Pi if requested.

 

 

References
[1] Bluetooth Secure Simple Pairing Using NFC – NFC Forum
[2] Python module for near field communication – nfcpy
[3] nfcpy – GitHub
[4] NFC Data Exchange Format – nfcpy
[5] make btcfg – nfcpy
[6] emulate – nfcpy

 

 

Setting Up Wi-Fi Simple Configuration with NFC on Raspberry Pi

This post shows steps to setup Wi-Fi Simple Configuration with NFC adapter on Raspberry Pi using nfcpy[1]. The goal is to enable “tap-to-connect” a NFC enabled phone with a Wi-Fi access point [2].

 

Prerequisites (parentheses indicate my environment)

 

Steps
1. Installation
1-1. Install nfcpy.

1-2. Verify installation by running the module.

The output should be like this:

1-3. As the output suggests, copy line 11 above and execute it.

1-4. Reboot the system.

1-5. After reboot, run the module again.

This time, the output should be like this:

 

2. Setting up Wi-Fi Simple Configuration
2-1. Download example code [3].

2-2. Create NDEF data [4] for Configuration token [5].

Note: Replace “NETWORK_NAME” and “PASSWORD” based on your environment.

2-3. Write NDEF data to NFC adapter [6].

 

3. Test
3-1. Enable NFC on the phone.

3-2. Move the phone close to the NFC adapter.

3-3. Allow to connect if the phone asks for permission.

 

 

References
[1] Python module for near field communication – nfcpy
[2] WPS adds NFC “tap-to-connect” for simple set up – Wi-Fi Alliance
[3] nfcpy – GitHub
[4] NFC Data Exchange Format – nfcpy
[5] make wificfg – nfcpy
[6] emulate – nfcpy

 

 

Changing a Bluetooth Device Address on Raspberry Pi

This post shows how to change Bluetooth device address on Raspberry Pi.

Bluetooth device address (aka BD_ADDR, Bluetooth MAC address) is a 48-bit identifier assigned to each Bluetooth chip. Whether it can be changed is depends on each chip. Fortunately, Raspberry Pi’s on-board Bluetooth chip (Cypress/Broadcom) allows device address change.

 

Assumptions
Raspberry Pi board with on-board Bluetooth chip (e.g. Raspberry Pi3 B+Raspberry Pi Zero W)

 

Steps
1. Prep
1-1.Install prerequisite package.

1-2. Download the archived file of bdaddr tool. [1][2]

1-3. Extract the archive file.

1-4. Make.

 

2. Bluetooth Address Change
2-1. Check the original Bluetooth address..

2-2. Change Bluetooth device address.

The result should be like this:

2-3. Reset hci device.

2-4. Also, restart bluetooth service.

 

3. Verify
3-1. Check the change with bdaddr tool.

3-2. Check the change with bluetoothctl.

 

References
[1] Change your bluetooth device mac-address
[2] Wget: Error 403- Can I get around this?