Observation-Lib

Observation-Lib contains methods that allow you to save features or observations to cloud storage supported by HERE and also retrieve them from this storage after Live Sense SDK detects them. This can be leveraged for real time alerts between vehicles in the vicinity.

Requirements and assumptions

The following list describes assumptions and requirements for this function:

• The customer owns and maintains the cloud storage.
• This library is not available for self service customers. For information on how to contact us for more details, see Help.
• To locate the detected features accurately on any given map, add a geolocation to the feature details.

Usage - data hub

Methods to validate credentials, save and retrieve features from Data Hub.

1. Initialization

Intialize the interface (LSOClient) that is used to call the public methods.

func convenience init(spaceID:String, auth:String)

Parameters:

• spaceID: ID of the space to which client needs to communicate. This is a unique ID provided by Data Hub
• auth: Auth token to authorize the interfacing

Usage:

let observationClient = LSOClient(spaceID:"YOUR SPACE_ID", auth:"YOUR TOKEN")

2. Validate Credentials

Use this method to validate the credentials using spaceId and authToken

func validateCredentials(spaceId: String, authToken:String, output: @escaping (LSOResponseHandler))

Parameters:

• spaceId: SpaceID of the Data hub
• authToken: Token for authorization

Closures:

• output: [String:Any] and LSOError

Usage:

self.observationClient.validateCredentials(spaceId:"YOUR SPACE_ID", authToken:"YOUR TOKEN") { (res, error) in
  // Your code here
}

3. Put Observations

Pushes a list of observations to the Data Hub space.

 func putObservations(_ observation: LSOData, success: @escaping (LSOSuccessHandler), failure: @escaping (LSOFailureHandler))

Parameters:

• observation: LSOData :- Data type that contains a customer ID and that submits a timestamp and list of observation objects. For more information on observation objects, see Usage below.

Closures:

• success: Callback when the data is successfully inserted/updated in storage
• failure: Callback when there is a failure

Usage:

  let obData = LSOData()

  //Create observation object
  let observation = ObservationData()
  observation._id = "12323"
  observation.type = "pedestrian"
  observation.confidence = 0.8
  observation.value = "road-basics"
  observation.timestamp = Date().millisecondsSince1970
  observation.coordinates = [41.882702,-87.619392]

  /**Adding metadata (Optional) **/
  observation.metadata = Metadata()

  /**Add tags (Optional) **/
  observation.tags  = ["test"]

  /**Add custom Payload (Optional) **/
  observation.customPayload = [["Key":"some data"]]

  obData.observations?.append(observation)

  //Publish the detection
  self.observationClient.putObservations(obData, success: {(observations, res) in}) { (error, res) in
     print("Failed \(error.message)")
  }

4. Get Observations

Retrieve observations asynchronously within a specified area centered at given coordinates (latitude, longitude). To filter the observations for a specific date range, you need to specify the range in from and to parameters.`

func getObservations(_ position: CLLocation, to:Int, from:Int,
                    success: @escaping (LSOSuccessHandler),
                    failure: @escaping (LSOFailureHandler))

Parameters:

• position: CLLocation provided by user
• to: End range for observations (optional)
• from: Start range for observations (optional)

Closures:

• success: LSOData and HTTPURLResponse
• failure: LSOError and HTTPURLResponse

Usage:

  let location = CLLocation(latitude:41.881832, longitude: -87.623177)
  self.observationClient.getObservations(location, success: { (data, resp) in}) { (error, response) in
    //Your code here
  }

Points to remember

• Live Sense SDK does not cache any data or feature that was have not successfully saved to the cloud due to any reason like network unavailability, server/cloud service unavailability, or invalid credentials.
• Data Hub was previously named as XYZ.
• To add any extra detail to each feature, you can use the customPayload object.

Additional resources

• A simple example is bundled in the download package, which demonstates how to use the library. It also includes a readme file that lists the steps required to run the example. To learn more, experiment with the example code.