PLXCoreBluetooth 0.2

Maintained by Maciej Oczko, Polidea, Michał Mizera.

You want to add pod 'PLXCoreBluetooth', '~> 0.2' similar to the following to your Podfile:

target 'MyApp' do
  pod 'PLXCoreBluetooth', '~> 0.2'
end

Then run a pod install inside your terminal, or from CocoaPods.app.

Alternatively to give it a test run, run the command:

pod try PLXCoreBluetooth

PLXCoreBluetooth 0.2

By
Michal Mizera and Maciej Oczko
polidea

PLXCoreBluetooth is a thin abstraction layer over CBCentralManager and CBPeripheral that enables programming using Reactive Cocoa.

Usage

Sample App

Take a look at example app, it illustrates all common usage cases pretty straightforward. To run it, clone the repo, and run pod install from the Example directory first or run pod try PLXCoreBluetooth.

Example

Let's try to scan for some peripherals, connect to them, discover characteristics for given services and read them. Easy.

@weakify(self)
[[[[self.centralManager rac_scanForPeripheralsWithServices:@[mySpecialService]
                                                     count:PLXCBCentralManagerScanInfiniteCount
                                                   options:@{CBCentralManagerScanOptionAllowDuplicatesKey : @NO}]
        reduceEach:^id(CBPeripheral *peripheral, NSDictionary<NSString *, id> *advertisementData, NSNumber *RSSI) {
            return peripheral;
        }]
        flattenMap:^RACSignal *(CBPeripheral *peripheral) {
            @strongify(self)
            return [[[self.centralManager
                    rac_connectPeripheral:peripheral options:nil]
                    flattenMap:^RACSignal *(CBPeripheral *_) {
                        return [peripheral rac_discoverCharacteristics:nil forService:mySpecialService];
                    }]
                    flattenMap:^RACSignal *(NSArray<CBCharacteristic *> *characteristics) {
                        return [[[characteristics.rac_sequence signal]
                                flattenMap:^RACSignal *(CBCharacteristic *characteristic) {
                                    return [peripheral rac_readValueForCharacteristic:characteristic];
                                }]
                                collect];
                    }];
        }]

API

There are two sets of extensions, first for CBCentralManager, second for CBPeripheral.

`CBCentralManager`

This is a property that determines whether all methods below should continue only if CBCentralManager is in powered on state. If it's set to YES each of them will be blocking and will wait for powered on state. Otherwise, default behavior is to finish immediately with error.

By default set to NO.

@property(nonatomic, assign) BOOL plx_shouldWaitUntilPoweredOn;

Scanning

Scan method returns signal with first count scanned peripherals info tuples (peripheral, advertisementData, RSSI) for given services. For infinite scan count there should be passed PLXCBCentralManagerScanInfiniteCount.

If scan is limited and all peripherals are discovered stopScan will be called automatically. stopScan will be called as well when signal is disposed.

- (RACSignal *)rac_scanForPeripheralsWithServices:(nullable NSArray<CBUUID *> *)serviceUUIDs
                                            count:(NSInteger)count
                                          options:(nullable NSDictionary<NSString *, id> *)options;

Stop scan method is just a wrapper for stopScan that returns @YES after calling it.

- (RACSignal *)rac_stopScan;

Connecting

Connect method connects to the peripheral and returns it on success. On connection failure it returns error signal.

- (RACSignal *)rac_connectPeripheral:(CBPeripheral *)peripheral
                             options:(nullable NSDictionary<NSString *, id> *)options;

Disconnect method disconnects from the peripheral and returns it on success. On disconnection failure it returns error signal.

- (RACSignal *)rac_disconnectPeripheralConnection:(CBPeripheral *)peripheral;

Misc

There's a signal that is updated whenever power on property changes.

- (RACSignal *)rac_isPoweredOn;

`CBPeripheral`

This is a property that determines whether all methods below should continue only if CBPeripheral is in connected state. If it's set to YES each of them will be blocking and will wait for connected state. Otherwise, default behavior is to finish immediately with error.

By default set to NO.

@property(nonatomic, assign) BOOL plx_shouldWaitUntilConnected;

This property returns most recent name and subscribes for peripheral name changes.

@property(nonatomic, strong, readonly) RACSignal *rac_name;

This method returns signal subscribed for peripheral name changes.

- (RACSignal *)rac_peripheralDidUpdateName;

This method returns signal containing services peripheral that have been changed over time.

- (RACSignal *)rac_peripheralDidModifyServices;

Discovery

Returns an array of discovered services.

- (RACSignal *)rac_discoverServices:(nullable NSArray<CBUUID *> *)serviceUUIDs;

Returns an array of discovered included services for given service.

- (RACSignal *)rac_discoverIncludedServices:(nullable NSArray<CBUUID *> *)includedServiceUUIDs
                                 forService:(CBService *)service;

Returns an array of discovered characteristics for given service.

- (RACSignal *)rac_discoverCharacteristics:(nullable NSArray<CBUUID *> *)characteristicUUIDs
                                forService:(CBService *)service;

Returns an array of discovered descriptors for given characteristic.

- (RACSignal *)rac_discoverDescriptorsForCharacteristic:(CBCharacteristic *)characteristic;

Reading

This method returns RSSI and completes, error signal otherwise.

- (RACSignal *)rac_readRSSI;

Those methods return read value and complete on successful read, error otherwise.

- (RACSignal *)rac_readValueForCharacteristic:(CBCharacteristic *)characteristic;

- (RACSignal *)rac_readValueForDescriptor:(CBDescriptor *)descriptor;

Writing

Those methods return boolean YES and complete on successful write, error otherwise.

- (RACSignal *)rac_writeValue:(NSData *)data
            forCharacteristic:(CBCharacteristic *)characteristic
                    writeType:(CBCharacteristicWriteType)writeType;

- (RACSignal *)rac_writeValue:(NSData *)data
                forDescriptor:(CBDescriptor *)descriptor;

Updating

This method returns boolean YES and completes if change succeeds, or error otherwise.

- (RACSignal *)rac_setNotifyValue:(BOOL)enabled
       forChangesInCharacteristic:(CBCharacteristic *)characteristic;

This method returns updated values (from peripheral:didUpdateValueForCharacteristic:error: callback), or error if update fails.

- (RACSignal *)rac_setNotifyValue:(BOOL)enabled
andGetUpdatesForChangesInCharacteristic:(CBCharacteristic *)characteristic;

This method returns stream of signals with value or error (taken from peripheral:didUpdateValueForCharacteristic:error: callback).

- (RACSignal *)rac_listenForUpdatesForCharacteristic:(nullable CBCharacteristic *)characteristic;

Requirements

iOS 8.0+
Xcode 7.2+

Installation

PLXCoreBluetooth is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "PLXCoreBluetooth"

Authors

Maciej Oczko, [email protected]

Michal Mizera, [email protected]

License

PLXCoreBluetooth is available under the MIT license. See the LICENSE file for more info.