Skip to content

RiftValleySoftware/RVS_BlueThoth

Repository files navigation

Icon

RVS_BlueThoth

This is a low-level, native Swift Bluetooth SDK for "Central" (Client) Core Bluetooth (BLE) implementation.

It abstracts some of the more "tedious" aspects of using Core Bluetooth; allowing the app to easily implement a Bluetooth Client functionality.

This is the GitHub repo for this project.

This is the project technical documentation

WHAT PROBLEM DOES THIS SOLVE?

Implementing the Apple Core Bluetooth SDK can be a rather tedious process. For example, discovery of Services, Characteristics, and Descriptors can be intricate and time-consuming. RVS_BlueThoth takes care of that in the "background," allowing you to concentrate on providing a richer experience to the users of your application or SDK.

LOW-LEVEL SDK

RVS_BlueThoth is not really designed to be a direct dependency of an application-layer system (although it is demonstrated that way, in the test harnesses). Rather, it is designed to be the basis for application-specific "Façade" layers, such as OBD adapters, or mesh device drivers.

ULTRA-HIGH QUALITY

The basic philosophy behind RVS_BlueThoth, is that it is a fundamental infrastructure element, and, as such, it needs to be of the highest quality possible. All efforts have been made to ensure that it works flawlessly.

LICENSE

RVS_BlueThoth is 100% open-source, MIT-licensed code.

You are free to use it as you wish, but be aware that we are under no obligation to support the project, and there are NO GUARANTEES as to whether or not it is fit for your purposes.

REQUIREMENTS

External Dependencies

If you are unfamiliar with the SPM, this series may be helpful.

RVS_BlueThoth has one external build dependency: the RVS_Generic_Swift_Toolbox Project (also written and supported by The Great Rift Valley Software Company). If you wish to build the test harnesses, then you also need the RVS_PersistentPrefs Project.

The included XCode workspace has these dependencies already.

Native Swift Only

RVS_BlueThoth is a fully native Swift SDK. It does not interface with Objective-C.

RVS_BlueThoth will work on all of the Apple operating systems (iOS/iPadOS, MacOS, tvOS, and WatchOS). It can be incorporated into projects that target any of these environments.

Static Library

The SPM build is provided as a static library, as opposed to a dynamic framework. RVS_BlueThoth is a fairly "light" codebase, and is likely to be one of the smaller components of any given project. If you prefer a dynamic library, it can be easily changed in the Package.swift file for the project. There are no resource, or non-code components, in the SDK. It is a simple executable codebase.

Will Not Work On A simulator

It should be noted that Core Bluetooth requires use of a device; not a simulator. The library will not work on a simulator, registering a Bluetooth Not Available error.

TESTING

RVS_BlueThoth does not implement unit tests. Instead, it provides four test harness apps; one for each of the supported platforms (iOS/iPadOS, MacOS, tvOS, and WatchOS).

Here is an article that explains the philosophy behind the use of test harnesses.

The Test Harness Apps Are Serious code

Each of the test harness apps is a fully-qualified, "App Store release-ready" application. They act as "Bluetooth sniffer" apps. In fact, the iOS test harness has actually been converted into a released app on the iOS App Store (here is the source code).

They should provide excellent "starting points," when learning to implement the SDK.

IMPLEMENTATION

Installation

As noted previously, you should use the Swift Package Manager (SPM) to import the project into your own project. If you are unsure how to do that, then this article may be quite helpful.

The SSH GitHub URI is git@github.com:RiftValleySoftware/RVS_BlueThoth.git, and the HTTPS GitHub URI is https://github.com/RiftValleySoftware/RVS_BlueThoth.git).

Once you have the package installed, you'll need to import the module into any files that use it, by adding the following to the beginning of the file:

import RVS_BlueThoth

Delegate Required

RVS_BlueThoth implements a Delegate pattern (but implemented more like an Observer).

In order to reduce the complexity of the SDK, we have created a single "bottleneck" delegate protocol, that handles all responses from the SDK.

If you are implementing an application-focused layer over RVS_BlueThoth, then you may want to consider dividing this into Observers or Bindings. That's up to you. In order to use the SDK, you need to have a single delegate that can handle the various callbacks, and dispatch them accordingly.

The delegate is "one-way," like an observer. It receives callbacks from the SDK, and does not respond in any way.

All delegate callbacks are in the main thread.

The delegate needs to be a class (as opposed to a struct), and is weakly referenced from within the SDK (meaning that you need to make sure that it stays around).

Examples of the delegate in the four test harnesses are in the following source files:

Creating An Instance

We start by instantiating the RVS_BlueThoth class:

CGA_AppDelegate.centralManager = RVS_BlueThoth(delegate: self)

This example is from the tvOS Test Harness

Note that we provide the delegate immediately. It is likely to get a callback quickly, indicating that the Bluetooth system is set up, and ready to start scanning for peripherals.

Scanning for Peripherals

Once the Bluetooth system is ready, we can start scanning for Peripherals (also from the tvOS test harness):

centralManager?.scanCriteria = scanCriteria
centralManager?.minimumRSSILevelIndBm = prefs.minimumRSSILevel
centralManager?.discoverOnlyConnectablePeripherals = prefs.discoverOnlyConnectableDevices
centralManager?.allowEmptyNames = prefs.allowEmptyNames
centralManager?.startScanning(duplicateFilteringIsOn: !prefs.continuouslyUpdatePeripherals)

It is possible to set a few properties that control how to deal with discovered Peripherals.

From here, on, it is best to use the API documentation, or the [in-depth technical documentation](the technical documentation).

REPORTING ISSUES

If you have any bugs, feature requests, feedback, etc., please feel free to open a GitHub issue, or contact us directly.