Peripheral

public class Peripheral

Peripheral is a class implementing ReactiveX API which wraps all Core Bluetooth functions allowing to talk to peripheral like discovering characteristics, services and all of the read/write calls.

  • Intance of CentralManager which is used to the bluetooth communication

    Declaration

    Swift

    public unowned let manager: CentralManager
  • Implementation of peripheral

    Declaration

    Swift

    public let peripheral: CBPeripheral
  • Attaches RxBluetoothKit delegate to CBPeripheral. This method is useful in cases when delegate of CBPeripheral was reassigned outside of RxBluetoothKit library (e.g. CBPeripheral was used in some other library or used in non-reactive way)

    Declaration

    Swift

    public func attach()
  • Value indicating if peripheral is currently in connected state.

    Declaration

    Swift

    public var isConnected: Bool
  • Current state of Peripheral instance described by CBPeripheralState.

    Declaration

    Swift

    public var state: CBPeripheralState

    Return Value

    Current state of Peripheral as CBPeripheralState.

  • Current name of Peripheral instance. Analogous to name of CBPeripheral.

    Declaration

    Swift

    public var name: String?
  • Unique identifier of Peripheral instance. Assigned once peripheral is discovered by the system.

    Declaration

    Swift

    public var identifier: UUID
  • A list of services that have been discovered. Analogous to services of CBPeripheral.

    Declaration

    Swift

    public var services: [Service]?
  • YES if the remote device has space to send a write without response. If this value is NO, the value will be set to YES after the current writes have been flushed, and peripheralIsReadyToSendWriteWithoutResponse: will be called.

    Declaration

    Swift

    public var canSendWriteWithoutResponse: Bool
  • Continuous value indicating if peripheral is in connected state. This is continuous value, which emits .next whenever state change occurs

    Declaration

    Swift

    public func observeConnection() -> Observable<Bool>
  • Establishes connection with a given Peripheral. For more information look into CentralManager.establishConnection(with:options:) because this method calls it directly.

    Declaration

    Swift

    public func establishConnection(options: [String: Any]? = nil) -> Observable<Peripheral>

    Parameters

    options

    Dictionary to customise the behaviour of connection.

    Return Value

    Observable which emits next event after connection is established.

  • Triggers discover of specified services of peripheral. If the servicesUUIDs parameter is nil, all the available services of the peripheral are returned; setting the parameter to nil is considerably slower and is not recommended. If all of the specified services are already discovered - these are returned without doing any underlying Bluetooth operations.

    Declaration

    Swift

    public func discoverServices(_ serviceUUIDs: [CBUUID]?) -> Single<[Service]>

    Parameters

    serviceUUIDs

    An array of CBUUID objects that you are interested in. Here, each CBUUID object represents a UUID that identifies the type of service you want to discover.

    Return Value

    Single that emits next with array of Service instances, once they’re discovered.

  • Function that triggers included services discovery for specified services. Discovery is called after subscribtion to Observable is made. If all of the specified included services are already discovered - these are returned without doing any underlying Bluetooth operations.

    Declaration

    Swift

    public func discoverIncludedServices(_ includedServiceUUIDs: [CBUUID]?, for service: Service) -> Single<[Service]>

    Parameters

    includedServiceUUIDs

    Identifiers of included services that should be discovered. If nil - all of the included services will be discovered. If you’ll pass empty array - none of them will be discovered.

    service

    Service of which included services should be discovered.

    Return Value

    Single that emits next with array of Service instances, once they’re discovered.

  • Function that triggers characteristics discovery for specified Services and identifiers. Discovery is called after subscribtion to Observable is made. If all of the specified characteristics are already discovered - these are returned without doing any underlying Bluetooth operations.

    Declaration

    Swift

    public func discoverCharacteristics(_ characteristicUUIDs: [CBUUID]?, for service: Service) -> Single<[Characteristic]>

    Parameters

    characteristicUUIDs

    Identifiers of characteristics that should be discovered. If nil - all of the characteristics will be discovered. If you’ll pass empty array - none of them will be discovered.

    service

    Service of which characteristics should be discovered.

    Return Value

    Single that emits next with array of Characteristic instances, once they’re discovered.

  • Function that allow to observe writes that happened for characteristic.

    Declaration

    Swift

    public func observeWrite(for characteristic: Characteristic? = nil) -> Observable<Characteristic>

    Parameters

    characteristic

    Optional Characteristic of which value changes should be observed. When not specified it will observe for any Characteristic.

    Return Value

    Observable that emits next with Characteristic instance every time when write has happened. It’s infinite stream, so .complete is never called.

  • The maximum amount of data, in bytes, that can be sent to a characteristic in a single write.

    Declaration

    Swift

    public func maximumWriteValueLength(for type: CBCharacteristicWriteType) -> Int

    Parameters

    type

    Type of write operation. Possible values: .withResponse, .withoutResponse

  • Function that triggers write of data to characteristic. Write is called after subscribtion to Observable is made. Behavior of this function strongly depends on CBCharacteristicWriteType, so be sure to check this out before usage of the method.

    Behavior is following:

    • withResponse - Observable emits next with Characteristic instance write was confirmed without any errors. Immediately after that complete is called. If any problem has happened, errors are emitted.
    • withoutResponse - Observable emits next with Characteristic instance once write was called. Immediately after that .complete is called. Result of this call is not checked, so as a user you are not sure if everything completed successfully. Errors are not emitted. It ensures that peripheral is ready to write without response by listening to the proper delegate method

    Declaration

    Swift

    public func writeValue(_ data: Data,
                           for characteristic: Characteristic,
                           type: CBCharacteristicWriteType) -> Single<Characteristic>

    Parameters

    data

    Data that’ll be written to Characteristic instance

    characteristic

    Characteristic instance to write value to.

    type

    Type of write operation. Possible values: .withResponse, .withoutResponse

    Return Value

    Observable that emition depends on CBCharacteristicWriteType passed to the function call.

  • Function that allow to observe value updates for Characteristic instance.

    Declaration

    Swift

    public func observeValueUpdate(for characteristic: Characteristic? = nil) -> Observable<Characteristic>

    Parameters

    characteristic

    Optional Characteristic of which value changes should be observed. When not specified it will observe for any Characteristic.

    Return Value

    Observable that emits next with Characteristic instance every time when value has changed. It’s infinite stream, so .complete is never called.

  • Function that triggers read of current value of the Characteristic instance. Read is called after subscription to Observable is made.

    Declaration

    Swift

    public func readValue(for characteristic: Characteristic) -> Single<Characteristic>

    Parameters

    characteristic

    Characteristic to read value from

    Return Value

    Single which emits next with given characteristic when value is ready to read.

  • Setup characteristic notification in order to receive callbacks when given characteristic has been changed. Returned observable will emit Characteristic on every notification change. It is possible to setup more observables for the same characteristic and the lifecycle of the notification will be shared among them.

    Notification is automaticaly unregistered once this observable is unsubscribed

    This is infinite stream of values.

    Declaration

    Swift

    public func observeValueUpdateAndSetNotification(for characteristic: Characteristic) -> Observable<Characteristic>

    Parameters

    characteristic

    Characteristic for notification setup.

    Return Value

    Observable emitting Characteristic when given characteristic has been changed.

  • Use this function in order to know the exact time, when isNotyfing value has changed on a Characteristic.

    Declaration

    Swift

    public func observeNotifyValue(for characteristic: Characteristic) -> Observable<Characteristic>

    Parameters

    characteristic

    Characteristic which you observe for isNotyfing changes.

    Return Value

    Observable emitting Characteristic when given characteristic has changed it’s isNoytfing value.

  • Function that triggers descriptors discovery for characteristic If all of the descriptors are already discovered - these are returned without doing any underlying Bluetooth operations.

    Declaration

    Swift

    public func discoverDescriptors(for characteristic: Characteristic) -> Single<[Descriptor]>

    Parameters

    characteristic

    Characteristic instance for which descriptors should be discovered.

    Return Value

    Single that emits next with array of Descriptor instances, once they’re discovered.

  • Function that allow to observe writes that happened for descriptor.

    Declaration

    Swift

    public func observeWrite(for descriptor: Descriptor? = nil) -> Observable<Descriptor>

    Parameters

    descriptor

    Optional Descriptor of which value changes should be observed. When not specified it will observe for any Descriptor.

    Return Value

    Observable that emits next with Descriptor instance every time when write has happened. It’s infinite stream, so .complete is never called.

  • Function that allow to observe value updates for Descriptor instance.

    Declaration

    Swift

    public func observeValueUpdate(for descriptor: Descriptor? = nil) -> Observable<Descriptor>

    Parameters

    descriptor

    Optional Descriptor of which value changes should be observed. When not specified it will observe for any Descriptor.

    Return Value

    Observable that emits next with Descriptor instance every time when value has changed. It’s infinite stream, so .complete is never called.

  • Function that triggers read of current value of the Descriptor instance. Read is called after subscription to Observable is made.

    Declaration

    Swift

    public func readValue(for descriptor: Descriptor) -> Single<Descriptor>

    Parameters

    descriptor

    Descriptor to read value from

    Return Value

    Single which emits next with given descriptor when value is ready to read.

  • Function that triggers write of data to descriptor. Write is called after subscribtion to Observable is made.

    Declaration

    Swift

    public func writeValue(_ data: Data, for descriptor: Descriptor) -> Single<Descriptor>

    Parameters

    data

    Data that’ll be written to Descriptor instance

    descriptor

    Descriptor instance to write value to.

    Return Value

    Single that emits next with Descriptor instance, once value is written successfully.

  • Function that triggers read of Peripheral RSSI value. Read is called after subscription to Observable is made.

    Declaration

    Swift

    public func readRSSI() -> Single<(Peripheral, Int)>

    Return Value

    Single that emits tuple: (Peripheral, Int) once new RSSI value is read. Int is new RSSI value, Peripheral is returned to allow easier chaining.

  • Function that allow user to observe incoming name property changes of Peripheral instance.

    Declaration

    Swift

    public func observeNameUpdate() -> Observable<(Peripheral, String?)>

    Return Value

    Observable that emits tuples: (Peripheral, String?) when name has changed. It’s optional String because peripheral could also lost his name. It’s infinite stream of values, so .complete is never emitted.

  • Function that allow to observe incoming service modifications for Peripheral instance. In case you’re interested what exact changes might occur - please refer to Apple Documentation

    Declaration

    Swift

    public func observeServicesModification() -> Observable<(Peripheral, [Service])>

    Return Value

    Observable that emits tuples: (Peripheral, [Service]) when services were modified. It’s infinite stream of values, so .complete is never emitted.

  • Resulting observable emits next element if call to writeValue:forCharacteristic:type: has failed, to indicate when peripheral is again ready to send characteristic value updates again.

    Declaration

    Swift

    public func observeWriteWithoutResponseReadiness() -> Observable<Void>
  • Undocumented

    Declaration

    Swift

    public func openL2CAPChannel(PSM: CBL2CAPPSM) -> Single<CBL2CAPChannel>
  • Function used to receive service with given identifier. It’s taken from cache if it’s available, or directly by discoverServices call

    Declaration

    Swift

    public func service(with identifier: ServiceIdentifier) -> Single<Service>

    Parameters

    identifier

    Unique identifier of Service

    Return Value

    Single which emits next event, when specified service has been found.

  • Function used to receive characteristic with given identifier. If it’s available it’s taken from cache. Otherwise - directly by discoverCharacteristics call

    Declaration

    Swift

    public func characteristic(with identifier: CharacteristicIdentifier) -> Single<Characteristic>

    Parameters

    identifier

    Unique identifier of Characteristic, that has information about service which characteristic belongs to.

    Return Value

    Single which emits next event, when specified characteristic has been found.

  • Function used to receive descriptor with given identifier. If it’s available it’s taken from cache. Otherwise - directly by discoverDescriptor call

    Declaration

    Swift

    public func descriptor(with identifier: DescriptorIdentifier) -> Single<Descriptor>

    Parameters

    identifier

    Unique identifier of Descriptor, that has information about characteristic which descriptor belongs to.

    Return Value

    Single which emits next event, when specified descriptor has been found.

  • Function that allow to observe writes that happened for characteristic.

    Declaration

    Swift

    public func observeWrite(for identifier: CharacteristicIdentifier)
        -> Observable<Characteristic>

    Parameters

    identifier

    Identifier of characteristic of which value writes should be observed.

    Return Value

    Observable that emits next with Characteristic instance every time when write has happened. It’s infinite stream, so .complete is never called.

  • Function that triggers write of data to characteristic. Write is called after subscribtion to Observable is made. Behavior of this function strongly depends on CBCharacteristicWriteType, so be sure to check this out before usage of the method.

    • WithResponse - Observable emits next with Characteristic instance write was confirmed without any errors. Immediately after that complete is called. If any problem has happened, errors are emitted.
    • WithoutResponse - Observable emits next with Characteristic instance once write was called. Immediately after that .complete is called. Result of this call is not checked, so as a user you are not sure if everything completed successfully. Errors are not emitted

    Declaration

    Swift

    public func writeValue(_ data: Data, for identifier: CharacteristicIdentifier,
                           type: CBCharacteristicWriteType) -> Single<Characteristic>

    Parameters

    data

    Data that’ll be written written to Characteristic instance

    forCharacteristicWithIdentifier

    unique identifier of characteristic, which also holds information about service characteristic belongs to.

    type

    Type of write operation. Possible values: .withResponse, .withoutResponse

    Return Value

    Observable that emition depends on CBCharacteristicWriteType passed to the function call. Behavior is following:

  • Function that allow to observe value updates for Characteristic instance.

    Declaration

    Swift

    public func observeValueUpdate(for identifier: CharacteristicIdentifier) -> Observable<Characteristic>

    Parameters

    identifier

    unique identifier of characteristic, which also holds information about service that characteristic belongs to.

    Return Value

    Observable that emits next with Characteristic instance every time when value has changed. It’s infinite stream, so .complete is never called.

  • Function that triggers read of current value of the Characteristic instance. Read is called after subscription to Observable is made.

    Declaration

    Swift

    public func readValue(for identifier: CharacteristicIdentifier) -> Single<Characteristic>

    Parameters

    identifier

    unique identifier of characteristic, which also holds information about service that characteristic belongs to.

    Return Value

    Observable which emits next with given characteristic when value is ready to read. Immediately after that .complete is emitted.

  • Setup characteristic notification in order to receive callbacks when given characteristic has been changed. Returned observable will emit Characteristic on every notification change. It is possible to setup more observables for the same characteristic and the lifecycle of the notification will be shared among them.

    Notification is automaticaly unregistered once this observable is unsubscribed

    This is infinite stream of values.

    Declaration

    Swift

    public func observeValueUpdateAndSetNotification(for identifier: CharacteristicIdentifier)
        -> Observable<Characteristic>

    Parameters

    characteristic

    Characteristic for notification setup.

    Return Value

    Observable emitting Characteristic when given characteristic has been changed.

  • Function that triggers descriptors discovery for characteristic

    Declaration

    Swift

    public func discoverDescriptors(for identifier: CharacteristicIdentifier) ->
        Single<[Descriptor]>

    Parameters

    identifier

    unique identifier of descriptor, which also holds information about characteristic that descriptor belongs to.

    Return Value

    Single that emits next with array of Descriptor instances, once they’re discovered.

  • Function that allow to observe writes that happened for descriptor.

    Declaration

    Swift

    public func observeWrite(for identifier: DescriptorIdentifier) -> Observable<Descriptor>

    Parameters

    identifier

    unique identifier of descriptor, which also holds information about characteristic that descriptor belongs to.

    Return Value

    Observable that emits next with Descriptor instance every time when write has happened. It’s infinite stream, so .complete is never called.

  • Function that triggers write of data to descriptor. Write is called after subscribtion to Observable is made.

    Declaration

    Swift

    public func writeValue(_ data: Data, for identifier: DescriptorIdentifier)
        -> Single<Descriptor>

    Parameters

    data

    Data that’ll be written to Descriptor instance

    identifier

    unique identifier of descriptor, which also holds information about characteristic that descriptor belongs to.

    Return Value

    Single that emits next with Descriptor instance, once value is written successfully.

  • Function that allow to observe value updates for Descriptor instance.

    Declaration

    Swift

    public func observeValueUpdate(for identifier: DescriptorIdentifier) -> Observable<Descriptor>

    Parameters

    identifier

    unique identifier of descriptor, which also holds information about characteristic that descriptor belongs to.

    Return Value

    Observable that emits next with Descriptor instance every time when value has changed. It’s infinite stream, so .complete is never called.

  • Function that triggers read of current value of the Descriptor instance. Read is called after subscription to Observable is made.

    Declaration

    Swift

    public func readValue(for identifier: DescriptorIdentifier) -> Single<Descriptor>

    Parameters

    identifier

    Descriptor to read value from

    Return Value

    Observable which emits next with given descriptor when value is ready to read. Immediately after that .complete is emitted.