Location Capabilities

• Device Location History - ability to manage a history of "location observations" over the lifespan of the device.
• Device Last Known Location - Automatically keep track of last known coordinates for devices with location history.
• Device Location Change Actions - "Geofences" - via Policy, take action when devices transition between in or out of a geographic region.
• Search for Devices In Geographic Bounding Box - for instance, to display devices on a map.

Device Location History

Device location history is recorded in the form of Device Location Observation. These point-in-time observations of a device's location help keep track of a device's location over time.

When creating a device location observation, you specify a WSG84 compliant latitude and longitude, which is kept on the observation. This coordinate drives the other features relating to device location.

As a convenience, saved device location observations will return their coordinates in GeoJSON Feature, with a geometry of type 'Point', with the radius in the properties object.

Device Last Known Location

Devices will also keep track of their last known location via two methods:

• The last_device_location_observation field will reference the most recent location observation as ordered by thegenerated_at field. Meaning: the location observation's generated_at date supersedes created_at when the latest location observation is determined. Note that generated_at defaults to created_at if not specified on creation.
• Devices that have had location observations created for them at any point will also return a last_known_geographic_location GeoJSON object. This will correspond to the location in the device's last_device_location_observation. Note that if at any point the last known observation is deleted, last_device_location_observation will become undefined, but last_known_geographic_location will retain its data.

Adding to Device Location History via Policy

To create device location observations based on a device's report, create a new Rule (Policy) with any appropriate rule_condition, a rule action of type create_device_location_observation. Example:

{
    "company_id": "my_company",
    "cloud_rule": true,
    "active": true,
    "rule_condition": {
        "type": "true"
    },
    "description": "Create Location Observation",
    "then_actions": [
        {
            "type": "create_device_location_observation",
            "latitude_template": "{{.Report.Payload.lat}}",
            "longitude_template": "{{.Report.Payload.long}}",
            "radius_template": "{{.Report.Payload.acc}}",
            "generated_at_template": "{{.Report.Payload.date}}",
            "generated_at_format": "rfc3339",
            "via": "cell_tower"
        }
    ],
}

As shown here, using the template engine, it's possible to pull data from the incoming report and use it to populate the required fields of a device location observation.

Generated At Parsing

Using the generated_at_template and generated_at_format fields, the rule will parse the Generated At date from the report. The supported generated_at_format values are rfc3339 (viz. RFC3339 or unix_timestamp also known as Epoch Time. If the format is omitted or unrecognized, the parser will default to rfc3339.

Search for Devices In Geographic Bounding Box

It's possible to search for all devices in a given geographic bounding box with the List all devices within geographic bounding box endpoint.

"Geofences"

It's possible to create geofence behavior using a policy/rule that refers to a Geographic Region. For more information, go to Managing Geofences .