Situm Asset Tracking Library

This library helps you track your assets easily.

Description

With this library you’ll be in control of all your assets in one place. Main functionalities of the library are:

Discover and associate assets with a smartphone

You will be able to associate assets with an smartphone so you can track their location and never loose an asset again.

Register events on tracked assets

You will be able to know when different events happend regarding an asset (for example has entered/left a region, when its battery level goes below a certain level and many more).

Installation

In order to integrate this library in your Xcode project you need to follow these steps.

Manual installation

1.1. Configure dependencies

AssetTracking depends on SitumSDK for iOS version 2.41.1 onwards. Make sure to integrate it before continuing. See how on our developers page.

1.2. Add framework to your application Add AssetTracking framework to Link Binary with Libraries section of the Build Phases panel of your app.

How to use it

The entry point in order to access the whole functionality is AssetTrackingSdk.

How to obtain an Asset Tracker

1.1. Create a Configuration object
```
let configuration = ConfigurationBuilder.build()
```
Main parameters of the configuration object are:

uuids: a list that contains strings. Each string represent a different layout of beacons the AssetTracker will listen to. By default this value is set to 73697475-6d73-6974-756d-736974756d15 which is the layout of Situm Technologies.
powerThreshold: Power value that determines the minimum level of power received by an Asset Tracker in order to consider it as detected. Posible values are HIGH (an asset will be detected when it is very close to the tracker), MEDIUM (an asset will be detected when it is close to the tracker), LOW (an asset will be detected whern it is far from the tracker). An additional value of ANY is included meaning the tracker will not take this parameter into account. Default value is ANY.
lowBatteryThreshold: Int value (%) that represents the battery level of the assets that will be considered as low battery. An alert event will be fired when the battery level of a tracked asset falls below that percentage. Default value is 15. NOTE: this parameter does not affect iOS for now.
lostEventInterval: Int value seconds that determines when a tracked asset will be considered as lost. When the Asset Tracker stops listening for a tracked asset this amount of time it will fire an event. Default value is 10 seconds.

foundEventInterval: Int value in seconds that determines when a tracked asset will be considered as recovered. After a lost event the Asset Tracker can detect a tracked asset again. An event will be fired when this amount of time has elapsed. Default value is 5 seconds.

1.2. Conform to the AssetTrackerListener protocol

Conform and implement to the listener, for example in your ViewController. The Asset Tracker will use this methods to notify different events.

class SampleViewController: UIViewController, AssetTrackerListener {
...

// MARK: AssetTrackerListener
func onStateChanged(state: TrackerState) {
    print("state changed to \(state)")        
}

func onError(error: NSError) {
    print("Error reported: \(error)")
}

func onTrackedAssets(assetGroup: AssetGroup) {
    print("tracking assets: \(assetGroup)")
}

func onUntrackedAsset(asset: Asset) {
    print("untracking asset identified by: \(asset)")
}

func onAssetLost(asset: Asset) {
    print("lost asset: \(asset)")
}

func onAssetRecovered(asset: Asset) {
    print("recovered asset: \(asset)")
}

func onFoundAssets(assetGroup: AssetGroup) {
    print("found asset: \(assetGroup)")
}

func onAssetsReport(assetGroup: AssetGroup) {
    print("Asset report: \(assetGroup)")
}
...
}

1.3. Configure the Asset Tracker instance

Before atempting to use the sdk you must configure the Tracker properly. A sample of this can be seen below.

class SampleViewController: UIViewController, AssetTrackerListener {

    override func viewDidLoad() {
        ...
        AssetTrackingSdk.configure(configuration: configuration,listener: self)
        ...
    }
}

You should call this method when the tracker is not working or stopped.

Otherwise changes may not be applied. Following updates on configuration properties must be performed through the method

func updateConfiguration(configuration: Configuration)

1.4. Get the Asset Tracker instance

The AssetTracker instance can be retrieved at any point of your code with the following method of the AssetTrackingSdk class:

let assetTracker = AssetTrackingSdk.getAssetTracker()
assetTracker. ... // Call different methods to access to the provided functionality

From now on you can access all the functionality of the library that is described below.

Requesting Location, necessary step to make Asset Tracker works

As mentioned earlier the Asset Tracker library depends heavily on Situm Sdk.

Before using any of its functionality you need to start getting location updates.

Describing how to start the location system and all its parameters is outside the scope of this project as it can be seen on http://developers.situm.es/pages/mobile/ios/quick_start_guide_swift.html.

However to summarize a simplified process you can do it with:
```
let request: SITLocationRequest = SITLocationRequest.init(buildingId: "") // Include here the identifier of the building
var locationListener = object : LocationListener {
    ... 
    // override listener functions here
}
SitumSdk.locationManager().requestLocationUpdates(request)
```
Remember to stop location system once you no longer need to track assets in order to free resources.

This can be achieved with the following function:
```
SitumSdk.locationManager().removeUpdates() 
```
Searching for assets near you

Usually you want to track assets that are near you.

The first step to achieve this is to search for assets on your surroundings.

This is done with a call to:
```
assetTracker.requestAssetsUpdates()
```
From now on you will be continuosly receiving detected assets on the smartphone’s proximity.

This is achieve by implementing the function of the listener:
```
func onFoundAssets(assetGroup: AssetGroup) {
    // Do something with discovered Assets
}
```
Track an asset

Now that you have a list of nearby Assets you can start tracking them.

This means associate them with the smartphone and start detecting events related to that particular asset.
```
Asset asset = assetGroup.assets[0];
assetTracker.trackAsset(asset.identifier);
```
If tracking the asset succeeds you will receive a callback to the following method confirming that the link has successfully performed.
```
func onTrackedAssets(assetGroup: AssetGroup) {

}
```
From now on you will receive callbacks reporting different scenarios:

  // The asset is on the smartphone's vicinity. Periodic callbacks will be send to report the characteristics of the asset:

    func onAssetsReports(assetGroup: AssetGroup) {

    }

  // The asset has left the smartphone's vicinity

    func onAssetLost(asset: Asset) {

    }

  // The asset has entered again the smartphone's vicinity

    func onAssetRecovered(asset: Asset) {

    }

Untrack an asset

You can always stop tracking an asset. Example usage is:

assetTracker.untrackAsset(asset.identifier)

When successfully untraked object a callback will be send to the following function on AssetTrackerListener:

func onUntrackedAsset(asset: Asset) {
    // Asset has been untracked
}

Removing tracking Updates

At any point you can stop tracking associated assets with a call to the following function:

assetTracker.removeUpdates()

This will stops the tracker and you can expect to no longer receive callbacks.

License

This is a propietary software and all rights belong to Situm Technologies S.L.