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.
Swift
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
let nodle = Nodle.sharedInstance
Copied!

start

public fun start(public_key: String)
Immediately starts the Nodle SDK
Parameters
​
public_key
The application public_key created in Step 1
Example:
Swift
1
Nodle().start("ss58:public_key");
Copied!

isStarted

public fun isStarted(): Boolean
Checks if the Nodle SDK is started
Returns
​
boolean
true if the Nodle SDK is started, false otherwise
Example:
Swift
1
let sdkStarted = Nodle().isStarted()
Copied!

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:
Swift
1
let sdkScanning = Nodle().isScanning()
Copied!

stop

public fun stop()
Immediately stops the Nodle SDK
Example:
Swift
1
Nodle().stop();
Copied!

clear

public fun clear()
Clear any configs by Nodle SDK
Example:
Swift
1
Nodle().clear();
Copied!

getVersion

public fun getVersion(): String
Get the version identifier of the Nodle SDK.
Returns
​
String
the current version of the Nodle SDK
Example:
Swift
1
let nodleSdkVersion = Nodle().getVersion();
Copied!

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:
Swift - NodleSDK
Swift - NodleSDKWCB
1
nodle.getEvents { event in
2
// collect the NodleEvent events by chosing a type
3
switch event.type {
4
case .BlePayloadEvent:
5
let payload = event as! NodleBluetoothRecord
6
print("Bluetooth payload available \(payload.device)")
7
break
8
case .BleStartSearching:
9
print("Bluetooth started searching")
10
break
11
case .BleStopSearching:
12
print("Bluetooth stopped searching")
13
break
14
@unknown default:
15
print("Failed to get any event")
16
}
17
}
Copied!
1
nodle.getEvents { event in
2
// collect the NodleEvent events by chosing a type
3
switch event.type {
4
case .BeaconPayloadEvent:
5
let payload = event as! NodleBeaconRecord
6
print("iBeacon payload available \(payload.identifier) major: \(payload.major) minor: \(payload.minor) delivered at \(Date())")
7
break
8
case .BeaconStartSeaching:
9
print("iBeacon started searching \(Date())")
10
break
11
case .BeaconStopSearching:
12
print("iBeacon stop searching \(Date())")
13
break
14
@unknown default:
15
print("Failed to get any event")
16
}
17
}
Copied!
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:
Swift
1
Nodle().registerNodleBackgroundTask()
Copied!

scheduleNodleBackgroundTask

public fun scheduleNodleBackgroundTask()
Schedules the Nodle SDK background task
Example:
Swift
1
Nodle().scheduleNodleBackgroundTask()
Copied!

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:
1
{
2
"ble": {
3
"scan": {
4
"duration-msec": 10000,
5
"interval-msec": 90000,
6
"interval-x-factor": 1
7
}
8
},
9
"dtn": {
10
"use-cellular": false
11
}
12
}
Copied!
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:
Swift
1
import UIKit
2
import SwiftCBOR
3
import SwiftProtobuf
4
import NodleSDK
5
import SQLite
6
import CoreLocation
7
import CoreBluetooth
8
​
9
// load the json config located in your app folder config.json
10
let bundle = Foundation.Bundle(identifier: "io.nodle.apptest.AppTest")
11
12
// path for the file in the project
13
let path = bundle!.path(forResource: "config", ofType: "json")
14
​
15
// or you can manually set the entries, for instance
16
Nodle().config("dtn.use-cellular", false);
17
​
18
// background mode selected - foreground only
19
Nodle().config("cron.ios-bg-mode", 0);
20
​
21
// then proceed to start Nodle
22
Nodle().start()
Copied!