Process sensor data

Create a sensor rule

The Tracking API supports different types of sensors such as battery, temperature, acceleration, and tamper sensors. In this example we create a "My battery level" rule to notify the owner when the battery level of a device goes below 20%.

To create a sensor rule, send a request to the sensors endpoint. If the user is a member of multiple projects, the target project ID needs to be specified in the projectId query parameter.

curl -X POST \
  'https://tracking.api.here.com/sensors/v3?projectId=`projectId`' \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json' \
  -d '{
  "type": "battery",
  "range":  {
    "begin": 20,
    "end": 80
  },
  "name": "My battery level"
}'

This will create a battery rule and return the unique rule ID. At this point, the rule isn't associated with any device but it will be visible in the Asset Tracking web application.

curl -X GET \
  'https://tracking.api.here.com/sensors/v3?projectId=`projectId`' \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

This will return a list of sensor rules the user previously created.

Associate rule and device

Once created, the sensor rule can be associated to a device, which is sending its sensor data to the Tracking API. This will generate an event whenever the reported device battery level goes in or out of range defined by the rule.

The trackingId is a Tracking ID of a device claimed by the user.

curl -X PUT \
  https://tracking.api.here.com/associations/v3/{trackingId}/sensors/{ruleId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

Send telemetry

Send telemetry, including battery information, within the defined range and then below the range.

NOTE: The timestamp is the UNIX Epoch time in milliseconds.

curl -X POST \
  https://tracking.api.here.com/v2/ \
  -H 'authorization: Bearer {deviceToken}' \
  -H 'content-type: application/json' \
  -d '[{
      "timestamp": 1569300623010,
      "position": {
        "alt": 107,
        "accuracy": 13,
        "lat": 52.520806,
        "lng": 13.410514,
        "altaccuracy": 14
      },
      "system": {
        "reportedSensorData": {
          "batteryLevel": 21
        }
      }
}]'

curl -X POST \
  https://tracking.api.here.com/v2/ \
  -H 'authorization: Bearer {deviceToken}' \
  -H 'content-type: application/json' \
  -d '[{
      "timestamp": 1569300814020,
      "position": {
        "alt": 107,
        "accuracy": 10,
        "lat": 52.521880,
        "lng": 13.412724,
        "altaccuracy": 15
      },
      "system": {
        "reportedSensorData": {
          "batteryLevel": 19
        }
      }
}]'

See that an event was recorded

All sensor events are recorded. You will see two different events: an event "in range" triggered by the first telemetry ingestion, and an event "below range" by the second one. Events are generated whenever the reported sensor state crosses the rule upper or lower threshold.

curl -X GET \
  https://tracking.api.here.com/events/v3/{trackingId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'