RTLS Zones and Geofencing

Introduction

The geofencing subsystem is designed to help the user with the following features:

The concept of zones – the user is able to define a set of static or dynamic (tag-based) zones and the RTLS is able to tell, in which zones the tag currently resides.
Automatically change the tag’s settings when it enters a new zone. This may mean increasing or decreasing the tag’s update interval, modify the filter values, set or reset the alarms, etc.

For more information about the 1D mode in the Eliko RTLS, please refer to the “Zones/geofences and dynamic configuration“ chapter in the Eliko Knowledge Hub.

SET_GEOFENCING_MODE

This is a global switch which enables or disables the geofencing subsystem. When disabled, no zone calculations are done and the tag configuration is not modified when the tag moves. It is still possible to request or modify the settings belonging to the geofencing subsystem – these will take effect when the subsystem will be enabled.

To switch the geofencing subsystem ON, the client sends:

$PEKIO,SET_GEOFENCING_MODE,ON

To switch the geofencing subsystem OFF, the client sends:

$PEKIO,SET_GEOFENCING_MODE,OFF

If the request was successful, the system responds:

$PEKIO,OK

If the supplied parameter was not ON or OFF, the system responds:

$PEKIO,NOT_GOOD,CANNOT_UNDERSTAND_PARAMETER

GET_GEOFENCING_MODE

This request allows to read back the global switch set by SET_GEOFENCING_MODE.

Client sends:

$PEKIO,GET_GEOFENCING_MODE

When enabled, the system responds:

$PEKIO,GEOFENCING_MODE,ENABLED

When disabled, the system responds:

$PEKIO,GEOFENCING_MODE,DISABLED

ADD_GF_ZONE

This request allows to define a static geofence zone.

Client sends:

$PEKIO,ADD_GF_ZONE,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Field name	Explanation	Example
Zone ID	A unique numeric value to identify this zone. Must be a positive value. The value of 0 is reserved and can’t be used here. This field may be left empty – in that case the Zone ID will be automatically generated.	2
Zone Alias	A unique human-readable name for the zone.	Charging area
Zone Priority	A numeric (float) value that is used to decide, which zone commands the tag will get If the tag simultaneously resides in multiple overlapping zones. Higher value means higher priority.	1.2
Border width	A value in meters (range from -0.85 to 0.85), which defines the hysteresis for the tags to enter and exit the zone. This functionality is used to avoid a tag residing in the border area from jumping in and out of the zone too frequently. If this value is negative, the user-defined polygon border becomes the “exit border” for the tags. The “enter border” will be constructed by the RTLS, by shrinking the user-defined border by the “Border width” value. If this value is positive, the user-defined polygon border becomes the “enter border” for the tags. The “exit border” will be constructed by the RTLS, by expanding the user-defined border by the “Border width” value. If this value is zero, there will be no hysteresis.	0.8
Keyword “Z_RANGE”	A keyword that specifies the meaning for the next two values – these are the lower and upper limits for the Z coordinate, which are considered to be inside the zone.	Z_RANGE
Z_MIN	Lower limit for the Z coordinate, which is considered to be inside the zone.	5.4
Z_MAX	Upper limit for the Z coordinate, which is considered to be inside the zone.	12.56
Keyword “POLYGON”	A keyword that specifies that the polygon definition will follow. The polygon is defined by a list of vertices (corner points), each defined by their X and Y coordinates.	POLYGON
V,x,y, V,x,y, ... V,x,y	A list of vertices (corner points) that define the polygon. A minimum of 3 vertices are required. Each vertex contains 3 comma-separated fields: the fixed letter “V” and the X and Y coordinates of the vertex.	V,2.1,3,V,4.14,5.22,V,5.99,2.2

A full example of client request would be:

$PEKIO,ADD_GF_ZONE,2,Alias1,4.5,0.25,Z_RANGE,1.5,25.4,POLYGON,V,2,3,V,4,5,V,5.12,2

If the request was successful, the system responds:

$PEKIO,OK

If there was an error while processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
NO_ALL_FIELDS	Some of the fields are missing.
Z_RANGE_MISSING	Problem with the Z_RANGE parameters.
POLYGON_MISSING	Problem with polygon definition.
TOO_FEW_VERTICES	Less than 3 vertices (which is the minimum to define a polygon).
NAME_MISSING	Zone Alias is missing.
PRIORITY_MISSING	Zone Priority is missing.
Z_RANGE_ORDER	Z Range must be given as lower number first, higher last. The request violated this rule.
POLYGON_SELFINTERSECTING	Error in polygon definition, the polygon can’t be self-intersecting.
BORDER_WIDTH_OUT_OF_RANGE	Border with is not within the accepted limits (which would be from -0.85 to 0.85).
Z_RANGE_BORDER_WIDTH_CONFLICT	Given Z Range was okay, but when shrank by the given negative border width, the tag’s “enter range” can’t be constructed (because its size would be negative).
UNSUCCESSFUL_PARSING	Some other request parsing error that does not have a dedicated error message.
ID_ALREADY_EXISTS	Given Zone ID is already used by some other zone.
NAME_ALREADY_EXISTS	Given Zone Alias is already used by some other zone.
<any other error>	Other errors are considered to be server’s internal errors. Please report them to Eliko.

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,Z_RANGE_MISSING

ADD_TAG_ZONE

This request allows to define a dynamic zone around a tag.

Client sends:

$PEKIO,ADD_TAG_ZONE,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Field name	Explanation	Example
Zone ID	A unique numeric value to identify this zone. Must be a positive value. The value of 0 is reserved and can’t be used here. This field may be left empty – in that case the Zone ID will be automatically generated.	2
Zone Alias	A unique human-readable name for the zone.	Tag_0x0ABC
Zone Priority	A numeric (float) value that is used to decide, which zone commands the tag will get If the tag simultaneously resides in multiple overlapping zones. Higher value means higher priority.	1.2
Border width	A value in meters (range from -0.85 to 0.85), which defines the hysteresis for the tags to enter and exit the zone. This functionality is used to avoid a tag residing in the border area from jumping in and out of the zone too frequently. If this value is negative, the user-defined polygon border becomes the “exit border” for the tags. The “enter border” will be constructed by the RTLS, by shrinking the user-defined dynamic zone radius by the “Border width” value. If this value is positive, the user-defined polygon border becomes the “enter border” for the tags. The “exit border” will be constructed by the RTLS, by expanding the user-defined dynamic zone radius by the “Border width” value. If this value is zero, there will be no hysteresis.	0.8
Keyword “Z_RANGE”	A keyword that specifies the meaning for the next two values – these are the lower and upper limits for the Z coordinate, which are considered to be inside the zone.	Z_RANGE
Z_MIN	Lower limit for the Z coordinate, which is considered to be inside the zone.	5.4
Z_MAX	Upper limit for the Z coordinate, which is considered to be inside the zone.	12.56
Keyword “TAG”	A keyword indicating that the next parameter is the tag serial number	TAG
Tag serial number	The serial number of the tag selected for this dynamic zone	0x0ABC
Keyword “RADIUS”	A keyword indicating that the next parameter is the radius of this dynamic tag zone	RADIUS
Dynamic tag zone radius	Dynamic tag zone radius in meters. Must be greater than zero.	3.5

A full example of client request would be:

$PEKIO,ADD_TAG_ZONE,6,Alias2,10,,Z_RANGE,-10,10.5,TAG,0x026E,RADIUS,3.4

If the request was successful, the system responds:

$PEKIO,OK

If there was an error while processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
Z_RANGE_MISSING	Problem with the Z_RANGE parameters.
NAME_MISSING	Zone Alias is missing.
PRIORITY_MISSING	Zone Priority is missing.
Z_RANGE_ORDER	Z Range must be given as lower number first, higher last. The request violated this rule.
RADIUS_OUT_OF_RANGE	Radius value is negative
TAG_MISSING	Tag ID is not given or missing in the system
BORDER_WIDTH_OUT_OF_RANGE	Border with is not within the accepted limits (which would be from -0.85 to 0.85).
Z_RANGE_BORDER_WIDTH_CONFLICT	Given Z Range was okay, but when shrank by the given negative border width, the tag’s “enter range” can’t be constructed (because its size would be negative).
UNSUCCESSFUL_PARSING	Some other request parsing error that does not have a dedicated error message.
ID_ALREADY_EXISTS	Given Zone ID is already used by some other zone.
NAME_ALREADY_EXISTS	Given Zone Alias is already used by some other zone.
<any other error>	Other errors are considered to be server’s internal errors. Please report them to Eliko.

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,TAG_MISSING

GET_ZONE

This request allows to read back the defined zones. It is possible to request information for a single zone, as well as to list all of them.

Client sends:

$PEKIO,GET_ZONE,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Zone ID

The keyword “ALL”

The numeric value that identifies the geofence zone to be requested. This is the same value that was created when the ADD_GF_ZONE or ADD_TAG_ZONE command was used (whether chosen by the user or automatically generated).

Alternatively, the keyword “ALL” may be used to get the list of all the geofence zones that exist in the system.

A full example of client request would be:

$PEKIO,GET_ZONE,2

If the request was successful, the system responds:

$PEKIO,GF_ZONE,<parameter list>

<parameter list> is a comma-separated list with exactly the same fields as with the ADD_GF_ZONE or ADD_TAG_ZONE request.

A full example of the system’s response, when requested for a specific static geofence zone, may be:

$PEKIO,GF_ZONE,2,Alias1,4.5,0.25,Z_RANGE,1.5,25.4,POLYGON,V,2,3,V,4,5,V,5.12,2

A full example of the system’s response, when requested for a specific dynamic tag zone, may be:

$PEKIO,TAG_ZONE,6,Alias2,10,,Z_RANGE,-10,10.5,TAG,0x026E,RADIUS,3.4

If the client used the request with the “ALL” keyword, a list of all the geofence zones existing in the system will be sent, terminated by the EOF marker:

$PEKIO,GF_ZONE,<parameter list>

$PEKIO,GF_ZONE,<parameter list>

...

$PEKIO,EOF

If there was an error while processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
NO_ID	The Zone ID was missing from the request.
UNKNOWN_ID	The specified Zone ID does not exist in the system’s database.

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,NO_ID

REMOVE_ZONE

This request allows to remove a previously defined geofence zone.

Client sends:

$PEKIO,REMOVE_ZONE,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Zone ID

The keyword “ALL”

The numeric value that identifies the geofence zone to be removed. This is the same value that was created when the ADD_GF_ZONE or ADD_TAG_ZONE request was used (whether chosen by the user or automatically generated).

Alternatively, the keyword “ALL” may be used to remove all the geofence zones that exist in the system.

Some full examples of client request would be:

$PEKIO,REMOVE_ZONE,2

$PEKIO,REMOVE_ZONE,ALL

If the request was successful, the system responds:

$PEKIO,OK

If there was an error while processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
NO_ID	The Zone ID was missing from the request.
UNKNOWN_ID	The specified Zone ID does not exist in the system's database.

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,NO_ID

ADD_ZONE_COMMAND

This request can be used to define a command that will be automatically emitted and executed by the system when the specified tag enters or leaves the specified geofence zone. The main purpose of this functionality is to control some of the tag’s settings, according to the zone it currently resides (for example lowering the update rate when the tag is in the charging area, etc).

Client sends:

$PEKIO,ADD_ZONE_COMMAND,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Field name	Explanation	Example
Zone ID	A unique numeric value to identify the zone, to which the tag should enter for the command to be executed. For tags leaving the specified zone the tilde (“~”) symbol is used in front of the numeric zone ID.	2
Tag’s Serial Number OR The keyword “ALL”	This field can be used to select the tag, which triggers the specified command when it enters or leaves the specified geofence zone. Alternatively, the keyword “ALL” may be used to specify a command that will be executed for every tag which enters or leaves the specified geofence zone.	0x003434
Command ID	A numeric ID for the command that can later be used to read back or remove the command. May be left empty, in which case the command ID will be automatically generated by the system.	15
[command]	A comma-separated list of fields, which make up the command and its parameters. When the specified tag enters or leaves the specified zone, the RTLS automatically emits and executes this command. Technically, most of the commands that can be sent to the system over the TCP connection, may be automatically generated when a tag enters or leaves a zone. In real life, this functionality is mainly meant to modify the tag’s settings or set its alarms according to the zones it enters. When specifying the command, there are two differences, compared to the regular commands entered directly via the communication protocol: The $PEKIO prefix is not repeated here. When using a command meant for a specific tag, a special keyword “THIS” may be used (instead of the tag’s serial number) to address the tag that enters the zone.	SET_TAG_ALARM,THIS,ON,0

A full example of client request would be:

$PEKIO,ADD_ZONE_COMMAND,2,ALL,15,SET_TAG_ALARM,THIS,ON,0

If processing the request was successful, the system responds:

$PEKIO,OK

If there was an error while processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
NOT_ENOUGH_PARAMS	Some parameters were missing from the request.
ZONE_ID_NOT_GIVEN	The Zone ID field was missing from the request.
UNKNOWN_ZONE_ID	The specified Zone ID does not exist in the system.
TAG_SN_NOT_GIVEN	Tag’s serial number was missing from the request.
COMMAND_NOT_GIVEN	The command to be executed was missing from the request.
NO_SUCH_COMMAND_AVAILABLE	The command to be executed does not exist in the system
COMMAND_ID_PARSE_FAIL	The command ID could not be parsed from the request.
COMMAND_ID_CONFLICT	The specified command ID already exists.

Important! The error messages listed above are only related to the ADD_ZONE_COMMAND request itself but not to the “internal” command sent with the ADD_ZONE_COMMAND request. The only error messages related to the “internal” command are COMMAND_NOT_GIVEN, which appears if a command is not given at all, i.e. the command field is left empty and NO_SUCH_COMMAND_AVAILABLE, which appears when trying to send a non-existing command. The command parameters and their values, however, are not controlled by the system when sending ADD_ZONE_COMMAND request and, therefore, may be passed incorrectly without any error message returned by the system immediately after sending the request. For example, a user can send empty SET_TAG_SAMPLE_INTERVALS command without any arguments inside the ADD_ZONE_COMMAND request and the system will respond $PEKIO,OK. However, when a zone event is later triggered, an error message specific to that particular “internal” command will then be generated by the system.

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,COMMAND_ID_PARSE_FAIL

LIST_ZONE_COMMANDS

This request allows to read back the previously defined zone commands.

Client sends:

$PEKIO,LIST_ZONE_COMMANDS,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Zone ID

The keyword “ALL”

The Zone ID, for which the commands will be queried. Alternatively, the keyword “ALL” may be specified to request the zone commands for all of the zones.

A full example of client request would be:

$PEKIO,LIST_ZONE_COMMANDS,2

If processing the request was successful, the system responds:

$PEKIO,ZONE_COMMAND,<parameter list>

$PEKIO,ZONE_COMMAND,<parameter list>

...

$PEKIO,EOF

<parameter list> has exactly the same fields as with the ADD_ZONE_COMMAND request.

If there was an error while processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
NO_ID	The Zone ID field was missing from the request.
UNKNOWN_ID	The requested Zone ID does not exist in the system.

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_ID

REMOVE_ZONE_COMMANDS

This request allows to remove the previously defined zone commands.

Client sends:

$PEKIO,REMOVE_ZONE_COMMANDS,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Field name

Explanation

Example

Zone ID

The keyword “ALL”

The Zone ID, for which the zone command(s) should be removed. Alternatively, the keyword “ALL” may be used to remove all the zone commands for all of the zones.

Command ID

The keyword “ALL”

The Command ID, which will be removed. Alternatively, the keyword “ALL” may be used to remove all the zone commands for the specified zone.

This field may be omitted – in this case the behavior is exactly as with the “ALL” keyword.

Some full examples of client request would be:

$PEKIO,REMOVE_ZONE_COMMANDS,ALL

$PEKIO,REMOVE_ZONE_COMMANDS,2

$PEKIO,REMOVE_ZONE_COMMANDS,2,ALL

$PEKIO,REMOVE_ZONE_COMMANDS,2,15

If the request was successful, the system responds:

$PEKIO,OK

If there was an error while processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
NO_ZONE_ID	The Zone ID was missing from the request.
UNKNOWN_ZONE_ID	The specified Zone ID does not exist in the system’s database.
COMMAND_ID	The command ID could not be parsed from the request.
UNKNOWN_COMMAND_ID	There is no such command in the specified zone.

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,NO_ZONE_ID

GET_TAGS_IN_ZONE

This request allows the client to ask for the list of tags residing in a zone. This request is supported from RTLS Server software 2.6.0.

Client sends:

$PEKIO,GET_TAGS_IN_ZONE,<parameter>

<parameter> has the following meaning:

Field name	Explanation	Example
Zone ID	The Zone ID, for which the list of tags will be queried.	2

A full example of client request would be:

$PEKIO,GET_TAGS_IN_ZONE,2

If processing the request was successful, the system responds:

$PEKIO,IN_ZONE,<parameter list>

$PEKIO,IN_ZONE,<parameter list>

...

$PEKIO,EOF

<parameter list> is a comma-separated list with the following fields:

Field name	Explanation	Example
Keyword “TAG”	A keyword that indicates that a tag’s serial number will follow.	TAG
Tag’s Serial Number	Serial number of a tag residing in the queried zone.	0x003434
Keyword “ZONE”	A keyword that indicates that the Zone ID will follow.	ZONE
Zone ID	Zone ID that was queried.	2
Keyword “TIME”	A keyword that indicates that a timestamp will follow.	TIME
Time	Unix Timestamp when the tag entered that zone.	1647323445