Geofencing
Particle Edge Geofencing is an Asset Tracker feature that enables customers to create virtual geographic boundaries and evaluate entries and exits from the zone.
- Geofence evaluation on the device replaces the need to publish high frequency location data for evaluation in the cloud, therefore minimizing cellular costs. Geofence evaluation occurs in the field even when cellular connection is unstable.
- Geofence zones can be configured in Particle Console or by third party applications via Particle Cloud API. For devices in sleep mode, Geofence settings will sync to the device as soon as it is available to receive it.
Some common use cases:
- Theft detection, by triggering if a tracked item leaves a geofenced location
- Destination tracking, by triggering when a tracked item arrives the geofenced location of its destination
Geofencing requires Tracker Edge firmware v17. To upgrade your Tracker firmware, see Tracker Edge Firmware.
Processing location data
Geofencing events are provided as part of the Tracker location event.
There are additional values that can be included in the trig
array that indicate the reason geofence status:
outside1
The device is currently outside of geofence zone 1 (and outside trigger is enabled)inside1
The device is currently inside of geofence zone 1 (and inside trigger is enabled)enter1
The device has entered geofence zone 1 (and enter trigger is enabled)exit1
The device has exited geofence zone 1 (and exit trigger is enabled)outside2
,inside2
,enter2
, andexit2
outside3
,inside3
,enter3
, andexit3
outside4
,inside4
,enter4
, andexit4
Thus geofence data can be processed by any methods used to handle location events, including:
- Webhooks
- Other integrations such as Google Cloud Platform
- The Server-Sent Events Stream
- Querying historical location data
Console configuration
Configuration of Geofence settings can be done from the console on a per-device basis, as described in the console documentation.
Geofence support is part of the Tracker configuration schema. If you are using the default schema, it will automatically be enabled for you, however if you are using a custom schema, the feature will not be available in the console until you merge the geofence options into your custom schema. You must do this manually and update your product schema; schema changes are never automatically merged.
API configuration
In many cases, you will want to programmatically update geofence settings. The geofence settings are part of the standard configuration along with other settings, and are set in the same way.
You will likely need to:
The geofence settings are at the same level as the other settings such as location, imu_trig, and sleep, and include:
geofence | Geofence settings | ||||
interval | Wake interval (every n seconds) | integer | |||
zone1 | Configuration for Zone 1 settings | ||||
enable | Enable zone 1 configuration | boolean (true or false) | |||
shape_type | Shape of the geofence | "circle" | |||
lat | Latitude (Degrees) | number -180.0 to 180.0 | |||
lon | Longitude (Degrees) | number -90.0 to 90.0 | |||
radius | Radius (Meters) | number | |||
inside | Publish inside zone | boolean (true or false) | |||
outside | Publish outside zone | boolean (true or false) | |||
enter | Publish on enter zone | boolean (true or false) | |||
leave | Publish on exit zone | boolean (true or false) | |||
verif | Time Before Trigger (Seconds) | integer | |||
zone2 | Configuration for Zone 2 settings | ||||
enable | Enable zone 2 configuration | boolean (true or false) | |||
... | |||||
zone3 | Configuration for Zone 3 settings | ||||
... | |||||
zone4 | Configuration for Zone 4 settings | ||||
... |
When managing per-device configuration:
- The set configuration endpoint requires the whole configuration, not just changes, so you will likely always want to read, modify, then write configurations.
- An entire top-level module (location, imu_trig, sleep, etc.) can be omitted if all of the settings should use the product default settings).
- There are no product default settings for geofence.
Tracker devices with device level only configuration (such as geofencing) and devices that are marked as development devices can have per-device configuration. In addition to using the console or curl, above, this tool makes it easy to view and edit the configuration in JSON format:
This will only show the modules that different than the product default. If the device is not a development device and geofence has not been configured yet, it will show No custom configuration; this is normal.