RxBluetoothKit Documentation

RxBluetoothKit provides reactive APIs for both Central and Peripheral modes:

Central Mode

• Observing manager states
• Scanning for peripherals
• Connecting to peripherals
• Discovering services and characteristics
• Reading and writing characteristic values
• Monitoring characteristic value changes
• Opening L2CAP channels
• Convenience helper methods

Peripheral Mode

• Observing manager states
• Advertising
• Observing reads and writes
• Observing subscriptions
• Publishing L2CAP channels

The ExampleApp is built with Catalyst, allowing you to use a Mac as a Central device and an iOS device as a Peripheral (or vice versa) to test BLE connections without needing extra hardware sensors.

Requirements

• Xcode 12.0 or later

Setup Steps

1. Open ExampleApp.xcodeproj in Xcode and wait for Swift Package Manager (SPM) to resolve dependencies.
2. In the Signing & Capabilities tab, set the iOS distribution team to your "personal team".
3. Select the "My Mac" target and run the project.
4. While the Mac target is still running, select an iOS device target and run the project again.
5. You can now observe BLE communication between your Mac and your iOS device.

To integrate RxBluetoothKit using Carthage, add the following line to your Cartfile:

gitHub "Polidea/RxBluetoothKit"

Then, run the following command to build the framework:

carthage update

After the build completes, drag RxBluetoothKit.framework into your Xcode project.

To integrate RxBluetoothKit into your Xcode project using CocoaPods, add the following line to your Podfile:

pod 'RxBluetoothKit'

Then, execute the following command in your terminal:

$ pod install

Follow these steps to verify that a Central device can write data to a Peripheral device:

1. On the iOS device (Peripheral):
   • Select Peripheral mode, then Write.
   • Enter a Service UUID (e.g., AAA1) and a Characteristic UUID (e.g., BBB2).
   • Tap Advertise.
2. On the Mac (Central):
   • Select Central mode, then List.
   • Click the magnifying glass toolbar icon (top-right) to start scanning.
   • Find and tap the peripheral named RxBluetoothKit.
   • Locate the service and characteristic matching the UUIDs entered in step 1.
   • Click Write.
   • Enter a string value and click Write again.
3. Observe: The written value will appear on the iOS device.

Follow these steps to verify that a Central device can receive value updates from a Peripheral device:

1. On the iOS device (Peripheral):
   • Select Peripheral mode, then Update.
   • Enter a Service UUID (e.g., AAA1) and a Characteristic UUID (e.g., BBB2).
   • Tap Advertise.
2. On the Mac (Central):
   • Select Central mode, then Specific.
   • Enter the same Service and Characteristic UUIDs used in step 1.
   • Click Connect.
   • When successful, the Read value label will turn green.
3. Trigger an update:
   • On the iOS device, enter text in the Value field and tap Update.
   • Observe the updated value appearing on the Mac.

RxBluetoothKit allows you to chain BLE operations using RxSwift operators. The following example demonstrates a complete workflow: scanning for a peripheral with a specific service ID, connecting, discovering services and characteristics, and finally reading a characteristic's value.

manager.scanForPeripherals(withServices: [serviceId])
    .take(1)
    .flatMap { $0.peripheral.establishConnection() }
    .flatMap { $0.discoverServices([serviceId]) }
    .flatMap { Observable.from($0) }
    .flatMap { $0.discoverCharacteristics([characteristicId]) }
    .flatMap { Observable.from($0) }
    .flatMap { $0.readValue() }
    .subscribe(onNext: { print("Value: \($0.value)") })

Ensure your environment meets the following requirements:

Operating Systems

• iOS 9.0+
• OSX 10.13+
• watchOS 4.0+
• tvOS 11.0+

Development Tools

• Xcode 11.4+