e-sites / bluetonium Goto Github PK

Bluetonium is part of the E-sites iOS Suite.

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

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

• iOS 8.0+
• Xcode 7.2+

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.

Add the following to your Cartfile:

github "e-sites/Bluetonium"

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

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.

Connecting to a device is simple.

manager.connect(with: device)

The device is a device form the foundDevices array.

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)
}

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)

batteryServiceModel.readValue(withUUID: "2A19")

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

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

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())
}

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

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

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