Bluejay

public class Bluejay : NSObject

Bluejay is a simple wrapper around CoreBluetooth that focuses on making a common usage case as straight forward as possible: a single connected peripheral that the user is interacting with regularly (think most personal electronics devices that have an associated iOS app: fitness trackers, guitar amps, etc).

It also supports a few other niceties for simplifying usage, including automatic discovery of services and characteristics as they are used, as well as supporting a background task mode where the interaction with the device can be written as synchronous calls running on a background thread to avoid callback pyramids of death, or heavily chained promises.

Public Properties

  • Helps distinguish one Bluejay instance from another.

    Declaration

    Swift

    public let uuid: UUID

  • Allows checking whether Bluetooth is powered on. Also returns false if Bluejay is not started yet.

    Declaration

    Swift

    public var isBluetoothAvailable: Bool { get }

  • Allows checking for if CoreBluetooth state is transitional (update is imminent) please re-evaluate the bluetooth state again as it may change momentarily after it has returned true

    Declaration

    Swift

    public var isBluetoothStateUpdateImminent: Bool { get }

  • Allows checking whether Bluejay is currently connecting to a peripheral.

    Declaration

    Swift

    public var isConnecting: Bool { get }

  • Allows checking whether Bluejay is currently connected to a peripheral.

    Declaration

    Swift

    public var isConnected: Bool { get }

  • Allows checking whether Bluejay is currently disconnecting from a peripheral.

    Declaration

    Swift

    private(set) public var isDisconnecting: Bool

  • Allowing checking whether Bluejay will automatic reconnect after an unexpected disconnection. Default is true, and Bluejay will also always set this to true on a successful connection to a peripheral. Conversely, Bluejay will always set this to false after an explicit disconnection request.

    Declaration

    Swift

    private(set) public var shouldAutoReconnect: Bool

  • Allows checking whether Bluejay is currently scanning.

    Declaration

    Swift

    public var isScanning: Bool { get }

  • Allows checking whether Bluejay has started and is available for use.

    Declaration

    Swift

    public var hasStarted: Bool { get }

  • Warning options to use for each new connection if the options are not specified at the creation of those connections.

    Declaration

    Swift

    private(set) public var defaultWarningOptions: WarningOptions

  • Allows checking whether Bluejay has background restoration enabled.

    Declaration

    Swift

    public var isBackgroundRestorationEnabled: Bool { get }

Logging

  • Allow apps that use Bluejay to log alongside of Bluejay’s internal logs.

    Declaration

    Swift

    public func log(_ string: String)

    Parameters

    string

    the message you want to log.

  • Get the current content of the log file.

    Declaration

    Swift

    public func getLogs() -> String?

    Return Value

    The current content of the log file as a String.

  • Clears the log file.

    Declaration

    Swift

    public func clearLogs()

Initialization

  • Initializing a Bluejay instance will not yet initialize the CoreBluetooth stack. An explicit start call after Bluejay is intialized will then initialize the CoreBluetooth stack and is required because in cases where a state resotration is trying to restore a listen on a characteristic, a listen restorer must be available before the CoreBluetooth stack is re-initialized. This two-step startup allows you to prepare and gaurantee the setup of your listen restorer in between the initialization of Bluejay and the initialization of the CoreBluetooth stack.

    Declaration

    Swift

    public override init()

  • Starting Bluejay will initialize the CoreBluetooth stack. Simply initializing a Bluejay instance without calling this function will not initialize the CoreBluetooth stack. An explicit start call is required so that we can also support proper background restoration, where CoreBluetooth must be initialized in the AppDelegate’s application(_:didFinishLaunchingWithOptions:) for both starting an iOS background task and for parsing the restore identifier.

    Declaration

    Swift

    public func start(mode: StartMode = .new(.default))

    Parameters

    mode

    CoreBluetooth initialization modes and options.

  • Stops all operations and clears all states in Bluejay before returning a Core Bluetooth state that can then be used by another library or code outside of Bluejay.

    Warning

    Will crash if Bluejay has not been instantiated properly or if Bluejay is still connecting.

    Declaration

    Swift

    public func stopAndExtractBluetoothState() -> (manager: CBCentralManager, peripheral: CBPeripheral?)

    Return Value

    Returns a CBCentralManager and possibly a CBPeripheral as well if there was one connected at the time of this call.

Cancellation

  • This will cancel the current and all pending operations in the Bluejay queue. It will also disconnect by default after the queue is emptied, but you can cancel everything without disconnecting.

    Declaration

    Swift

    public func cancelEverything(error: Error = BluejayError.cancelled, shouldDisconnect: Bool = true)

    Parameters

    error

    Defaults to a generic cancelled error. Pass in a specific error if you want to deliver a specific error to all of your running and queued tasks.
    shouldDisconnect

    Defaults to true, will not disconnect if set to false, but only matters if Bluejay is actually connected.

Events Registration

  • Register for notifications on Bluetooth connection events and state changes. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func register(connectionObserver: ConnectionObserver)

    Parameters

    connectionObserver

    object interested in receiving Bluejay’s Bluetooth connection related events.

  • Unregister for notifications on Bluetooth connection events and state changes. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func unregister(connectionObserver: ConnectionObserver)

    Parameters

    connectionObserver

    object no longer interested in receiving Bluejay’s connection related events.

  • Register for notifications when readRSSI is called. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func register(rssiObserver: RSSIObserver)

    Parameters

    rssiObserver

    object interested in receiving Bluejay’s readRSSI response.

  • Unregister for notifications when readRSSI is called. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func unregister(rssiObserver: RSSIObserver)

    Parameters

    rssiObserver

    object no longer interested in receiving Bluejay’s readRSSI response.

  • Register for notifications when a connected peripheral’s services change. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func register(serviceObserver: ServiceObserver)

    Parameters

    serviceObserver

    object interested in receiving the connected peripheral’s did modify services event.

  • Unregister for notifications when a connected peripheral’s services change. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func unregister(serviceObserver: ServiceObserver)

    Parameters

    serviceObserver

    object no longer interested in receiving the connected peripheral’s did modify services event.

  • Register for notifications when the log file is updated. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func register(logObserver: LogObserver)

    Parameters

    logObserver

    object interested in receiving log file updates.

  • Unregister for notifications when the log file is updated. Unregistering is not required, Bluejay will unregister for you if the observer is no longer in memory.

    Declaration

    Swift

    public func unregister(logObserver: LogObserver)

    Parameters

    logObserver

    object no longer interested in notifications when the log file is updated.

  • Register a single disconnection handler for giving it a final say on what to do at the end of a disconnection, as well as evaluate and control Bluejay’s auto-reconnect behaviour.

    Declaration

    Swift

    public func registerDisconnectHandler(handler: DisconnectHandler)

    Parameters

    handler

    object interested in becoming Bluejay’s optional but most featureful disconnection handler.

  • Remove any registered disconnection handler.

    Declaration

    Swift

    public func unregisterDisconnectHandler()

Scanning

  • Scan for the peripheral(s) specified.

    Warning

    Setting serviceIdentifiers to nil will result in picking up all available Bluetooth peripherals in the vicinity, but is not recommended by Apple. It may cause battery and cpu issues on prolonged scanning, and it also doesn’t work in the background. If you need to scan for all Bluetooth devices, we recommend making use of the duration parameter to stop the scan after 5 ~ 10 seconds to avoid scanning indefinitely and overloading the hardware.

    Declaration

    Swift

    public func scan(
    duration: TimeInterval = 0,
    allowDuplicates: Bool = false,
    throttleRSSIDelta: Int = 5,
    serviceIdentifiers: [ServiceIdentifier]?,
    discovery: @escaping (ScanDiscovery, [ScanDiscovery]) -> ScanAction,
    expired: ((ScanDiscovery, [ScanDiscovery]) -> ScanAction)? = nil,
    stopped: @escaping ([ScanDiscovery], Error?) -> Void
    )

    Parameters

    duration

    Stops the scan when the duration in seconds is reached. Defaults to zero (indefinite).
    allowDuplicates

    Determines whether a previously scanned peripheral is allowed to be discovered again.
    throttleRSSIDelta

    Throttles discoveries by ignoring insignificant changes to RSSI.
    serviceIdentifiers

    Specifies what visible services the peripherals must have in order to be discovered.
    discovery

    Called whenever a specified peripheral has been discovered.
    expired

    Called whenever a previously discovered peripheral has not been seen again for a while, and Bluejay is predicting that it may no longer be in range. (Only for a scan with allowDuplicates enabled)
    stopped

    Called when the scan is finished and provides an error if there is any.

  • Stops current or queued scan.

    Declaration

    Swift

    public func stopScanning()

Connection

  • Attempt to connect directly to a known peripheral. The call will fail if Bluetooth is not available, or if Bluejay is already connected. Making a connection request while Bluejay is scanning will also cause Bluejay to stop the current scan for you behind the scene prior to fulfilling your connection request.

    Declaration

    Swift

    public func connect(
    _ peripheralIdentifier: PeripheralIdentifier,
    timeout: Timeout = .none,
    warningOptions: WarningOptions? = nil,
    completion: @escaping (ConnectionResult) -> Void)

    Parameters

    peripheralIdentifier

    The peripheral to connect to.
    timeout

    Specify how long the connection time out should be.
    warningOptions

    Optional connection warning options, if not specified, Bluejay’s default will be used.
    completion

    Called when the connection request has ended.

  • Disconnect a connected peripheral or cancel a connecting peripheral.

    Attention

    If you are going to use the completion block, be careful on how you orchestrate and organize multiple disconnection callbacks if you are also using a DisconnectHandler.

    Declaration

    Swift

    public func disconnect(immediate: Bool = false, completion: ((DisconnectionResult) -> Void)? = nil)

    Parameters

    immediate

    If true, the disconnect will not be enqueued and will cancel everything in the queue immediately then disconnect. If false, the disconnect will wait until everything in the queue is finished.
    completion

    Called when the disconnect request is fully completed.

Actions

  • Read from the specified characteristic.

    Declaration

    Swift

    public func read<R: Receivable>(from characteristicIdentifier: CharacteristicIdentifier, completion: @escaping (ReadResult<R>) -> Void)

    Parameters

    characteristicIdentifier

    The characteristic to read from.
    completion

    Called with the result of the attempt to read from the specified characteristic.

  • Write to the specified characteristic.

    Declaration

    Swift

    public func write<S: Sendable>(
    to characteristicIdentifier: CharacteristicIdentifier,
    value: S,
    type: CBCharacteristicWriteType = .withResponse,
    completion: @escaping (WriteResult) -> Void)

    Parameters

    characteristicIdentifier

    The characteristic to write to.
    type

    Write type.
    completion

    Called with the result of the attempt to write to the specified characteristic.

  • Listen for notifications on the specified characteristic.

    Declaration

    Swift

    public func listen<R: Receivable>(
    to characteristicIdentifier: CharacteristicIdentifier,
    multipleListenOption option: MultipleListenOption = .trap,
    completion: @escaping (ReadResult<R>) -> Void)

    Parameters

    characteristicIdentifier

    The characteristic to listen to.
    completion

    Called with the result of the attempt to listen for notifications on the specified characteristic.

  • End listening on the specified characteristic.

    Declaration

    Swift

    public func endListen(to characteristicIdentifier: CharacteristicIdentifier, completion: ((WriteResult) -> Void)? = nil)

    Parameters

    characteristicIdentifier

    The characteristic to stop listening to.
    completion

    Called with the result of the attempt to stop listening to the specified characteristic.

  • Check if a peripheral is listening to a specific characteristic.

    Declaration

    Swift

    public func isListening(to characteristicIdentifier: CharacteristicIdentifier) throws -> Bool

    Parameters

    to

    The characteristic we want to check.

  • Attempts to read the RSSI (signal strength) of the currently connected peripheral.

    Warning

    Will throw if called while a Bluejay background task is running, or if not connected.

    Declaration

    Swift

    public func readRSSI() throws

Background Task

  • One of the three ways to run a background task using a synchronous interface to the Bluetooth peripheral. This is the simplest one as the background task will not return any typed values back to the completion block on finishing the background task, except for thrown errors, and it also doesn’t provide an input for an object that might need thread safe access.

    Warning

    Be careful not to access anything that is not thread safe inside background task.

    Declaration

    Swift

    public func run(
    backgroundTask: @escaping (SynchronizedPeripheral) throws -> Void,
    completionOnMainThread: @escaping (RunResult<Void>) -> Void)

    Parameters

    backgroundTask

    A closure with the jobs to be executed in the background.
    completionOnMainThread

    A closure called on the main thread when the background task has either completed or failed.

  • One of the three ways to run a background task using a synchronous interface to the Bluetooth peripheral. This one allows the background task to potentially return a typed value back to the completion block on finishing the background task successfully.

    Warning

    Be careful not to access anything that is not thread safe inside background task.

    Declaration

    Swift

    public func run<Result>(
    backgroundTask: @escaping (SynchronizedPeripheral) throws -> Result,
    completionOnMainThread: @escaping (RunResult<Result>) -> Void)

    Parameters

    backgroundTask

    A closure with the jobs to be executed in the background.
    completionOnMainThread

    A closure called on the main thread when the background task has either completed or failed.

  • One of the three ways to run a background task using a synchronous interface to the Bluetooth peripheral. This one allows the background task to potentially return a typed value back to the completion block on finishing the background task successfully, as well as supplying an object for thread safe access inside the background task.

    Warning

    Be careful not to access anything that is not thread safe inside background task.

    Declaration

    Swift

    public func run<UserData, Result>(
    userData: UserData,
    backgroundTask: @escaping (SynchronizedPeripheral, UserData) throws -> Result,
    completionOnMainThread: @escaping (RunResult<Result>) -> Void)

    Parameters

    userData

    Any object you wish to have thread safe access inside background task.
    backgroundTask

    A closure with the jobs to be executed in the background.
    completionOnMainThread

    A closure called on the main thread when the background task has either completed or failed.

Helpers

  • A helper function to take an array of Sendables and combine their data together.

    Declaration

    Swift

    public static func combine(sendables: [Sendable]) -> Data

    Parameters

    sendables

    An array of Sendables whose Data should be appended in the order of the given array.

    Return Value

    The resulting data of all the Sendables combined in the order of the passed in array.

CBCentralManagerDelegate

  • Bluejay uses this to figure out whether Bluetooth is available or not.

    • If Bluetooth is available for the first time, start running the queue.
    • If Bluetooth is available for the first time and the app is already connected, then this is a state restoration event. Try listen restoration if possible.
    • If Bluetooth is turned off, cancel everything with the bluetoothUnavailable error and disconnect.
    • Broadcast state changes to observers.

    Declaration

    Swift

    public func centralManagerDidUpdateState(_ central: CBCentralManager)

  • If Core Bluetooth will restore state, update Bluejay’s internal states to match the states of the Core Bluetooth stack by assigning the peripheral to connectingPeripheral or connectedPeripheral, or niling them out, depending on what the restored CBPeripheral state is.

    Declaration

    Swift

    public func centralManager(_ central: CBCentralManager, willRestoreState dict: [String : Any])

  • When connected, update Bluejay’s states by updating the values for connectingPeripheral, connectedPeripheral, and shouldAutoReconnect. Also, make sure to broadcast the event to observers, and notify the queue so that the current operation in-flight can process this event and get a chance to finish.

    Declaration

    Swift

    public func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral)

  • Handle a disconnection event from Core Bluetooth by figuring out what kind of disconnection it is (planned or unplanned), and updating Bluejay’s internal state and sending notifications as appropriate.

    Declaration

    Swift

    public func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?)

  • This mostly happens when either the Bluetooth device or the Core Bluetooth stack somehow only partially completes the negotiation of a connection. For simplicity, Bluejay is currently treating this as a disconnection event, so it can perform all the same clean up logic.

    Declaration

    Swift

    public func centralManager(_ central: CBCentralManager, didFailToConnect peripheral: CBPeripheral, error: Error?)

  • This should only be called when the current operation in the queue is a Scan task.

    Declaration

    Swift

    public func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber)