Geofencing smartCORE module
Description
The "geofencing" module uses GPS position data to continuously check whether the system is located in a geo-area contained in a configuration. As soon as it is detected that the device is located within certain configured geo-coordinates, the data for this area (ID and name of the entry from the configuration) is recorded in the measurement data and can be sent to a cloud. This allows further actions, such as sending an email or SMS, to be triggered.
The module itself does not record any GPS data, but accesses signal data from the smartCORE data pool. The signal names that contain GPS information (latitude, longitude) must therefore be entered in the module configuration. Typical data sources for GPS data are the GPS module or external sources that are provided via CAN bus or other protocols.
JSON configuration
The following section describes the entire JSON configuration of a geofence module and explains the individual areas and parameters.
Geofence types
There are two types of geofence areas that can be used in the configuration.
- Circle
- Polygon
Both types have three common parameters that must be specified:
- "id"
- "name"
- "description"
If a violation of a geolocalized boundary is detected, this data is saved in the measurement data. The module recognizes whether it is a circle or a polygon based on the number of coordinates. A circle always has only one coordinate, whereas a polygon always has at least three or more. Polygons with up to 20 coordinates were tested. If an entry has only two coordinates, it is ignored and not taken into account.
Circle
To define a circle, you only need to enter the GPS coordinate, which serves as the center of the circle. The radius (in km) can be entered as an additional parameter. If the radius is not specified, 0.5 km (500 meters) is used as the default value.
Below, a geofence area is defined as a circle with a radius of 900 meters.
{
"id": 1,
"name": "AA",
"description": "Hmb-Altona",
"radius":0.9,
"choords": [
{
"latitude": 53.552695,
"longitude": 9.935175
}
]
}
Polygon
A polygon can be defined by entering several coordinates (at least three!). The order in the config is very important, as one coordinate is always connected to the next The first and last coordinates must not be identical; the software automatically connects these two points during the calculation.
{
"id": 111103,
"name": "Bhbf",
"description": "Berlin",
"choords": [
{
"latitude": 53.552695,
"longitude": 9.935175
},
{
"latitude": 53.552691,
"longitude": 9.935172
},
{
"latitude": 53.552690,
"longitude": 9.935178
}
]
}
Complete example configuration (minimal)
The following configuration uses the minimum settings and two geofences are defined in the "stations" area.
{
"module": "geofencing",
"factory": "geofencing",
"config": {
"timeoutMs": 2000,
"gpsSatCountName": [
"GPS.SatelliteCount",
"Colibri.SatelliteCount"
],
"minimalAvailableSatCount": 6,
"gpsLocationName": "GPS.Location",
"longitudeName": "DBC.longitude",
"latitudeName": "DBC.latitude",
"stations": [
{
"id": 1,
"name": "AA",
"description": "Hmb-Altona BP",
"radius":0.9,
"choords": [
{
"latitude": 53.552695,
"longitude": 9.935175
}
]
},
{
"id": 2,
"extNo": 8000011201,
"name": "AAG",
"description": "Ascheberg/Holst BP",
"choords": [
{
"latitude": 54.148462,
"longitude": 10.339481
}
]
}
]
}
}
Complete example configuration with external geofence file
It is also possible to store the geofence stations in an external file. The file path must then be entered in the "stationsFile" field in the config.
{
"module": "geofencing",
"factory": "geofencing",
"config": {
"timeoutMs": 2000,
"minimalAvailableSatCount": 6,
"gpsSatCountName": [
"GPS.SatelliteCount",
"Colibri.SatelliteCount"
],
"gpsLocationName": "GPS.Location",
"longitudeName": "DBC.longitude",
"latitudeName": "DBC.latitude",
"stationsFile":"/sdi/config/geofence_stations.json",
"stations": [
]
}
}
Structure of the external file
The structure of the external file, which is entered in the "stationsFile" config field, is described below. A version name can be entered in the "file_version" field, which can then also be sent to the cloud if required. The geofence areas are entered in the "geofence_stations" field, as in the "stations" field in the smartCORE config file.
{
"file_version": "File version 1.0",
"geofence_stations": [
{
"id": 111101,
"name": "AA",
"description": "Hmb-Altona",
"choords": [
{
"latitude": 53.552695,
"longitude": 9.935175
}
]
},
{
"id": 111103,
"name": "Bhbf",
"description": "Berlin",
"choords": [
{
"latitude": 53.552695,
"longitude": 9.935175
},
{
"latitude": 53.552691,
"longitude": 9.935172
},
{
"latitude": 53.552690,
"longitude": 9.935178
}
]
},
{
"id": 111104,
"name": "AEC",
"description": "Eckernfoerde Bstg",
"choords": [
{
"latitude": 54.4676,
"longitude": 9.835115
},
{
"latitude": 54.4675,
"longitude": 9.835114
},
{
"latitude": 54.4677,
"longitude": 9.835125
},
{
"latitude": 54.46761,
"longitude": 9.835112
},
{
"latitude": 54.4675,
"longitude": 9.835113
},
{
"latitude": 54.4678,
"longitude": 9.835112
}
]
}
]
}
Parameter list
| parameter name | required | data type | meaningful value range | default | description |
|---|---|---|---|---|---|
| timeoutMs | No | INT | 1000 - 10000 | 2000 | A Execution interval of the check whether the current GPS coordinates are in a geofecne area. |
| stations | No | Array | - | - | Contains the definitions of the geofence areas. |
| stationsFile | No | String | "" | "" | Path to the external json file with the geofence areas. Enables the geofence areas to be outsourced to an external file in order to keep the smartCORE configuration small and manageable. |
| channelNameLocationID | No | String | "" | [Module name].LocationID | This parameter can be used to change the name of the signal with the ID of the geofence area. This signal name then appears in the measurement data. It is recommended to use the default settings. |
| channelNameLocationName | No | String | "" | [Module name].LocationName | This parameter specifies the name of the signal with the description ("description" field) of the geofence area. This signal name then appears in the measurement data. It is recommended to use the default settings. |
| gpsSatCountName | Yes | Array | - | - | Contains one or more signal names from the data pool that contain the current number of satellites of the GPS signal. If several names are specified, the signal that is available and provides data is used. It is therefore automatically determined which signal is used. |
| minimalAvailableSatCount | No | INT | 3-15 | 5 | Is required for the plausibility check of the GPS signal. Minimum number of satellites that must be present in a signal from "gpsSatCountName" for the GPS data to be valid. |
Parameter station
| Parameter name | Required | Data type | Sensible value range | Default | Description |
|---|---|---|---|---|---|
| id | Yes | INT | 1 - 10000 | - | Must be unique within the config. This number is written to the measurement data or sent to a cloud. |
| name | Yes | String | "" | "" | Abbreviation/short form of the geofence area name. |
| description | Yes | String | "" | "" | Long name of the geofence area name. Is saved in the measurement data and transferred to the cloud. |
| radius | Yes | Double | 0.1 - 10 | 0.5 | Only taken into account for areas defined as a circle. The radius is specified in km. |
| choords | Yes | Array | - | - | Area with the coordinate (circle) or the coordinates (polygon). |
Generated signals (Producer)
The following signals are generated by the geofence module and stored in the smartCORE's data pool. These signals can then be saved in the measurement data and sent to the cloud. The signal names can be adapted in the configuration (the "channelNameLocationID" and "channelNameLocationName" fields). On the cloud side, these signals can then be used in monitoring and alerting tasks.
| Signal Name | Data Type | Description |
|---|---|---|
| [Module name].LocationName | String | The description ("description" field) of the geofence area is saved in this signal as soon as the current GPS coordinates are located in one of the geofence areas. If the current GPS coordinates are not in an area, the value is an empty string. |
| [Module name].LocationID | INT | The ID ("id" field) of the geofence area in which the current GPS coordinates are located is saved in this signal. If the current GPS coordinates are not in an area, the value is -1. |
| [Module name].Valid | Bool | Specifies whether the current GPS coordinates are valid or not. |
| [Module name].Fileversion | String | This signal contains the content of the "file_version" entry in the external file. |
Module information
| Information | Value |
|---|---|
| Author | optiMEAS Measurement and Automation Systems GmbH |
| since smartCORE | 2.2 |
| Module type | Producer and Consumer |
| Dependencies | NONE |