SwiftyBluetooth
Closures based APIs for CoreBluetooth.
Features
- Replace the delegate based interface with a closure based interface for every
CBCentralManagerandCBPeripheraloperation. - Notification based event for CBCentralManager state changes and state restoration.
- Notification based event for CBPeripheral name updates, characteristic value updates and services updates.
- Precise errors and guaranteed timeout for every Bluetooth operation.
- Will automatically connect to a CBPeripheral and attempt to discover the required BLE services and characteristics required for a read or write operation if necessary.
Usage
The Library has 2 important class:
- The
Centralclass, a Singleton wrapper aroundCBCentralManagerused to scan for peripherals with a closure callback and restore previous sessions. - The
Peripheralclass, a wrapper aroundCBPeripheralused to callCBPeripheralfunctions with closure callbacks.
Below are a couple examples of operations that might be of interest to you.
Scanning for Peripherals
Scan for peripherals by calling scanWithTimeout(...) while passing a timeout in seconds and a callback closure to receive Peripheral result callbacks as well as update on the status of your scan:
// You can pass in nil if you want to discover all Peripherals
SwiftyBluetooth.scanForPeripherals(withServiceUUIDs: nil, timeoutAfter: 15) { scanResult in
switch scanResult {
case .scanStarted:
// The scan started meaning CBCentralManager scanForPeripherals(...) was called
case .scanResult(let peripheral, let advertisementData, let RSSI):
// A peripheral was found, your closure may be called multiple time with a .ScanResult enum case.
// You can save that peripheral for future use, or call some of its functions directly in this closure.
case .scanStopped(let error):
// The scan stopped, an error is passed if the scan stopped unexpectedly
}
}
Note that the callback closure can be called multiple times, but always start and finish with a callback containing a .scanStarted and .scanStopped result respectively. Your callback will be called with a .scanResult for every unique peripheral found during the scan.
Connecting to a peripheral
peripheral.connect { result in
switch result {
case .success:
break // You are now connected to the peripheral
case .failure(let error):
break // An error happened while connecting
}
}
Reading from a peripheral's service's characteristic
If you already know the characteristic and service UUIDs you want to read from, once a peripheral has been found you can read from it right away like this:
peripheral.readValue(ofCharacWithUUID: "2A29", fromServiceWithUUID: "180A") { result in
switch result {
case .success(let data):
break // The data was read and is returned as an NSData instance
case .failure(let error):
break // An error happened while attempting to read the data
}
}
This will connect to the peripheral if necessary and ensure that the characteristic and service needed are discovered before reading from the characteristic matching characteristicUUID. If the charac/service cannot be retrieved you will receive an error specifying which charac/service could not be found.
If you have a reference to a CBCharacteristic, you can read using the characteristic directly:
peripheral.readValue(ofCharac: charac) { result in
switch result {
case .success(let data):
break // The data was read and is returned as a Data instance
case .failure(let error):
break // An error happened while attempting to read the data
}
}
Writing to a Peripheral's service's characteristic
If you already know the characteristic and service UUID you want to write to, once a peripheral has been found, you can write to that characteristic right away like this:
let data = String(0b1010).dataUsingEncoding(NSUTF8StringEncoding)!
peripheral.writeValue(ofCharacWithUUID: "1d5bc11d-e28c-4157-a7be-d8b742a013d8",
fromServiceWithUUID: "4011e369-5981-4dae-b686-619dc656c7ba",
value: data) { result in
switch result {
case .success:
break // The write was succesful.
case .failure(let error):
break // An error happened while writting the data.
}
}
Receiving Characteristic update notifications
Receiving characteristic value updates is done through notifications on the default NotificationCenter. All supported Peripheral notifications are part of the PeripheralEvent enum. Use this enum's raw values as the notification string when registering for notifications:
// First we prepare ourselves to receive update notifications
let peripheral = somePeripheral
NotificationCenter.default.addObserver(forName: Peripheral.PeripheralCharacteristicValueUpdate,
object: peripheral,
queue: nil) { (notification) in
let charac = notification.userInfo!["characteristic"] as! CBCharacteristic
if let error = notification.userInfo?["error"] as? SBError {
// Deal with error
}
}
// We can then set a characteristic's notification value to true and start receiving updates to that characteristic
peripheral.setNotifyValue(toEnabled: true, forCharacWithUUID: "2A29", ofServiceWithUUID: "180A") { (isNotifying, error) in
// If there were no errors, you will now receive Notifications when that characteristic value gets updated.
}
Discovering services
Discover services using the discoverServices(...) function:
peripheral.discoverServices(withUUIDs: nil) { result in
switch result {
case .success(let services):
break // An array containing all the services requested
case .failure(let error):
break // A connection error or an array containing the UUIDs of the services that we're not found
}
}
Like the CBPeripheral discoverServices(...) function, passing nil instead of an array of service UUIDs will discover all of this Peripheral's services.
Discovering characteristics
Discover characteristics using the discoverCharacteristics(...) function. If the service on which you are attempting to discover characteristics from has not been discovered, an attempt will first be made to discover that service for you:
peripheral.discoverCharacteristics(withUUIDs: nil, ofServiceWithUUID: "180A") { result in
// The characteristics discovered or an error if something went wrong.
switch result {
case .success(let services):
break // An array containing all the characs requested.
case .failure(let error):
break // A connection error or an array containing the UUIDs of the charac/services that we're not found.
}
}
Like the CBPeripheral discoverCharacteristics(...) function, passing nil instead of an array of service UUIDs will discover all of this service's characteristics.
State preservation
SwiftyBluetooth is backed by a CBCentralManager singleton wrapper and does not give you direct access to the underlying CBCentralManager.
But, you can still setup the underlying CBCentralManager for state restoration by calling setSharedCentralInstanceWith(restoreIdentifier: ) and use the restoreIdentifier of your choice.
Take note that this method can only be called once and must be called before anything else in the library otherwise the Central sharedInstance will be lazily initiated the first time you access it.
As such, it is recommended to call it in your App Delegate's didFinishLaunchingWithOptions(:)
SwiftyBluetooth.setSharedCentralInstanceWith(restoreIdentifier: "MY_APP_BLUETOOTH_STATE_RESTORE_IDENTIFIER")
Register for state preservation notifications on the default NotificationCenter. Those notifications will contain an array of restored Peripheral.
NotificationCenter.default.addObserver(forName: Central.CentralManagerWillRestoreStateNotification,
object: Central.sharedInstance,
queue: nil) { (notification) in
if let restoredPeripherals = notification.userInfo?["peripherals"] as? [Peripheral] {
}
}
Installation
CocoaPods
Add this to your Podfile:
pod 'SwiftyBluetooth', '~> 2.1.0'
Swift Package Manager
Simply add the library to your xcode project as a "Package Dependency"
Carthage
Add this to your Cartfile
github "jordanebelanger/SwiftyBluetooth"
Requirements
SwiftyBluetooth requires iOS 10.0+
License
SwiftyBluetooth is released under the MIT License.
