Features

BlueCap provides a swift wrapper around CoreBluetooth and much more.

Features

A futures interface replacing protocol implementations.
Connection events for connect, disconnect and timeout.
Service scan timeout.
Characteristic read/write timeout.
A DSL for specification of GATT profiles.
Characteristic profile types encapsulating serialization and deserialization.
Example applications implementing Central and Peripheral.
A full featured extendable Central scanner and Peripheral emulator available in the App Store.
Comprehensive test coverage.

Requirements

iOS 8.0+
Xcode 7.0+

Installation

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 8.0 and verify that the BlueCapKit.xcodeproj iOS Deployment Target is also 8.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.
To enable debug log output select your project target and the Build Settings tab. Under Other Swift Flags and Debug add -D DEBUG.

Getting Started

With BlueCap it is possible to easily implement Central and Peripheral applications, serialize and deserialize messages exchanged with bluetooth devices and define reusable GATT profile definitions. This section will provide a short overview of the BLE model and simple application implementations. Following sections will describe all use cases supported in some detail. Example applications are also available.

BLE Model

Communication in BLE uses the Client-Server model. The Client is called a Central and the server a Peripheral. The Peripheral presents structured data to the Central organized into Services that have Characteristics. This called is a Generic Attribute Table (GATT) Profile. Characteristics contain the data values as well as attributes describing permissions and properties. At a high level Central and Peripheral use cases are,

Central	Peripheral
Scans for Services	Advertises Services
Discovers Services and Characteristics	Supports GATT Profile
Data Read/Write/Notifications	Data Read/Write/Notifications

Simple Central Implementation

A simple Central implementation that scans for Peripherals advertising a TI SensorTag Accelerometer Service, connects on peripheral discovery and then discovers the service characteristics is listed below,

public enum CentralExampleError : Int {
    case PeripheralNotConnected = 1
}

public struct CentralError {
    public static let domain = "Central Example"
    public static let peripheralNotConnected = NSError(domain:domain, code:CentralExampleError.PeripheralNotConnected.rawValue, userInfo:[NSLocalizedDescriptionKey:"Peripheral not connected"])
}
    
let serviceUUID = CBUUID(string:TISensorTag.AccelerometerService.uuid)!
                                
// on power, start scanning. when peripheral is discovered connect and stop scanning
let manager = CentralManager.sharedInstance
let peripheralConnectFuture = manager.powerOn().flatmap {_ -> FutureStream<Peripheral> in
	manager.startScanningForServiceUUIDs([serviceUUID], capacity:10)
}.flatmap {peripheral -> FutureStream<(Peripheral, ConnectionEvent)> in
	manager.stopScanning()
	return peripheral.connect(capacity:10, timeoutRetries:5, disconnectRetries:5)
}

// on .Timeout and .Disconnect try to reconnect on .Giveup terminate connection
peripheralConnectFuture.onSuccess{(peripheral, connectionEvent) in
	switch connectionEvent {
	case .Connect:
		…
	case .Timeout:
		peripheral.reconnect()
	case .Disconnect:
		peripheral.reconnect()
	case .ForceDisconnect:
		…
	case .Failed:
		…
	case .GiveUp:
		peripheral.terminate()
	}
}
                
// discover services and characteristics
let peripheralDiscoveredFuture = peripheralConnectFuture.flatmap {(peripheral, connectionEvent) -> Future<Peripheral> in
	if peripheral.state == .Connected {
		return peripheral.discoverPeripheralServices([serviceUUID])
	} else {
		let promise = Promise<Peripheral>()
		promise.failure(CentralError.peripheralNotConnected)
		return promise.future
	}
}
peripheralDiscoveredFuture.onSuccess {peripheral in
	…
}
peripheralDiscoveredFuture.onFailure {error in
	…
}

Simple Peripheral Implementation

A simple Peripheral application that emulates a TI SensorTag Accelerometer Service with all characteristics and responds to characteristic writes is listed below,

// create service and characteristics using profile definitions
let accelerometerService = MutableService(profile:ConfiguredServiceProfile<TISensorTag.AccelerometerService>())
let accelerometerDataCharacteristic = MutableCharacteristic(profile:RawArrayCharacteristicProfile<TISensorTag.AccelerometerService.Data>())
let accelerometerEnabledCharacteristic = MutableCharacteristic(profile:RawCharacteristicProfile<TISensorTag.AccelerometerService.Enabled>())
let accelerometerUpdatePeriodCharacteristic = MutableCharacteristic(profile:RawCharacteristicProfile<TISensorTag.AccelerometerService.UpdatePeriod>())

// add characteristics to service
accelerometerService.characteristics = [accelerometerDataCharacteristic, accelerometerEnabledCharacteristic, accelerometerUpdatePeriodCharacteristic]

// respond to update period write requests
let accelerometerUpdatePeriodFuture = accelerometerUpdatePeriodCharacteristic.startRespondingToWriteRequests(capacity:2)
accelerometerUpdatePeriodFuture.onSuccess {request in
	if request.value.length > 0 &&  request.value.length <= 8 {
		accelerometerUpdatePeriodCharacteristic.value = request.value
		accelerometerUpdatePeriodCharacteristic.respondToRequest(request, withResult:CBATTError.Success)
	} else {
		accelerometerUpdatePeriodCharacteristic.respondToRequest(request, withResult:CBATTError.InvalidAttributeValueLength)
	}
}

// respond to enabled write requests
let accelerometerEnabledFuture = self.accelerometerEnabledCharacteristic.startRespondingToWriteRequests(capacity:2)
accelerometerEnabledFuture.onSuccess {request in  
	if request.value.length == 1 {
		accelerometerEnabledCharacteristic.value = request.value
		accelerometerEnabledCharacteristic.respondToRequest(request, withResult:CBATTError.Success)
	} else {
		accelerometerEnabledCharacteristic.respondToRequest(request, withResult:CBATTError.InvalidAttributeValueLength)
	}
}

// power on remove all services add service and start advertising
let manager = PeripheralManager.sharedInstance
let startAdvertiseFuture = manager.powerOn().flatmap {_ -> Future<Void> in
	manager.removeAllServices()
}.flatmap {_ -> Future<Void> in
	manager.addService(accelerometerService)
}.flatmap {_ -> Future<Void> in
	manager.startAdvertising(TISensorTag.AccelerometerService.name, uuids:[uuid])
}
startAdvertiseFuture.onSuccess {
	…
}
startAdvertiseFuture.onFailure {error in
	…
}

Usage

BlueCap supports many features that simplify writing Bluetooth LE applications. This section will describe all features in detail and provide code examples.

Serialization/Deserialization: Serialization and deserialization of device messages.

String: String serialization and deserialization.
Deserializable Protocol: Deserialize numeric types.
RawDeserializable Protocol: Deserialize messages with a single value of a single Deserializable type.
RawArrayDeserializable Protocol: Deserialize messages with multiple values of single Deserializable type.
RawPairDeserializable Protocol: Deserialize messages with two values of two different Deserializable types.
RawArrayPairDeserializable Protocol: Deserialize messages with multiple values of two different Deserializable types.

GATT Profile Definition: Define reusable GATT profiles and add profiles to the BlueCap app.

ServiceConfigurable Protocol: Define a service configuration.
CharacteristicConfigurable Protocol: Define a characteristic configuration.
StringDeserializable Protocol: Convert characteristic values to strings.
ConfiguredServiceProfile: Define a service profile.
CharacteristicProfile: Characteristic profile base class.
RawCharacteristicProfile: Define a characteristic profile for messages supporting RawDeserializable.
RawArrayCharacteristicProfile: Define a characteristic profile for messages supporting RawArrayDeserializable.
RawPairCharacteristicProfile: Define a characteristic profile for messages supporting RawPairDeserializable.
RawArrayPairCharacteristicProfile: Define a characteristic profile for messages supporting RawArrayPairDeserializable.
StringCharacteristicProfile: Define a characteristic profile for String messages.
ProfileManager: How the BlueCap app manages GATT profiles.
Add Profile to BlueCap App: Add a GATT profile to the BlueCap app.

CentralManager: The BlueCap CentralManager implementation replaces CBCentralManagerDelegate and CBPeripheralDelegate protocol implementations with a Scala Futures interface using SimpleFutures.

PowerOn/PowerOff: Detect when the bluetooth transceiver is powered on and off.
Service Scanning: Scan for services.
Service Scanning with Timeout: Scan for services with timeout.
Peripheral Advertisements: Access Advertisements of discovered Peripherals.
Peripheral Connection: Connect to discovered Peripherals.
Service and Characteristic Discovery: Discover Services and Characteristics of connected Peripherals.
Characteristic Write: Write a characteristic value to a connected Peripheral.
Characteristic Read: Read a characteristic value from a connected Peripheral.
Characteristic Update Notifications: Subscribe to characteristic value updates on a connected Peripheral.

PeripheralManager: The BlueCap PeripheralManager implementation replaces CBPeripheralManagerDelegate protocol implementations with a Scala Futures interface using SimpleFutures.

PowerOn/PowerOff: Detect when the bluetooth transceiver is powered on and off.
Add Services and Characteristics: Add services and characteristics to a Peripheral application.
Advertising: Advertise a Peripheral application.
Set Characteristic Value: Set a characteristic value for a Peripheral application.
Update Characteristic Value: Send characteristic value update notifications to Centrals.
Respond to Characteristic Write: Respond to characterize value writes from a Central.
iBeacon Emulation: Emulate an iBeacon with a Peripheral application.

Serialization/Deserialization

Serialization and deserialization of device messages requires protocol implementations. Then application objects can be converted to and from NSData objects using methods on Serde. Example implantations of each protocol can be found in the TiSensorTag GATT profile available in BlueCapKit and the following examples are implemented in a BlueCap Playground.

Strings

For Strings Serde serialize and deserialize are defined by,

// Deserialize Strings
public static func deserialize(data:NSData, encoding:NSStringEncoding = NSUTF8StringEncoding) -> String?

// Serialize Strings
public static func serialize(value:String, encoding:NSStringEncoding = NSUTF8StringEncoding) -> NSData?

NSStringEncoding supports many encodings.

to use in an application,

if let data = Serde.serialize("Test") {
    if let value = Serde.deserialize(data) {
        println(value)
    }
}

Deserializable Protocol

The Deserializable protocol is used to define deserialization of numeric objects and is defined by,

public protocol Deserializable {
    static var size : Int {get}
    static func deserialize(data:NSData) -> Self?
    static func deserialize(data:NSData, start:Int) -> Self?
    static func deserialize(data:NSData) -> [Self]
    init?(stringValue:String)
}

Description

size	Size of object in bytes
deserialize(data:NSData) -> Self?	Deserialize entire message to object
deserialize(data:NSData, start:Int) -> Self?	Deserialize message starting at offset to object
deserialize(data:NSData) -> [Self]	Deserialize entire message to array of objects
init?(stringValue:String)	Create object from string

BlueCalKit provides implementation of Deserializable for UInt8, Int8, UInt16 and Int16. The Serde serialize and deserialize are defined by,

// Deserialize objects supporting Deserializable
public static func deserialize<T:Deserializable>(data:NSData) -> T?

// Serialize objects supporting Deserializable
public static func serialize<T:Deserializable>(value:T) -> NSData

For UInt8 data,

let data = Serde.serialize(UInt8(31))
if let value : UInt8 = Serde.deserialize(data) {
    println("\(value)")
}

RawDeserializable Protocol

The RawDeserializable protocol is used to define a message that contains a single value and is defined by,

public protocol RawDeserializable {
    typealias RawType
    static var uuid   : String  {get}
    var rawValue      : RawType {get}
    init?(rawValue:RawType)
}

Description

uuid	Characteristic UUID
rawValue	Characteristic RawType value
init?(rawValue:RawType)	Create object from rawValue

The Serde serialize and deserialize are defined by,

// Deserialize objects supporting RawDeserializable
public static func deserialize<T:RawDeserializable where T.RawType:Deserializable>(data:NSData) -> T?

// Serialize objects supporting RawDeserializable
public static func serialize<T:RawDeserializable>(value:T) -> NSData

Note that RawType is required to be Deserializable to be deserialized. An Enum partially supports RawDeserializable, so,

enum Enabled : UInt8, RawDeserializable {
	case No  = 0
	case Yes = 1
	public static let uuid = "F000AA12-0451-4000-B000-000000000000"
}

and,

let data = Serde.serialize(Enabled.Yes)
if let value : Enabled = Serde.deserialize(data) {
    println("\(value.rawValue)")
}

RawDeserializable can also be implemented in a struct or class.

struct Value : RawDeserializable {
	let rawValue : UInt8
	static let uuid = "F000AA13-0451-4000-B000-000000000000"
	init?(rawValue:UInt8) {
	  self.rawValue = rawValue
	}
}

and,

if let initValue = Value(rawValue:10) {
    let data = Serde.serialize(initValue)
    if let value : Value = Serde.deserialize(data) {
        println(“\(value.rawValue)”)
    }
}

RawArrayDeserializable Protocol

The RawArrayDeserializable protocol is used to define a message that contains multiple values of a single type and is defined by,

public protocol RawArrayDeserializable {
    typealias RawType
    static var uuid   : String    {get}
    static var size   : Int       {get}
    var rawValue      : [RawType] {get}
    init?(rawValue:[RawType])
}

Description

uuid	Characteristic UUID
size	Size of array
rawValue	Characteristic RawType values
init?(rawValue:[RawType])	Create object from rawValues

The Serde serialize and deserialize are defined by,

// Deserialize objects supporting RawArrayDeserializable
public static func deserialize<T:RawArrayDeserializable where T.RawType:Deserializable>(data:NSData) -> T?

// Serialize objects supporting RawArrayDeserializable
public static func serialize<T:RawArrayDeserializable>(value:T) -> NSData

Note that RawType is required to be Deserializable to be deserialized. RawArrayDeserializable can be implemented in a struct or class.

struct RawArrayValue : RawArrayDeserializable {    
    let rawValue : [UInt8]
    static let uuid = "F000AA13-0451-4000-B000-000000000000"
    static let size = 2
    
    init?(rawValue:[UInt8]) {
        if rawValue.count == 2 {
            self.rawValue = rawValue
        } else {
            return nil
        }
    }
}

and,

if let initValue = RawArrayValue(rawValue:[4,10]) {
    let data = Serde.serialize(initValue)
    if let value : RawArrayValue = Serde.deserialize(data) {
        println("\(value.rawValue)")
    }
}

RawPairDeserializable Protocol

The RawPairDeserializable is used to define a message that contains two values of different types and is defined by,

public protocol RawPairDeserializable {
    typealias RawType1
    typealias RawType2
    static var uuid : String   {get}
    var rawValue1   : RawType1 {get}
    var rawValue2   : RawType2 {get}
    init?(rawValue1:RawType1, rawValue2:RawType2)
}

Description

uuid	Characteristic UUID
rawValue1	Characteristic RawType1 value
rawValue2	Characteristic RawType2 value
init?(rawValue1:RawType1, rawValue2:RawType2)	Create object from rawValues

The Serde serialize and deserialize are defined by,

// Deserialize objects supporting RawPairDeserializable
public static func deserialize<T:RawPairDeserializable where T.RawType1:Deserializable, T.RawType2:Deserializable>(data:NSData) -> T?

// Serialize objects supporting RawPairDeserializable
public static func serialize<T:RawPairDeserializable>(value:T) -> NSData

Note that RawType1 and RawType2 are required to be Deserializable to be deserialized. RawPairDeserializable can be implemented in a struct or class.

struct RawPairValue : RawPairDeserializable {
    let rawValue1 : UInt8
    let rawValue2 : Int8
    static let uuid = "F000AA13-0451-4000-B000-000000000000"
    
    init?(rawValue1:UInt8, rawValue2:Int8) {
        self.rawValue1 = rawValue1
        self.rawValue2 = rawValue2
    }
}

and,

if let initValue = RawPairValue(rawValue1:10, rawValue2:-10) {
    let data = Serde.serialize(initValue)
    if let value : RawPairValue = Serde.deserialize(data) {
        println("\(value.rawValue1)")
        println("\(value.rawValue2)")
    }
}

RawArrayPairDeserializable Protocol

The RawArrayPairDeserializable is used to define a message that contains multiple values of two different types and is defined by,

public protocol RawArrayPairDeserializable {
    typealias RawType1
    typealias RawType2
    static var uuid   : String     {get}
    static var size1  : Int        {get}
    static var size2  : Int        {get}
    var rawValue1     : [RawType1] {get}
    var rawValue2     : [RawType2] {get}
    init?(rawValue1:[RawType1], rawValue2:[RawType2])
}

Description

uuid	Characteristic UUID
size1	Size of RawType1 array
size2	Size of RawType2 array
rawValue1	Characteristic RawType1 value
rawValue2	Characteristic RawType2 value
init?(rawValue1:[RawType1], rawValue2:[RawType2])	Create object from rawValues

The Serde serialize and deserialize are defined by,

// Deserialize objects supporting RawPairDeserializable
public static func deserialize<T:RawArrayPairDeserializable where T.RawType1:Deserializable,  T.RawType2:Deserializable>(data:NSData) -> T?

// Deserialize objects supporting RawPairDeserializable
public static func serialize<T:RawArrayPairDeserializable>(value:T) -> NSData

Note that RawType1 and RawType2 are required to be Deserializable to be deserialized. RawArrayPairDeserializable can be implemented in a struct or class.

struct RawArrayPairValue : RawArrayPairDeserializable {
    let rawValue1 : [UInt8]
    let rawValue2 : [Int8]
    static let uuid = "F000AA13-0451-4000-B000-000000000000"
    static let size1 = 2
    static let size2 = 2
    
    init?(rawValue1:[UInt8], rawValue2:[Int8]) {
        if rawValue1.count == 2 && rawValue2.count == 2 {
            self.rawValue1 = rawValue1
            self.rawValue2 = rawValue2
        } else {
            return nil
        }
    }
}

and,

if let initValue = RawArrayPairValue(rawValue1:[10, 100], rawValue2:[-10, -100]) {
    let data = Serde.serialize(initValue)
    if let value : RawArrayPairValue = Serde.deserialize(data) {
        println("\(value.rawValue1)")
        println("\(value.rawValue2)")
    }
}

GATT Profile Definition

GATT profile definitions are required to add support for a device to the BlueCap app but are not required to build a functional application using the framework. Implementing a GATT profile for a device allows the framework to automatically identify and configure Services and Characteristics and provides serialization and deserialization of Characteristic values to and from Strings. The examples in this section are also available in a BlueCap Playground

ServiceConfigurable Protocol

The ServiceConfigurable protocol is used to specify Service configuration and is defined by,

public protocol ServiceConfigurable {
    static var name  : String {get}
    static var uuid  : String {get}
    static var tag   : String {get}
}

Description

name	Service name
uuid	Service UUID
tag	Used to organize services in the BlueCap app profile browser

CharacteristicConfigurable Protocol

The CharacteristicConfigurable is used to specify Characteristic configuration and is defined by,

public protocol CharacteristicConfigurable {
    static var name          : String {get}
    static var uuid          : String {get}
    static var permissions   : CBAttributePermissions {get}
    static var properties    : CBCharacteristicProperties {get}
    static var initialValue  : NSData? {get}
}

Description

name	Characteristic name
uuid	Characteristic UUID
permissions	CBAttributePermissions
properties	CBCharacteristicProperties
initialValue	Characteristic initial value

StringDeserializable Protocol

The StringDeserializable protocol is used to specify conversion of rawValues to Strings and is defined by,

public protocol StringDeserializable {
    static var stringValues : [String] {get}
    var stringValue         : [String:String] {get}
    init?(stringValue:[String:String])
}

Description

stringValues	Used for enums to specify Strings for values but ignored for other types
stringValue	The String values of the rawType
init?(stringValue:[String:String])	Create object from stringValue

ConfiguredServiceProfile

A ConfiguredServiceProfile object encapsulates a service configuration and can be used to instantiate either Service or MutableService objects.

struct AccelerometerService : ServiceConfigurable  {
  static let uuid  = "F000AA10-0451-4000-B000-000000000000"
  static let name  = "TI Accelerometer"
  static let tag   = "TI Sensor Tag"
}

let serviceProfile = ConfiguredServiceProfile<AccelerometerService>()

The CharacteristicProfiles belonging to a ServiceProfile are added using the method,

public func addCharacteristic(characteristicProfile:CharacteristicProfile)

CharacteristicProfile

CharacteristicProfile is the base class for each of the following profile types and is instantiated as the characteristic profile if a profile is not explicitly defined for a discovered Characteristic. In this case, with no String conversions implemented in a GATT Profile definition, a Characteristic will support String conversions to a from hexadecimal Strings.

When defining a GATT profile it is sometimes convenient to specify that something be done after a Characteristic is discovered by a Central.

public func afterDiscovered(capacity:Int?) -> FutureStream<Characteristic>

RawCharacteristicProfile

A RawCharacteristicProfile object encapsulates configuration and String conversions for a Characteristic implementing RawDeserializable. It can be used to instantiate both Characteristic and MutableCharacteristic objects.

enum Enabled : UInt8, RawDeserializable, StringDeserializable, CharacteristicConfigurable {
  case No     = 0
  case Yes    = 1

  // CharacteristicConfigurable
  static let uuid = "F000AA12-0451-4000-B000-000000000000"
  static let name = "Accelerometer Enabled"
  static let properties = CBCharacteristicProperties.Read | CBCharacteristicProperties.Write
  static let permissions = CBAttributePermissions.Readable | CBAttributePermissions.Writeable
  static let initialValue : NSData? = Serde.serialize(Enabled.No.rawValue)
    
  // StringDeserializable
  static let stringValues = ["No", "Yes"]
    
  init?(stringValue:[String:String]) {
    if let value = stringValue[Enabled.name] {
      switch value {
      case "Yes":
        self = Enabled.Yes
      case "No":
        self = Enabled.No
      default:
        return nil
      }
    } else {
      return nil
    }
  }
    
  var stringValue : [String:String] {
    switch self {
      case .No:
        return [Enabled.name:"No"]
      case .Yes:
        return [Enabled.name:"Yes"]
    }
  }
}