BlueCap - iOS蓝牙LE框架

BlueCap - iOS蓝牙LE框架

Features

A futures interface replacing protocol implementations.Timeout for Peripheral connection, Service scan, Service + Characteristic discovery and Characteristic read/write.A DSL for specification of GATT profiles.Characteristic profile types encapsulating serialization and deserialization.Example applications implementing CentralManager and PeripheralManager.A full featured extendable scanner and Peripheral simulator available in the App Store.Thread safe.Comprehensive test coverage.

Requirements

iOS 12.0+Xcode 11.3.1

Installation

CocoaPods

CocoaPods is an Xcode dependency manager. It is installed with the following command,

gem install cocoapods

Requires CocoaPods 1.1+

Add BluCapKit to your to your project Podfile,

platform :ios, '10.0'use_frameworks!target 'Your Target Name' do pod 'BlueCapKit', '~> 0.7'end

To enable DBUG output add this post_install hook to your Podfile

Carthage

Carthage is a decentralized dependency manager for Xcode projects. It can be installed using Homebrew,

brew updatebrew install carthage

To add BlueCapKit to your Cartfile

github "troystribling/BlueCap" ~> 0.7

To download and build BlueCapKit.framework run the command,

carthage update

then add BlueCapKit.framework to your project.

If desired use the --no-build option,

carthage update --no-build

This will only download BlueCapKit. Then follow the steps in Manual to add it to a project.

Manual

Place the BlueCap somewhere in your project directory. You can either copy it or add it as a git submodule.Open the BlueCap project folder and drag BlueCapKit.xcodeproj into the project navigator of your applications Xcode project.Under your Projects Info tab set the iOS Deployment Target to 9.0 and verify that the BlueCapKit.xcodeproj iOS Deployment Target is also 9.0.Under the General tab for your project target add the top BlueCapKit.framework as an Embedded Binary.Under the Build Phases tab add BlueCapKit.framework as a Target Dependency and under Link Binary With Libraries add CoreLocation.framework and CoreBluetooth.framework.

Getting Started

With BlueCap it is possible to easily implement CentralManager and PeripheralManager applications, serialize and deserialize messages exchanged with Bluetooth devices and define reusable GATT profile definitions. The BlueCap asynchronous interface uses Futures instead of the usual block interface or the protocol-delegate pattern. Futures can be chained with the result of the previous passed as input to the next. This simplifies application implementation because the persistence of state between asynchronous calls is eliminated and code will not be distributed over multiple files, which is the case for protocol-delegate, or be deeply nested, which is the case for block interfaces. In this section a brief overview of how an application is constructed will be given. Following sections will describe supported use cases. Example applications are also available.

CentralManager

A simple CentralManager implementation that scans for Peripherals advertising a TiSensorTag Accelerometer Service, connects on peripheral discovery, discovers service and characteristics and subscribes to accelerometer data updates will be described.

All applications begin by calling CentralManager#whenStateChanges.

let manager = CentralManager(options: [CBCentralManagerOptionRestoreIdentifierKey : "us.gnos.BlueCap.central-manager-documentation" as NSString])let stateChangeFuture = manager.whenStateChanges()

To start scanning for Peripherals advertising the TiSensorTag Accelerometer Service follow whenStateChanges() with CentralManager#startScanning and combine the two with the SimpleFutures FutureStream#flatMap combinator. An application error object is also defined,

public enum AppError : Error { case invalidState case resetting case poweredOff case unknown case unlikely}let serviceUUID = CBUUID(string: TISensorTag.AccelerometerService.uuid)let scanFuture = stateChangeFuture.flatMap { [weak manager] state -> FutureStream in guard let manager = manager else { throw AppError.unlikely } switch state { case .poweredOn: return manager.startScanning(forServiceUUIDs: [serviceUUID]) case .poweredOff: throw AppError.poweredOff case .unauthorized, .unsupported: throw AppError.invalidState case .resetting: throw AppError.resetting case .unknown: throw AppError.unknown }}scanFuture.onFailure { [weak manager] error in guard let appError = error as? AppError else { return } switch appError { case .invalidState: break case .resetting: manager?.reset() case .poweredOff: break case .unknown: break }}

Here when .poweredOn is received the scan is started. On all other state changes the appropriate error is thrown and handled in the error handler.

To connect discovered peripherals the scan is followed by Peripheral#connect and combined with FutureStream#flatMap,

var peripheral: Peripheral?let connectionFuture = scanFuture.flatMap { [weak manager] discoveredPeripheral -> FutureStream in manager?.stopScanning() peripheral = discoveredPeripheral return peripheral.connect(connectionTimeout: 10.0)}

Here the scan is also stopped after a peripheral with the desired service UUID is discovered.

The Peripheral Services and Characteristics need to be discovered and the connection errors need to be handled. Service and Characteristic discovery are performed by 'Peripheral#discoverServices' and Service#discoverCharacteristics and more errors are added to AppError.

public enum AppError : Error { case dataCharactertisticNotFound case enabledCharactertisticNotFound case updateCharactertisticNotFound case serviceNotFound case invalidState case resetting case poweredOff case unknown case unlikely}let discoveryFuture = connectionFuture.flatMap { [weak peripheral] () -> Future in guard let peripheral = peripheral else { throw AppError.unlikely } return peripheral.discoverServices([serviceUUID])}.flatMap { [weak peripheral] () -> Future in guard let peripheral = peripheral, let service = peripheral.services(withUUID: serviceUUID)?.first else { throw AppError.serviceNotFound } return service.discoverCharacteristics([dataUUID, enabledUUID, updatePeriodUUID])}discoveryFuture.onFailure { [weak peripheral] error in switch error { case PeripheralError.disconnected: peripheral?.reconnect() case AppError.serviceNotFound: break default: break }}

Here a reconnect attempt is made if the Peripheral is disconnected and the AppError.serviceNotFound error is handled. Finally read and subscribe to the data Characteristic and handle the dataCharactertisticNotFound.

public enum AppError : Error { case dataCharactertisticNotFound case enabledCharactertisticNotFound case updateCharactertisticNotFound case serviceNotFound case invalidState case resetting case poweredOff case unknown}var accelerometerDataCharacteristic: Characteristic?let subscriptionFuture = discoveryFuture.flatMap { [weak peripheral] () -> Future in guard let peripheral = peripheral, let service = peripheral.services(withUUID: serviceUUID)?.first else { throw AppError.serviceNotFound } guard let dataCharacteristic = service.service.characteristics(withUUID: dataUUID)?.first else { throw AppError.dataCharactertisticNotFound } accelerometerDataCharacteristic = dataCharacteristic return dataCharacteristic.read(timeout: 10.0)}.flatMap { [weak accelerometerDataCharacteristic] () -> Future in guard let accelerometerDataCharacteristic = accelerometerDataCharacteristic else { throw AppError.dataCharactertisticNotFound } return accelerometerDataCharacteristic.startNotifying()}.flatMap { [weak accelerometerDataCharacteristic] () -> FutureStream in guard let accelerometerDataCharacteristic = accelerometerDataCharacteristic else { throw AppError.dataCharactertisticNotFound } return accelerometerDataCharacteristic.receiveNotificationUpdates(capacity: 10)}dataUpdateFuture.onFailure { [weak peripheral] error in switch error { case PeripheralError.disconnected: peripheral?.reconnect() case AppError.serviceNotFound: break case AppError.dataCharactertisticNotFound: break default: break }}

These examples can be written as a single flatMap chain as shown in the CentralManager Example.

PeripheralManager

A simple PeripheralManager application that emulates a TiSensorTag Accelerometer Service supporting all Characteristics will be described. It will advertise the service and respond to characteristic write requests on the writable Characteristics.

First the Characteristics and Service are created and the Characteristics are then added to Service

// create accelerometer servicelet accelerometerService = MutableService(uuid: TISensorTag.AccelerometerService.uuid)// create accelerometer data characteristiclet accelerometerDataCharacteristic = MutableCharacteristic(profile: RawArrayCharacteristicProfile())// create accelerometer enabled characteristiclet accelerometerEnabledCharacteristic = MutableCharacteristic(profile: RawCharacteristicProfile())// create accelerometer update period characteristiclet accelerometerUpdatePeriodCharacteristic = MutableCharacteristic(profile: RawCharacteristicProfile())// add characteristics to serviceaccelerometerService.characteristics = [accelerometerDataCharacteristic, accelerometerEnabledCharacteristic, accelerometerUpdatePeriodCharacteristic]

Next create the PeripheralManager add the Service and start advertising.

enum AppError: Error { case invalidState case resetting case poweredOff case unsupported case unlikely}let manager = PeripheralManager(options: [CBPeripheralManagerOptionRestoreIdentifierKey : "us.gnos.BlueCap.peripheral-manager-documentation" as NSString])let startAdvertiseFuture = manager.whenStateChanges().flatMap { [weak manager] state -> Future in guard let manager = manager else { throw AppError.unlikely } switch state { case .poweredOn: manager.removeAllServices() return manager.add(self.accelerometerService) case .poweredOff: throw AppError.poweredOff case .unauthorized, .unknown: throw AppError.invalidState case .unsupported: throw AppError.unsupported case .resetting: throw AppError.resetting }}.flatMap { [weak manager] _ -> Future in guard let manager = manager else { throw AppError.unlikely } manager.startAdvertising(TISensorTag.AccelerometerService.name, uuids:[CBUUID(string: TISensorTag.AccelerometerService.uuid)])}startAdvertiseFuture.onFailure { [weak manager] error in switch error { case AppError.poweredOff: manager?.reset() case AppError.resetting: manager?.reset() default: break } manager?.stopAdvertising()}

Now respond to write events on accelerometerEnabledFuture and accelerometerUpdatePeriodFuture.

// respond to Update Period write requestslet accelerometerUpdatePeriodFuture = startAdvertiseFuture.flatMap { accelerometerUpdatePeriodCharacteristic.startRespondingToWriteRequests()}accelerometerUpdatePeriodFuture.onSuccess { [weak accelerometerUpdatePeriodCharacteristic] (request, _) in guard let accelerometerUpdatePeriodCharacteristic = accelerometerUpdatePeriodCharacteristic else { throw AppError.unlikely } guard let value = request.value, value.count > 0 && value.count <= 8 else { return } accelerometerUpdatePeriodCharacteristic.value = value accelerometerUpdatePeriodCharacteristic.respondToRequest(request, withResult:CBATTError.success)}// respond to Enabled write requestslet accelerometerEnabledFuture = startAdvertiseFuture.flatMap { accelerometerEnabledCharacteristic.startRespondingToWriteRequests(capacity: 2)}accelerometerEnabledFuture.onSuccess { [weak accelerometerUpdatePeriodCharacteristic] (request, _) in guard let accelerometerEnabledCharacteristic = accelerometerEnabledCharacteristic else { throw AppError.unlikely } guard let value = request.value, value.count == 1 else { return } accelerometerEnabledCharacteristic.value = request.value accelerometerEnabledCharacteristic.respondToRequest(request, withResult:CBATTError.success)}

See PeripheralManager Example for details.

Test Cases

Test Cases are available. To run type,

pod install

and run from test tab in generated workspace.

Examples

Examples are available that implement both CentralManager and PeripheralManager. The BluCap app is also available. The example projects are constructed using either CocoaPods or Carthage. The CocaPods projects require installing the Pod before building,

pod install

and Carthage projects require,

carthage update

Documentation

BlueCap supports many features that simplify writing Bluetooth LE applications. Use cases with example implementations are described in each of the following sections.

CentralManager: The BlueCap CentralManager implementation replaces CBCentralManagerDelegate and CBPeripheralDelegate protocol implementations with a Scala Futures interface using SimpleFutures. PeripheralManager: The BlueCap PeripheralManager implementation replaces CBPeripheralManagerDelegate protocol implementations with a Scala Futures interface using SimpleFutures. Serialization/Deserialization: Serialization and deserialization of device messages. GATT Profile Definition: Define reusable GATT profiles and add profiles to the BlueCap app.

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。