Nodle SDK - iOS API and Configuration

The SDK receives configuration remotely from Nodle servers as well as statically using API calls. The static configuration always takes precedence over the remote configuration.

Nodle SDK Api

To interact with the SDK you need to call the Nodle.sharedInstance method that will give you an Instance of the INodle class. The following are all the public methods for the Nodle API.

import UIKit
import SwiftCBOR
import SwiftProtobuf
import NodleSDK
import SQLite
import CoreLocation
import CoreBluetooth

let nodle = Nodle.sharedInstance

start

public fun start(public_key: String)

Immediately starts the Nodle SDK

Parameters

public_key

The application public_key created in Step 1

Example:

Nodle().start("ss58:public_key");

isStarted

public fun isStarted(): Boolean

Checks if the Nodle SDK is started

Returns

boolean

true if the Nodle SDK is started, false otherwise

Example:

let sdkStarted = Nodle().isStarted()

isScanning

public fun isScanning(): Boolean

Checks if the Nodle SDK is currently scanning the BLE neighborhood. This is useful if you want to show that the SDK is working.

Returns

boolean

true if the Nodle SDK is scanning, false otherwise

Example:

let sdkScanning = Nodle().isScanning()

stop

public fun stop()

Immediately stops the Nodle SDK

Example:

Nodle().stop();

clear

public fun clear()

Clear any configs by Nodle SDK

Example:

Nodle().clear();

getVersion

public fun getVersion(): String

Get the version identifier of the Nodle SDK.

Returns

String

the current version of the Nodle SDK

Example:

let nodleSdkVersion = Nodle().getVersion();

getEvents

public fun getEvents(): NodleEvent

Get the raw bluetooth events from the Nodle SDK with the following type:

Returns

NodleEventType.BlePayloadEvent

Returns NodleBluetoothScanRecord

NodleEventType.BleStartSearching

Returns NodleBluetoothEvent

NodleEventType.BleStopSearching

Returns NodleBluetoothEvent

NodleEventType.BeaconPayloadEvent

Returns

NodleBeaconRecord

NodleEventType.BeaconStartSearching

Returns

NodleBeaconEvent

NodleEventType.BeaconStopSearching

Returns

NodleBeaconEvent

Example of available return event classes below:

Returns

NodleBluetoothScanRecord

Raw Bluetooth Record from Nodle SDK

NodleBluetoothEvent

Bluetooth Event when the SDK start/stop

NodleBeaconScanRecord

Raw Beacon Record from the Nodle SDK

NodleBeaconEvent

Beacon Event when the SDK start/stop

Example:

nodle.getEvents { event in
    // collect the NodleEvent events by chosing a type
    switch event.type {
        case .BlePayloadEvent:
            let payload = event as! NodleBluetoothRecord
            print("Bluetooth payload available \(payload.device)")
            break
        case .BleStartSearching:
            print("Bluetooth started searching")
            break
        case .BleStopSearching:
            print("Bluetooth stopped searching")
            break
        @unknown default:
            print("Failed to get any event")
    }
}

The following data can be collected from the NodleEventType:

Key

Description

Default Value

type

returns nodle bluetooth event type

NodleEventType

The following data can be collected from the NodleBluetoothScanRecord:

Key

Description

Default Value

device

returns device unique identifier

String

rssi

returns received signal strength indicator

Int

bytes

returns raw bytes of the record

[UInt8]

manufacturerSpecificData

returns the manufacturer specific data associated with the manufacturer id

[Int : [UInt8]]

servicesUuids

returns an array of services UUID's within the advertisement

Array<CBUUID>

The following data can be collected from the NodleBluetoothEvent:

Key

Description

Default Value

scanning

returns bluetooth scanning state

Bool

The following data can be collected from the NodleBeaconScanRecord:

Key

Description

Default Value

identifier

returns device unique identifier

String

major

returns major value of the beacon

NSNumber

minor

returns minor value of the beacon

NSNumber

proximity

returns proximity value of the beacon

Int

accuracy

returns accuracy value of the beacon

Double

rssi

returns received signal strength value of the beacon

Int

The following data can be collected from the NodleBeaconEvent:

Key

Description

Default Value

scanning

returns beacon scanning state

Bool

The table shows rational range for the beacon devices that are found:

Key

Description

Range

proximity

Int

unknown = 0, immediate = 1, near = 2, far = 3

accuracy

Double

unknown 0, 0 - 0.5 immediate, 0.5 - 3 near, 3+ far in meters

rssi

Int

-128|+127

registerNodleBackgroundTask

public fun registerNodleBackgroundTask()

Register the Nodle SDK background task

Example:

Nodle().registerNodleBackgroundTask()

scheduleNodleBackgroundTask

public fun scheduleNodleBackgroundTask()

Schedules the Nodle SDK background task

Example:

Nodle().scheduleNodleBackgroundTask()

config

public fun config(path: Path)

public fun <T> config(key: String, value: T)

configure the SDK either by supplying a json file located in ../config.json or by directly configuring a key. An example of a json configuration look like this:

{
  "ble": {
    "scan": {
      "duration-msec": 10000,
      "interval-msec": 90000,
      "interval-x-factor": 1
    }
  },
  "dtn": {
    "use-cellular": false
  }
}

the following are the table of all the keys available and their description:

Key

Description

Default Value

ble.scan.duration-msec

duration of a single ble pass in milliseconds. Longer scan increase battery consumption but gives more reward.

10000

ble.scan.interval-msec

wait time between two ble pass in milliseconds. Longer period reduce battery consumption but gives less reward

90000

ble.scan.interval-x-factor

multiplier for the ble scan interval above.

1

dtn.use-cellular

if true, the cellular connexion will be used. if false, only wifi connection will be used.

true

cron.ios-bg-mode

If specified, the SDK will run in the specific background mode that it is selected.

2

cron.ios-bg-mode-distance-meters

If specified, the SDK will trigger background scans for Normal mode depending on the meters that are specified with this option.

20

there is another table that will allow you to configure our SDK background modes. There are 4 available modes: NONE, ECO, NORMAL, AGGRESSIVE for the NodleSDK please check them in the table below:

Key

Description

Default Value

NONE

The SDK will run in foreground mode only. You don't need to give allowAlways permissions. WhileInUse is enough for this mode. You may wish to only use Background Tasks for this mode.

0

AGGRESSIVE

The SDK will run in aggressive mode that require all permissions we requested to allowAlways. Then you have to enable Background Modes as well. There is no need to register Background Tasks for this mode. This mode will work even when the phone is with locked screen. This mode will keep the SDK awake without suspending it. Once terminated it won't be able to restore it.

1

NORMAL

The SDK will run in normal mode that require all permissions we requested to allowAlways since it still runs in the background. Then you have to enable Background Modes as well. This mode will be a bit less aggressive than the previous mode. It will trigger when there are location changes. You can change the distance with the config option. You may wish to combine Background Tasks for this mode. This mode will work even when the phone is with locked screen. This mode will be able to awake the SDK after it's fully suspended. Once terminated it won't be able to restore it.

2

ECO

The SDK will run in eco mode that require all permissions we requested to allowAlways since it still runs in the background. Then you have to enable Background Modes as well. This mode will provide a very limited background work. It will trigger really rarely in the background. And when there are location changes. You may wish to combine Background Tasks for this mode. This mode will work even when the phone is with locked screen. This mode will be able to awake the SDK after it's fully suspended and even terminated.

3

Example:

import UIKit
import SwiftCBOR
import SwiftProtobuf
import NodleSDK
import SQLite
import CoreLocation
import CoreBluetooth

// load the json config located in your app folder config.json
let bundle = Foundation.Bundle(identifier: "io.nodle.apptest.AppTest")
        
// path for the file in the project
let path = bundle!.path(forResource: "config", ofType: "json")

// or you can manually set the entries, for instance
Nodle().config("dtn.use-cellular", false);

// background mode selected - foreground only
Nodle().config("cron.ios-bg-mode", 0);

// then proceed to start Nodle
Nodle().start()

Last updated

Was this helpful?