- Essentials
- Types of geofences
- How geofences work
- Advanced application of geofences
- Arbitrary point hit-test
- How to create a geofence?
- Geofences API
- Troubleshooting
Essentials
A geofence is an independent entity characterized by an id, name, geometry (polygon, circle, or corridor), and metadata.
Geofences can be applied only via linked plugins, calculators, or streams.
Grouping: Geofences can be organized into groups and automatically applied to plugins, streams and calculators within a group.
Geofences assigned to the device automatically added to geofences assigned to plugin, calculator or stream during processing of messages from this device.
Access Management: Geofence access can be managed through token ACLs.
Priority System: Geofences have a priority range from 0 to 100, with higher priority geofences being checked first in case of intersections.
Types of geofences
We support three geofence geometry types:
Circle: Defined by a center point and a radius.
Polygon: Closed shape with three or more vertices.
Corridor: Polyline with a specified width.
How geofences work
You link geofences to:
- Calculators - for geofences-based reporting and to be notified about geofence enter/exit events of all devices assigned to the calculator. You can access geofence status in all expressions within calculator or just use interval selector of type geofence to split device messages on intervals based on the name of active geofence.
- Plugins - to transform or correct incoming messages based on the geofence in/out status for all devices assigned to plugin. To mark messages with geofence status you usually apply msg-geofence plugin.
- Streams - to be able to stream messages depending on their geofence in/out status for all devices assigned to the stream.
You can link geofences to plugins, streams, and calculators in two ways:
Directly by assigning specific geofences to the target entity (plugin, stream, calculator).
Indirectly by assigning geofences to groups. Geofence will be automatically available to all plugins, streams and calculators in the group.
You can directly link geofences with specific device. In that case when calculator, plugin or stream is processing messages from this device such geofences will be merged to the common list of geofences for this plugin, stream or calculator.
Note. If you instead of linked defined geofences boundaries directly in the plugin or calculator configuration they will be used exclusively instead of any geofence directly or indirectly linked to this plugin or calculator. To simplify the setup and avoid any processing ambiguity we suggest to use only linked geofences everywhere.
Advanced application of geofences
Geofences linked to calculators, plugins or streams enriched with geofences linked directly to the device can be used within their expressions to test if the device is inside or outside the geofence(s). This is done using two special functions:
geofence(): returns the name of the geofence with the highest priority the device is currently in; if the device is outside all linked geofences, the function will return null.
geofences(): returns an array with the names of all geofences the device is currently in.
For instance, to apply a plugin only to messages reported from inside any of the linked geofences, use the expression "geofence() != null" in the validate_expression parameter of the plugin configuration.
Similarly, to set up a stream to forward only messages coming from outside all linked geofences, use the expression "geofence() == null" in the validate_expression option of the stream configuration.
You can make geofencing even more powerful by accessing properties of the highest-priority geofence in a mathematical expression. For example, if you store the maximum allowed speed for the geofence in its metadata, you can compare it against the actual device speed using the expression "position.speed > geofence('metadata.max_speed')".
Arbitrary point hit-test
You may test if a point with arbitrary coordinates is inside selected geofences using GET /gw/geofences/{geofences.selector}/hittest REST API call. The call will return a list of geofences that contain this point. You may use all as geofences.selector to perform hit-test for all geofences available for user account or token.
API call under the hood utilizes a geospatial R-Tree index and can quickly provide hit-test results. This can be particulary usefull if you have thousands of geofences and need to perform on-demand check inside which geofence device is currently in.
How to create geofence?
Log in to the flespi panel
Navigate to Telematics hub -> Geofences and click the "+" button in the bottom right corner to add a new geofence:
Give the new geofence a name, pick the proper geometry type, define its on the map with the mouse, adjust geometry properties such as corridor width or circle radius and click Save:
Go to the Calculators, Streams, Plugins or Groups tab for the geofence and assign it to the entities you want to link it with:
Geofences API
To perform any operations with the geofences, use the geofences API.
Troubleshooting
In case of any issues, check the Logs tab on the geofence screen. There you will find all modifications that were done to a geofence within the last 365 days.
To manually check whether a point is inside or outside of geofence you may use GET /gw/geofences/{geofences.selector}/hittest REST API call.