Core Bluetooth Mock
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 inundefined 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],
- watchOS 4.0+
[!Note]
For projects running Objective-C we recommend https://github.com/Rightpoint/RZBluetooth library.
[^1]: 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.
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/nordicsemi/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,
- If you have Swift.package file, include the following dependency:
dependencies: [
// [...]
.package(name: "CoreBluetoothMock",
url: "https://github.com/nordicsemi/IOS-CoreBluetooth-Mock.git",
.upToNextMajor(from: "x.y")) // Replace x.y with your required version
]targets: [
// [...]
.target(
name: "<Your target name>",
dependencies: ["CoreBluetoothMock"]),
]Documentation
The documentation of the library is available here.
Migration from CoreBluetooth
We have a couple of examples that show migrations from the platform's CoreBluetooth import to CoreBluetoothMock:
- nRF Connect Device Manager has migrated to aid in UI-level testing as well as being able to run the app in the Simulator. You can find the appropriate Pull Request here.
- CoreBluetooth-Mock-Example is available here. There is also a step-by-step guide available via this Pull Request.
[!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
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.
- 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).
Special Thanks
On behalf of Nordic and all the maintainers of this repo, we'd like to thank all contributors for their contributions.