Swiftpack.co - StarryInternet/CombineCoreBluetooth as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by StarryInternet.
StarryInternet/CombineCoreBluetooth 0.3.0
A wrapper API for CoreBluetooth using Combine Publishers
⭐️ 51
🕓 6 weeks ago
iOS macOS watchOS tvOS
.package(url: "https://github.com/StarryInternet/CombineCoreBluetooth.git", from: "0.3.0")

CombineCoreBluetooth

CI GitHub

CombineCoreBluetooth is a library that bridges Apple's CoreBluetooth framework and Apple's Combine framework, making it possible to subscribe to perform bluetooth operations while subscribing to a publisher of the results of those operations, instead of relying on implementing delegates and manually filtering for the results you need.

Requirements:

  • iOS 13, tvOS 13, macOS 10.15, or watchOS 6
  • Xcode 12 or higher
  • Swift 5.3 or higher

Installation

Swift Package Manager

Add this line to your dependencies list in your Package.swift:

.package(name: "CombineCoreBluetooth", url: "https://github.com/StarryInternet/CombineCoreBluetooth.git", from: "0.3.0"),

Cocoapods

Add this line to your Podfile:

pod 'CombineCoreBluetooth'

Carthage

Add this line to your Cartfile:

github "StarryInternet/CombineCoreBluetooth"

Usage

This library is heavily inspired by pointfree.co's approach to designing dependencies, but with some customizations. Many asynchronous operations returns their own Publisher or expose their own long-lived publisher you can subscribe to.

This library doesn't maintain any additional state beyond what's needed to enable this library to provide a combine-centric API. This means that you are responsible for maintaining any state necessary, including holding onto any Peripherals returned by discovering and connected to via the CentralManager type.

To scan for a peripheral, much like in plain CoreBluetooth, you call the scanForPeripherals(withServices:options:) method. However, on this library's CentralManager type, this returns a publisher of PeripheralDiscovery values. If you want to store a peripheral for later use, you could subscribe to the returned publisher by doing something like this:

let serviceID = CBUUID(string: "0123")

centralManager.scanForPeripherals(withServices: [serviceID])
  .first()
  .assign(to: \.peripheralDiscovery, on: self) // property of type PeripheralDiscovery
  .store(in: &cancellables)

To do something like fetching a value from a characteristic, for instance, you could call the following methods on the Peripheral type and subscribe to the resulting Publisher:

// use whatever ids your peripheral advertises here
let characteristicID = CBUUID(string: "4567")

peripheralDiscovery.peripheral
  .readValue(forCharacteristic: characteristicID, inService: serviceID)
  .sink(receiveCompletion: { completion in
    // handle any potential errors here
  }, receiveValue: { data in
   // handle data from characteristic here, or add more publisher methods to map and transform it.
  })
  .store(in: &cancellables)

The publisher returned in readValue will only send values that match the service and characteristic IDs through to any subscribers, so you don't need to worry about any filtering logic yourself. Note that if the Peripheral never receives a value from this characteristic over bluetooth, it will never send a value into the publisher, so you may want to add a timeout if your use case requires it.

Caveats

All major types from CoreBluetooth should be available in this library, wrapped in their own types to provide the Combine-centric API. This library has been tested in production for most CentralManager related operations. Apps acting as bluetooth peripherals are also supported using the PeripheralManager type, but that side hasn't been as rigorously tested.

As of version 0.2, all write characteristic operations expect a response even if those characteristics are not specified by the peripheral to respond on write completion; this means that the publisher will never complete if you attempt to write to characteristics that don't respond. Until this is changed, you are responsible for managing the lifetime of publishers for writeable characteristics with these properties

GitHub

link
Stars: 51
Last commit: 1 week ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

6 weeks ago

This release makes the following changes:

Behavior changes/fixes:

  • Writes to characteristics that use the .withoutResponse write type will return a publisher that completes immediately, instead of a publisher that waits indefinitely for a response from the peripheral (which will never come when we don't want a response)
  • setNotifyValue's behavior is unified with other publishers: before, calling it would eagerly execute the operation on the underlying CBPeripheral. Now, setNotifyValue is lazy: you need to call the function and subscribe to the publisher in order to execute the operation, bringing the behavior in line with all other publishers returned from Peripheral types.

Internal:

  • Refactored much of the implementation of the live peripheral types to make the publisher chains a bit simpler to read and deal with
  • Added to the workspace a demo application that can behave as a peripheral or a central on any supported platform (with higher min version requirements however), for testing of various bluetooth scenarios (writable characteristics being the first implemented)

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics