¶ Geofences
This page describes how to use the geofencing engine within the IoT Bridge to detect when endpoints go in and out of designated locations. Geofencing allows quick events to be generated for polygon and circular geofences that can be defined from the user interface or from the API.
¶ What is a geofence?
A geofence describes a boundary in the form of a circle (latitude, longitude, and radius) or a polygon (a set of latitude/longitude pairs that describe a polygon shape) in which endpoints can enter and exit based on their moving location.
¶ Sample circular geofence
Here is a sample circlular geofence, it is easy to define with only a location and a radius, and can easily be used to determine if endpoints are at a particular building.
¶ Sample polygon geofence
Here is a sample polygon geofence describing the campus of Florida Atlantic University. As you can see, a polygon can follow the contours of the campus grounds, whereas a circle would encompass too large of an area.
¶ Defining a geofence
When creating a geofence, the user interface is the easiest way to define a new shape.
- You can search for an address near where you want to define your geofence in the
Search mapfield. Click the map icon to navigate to the address. - Choose the best shape, either a
polygon,rectangle, orcircleto define your geofence. - Draw the geofence on the map, make sure to close a polygon geofence for it to be saved.
¶ Notes
- You can select the pencil icon to
edita geofence, this allows you to change the shape and add new verticies. - you can create a new shape by selecting the appropriate shape and drawing, once you create a new shape, the old shape will be removed.
¶ Fields
- Geofence name: The name of the geofence.
- Geofence key: The key for the geofence.
- Tags: Key/value pairs for organizing your geofences.
¶ Evaluating geofences from triggers
Geofences are evaluated using the geofence.eval() function.
¶ geofence.eval(endpointKey, ts, latitude, longitude[, options])
Evaluate the geofences for an endpoint at a location.
// evaluate geofences at a given location.
geofence.eval(event.endpoint.key,event.ts,event.data.latitude,event.data.longitude,{context:{command:event.data.cmd, eventId: event.id}})
- endpointKey: The endpoint key to evaluate.
- ts: Timestamp when the location was collected.
- latitude: The latitude as a decimal -90.0 - 90.0.
- longitude: The longitude as a decimal -180.0 - 180.0.
- options: (optional)
- context: An object that will be propogated to any
enterorexitevents.
- context: An object that will be propogated to any
¶ Trigger Events
¶ geofence-enter
This event fires when an endpoint enters a geofence.
{
"dateEntered":"2024-03-25T12:10:00Z",
"dateExited":"2024-03-25T13:10:00Z",
"duration": 3600,
"geofence": {
"name":"My Geofence",
"key":"mygeofence"
},
"context": { "command": "PUB", "eventId":"asdf" }
}
- dateEntered: The date the geofence was last entered.
- dateExited: The date the geofence was last exited.
- duration: The time since the geofence was last exited, thus will be "time outside of the geofence".
- geofence: Extract from the geofence object.
- context: User defined object with information related to the published event.
¶ geofence-exit
This event fires when an endpoint exits a geofence.
{
"dateEntered":"2024-03-25T12:10:00Z",
"dateExited":"2024-03-25T13:10:00Z",
"duration": 3600,
"geofence": {
"name":"My Geofence",
"key":"mygeofence"
},
"context": { "command": "PUB", "eventId":"asdf" }
}
- dateEntered: The date the geofence was last entered.
- dateExited: The date the geofence was last exited.
- duration: The time since the geofence was last entered, thus will be "time inside of the geofence".
- geofence: Extract from the geofence object.
- context: User defined object with information related to the published event.
¶ Implementation notes
- When defining polygon geofences, the last point in the polygon must be the same as the first point in the polygon, otherwise an error will result.
- Geofences will only be evaluated if the timestamp for the endpoint is newer than the previous call to
geofence.eval(), this is to ensure that no out of order processing errors occur.
¶ Billable events
The following events are considered billable:
- Calls to
geofence.eval()