Skip to content

Latest commit

 

History

History
136 lines (95 loc) · 6.74 KB

README.md

File metadata and controls

136 lines (95 loc) · 6.74 KB
Raw

WLXBluetoothDevice

Carthage compatible ![Gitter](https://badges.gitter.im/Join Chat.svg) CI Status Coverage Status Release License Platform

WLXBluetoothDevice is a library we have developed at Wolox after working in several Bluetooth 4.0 related projects. For those who have used CoreBluetooth before would know that the API is not the most pleasant to use. The CoreBluetooth API is heavily based on delegators that have too much responsibility and its asynchronous nature makes it really easy to end up with spaghetti code.

WLXBluetoothDevice is block-based wrapper of CoreBluetooth that handles most of the boilerplate for you. It was designed with the following goals in mind:

  • Avoid having to deal with complex asynchronous logic spread all over several delegate methods.
  • Reduce the amount of ceremony necessary to start exchanging data between two devices.
  • Handle all the CBCentralManagerDelegate and CBPeripheralDelegate methods internally and expose a block-based API to the user.
  • Implement common uses cases and patterns that are found in most BLE apps.
  • Provide a clean architecture to build maintainable code on top of it.
  • Facilitate automated testing of Bluetooth dependent code.

Here are some of the most relevant features that are included in WLXBluetoothDevice:

  • Connection timeouts
  • Reconnection strategies
  • Block-based API
  • Automatic characteristic discovery
  • NSNotifications for Bluetooth connection and discovery events.
  • Storage service to remember devices.

Usage

To run the example project, clone the repo, and run pod install from the Example directory first. To actually use the example app you need a Bluetooth peripheral that exposes certain characteristics in a certain way. That is why we made a test iOS app that acts as a peripheral in the way the example project expects it. You can clone the test app from here.

NOTE: The example project is currently broken because it uses CocoaPods to install WLXBluetoothDevice. The actual code probably works. This will be fixed in future versions. Check issue #35.

Installation

Carthage

Add the following to your Cartfile:

github "Wolox/WLXBluetoothDevice" ~> 0.6.1

Then run carthage update.

Follow the current instructions in Carthage's README for up to date installation instructions.

You'll also need to add the following frameworks to your Xcode project:

  • CocoaLumberjack.framework

CocoaPods

CocoaPods is not supported yet. This issue is being tracked in #40. Pull requests are welcomed!!!

Reactive extensions

If you like to use ReactiveCocoa there is an extension of WLXBluetoothDevice that adds support for ReactiveCocoa. Check it out here

Documentation

You can check the library's wiki for documentation and examples of how to use different APIs. If there is something missing in the wiki you can ![Gitter](https://badges.gitter.im/Join Chat.svg).

Development

To start developing you just need to run the following commands:

git clone [email protected]:Wolox/WLXBluetoothDevice.git
cd WLXBluetoothDevice
script/bootstrap
open WLXBluetoothDevice.xcodeproj

Scripts

Inside the script folder there are several scripts to facilitate the development process. For up to date documentation of this scripts check this repository. The most relevant scripts are:

  • script/bootstrap: Bootstraps the project for the first time.
  • script/test: Runs the project's tests
  • script/update: Updates the project's dependencies.

About

This project is maintained by Guido Marucci Blas and it was written by Wolox.

Wolox

License

WLXBluetoothDevice is available under the MIT license.

Copyright (c) 2014 Guido Marucci Blas <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.