IOS CoreBluetooth Mock

Mocking library for CoreBluetooth framework.

114

Swift

Core Bluetooth Mock

Version number

The Core Bluetooth Mock library was designed to emulate Core Bluetooth objects, providing easy way to test
Bluetooth-enabled apps. As the native Bluetooth API is not supported on a simulator, using this library you can run, test
and take screenshots of such apps without the need of a physical phone or tablet. You may also start working on the
iOS app when your peripheral is still under development.

Core Bluetooth?

The Core Bluetooth framework provides the classes needed
for your apps to communicate with Bluetooth-equipped low energy (LE) wireless technology. It requires an iPhone or iPad to
work making Bluetooth-enabled apps difficult to test. As the documentation states:

Don’t subclass any of the classes of the Core Bluetooth framework. Overriding these classes isn’t supported and results in
undefined behavior.

Core Bluetooth Mock!

The Core Bluetooth Mock library defines a number of CBM… classes and constants, that wrap or imitate the corresponding
CB… counterparts from Core Bluetooth framework. For example, CBMCentralManager has the same API and
behavior as CBCentralManager, etc. On physical iDevices all calls to CBMCentralManager and CBMPeripheral are
forwarded to their native equivalents, but on a simulator a user defined mock implementation is used.

Requirements

The Core Bluetooth Mock library is available only in Swift, and compatible with

iOS 12.0+^[1],
macOS 10.14+,
tvOS 12.0+^[1:1],
watchOS 4.0+

(with some features available only on newer platforms).

[!Note]
For projects running Objective-C we recommend https://github.com/Rightpoint/RZBluetooth library.

Installation

The library support CocoaPods, Carthage and
Swift Package Manager.

CocoaPods

Create/Update your Podfile with the following contents

target 'YourAppTargetName' do
    pod 'CoreBluetoothMock'
end

Install dependencies
```
pod install
```
Open the newly created .xcworkspace

Carthage

Create a new Cartfile in your project’s root with the following contents

github "https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock" ~> x.y // Replace x.y with your required version

Build with carthage

carthage update --platform iOS // also supported are tvOS, watchOS and macOS

Copy the CoreBluetoothMock.framework from Carthage/Build to your project and follow instructions from Carthage.

Swift Package Manager

In Xcode: File -> Swift Packages -> Add package dependency,
type https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock.git and set required version, branch or commit.

If you have Swift.package file, include the following dependency:

dependencies: [
    // [...]
    .package(name: "CoreBluetoothMock", 
             url: "https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock.git", 
             .upToNextMajor(from: "x.y")) // Replace x.y with your required version
]

and add it to your target:

targets: [
    // [...]
    .target(
        name: "<Your target name>",
        dependencies: ["CoreBluetoothMock"]),
]

Documentation

The documentation of the library is available here.

Migration from CoreBluetooth

Migration example is available here.
See Pull Request #1 for
step-by-step guide.

[!Note]
The migration example application currently does not use mocks in tests.
For that, check out the Example folder in this repository with nRF Blinky app, which is
using mock peripherals in Unit Tests and UI Tests. See below.

Sample application: nRF Blinky

nRF Blinky is an example app targeted towards newcomer BLE developers, and also demonstrating the use
of Core Bluetooth Mock library. This application controls an LED on an
nRF5DK
and receive notifications whenever the button on the kit is pressed and released.

The mock implementation is used in Unit tests and UI tests.
See AppDelegate.swift where the mock environment is set up and
and UITests.swift and UITests.swift classes.

The mock peripherals are defined in MockPeripherals.swift.

Nordic LED and Button Service

A simplified proprietary service by Nordic Semiconductor, containing two characteristics one to control LED3 and Button1:

Service UUID: 00001523-1212-EFDE-1523-785FEABCD123
- First characteristic controls the LED state (On/Off).
  - UUID: 00001525-1212-EFDE-1523-785FEABCD123
  - Value: 1 => LED On
  - Value: 0 => LED Off
- Second characteristic notifies central of the button state on change (Pressed/Released).
  - UUID: 00001524-1212-EFDE-1523-785FEABCD123
  - Value: 1 => Button Pressed
  - Value: 0 => Button Released
For full specification, check out
documentation.

Requirements

An iOS device with BLE capabilities, or a simulator (to run the mock).
A Development Kit (unless testing mock).
The Blinky example firmware to flash on the Development Kit. For your convenience, we have bundled two firmwares in this project under the Firmwares directory.
To get the latest firmwares and check the source code, you may go directly to our Developers website and download the SDK version you need, then you can find the source code and hex files to the blinky demo in the directory /examples/ble_peripheral/ble_app_blinky/
The LBS (LED Button Service) is also supported in nRF Connect SDK: here.
More information about the nRFBlinky example firmware can be found in the documentation.

Installation and usage

Prepare your Development kit.
- Plug in the Development Kit to your computer via USB.
- Power On the Development Kit.
- The Development Kit will now appear as a Mass storage device.
- Drag (or copy/paste) the appropriate HEX file onto that new device.
- The Development Kit LEDs will flash and it will disconnect and reconnect.
- The Development Kit is now ready and flashed with the nRFBlinky example firmware.
Start Xcode and run build the project against your target iOS Device (Note: BLE is not available in the iOS simulator, so the iOS device is a requirement to test with real hardware).
- Launch the nRF Blinky app on your iOS device.
- The app will start scanning for nearby peripherals.
- Select the Nordic_Blinky peripheral that appears on screen (Note: if the peripheral does not show up, ensure that it’s powered on and functional).
- Your iOS device will now connect to the peripheral and state is displayed on the screen.
- Changing the value of the Toggle switch will turn LED 3 on or off.
- Pressing Button 1 on the Development Kit will show the button state as Pressed on the app.
- Releasing Button 1 will show the state as Released on the App.

Xcode 15 dropped support for iOS 9.0 and tvOS 9.0 in simulator. Now the minimum supported version is 12.0 for both platforms. ↩︎ ↩︎