Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock
Mocking library for CoreBluetooth framework.
https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock
ble bluetooth-low-energy corebluetooth mock mocking-framework nrf5x
Last synced: about 2 months ago
JSON representation
Mocking library for CoreBluetooth framework.
- Host: GitHub
- URL: https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock
- Owner: NordicSemiconductor
- License: bsd-3-clause
- Created: 2020-03-04T08:13:48.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-02-19T19:46:17.000Z (11 months ago)
- Last Synced: 2024-04-14T06:10:42.348Z (9 months ago)
- Topics: ble, bluetooth-low-energy, corebluetooth, mock, mocking-framework, nrf5x
- Language: Swift
- Homepage:
- Size: 3.28 MB
- Stars: 211
- Watchers: 10
- Forks: 47
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome - IOS-CoreBluetooth-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. (OOM-Leaks-Crash / Bluetooth)
README
# Core Bluetooth Mock
[](https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock)
[](https://github.com/Carthage/Carthage)
[](https://swift.org/package-manager)
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](https://developer.apple.com/documentation/corebluetooth) 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],
* 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.
[^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](https://github.com/CocoaPods/CocoaPods), [Carthage](https://github.com/Carthage/Carthage) and
[Swift Package Manager](https://swift.org/package-manager).
CocoaPods
- Create/Update your **Podfile** with the following contents
```ruby
target 'YourAppTargetName' do
pod 'CoreBluetoothMock'
end
```
- Install dependencies
```bash
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
```bash
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](https://github.com/Carthage/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:
```swift
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:
```swift
targets: [
// [...]
.target(
name: "",
dependencies: ["CoreBluetoothMock"]),
]
```
## Documentation
The documentation of the library is available [here](https://nordicsemiconductor.github.io/IOS-CoreBluetooth-Mock/documentation/corebluetoothmock).
## Migration from *CoreBluetooth*
Migration example is available [here](https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock-Example).
See [Pull Request #1](https://github.com/NordicSemiconductor/IOS-CoreBluetooth-Mock-Example/pull/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](https://www.nordicsemi.com/Software-and-Tools/Development-Kits)
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](Example/nRFBlinky/AppDelegate.swift) where the mock environment is set up and
and [UITests.swift](Example/Tests) and [UITests.swift](Example/UI%20Tests/UITests.swift) classes.
The mock peripherals are defined in [MockPeripherals.swift](Example/nRFBlinky/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](https://infocenter.nordicsemi.com/topic/sdk_nrf5_v17.0.2/ble_sdk_app_blinky.html?cp=8_1_4_2_2_3).
### Requirements
- An iOS device with BLE capabilities, or a simulator (to run the mock).
- A [Development Kit](https://www.nordicsemi.com/Software-and-Tools/Development-Kits) (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](http://developer.nordicsemi.com/nRF5_SDK/) 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](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/samples/bluetooth/peripheral_lbs/README.html).
- More information about the nRFBlinky example firmware can be found in the [documentation](https://infocenter.nordicsemi.com/topic/sdk_nrf5_v17.0.2/ble_sdk_app_blinky.html?cp=8_1_4_2_2_3).
### 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.