RVS_BlueThoth

public class RVS_BlueThoth : NSObject, RVS_SequenceProtocol
extension RVS_BlueThoth: CBCentralManagerDelegate
extension RVS_BlueThoth: CGA_Class_Protocol_UpdateDescriptor

This is the main class that is instantiated in order to implement the Bluetooth subsystem. This acts as a Core Bluetooth Central, and aggregates Peripherals, which, in turn, aggregate Services, which, in turn, aggregate Characteristics, which, in turn, may aggregate Descriptors.

  • This is how many seconds we wait, before declaring a timeout. Default is 5 seconds, but the value can be changed.

    Declaration

    Swift

    private static var _static_timeoutInSeconds: TimeInterval

  • This holds any Services (as Strings) that were specified when scanning started.

    Declaration

    Swift

    internal var scanningServices: [String]

  • This holds the instance of CBCentralManager that is used by this instance.

    Declaration

    Swift

    internal var cbElementInstance: CBCentralManager!

  • The Central Manager Delegate object.

    Declaration

    Swift

    public weak var delegate: CGA_BlueThoth_Delegate?

  • This is used to reference an “owning instance” of this instance, and it should be a CGA_Class_Protocol

    Declaration

    Swift

    public weak var parent: CGA_Class_Protocol?

  • Returns true, if the current state of the Bluetooth system is powered on.

    Declaration

    Swift

    public var isBTAvailable: Bool { get }

  • If true (default), then scanning is done with duplicate filtering on, which reduces the number of times the discovery callback is made.

    Declaration

    Swift

    public var duplicateFilteringIsOn: Bool

  • This Bool will be true, if we only want to discover devices that can be connected. Default is false.

    Declaration

    Swift

    public var discoverOnlyConnectablePeripherals: Bool

  • This Bool will be true, if we will allow devices that don’t broadcast names to be discovered. Default is false.

    Declaration

    Swift

    public var allowEmptyNames: Bool

  • This is a “Minimum RSSI Level” for filtering. If a device is discovered with an RSSI less than this, it is ignored. The Default is -100. It can be changed by the SDK user, for subsequent scans.

    Declaration

    Swift

    public var minimumRSSILevelIndBm: Int

  • This will hold BLE Peripherals, as they are being “loaded.” Once they are “complete,” they go into the main collection, wrapped in our class.

    Declaration

    Swift

    public var stagedBLEPeripherals: [RVS_BlueThoth.DiscoveryData]

  • This will hold BLE Peripherals that have been marked as “ignored.”

    Declaration

    Swift

    public var ignoredBLEPeripherals: [RVS_BlueThoth.DiscoveryData]

  • This will contain any required scan criteria.

    Declaration

    Swift

    public var scanCriteria: ScanCriteria?

  • We aggregate Peripherals.

    Declaration

    Swift

    public typealias Element = CGA_Bluetooth_Peripheral

  • This holds our cached Array of Peripheral instances.

    Declaration

    Swift

    public var sequence_contents: Array<Element>

  • This is the indicator as to whether or not the Bluetooth subsystem is actiively scanning for Peripherals.

    This is read-only. Use the startScanning(withServices:) and stopScanning() methods to change the scanning state.

    Declaration

    Swift

    public var isScanning: Bool { get }

  • This is how many seconds we wait, before declaring a timeout. Default is 5 seconds, but the value can be changed.

    Declaration

    Swift

    public var timeoutInSeconds: TimeInterval { get set }

  • The required init, with a “primed” sequence.

    Declaration

    Swift

    public required init(sequence_contents inSequenceContents: [Element])

    Parameters

    sequence_contents

    The initial value of the Array cache. It should be empty.

Internal Instance Methods

Public Instance Methods

  • Called to report an error.

    Declaration

    Swift

    public func reportError(_ inError: CGA_Errors)

    Parameters

    inError

    The error being reported.

  • This is the init that should always be used.

    Convenience init. This allows “no parameter” inits, and ones that only have the queue and/or the delegate. This will call the delegate’s updateFrom(_:) method, upon starting.

    Declaration

    Swift

    public convenience init(delegate inDelegate: CGA_BlueThoth_Delegate? = nil, scanCriteria inScanCriteria: ScanCriteria? = nil, queue inQueue: DispatchQueue? = nil)

    Parameters

    delegate

    The delegate instance.
    scanCriteria

    If there are particular scan criteria to be applied to the discovery process, they are supplied here. If left alone, it will be nil, and all entities will be searched.
    queue

    The queue to be used for this instance. If not specified, the main thread is used.

  • Asks the Central Manager to start scanning for Peripherals.

    Declaration

    Swift

    @discardableResult
public func startScanning(withServices inWithServices: [String]? = nil, duplicateFilteringIsOn inDuplicateFilteringIsOn: Bool = true) -> Bool

    Parameters

    withServices

    An Array of Strings, with the UUID strings. This is optional, and can be left out, in which case all services will be scanned.
    duplicateFilteringIsOn

    If true, then scans will be made with duplicate filtering, which reduces the number of times the discovery callback is made.

    Return Value

    True, if the scan attempt was made (not a guarantee of success, though). Can be ignored.

  • Asks the Central Manager to start scanning for Peripherals, but reuse any saved filters (as opposed to supplying them).

    Declaration

    Swift

    @discardableResult
public func restartScanning() -> Bool

    Return Value

    True, if the scan attempt was made (not a guarantee of success, though). Can be ignored.

  • Asks the Central Manager to stop scanning for Peripherals.

    Declaration

    Swift

    @discardableResult
public func stopScanning() -> Bool

    Return Value

    True, if the attempt was made (not a guarantee of success, though). Can be ignored.

  • This eliminates all of the stored results, and asks the Bluetooth subsystem to start over from scratch.

    Declaration

    Swift

    public func startOver(_ inScan: Bool? = nil)

    Parameters

    inScan

    OPTIONAL: If true, then the scan will be started afterwards. If false, then the scan will not be started, even if it was scanning. If not provided, then the scanning will restart, if it was previously scanning.

  • This forces disconnects for all Peripherals.

    Declaration

    Swift

    public func disconnectAllPeripherals()

  • Called to initiate a connection (and discovery process) with the peripheral.

    Declaration

    Swift

    @discardableResult
public func connect(_ inPeripheral: DiscoveryData?) -> Bool

    Parameters

    inPeripheral

    The Peripheral (CB) to connect, as the opaque DiscoveryData type.

    Return Value

    True, if the connection attempt was made (not a guarantee of success, though). Can be ignored.

  • Called to terminate a connection with the peripheral.

    Declaration

    Swift

    @discardableResult
public func disconnect(_ inPeripheral: DiscoveryData) -> Bool

    Parameters

    inPeripheral

    The Peripheral (CB) to connect.

    Return Value

    True, if the disconnection attempt was made (not a guarantee of success, though). Can be ignored.

  • This searches the hierarchy, and will return any instance that has an ID that matches the string passed in. This could be a Peripheral, Service, Characteristic or Descriptor. The response will need to be cast.

    Declaration

    Swift

    public func findEntityByUUIDString(_ inUUIDString: String) -> CGA_Class_Protocol?

    Parameters

    inUUIDString

    The String for the UUID for which we are searching.

    Return Value

    Any element in the hierarchy with a UUID that matches the one passed in, or nil.

Internal Instance Methods

ScanCriteria Struct

  • This is the struct that we use to narrow the search criteria for new instances of the CGA_Bluetooth_CentralManager class.

    If you will not be looking for particular Bluetooth instances, then leave the corresponding property nil, or empty.

    All members are String, but these will be converted internally into CBUUIDs.

    These are applied across the board. For example, if you specify a Service, then ALL scans will filter for that Service, and if you specify a Characteristic, then ALL Services, for ALL peripherals, will be scanned for that Characteristic.

    See more

    Declaration

    Swift

    public struct ScanCriteria

AdvertisementData Struct

  • This struct allows us to apply some data interpretation to the advertisement data.

    See more

    Declaration

    Swift

    public struct AdvertisementData

DiscoveryData Class

  • This is a class, as opposed to a struct, because I want to make sure that it is referenced, and not copied.

    See more

    Declaration

    Swift

    public class DiscoveryData

CBCentralManagerDelegate Conformance

  • Called to set up the CB instance. We define this here, so we can break this file out (for purposes of documentation).

    Declaration

    Swift

    internal func setCBInstance(_ inQueue: DispatchQueue?)

    Parameters

    inQueue

    The dispatch queue we’ll be using for this. If nil, then the main thread will be used.

  • This is called when the CentralManager state updates.

    Declaration

    Swift

    public func centralManagerDidUpdateState(_ inCentralManager: CBCentralManager)

    Parameters

    inCentralManager

    The CBCentralManager instance that is calling this.

  • This is called when a BLE device has been discovered.

    Declaration

    Swift

    public func centralManager(_ inCentralManager: CBCentralManager, didDiscover inPeripheral: CBPeripheral, advertisementData inAdvertisementData: [String : Any], rssi inRSSI: NSNumber)

    Parameters

    inCentralManager

    The CBCentralManager instance that is calling this.
    didDiscover

    The CBPeripheral instance that was discovered.
    advertisementData

    The advertisement data that was provided with the discovery.
    rssi

    The signal strength, in DB.

  • This is called when a Bluetooth device has been connected (but no discovery yet).

    Declaration

    Swift

    public func centralManager(_ inCentralManager: CBCentralManager, didConnect inPeripheral: CBPeripheral)

    Parameters

    inCentralManager

    The CBCentralManager instance that is calling this.
    didConnect

    The CBPeripheral instance that was connected.

  • This is called when a Bluetooth device has been disconnected.

    Declaration

    Swift

    public func centralManager(_ inCentralManager: CBCentralManager, didDisconnectPeripheral inPeripheral: CBPeripheral, error inError: Error?)

    Parameters

    inCentralManager

    The CBCentralManager instance that is calling this.
    didDisconnectPeripheral

    The CBPeripheral instance that was connected.
    error

    Any error that occurred. It can (and should) be nil.

  • This is called when a Bluetooth device connection has failed.

    Declaration

    Swift

    public func centralManager(_ inCentralManager: CBCentralManager, didFailToConnect inPeripheral: CBPeripheral, error inError: Error?)

    Parameters

    inCentralManager

    The CBCentralManager instance that is calling this.
    didFailToConnect

    The CBPeripheral instance that was not connected.
    error

    Any error that occurred. It can be nil.

CGA_Class_UpdateDescriptor Conformance

  • This returns the parent Central Manager(Ourself)

    Declaration

    Swift

    public var central: RVS_BlueThoth? { get }

  • This class is the “endpoint” of all errors, so it passes the error back to the delegate.

    Declaration

    Swift

    public func handleError(_ inError: CGA_Errors)
  • id

    The Central Manager does not have a UUID.

    Declaration

    Swift

    public var id: String { get }

  • This is called to inform an instance that a Device changed.

    Declaration

    Swift

    public func updateThisDevice(_ inDevice: CGA_Bluetooth_Peripheral)

    Parameters

    inDevice

    The Peripheral wrapper instance that changed.

  • This is called to inform an instance that a Device is ready for a write.

    Declaration

    Swift

    public func sendDeviceReadyForWrite(_ inDevice: CGA_Bluetooth_Peripheral)

    Parameters

    inDevice

    The Peripheral wrapper instance that is ready for a write.

  • This is called to inform an instance that a Service changed.

    Declaration

    Swift

    public func updateThisService(_ inService: CGA_Bluetooth_Service)

    Parameters

    inService

    The Service wrapper instance that changed.

  • This is called to inform an instance that a Characteristic downstream changed.

    Declaration

    Swift

    public func reportWriteCompleteForThisCharacteristic(_ inCharacteristic: CGA_Bluetooth_Characteristic)

    Parameters

    inCharacteristic

    The Characteristic wrapper instance that reported a write complete.

  • This is called to inform an instance that a Characteristic changed its notification state.

    Declaration

    Swift

    public func updateThisCharacteristicNotificationState(_ inCharacteristic: CGA_Bluetooth_Characteristic)

    Parameters

    inCharacteristic

    The Characteristic wrapper instance that changed.

  • This is called to inform an instance that a Characteristic downstream changed.

    Declaration

    Swift

    public func updateThisCharacteristic(_ inCharacteristic: CGA_Bluetooth_Characteristic)

    Parameters

    inCharacteristic

    The Characteristic wrapper instance that changed.

  • This is called to inform an instance that a Descriptor downstream changed.

    Declaration

    Swift

    public func updateThisDescriptor(_ inDescriptor: CGA_Bluetooth_Descriptor)

    Parameters

    inDescriptor

    The Descriptor wrapper instance that changed.

  • This eliminates all of the stored and staged results.

    Declaration

    Swift

    public func clear()