BKClient

open class BKClient : NSObject, BKDeviceDiscoveryServiceDelegate, BKDiscoveryBackendResolverDelegate

Main Controller class for discovering BLE modules

BlukiiClient is a single point of contact for all data retieving actions as follows:

  • Discovering BLE modules, extracting BLE advertised data
  • Decryption of blukii SecureBeacon advertising

A. Discover BLE modules and extract their BLE data

To do this you have to do the following steps:

1. Initialize and start discovery

Call initDiscovery() and implement the BKClientDiscoveryDelegate delegates. After initialization is ready (BKClientDiscoveryDelegate.onDiscoveryInitialized()) you can start the discovery.

 var mBlukiiClient: BKClient!

 override func viewDidLoad() {
     ...
     mBlukiiClient = BKController.instance.getDiscoveryClient()
     mBlukiiClient.discoveryDelegate = self
     mBlukiiClient.initDiscovery()
     ...
 }

 func stopDiscovery() {
     mBlukiiClient.stopDiscovery()
 }

 // Discovery Delegate
 func onDiscoveryInitialized() {
     if mBlukiiClient.startDiscovery() {
         // Discovery successfully started
     }
 }

 func onDiscoveryResult(discoveryResultList: [BKDiscoveryData]) {
     // retrieve BLE results
 }

 func onDiscoveryError(errorCode: BKDiscoveryError) {
     // retrieve errors
 }

 func onDiscoveryInfo(infoCode: BKDiscoveryInfo) {
     // retrieve infos and changed states
 }

2. Configure discovery settings

Use the BKDiscoverySettings object for configuring discovery. Get BKClient.discoverySettings to retrieve the settings property set.

 func onInitialized() {
       // Discovery successfully initialized

       let discoverySettings: BKDiscoverySettings = mBlukiiClient.discoverySettings
       discoverySettings.setRssiThreshold(-100)
       discoverySettings.scanDuration = 10000
       ...

       if mBlukiiClient.startDiscovery() {
           // Discovery successfully started
       }
  }

When BLE scanner is started the BLE discovery is acting according to the BKDiscoverySettings:

3. Retrieve results

The callback BKClientDiscoveryDelegate.onDiscoveryResult(_:) will be called after finishing every discovery phase. It retrieves the discovered list of BKOutputElements.

Note: If no BLE modules have been found discoveryResultList is empty (not nil).

 func onDiscoveryResult(discoveryResultList: [BKDiscoveryData]) {
   // Discovery phase has finished: list of OutputElements are retrieved

   for discoveryData in discoveryResultList {
      let id = discoveryData.blukiiId
      let rssi = discoveryData.getRssi()
      ...
   }
 }

4. Retrieve errors and infos

The callbacks BKClientDiscoveryDelegate.onDiscoveryError(_:) and BKClientDiscoveryDelegate.onDiscoveryInfo(_:) will be called if there is important information about the discover process.

 func onDiscoveryError(errorCode: BKDiscoveryError) {
     // An error has been sent from discover
 }

 func onDiscoveryInfo(infoCode: BKDiscoveryInfo) {
     // An info has been sent from discovery
 }

5. Permission

In Info.plist set the following keys for Beacon Detection:

  • NSLocationAlwaysUsageDescription
  • NSBluetoothAlwaysUsageDescription

Add the Follow Capapilities to your Project, for scanning Beacons in Background:

  • Background Mode: Location Updates
  • Background Mode: Uses Bluetooth LE accessoires

B. Decryption of SecureBeacon advertising

blukii SecureBeacons are encrypted to prevent third parties from misusing the Beacon identification.

The encryption is affecting the mac address and the iBeacon Major and Minor value.

You can decrypt DiscoveryData by calling decryptSecureBeacons(discoveryDataList:). To detect a SecureBeacon, you have to set your secureBeacon UUID to BKDiscoverySettings.securebeaconUUID

The delegate BKDecryptSecureBeaconsDelegate.onDecryptSecureBeacons(_:decryptedCount:) is retrieving a copy of the input parameter list containing decrypted values. Each BKDiscoveryData object, that has been decrypted is marked with BKDiscoveryData.secureBeaconState as BKSecureBeaconState.decrypted.

func onDecryptSecureBeacons(_ decryptedDiscoveryDataList: [BKDiscoveryData], decryptedCount: Int) {
   print("BlukiiClient.onDiscoveryResult: DecryptSecureBeacons Successful: Count=" +  decryptedCount)
}

func onDecryptError(_ error: Error) {
   print("BlukiiClient.onDiscoveryResult: DecryptSecureBeacons failed: error=" + error.localizedDescription)
}

Note: SecureBeacons can only be decrypted by its owner, so the corresponding user needs to be logged in (@see BKBlukiiCloud)

Delegates

Settings

Manage Discovery Service

  • Gets the state if BLE scanner is actuallly running.

    Declaration

    Swift

    open func isDiscovering() -> Bool

    Return Value

    true, if BLE scanner is scanning

  • Initializes the discovery service.

    If successful, the delegate BKClientDiscoveryDelegate.onDiscoveryInitialized() is called. Otherwise the delegate BKClientDiscoveryDelegate.onDiscoveryError(_:) is called with an error.

    Note: By calling this function the service instance BKDeviceDiscoveryService is started and binded by the BKClient object. This is required before calling startDiscovery() and stopDiscovery() for starting and stopping the discovery for BLE modules. Without startDiscovery() BKClient is not do any action and therefore not using the battery.

    Note: Use this function only, if the view is loaded. For Example viewDidAppear.

    Declaration

    Swift

    open func initDiscovery()

  • Gets the state if the discovery service is initialized.

    Declaration

    Swift

    open func isDiscoveryInitialized() -> Bool

    Return Value

    true, if discovery service is initialized

  • Starts the BLE scanner.

    It only can be started if the discovery service has been initialized befor by calling initDiscovery()!

    Note: Only when the BLE scanner is started successfully the BKClientDiscoveryDelegate delegates are called if there is any discovery result, error or info.

    You can stop scanning by calling stopDiscovery()

    Declaration

    Swift

    open func startDiscovery() -> Bool

    Return Value

    true, if start is successful.

  • Stops the BLE scanner.

    You can start scanning by calling startDiscovery()

    Declaration

    Swift

    open func stopDiscovery() -> Bool

    Return Value

    true, if stop is successful.

Secure Beacon