Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/e-sites/bluetonium
Bluetooth mapping in Swift
https://github.com/e-sites/bluetonium
bluetooth bluetooth-low-energy carthage cocoapods ios peripherals swift
Last synced: 2 months ago
JSON representation
Bluetooth mapping in Swift
- Host: GitHub
- URL: https://github.com/e-sites/bluetonium
- Owner: e-sites
- License: mit
- Created: 2016-01-11T07:55:30.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2019-08-13T05:23:11.000Z (over 5 years ago)
- Last Synced: 2024-12-15T02:04:57.906Z (2 months ago)
- Topics: bluetooth, bluetooth-low-energy, carthage, cocoapods, ios, peripherals, swift
- Language: Swift
- Homepage:
- Size: 86.9 KB
- Stars: 165
- Watchers: 16
- Forks: 15
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Bluetonium is part of the **[E-sites iOS Suite](https://github.com/e-sites/iOS-Suite)**.
---
Bluetonium is a Swift Library that makes it easy to communicate with Bluetooth devices.
[](http://forthebadge.com) [](http://forthebadge.com) [](http://forthebadge.com)
[](https://travis-ci.org/e-sites/Bluetonium)
[](https://img.shields.io/cocoapods/v/Bluetonium.svg)
[](https://codecov.io/gh/e-sites/Bluetonium)
[](https://github.com/Carthage/Carthage)
[](http://cocoadocs.org/docsets/Bluetonium)
[](https://cocoapods.org/pods/Bluetonium/quality)
## 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](http://cocoapods.org/)
Add the following to your [Podfile](http://guides.cocoapods.org/using/the-podfile.html):
```rb
pod 'Bluetonium'
```
Make sure that you are integrating your dependencies using frameworks: add `use_frameworks!` to your Podfile. Then run `pod install`.
### [Carthage](https://github.com/Carthage/Carthage)
Add the following to your [Cartfile](https://github.com/Carthage/Carthage/blob/master/Documentation/Artifacts.md#cartfile):
```
github "e-sites/Bluetonium"
```
Run `carthage update` and follow the steps as described in Carthage's [README](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application).
## Usage
### Get devices
The `Manager` will handle searching for devices and connecting to them.
```swift
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.
```swift
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](https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.battery_service.xml)
```swift
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.
```swift
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
```swift
batteryServiceModel.readValue(withUUID: "2A19")
// Or with completion
batteryServiceModel.readValue(withUUID: "2A19") { value in
print(value)
}
```
#### Writing
```swift
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.
```swift
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:
```swift
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.
```swift
func registerNotifyForCharacteristic(withUUID UUID: String) -> Bool
```
## Contributions
Feedback is appreciated and pull requests are always welcome. Let's make [this list](https://github.com/e-sites/Bluetonium/graphs/contributors) longer!
## License
Bluetonium is released under the MIT license. See LICENSE for details.