Bluetonium

Bluetooth mapping in Swift

Code Quality Rank: L4

Programming language: Swift

License: MIT License

Tags: Hardware     Bluetooth    

Latest version: v3.0

README

Bluetonium is part of the E-sites iOS Suite.

---

Bluetonium is a Swift Library that makes it easy to communicate with Bluetooth devices.

Features

• [x] 🎲 Services and characteristics mapping
• [x] 👓 Default data transformers
• [x] 🔧 Reading & writing to peripherals
• [x] 🌔 Background mode
• [x] 📻 Scanning and connecting to peripherals
• [x] 🦅 Swift 3 & 4

Requirements

• iOS 8.0+
• Xcode 7.2+

Installation

CocoaPods

Add the following to your Podfile:

pod 'Bluetonium'

Make sure that you are integrating your dependencies using frameworks: add use_frameworks! to your Podfile. Then run pod install.

Carthage

Add the following to your Cartfile:

github "e-sites/Bluetonium"

Run carthage update and follow the steps as described in Carthage's README.

Usage

Get devices

The Manager will handle searching for devices and connecting to them.

import Bluetonium

let manager = Manager()
manager.delegate = self
manager.startScanForDevices()

If a device is found you will get notified by the func manager(_ manager: Manager, didFindDevice device: Device) delegate call. You can also get all found devices in the foundDevices array of your manager.

Connect to a device

Connecting to a device is simple.

manager.connect(with: device)

The device is a device form the foundDevices array.

Create and register a ServiceModel

A ServiceModel subclass will represents a Service, all the properties represent the Characteristics.

This example represents the Battery Service

class BatteryServiceModel: ServiceModel {
    enum Characteristic : String {
        case batteryLevel = "2A19"
    }

    var batteryLevel: UInt8 = 0

    override var serviceUUID:String {
        return "180F"
    }

    override func mapping(_ map: Map) {
        batteryLevel <- map[Characteristic.batteryLevel.rawValue]
    }

}

Register a ServiceModel subclass. Make sure you do this before the device is actually connected.

let batteryServiceModel = BatteryServiceModel()

func manager(_ manager: Manager, willConnectToDevice device: Device) {
    device.register(serviceModel: batteryServiceModel)
}

---

ServiceModel subclass

A ServiceModel subclass will represents a Service, all the properties represent the Characteristics. Interacting with the peripheral is only possible once the characteristic did became available through the func characteristicBecameAvailable(withUUID UUID: String) function.
Or when the serviceReady boolean is set to true.

It's recommended to create a struct containing static properties of the UUID's along with your ServiceModel this way your app doesn't have to hardcode the UUID in different places and prevents errors. (See example: HeartRateServiceModel in project)

Reading

batteryServiceModel.readValue(withUUID: "2A19")

// Or with completion
batteryServiceModel.readValue(withUUID: "2A19") { value in
    print(value)
}

Writing

batteryServiceModel.batteryLevel = 10
batteryServiceModel.writeValue(withUUID: "2A19")

Custom DataTransformers

It is possible that your characteristic has a custom data format or has a data format not yet supported. Then you can create your own custom DataTransformer for that property.

The custom DataTransformer needs to conform to the DataTransformer protocol which has two functions.

class HeartRateDataTransformer: DataTransformer {

    func transform(dataToValue data: Data?) -> MapValue {
        // Used when reading from the characteristic.
        // Transform Data to your property MapValue.
    }

    func transform(valueToData value: MapValue?) -> Data {
        // Used when writing to the characteristic.
        // Transform your property MapValue to Data.
    }

}

To register your custom DataTransform you can add it to the mapping function:

func mapping(_ map: Map) {
    heartRate <- (map["2A37"], HeartRateDataTransformer())
}

Set notifications for a characteristic

The ServiceModel has a function that will let you register for value changes on the peripheral. When you return true for one of you characteristics it will automatically update the property.

func registerNotifyForCharacteristic(withUUID UUID: String) -> Bool

Contributions

Feedback is appreciated and pull requests are always welcome. Let's make this list longer!

License

Bluetonium is released under the MIT license. See LICENSE for details.