RTLS Tag Management | Knowledge Hub

Tag addressing

There are several tag-related requests that are meant to manipulate or read back parameters of certain tags. The most basic way of addressing the tags is to use its 24-bit unique serial number, which is expressed in 6-digit hexadecimal format. Another way is to address a request using a tag group ID with the keyword “TG” followed by a semicolon (instead of the tag’s serial number) to indicate the request should be applied to all the tags belonging to a particular group. Additionally, some requests allow to use the keyword “ALL” (instead of the tag’s serial number), to indicate the request should be applied to all the tags present in the RTLS’s database.

The different options to address the tag(s) via these requests are as follows:

Method	Description	Example
Single tag addressing	The tag’s 24-bit unique serial number, in 6-digit hexadecimal format is used to address the tag.	0x0009B7
Tag group ID	The tag group numeric (integer) ID is used to address all the tags belonging to a given group. Preceded by the flag “TG” and a semicolon.	TG;1
ALL	The keyword “ALL” is used to address all the tags present in the RTLS’s database.	ALL

When using the requests listed above, there are some common error messages related to tag addressing. To make descriptions of the relevant requests shorter, these error messages are not repeated under each chapter. Instead, we list them here.

In case the system encounters an error related to tag addressing when processing a client request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Error ID	Explanation
ID_MISSING	The field that should address the tag(s) is missing from the request. Note that depending on the exact request, this error might not be used, because an earlier check already returns the WRONG_NUMBER_OF_PARAMETERS error instead.
ID_PARSING	The tag addressing field looks like a tag’s serial number, but there was an error parsing this.
UNKNOWN_TAG	The tag addressing field was successfully parsed as the tag’s serial number, but there is no such tag in the RTLS’s database.
GROUP_ID_MISSING	The field that should address the tag group is missing from the request. Note that depending on the exact request, this error might not be used, because an earlier check already returns the WRONG_NUMBER_OF_PARAMETERS error instead.
GROUP_ID_PARSING	There was an error parsing the tag group ID, most likely due to a wrong format (other than integer).
UNKNOWN_GROUP	The tag group ID addressing field was successfully parsed, but there is no such tag group in the RTLS’s database.

Please refer to the description of the relevant requests for other request-specific error messages. The table above lists only the common error messages specific to tag addressing.

Main commands

GET_TAGS

This request allows the client to ask the list of known tags. As with anchors, the tags also automatically become known to the system when they first appear online and communicate with the system. In case the client wants to remove a tag from the database, this can be done by request REMOVE_TAGS.

Client sends:

$PEKIO,GET_TAGS,<optional parameter>

<optional parameter> has the following meaning:

Field name

Explanation

Examples

Tag’s Serial Number

Tag group ID

the keyword “ALL”

Can be one of the following:

Tag’s serial number to be queried.
Tag group ID preceded by the flag “TG” and a semicolon
Keyword “ALL” to query all the tags in the database (the same can be achieved by just omitting this parameter).

0x123464

TG;1

ALL

Some full examples of client requests would be:

$PEKIO,GET_TAGS

$PEKIO,GET_TAGS,ALL

$PEKIO,GET_TAGS,0x001E38

$PEKIO,GET_TAGS,TG;1

If processing the request was successful, the system responds with one row per tag and terminates the list with special EOF marker:

$PEKIO,TAG,<parameter list>

$PEKIO,TAG,<parameter list>

...

$PEKIO,EOF

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

Field name	Explanation	Example
Tag’s Serial Number	A 24-bit identifier that is unique among all the produced RTLS tags, in 6-digit hexadecimal format. The Serial Number does not change during the whole life cycle of the tag and can thus be used to uniquely identify it.	0x003464
Tag’s Alias	A human-readable alias for the tag. Empty when not set.	Peter’s wristband
Tag’s Positioning Mode	Selects the positioning mode. Values of “2D” and “3D” are allowed. The positioning algorithm is more reliable in “2D” mode, so the user should prefer this, if possible (ie when the height of tag is fixed and known).	2D
Tag’s Fixed Height	In case the “2D” positioning mode is used, this is the fixed Z coordinate of the tag (in meters). Can be used only in case the height of the tag is fixed and known. When “3D” positioning mode is used, this field should be ignored.	1.82
Tag’s Update Rate High value in Hz	Starting from RTLS Server software 2.3.0, this value is included here only for backward compatibility. When implementing new software, GET_TAG_SAMPLE_INTERVALS request should be used to query the tag’s update interval values. This new request allows support for dynamic update rate configuration, as well as status information during tag reconfiguration. This value here is the Tag’s Update Rate High value in Hz. This means the update rate in case the tag is moving. In case user has set an Update Rate High value for the tag, it is displayed here, even if the modification has not yet reached the tag itself. If there is no user-defined update rate value for the tag, the tag’s actual update rate value is displayed here instead. In case this is also not known (tag is offline or it has been online only short time), a value of “0” is displayed here. Note that the actual update rate may be different because of misconfiguration, radio overload or due to effects of a dynamic update rate.	2.5
Tag’s Last Seen Timestamp	Unix Timestamp when the tag was last seen online.	1512343243
Tag’s Last Position	Last X, Y and Z coordinates of the tag (in meters).	0.00,-9.20,1.10

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

$PEKIO,TAG,0x003464,John’s Tag,2D,1.12,2.5,1512343243,0.00,0.00,1.10

$PEKIO,TAG,0x003523,,2D,1.22,5,1512343244,2.31,4.02,1.19

$PEKIO,EOF

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

$PEKIO,NOT_GOOD,<error ID>

Possible values for the <error ID> field are defined in chapter “Tag Addressing”.

A full example of error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_TAG

GET_BATTERIES

This request allows the client to ask for battery statuses of known tags. It is up to the client to decide, whether to use this command periodically to poll for these values OR use the NOTIFICATIONS request to get automatic updates. The battery reports are the same in both cases.

Client sends:

$PEKIO,GET_BATTERIES,<optional parameter>

<optional parameter> has the following meaning:

Field name

Explanation

Examples

Tag’s Serial Number

Tag group ID

The keyword “ALL”

Can be one of the following:

Tag’s serial number to be queried.
Tag group ID preceded by the flag “TG” and a semicolon
Keyword “ALL” to query all the tags in the database (the same can be achieved by just omitting this parameter).

0x123464

TG;1

ALL

Some full examples of client requests would be:

$PEKIO,GET_BATTERIES

$PEKIO,GET_BATTERIES,ALL

$PEKIO,GET_BATTERIES,0x001E38

$PEKIO,GET_BATTERIES,TG;1

If processing the request was successful, the system responds with one row per tag and terminates the list with special EOF marker:

$PEKIO,TAG_BATTERY,<parameter list>

$PEKIO,TAG_BATTERY,<parameter list>

...

$PEKIO,EOF

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

Field name	Explanation	Example
Tag’s Serial Number	A 24-bit identifier that is unique among all the produced RTLS tags, in 6-digit hexadecimal format. The Serial Number does not change during the whole life cycle of the tag and can thus be used to uniquely identify it.	0x003464
Tag’s Alias	A human-readable alias for the tag. Empty when not set.	Peter’s wristband
Tag’s Battery Voltage	Battery voltage in millivolts.	4087
Tag’s Battery Status	Estimated battery percentage.	70%
Measurement’s Timestamp	Unix Timestamp when the measurement was taken.	1212343243

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

$PEKIO,TAG_BATTERY,0x000453,my tag,4087,70%,1212343243

$PEKIO,TAG_BATTERY,0x000492,,4012,60%,1212343243

$PEKIO,EOF

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

$PEKIO,NOT_GOOD,<error ID>

Possible values for the <error ID> field are defined in chapter “Tag Addressing”.

A full example of error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_TAG

SET_TAG_ALIAS

This request allows the client to assign a human-readable alias for the tag. Note that it is not possible to add a new tag into the database with SET_TAG_ALIAS request, only add or modify its alias. The tag must be present in the database before using this request. Tags are added into the database automatically after they first time appear online.

Client sends:

$PEKIO,SET_TAG_ALIAS,<parameter list>

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

Field name	Explanation	Example
Tag’s Serial Number	A 24-bit identifier that is unique among all the produced RTLS tags, in 6-digit hexadecimal format. The Serial Number does not change during the whole life cycle of the tag and can thus be used to uniquely identify it.	0x003464
Tag’s New Alias	A human-readable alias for the tag.	Peter’s wristband

A full example of client’s request would be:

$PEKIO,SET_TAG_ALIAS,0x003464,Peter’s wristband

If processing the request was successful, the system responds:

$PEKIO,OK

If there is no such tag in the database, the system responds:

$PEKIO,NOT_GOOD,UNKNOWN_ID

SET_TAG_PARAMS

This request allows to set the tag’s math parameters. Note that it is not possible to add a new tag into the database with SET_TAG_PARAMS request, only modify its math parameters. The tag must be present in the database before using this request. Tags are added into the database automatically after they first time appear online.

Client sends:

$PEKIO,SET_TAG_PARAMS,<parameter list>

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

Field name	Explanation	Example
Tag’s Serial Number OR Tag group ID OR The keyword “ALL”	Can be one of the following: Tag’s serial number for which the math parameters will be set. Tag group ID preceded by the flag “TG” and a semicolon. Keyword “ALL” to set the math parameters for all the tags in the database.	0x123464 TG;1 ALL
Tag’s Positioning Mode	Selects the positioning mode. Values of “2D” and “3D” are allowed. The positioning algorithm is more reliable in “2D” mode, so the user should prefer this, if possible (ie when the height of tag is fixed and known). This field may be left empty – in this case the previously set value will stay intact.	2D
Tag’s Fixed Height	In case the “2D” positioning mode is used, this is the fixed Z coordinate of the tag (in meters). Can be used only in case the height of the tag is fixed and known. This field may be left empty – in this case the previously set value will stay intact. When “3D” positioning mode is used, this field will be ignored by the system and may be left empty by the client.	-1.87
Fixed Height Bias	Can be used to set the tag’s relative height in “2D” positioning mode. This will help to support multifloor or multilevel environments. This value is added to the previous (Tag’s Fixed Height) value to get the total/absolute height of the tag. In a typical multilevel setup, the “Tag’s Fixed Height” value would be constant and equals to the height of the tag from any level/floor. The “Fixed Height Bias” is the level/floor height from the coordinate origin and should be modified during operation (depending on which floor the tag currently resides). This field may be left empty – in this case the previously set value will stay intact. Supported from RTLS Server software versions 2.7.x.	2.2

Some full examples of client requests would be:

$PEKIO,SET_TAG_PARAMS,0x004343,2D,1.34,2

$PEKIO,SET_TAG_PARAMS,ALL,2D,1.34

$PEKIO,SET_TAG_PARAMS,ALL,,,1.55

$PEKIO,SET_TAG_PARAMS,TG;5,3D

If processing the request was successful, the system responds:

$PEKIO,OK

If the system encountered an error when 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_PARAMS	All the fields are empty, nothing to set.
WRONG_D	The “2D/3D” mode selector was not “2D” or “3D”.
HEIGHT_VALUE	The Fixed Height value could not be properly parsed.
BIAS_VALUE	The Fixed Height Bias value could not be properly parsed.
<tag addressing errors>	If there was a problem with tag addressing, the common error messages described in chapter “Tag Addressing” may also appear.

Some full examples of the system’s error responses would be:

$PEKIO,NOT_GOOD,BIAS_VALUE

$PEKIO,NOT_GOOD,UNKNOWN_TAG

SET_TAG_SAMPLE_INTERVALS

This request allows to modify the tag’s update intervals. Note that actual update interval may be longer due to radio overload, which happens when too many tags are alive and configured for too frequent updates (i.e. have too short update intervals). Also note that response to this request does not check if the tag’s update intervals could actually be updated, only if processing the request was successful.

When receiving this request, the system stores the new desired update interval values in its database. As the actual configuration change happens over UWB radio link, this can be done only in case the tag is online. If the tag is currently offline or there are radio coverage problems, the system keeps trying to update the tag’s configuration as long as it finally succeeds. Note that for tags, which were previously working with long update intervals, this might take a lot of time.

To check the status of sample interval update, use the GET_TAG_SAMPLE_INTERVALS request.

Client sends:

$PEKIO,SET_TAG_SAMPLE_INTERVALS,<parameter list>

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

Field name	Explanation	Examples
Tag’s Serial Number OR Tag group ID OR The keyword “ALL”	Can be one of the following: Tag’s serial number for which the update intervals will be set. Tag group ID preceded by the flag “TG” and a semicolon Keyword “ALL” to set the update intervals for all the tags in the database.	0x123464 TG;1 ALL
Tag’s New Update Interval High	New Update Interval High in milliseconds. This value is used when the tag is moving. Please note that setting a large value (i.e. longer interval) here makes further configuration changes over UWB radio link very time consuming – this can happen only after the next “update blink” from the tag.	100
Tag’s New Update Interval Low	New Update Interval Low in milliseconds. This value is used when the tag is in standstill. Setting this value to be longer than the Tag’s Update Interval High helps to reduce UWB radio load and conserves battery power when the tag is not moving. Setting this value equal to the Update Interval High disables the dynamic update rate functionality. Otherwise Update Interval Low must always be longer than Update Interval High.	1000
Tag’s New Update Interval No Response	New Update Interval No Response in milliseconds. This value is used when the tag has reached the hard-coded limit of missed responses from anchors, which usually happens when it moves outside of the anchors' signal coverage area, i.e. there are no valid anchors in the range. This is an optional parameter and may be omitted. The value range is 10 - 60000 ms and the default value is 15000 ms.	15000

For all update intervals, values from 10 to 60000 ms are allowed. But please note that when using small values for tag’s update interval (i.e. shorter intervals), the real update interval may be longer due to UWB radio load, national RF regulations and system performance.

Update interval values longer than 60000 ms (which corresponds to one minute) do not make sense, as it does not help to conserve more power and would make further configuration changes over UWB radio link very time consuming.

A full example of client’s request would be:

$PEKIO,SET_TAG_SAMPLE_INTERVALS,0x003464,100,1000,10000

If processing the request was successful, the system responds:

$PEKIO,OK

If the system encountered an error when 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_PERIOD_HI	Could not parse the Interval High value.
NO_PERIOD_LO	Could not parse the Interval Low value.
WRONG_PERIOD_HI	The Interval High value is out of bounds (10 to 60000 ms).
WRONG_PERIOD_LO	The Interval Low value is out of bounds (10 to 60000 ms).
PARAMS_ORDER	The Interval High value is longer than Interval Low value.
NO_PERIOD_NR	The given value of No Response Interval could not be parsed as integer.
WRONG_PERIOD_NR	The given value of No Response Interval is out of bounds (10 to 60000 ms).
<tag addressing errors>	In case there was a problem with tag addressing, the common error messages described in chapter “Tag Addressing” may also appear.

Some full examples of the system’s error responses would be:

$PEKIO,NOT_GOOD,WRONG_PERIOD_HI

$PEKIO,NOT_GOOD,UNKNOWN_TAG

GET_TAG_SAMPLE_INTERVALS

This request allows the client to ask for tag’s update interval values and check the status of updating them.

Client sends:

$PEKIO,GET_TAG_SAMPLE_INTERVALS,<optional parameter>

<optional parameter> has the following meaning:

Field name

Explanation

Examples

Tag’s Serial Number

Tag group ID

The keyword “ALL”

Can be one of the following:

Tag’s serial number to be queried.
Tag group ID preceded by the flag “TG” and a semicolon
Keyword “ALL” to query all the tags in the database (the same can be achieved by just omitting this parameter).

0x123464

TG;1

ALL

Some full examples of client requests would be:

$PEKIO,GET_TAG_SAMPLE_INTERVALS

$PEKIO,GET_TAG_SAMPLE_INTERVALS,ALL

$PEKIO,GET_TAG_SAMPLE_INTERVALS,0x001E38

$PEKIO,GET_TAG_SAMPLE_INTERVALS,TG;3

If processing the request was successful, the system responds with one row per tag and terminates the list with special EOF marker:

$PEKIO,TAG_SAMPLE_INTERVALS,<parameter list>

$PEKIO,TAG_SAMPLE_INTERVALS,<parameter list>

...

$PEKIO,EOF

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

Field name	Explanation	Example
Tag’s Serial Number	A 24-bit identifier that is unique among all the produced RTLS tags, in 6-digit hexadecimal format. The Serial Number does not change during the whole life cycle of the tag and can thus be used to uniquely identify it.	0x003464
Tag’s Alias	A human-readable alias for the tag. Empty when not set.	Peter’s wristband
Keyword “HIGH”	“HIGH” – the keyword that specifies the meaning for the next three values. To enable future compatibility, the client should parse all the parameters following the “Tag’s Alias” by searching the keywords “HIGH” and “LOW”. When found, the following three values should be associated with that keyword. Unknown keywords should be skipped when parsing.	HIGH
Tag’s Desired Update Interval High	A value in milliseconds for the Tag’s Update Interval High that the user has set by the SET_TAG_SAMPLE_INTERVALS request. In case the user has not ever set a value for this tag, a value of 0 is used here. Note that this might not yet be the value actually configured into the tag, but is a value that the system tries to configure into the tag as soon as possible.	100
Tag’s Configured Update Interval High	A value in milliseconds that is actually configured into the tag as the Update Interval High. If this value is unknown, a value of 0 is used. This might happen after the tag comes online and the system has not yet asked for its update intervals. Depending on the UWB radio load, tag’s actual update intervals and radio link quality, it may take some time for this information to reach the system. In case this value is different from the Tag’s Desired Update Interval High, the system tries to configure the tag as soon as possible to match the Desired value. Note that this happens only in case the Desired value is greater than 0, which means the user has actually set a Desired value by using the SET_TAG_SAMPLE_INTERVALS request.	200
Tag’s Update Interval High Status	An integer that allows to get information about Tag’s Update Interval High Status: 0 – No Desired value has been set by the user. 1 – Desired value has been set, but the Tag’s Configured Update Interval High is not yet known. This might happen if the tag is offline or after it has come online, but the value has not yet been queried. 2 – User has set a new Desired value, but the system has not yet sent the command to the tag. 3 – System has sent the command to the tag, but this has not yet been acknowledged by the tag. 4 – Tag has acknowledged the Update Interval High update command, but the value is not yet verified. 5 – System has verified that the Update Interval High value configured into the tag matches the Desired value set by the user.	3
Keyword “LOW”	“LOW” – the keyword that specifies the meaning for the next three values. To enable future compatibility, the client should parse all the parameters following the “Tag’s Alias” by searching the keywords “HIGH” and “LOW”. When found, the following three values should be associated with that keyword. Unknown keywords should be skipped when parsing.	LOW
Tag’s Desired Update Interval Low	A value in milliseconds for the tag’s Update Interval Low that the user has set by the SET_TAG_SAMPLE_INTERVALS request. In case the user has not ever set a value for this tag, a value of 0 is used here. Note that this might not yet be the value actually configured into the tag, but is a value that the system tries to configure into the tag as soon as possible.	1000
Tag’s Configured Update Interval Low	A value in milliseconds that is actually configured into the tag as Update Interval Low. If this value is unknown, a value of 0 is used. This might happen after the tag comes online and the system has not yet asked for its update intervals. Depending on the UWB radio load, tag’s actual update intervals and radio link quality, it may take some time for this information to reach the system. In case this value is different from the Tag’s Desired Update Interval Low, the system tries to configure the tag as soon as possible to match the Desired value. Note that this happens only in case the Desired value is greater than 0, which means the user has actually set a Desired value by using the SET_TAG_SAMPLE_INTERVALS request.	1000
Tag’s Update Interval Low Status	An integer that allows to get information about Tag’s Update Interval Low Status: 0 – No Desired value has been set by the user. 1 – Desired value has been set, but the Tag’s Configured Update Interval Low is not yet known. This might happen if the tag is offline or after it has come online, but the value has not yet been queried. 2 – User has set a new Desired value, but the system has not yet sent the command to the tag. 3 – System has sent the command to the tag, but this has not yet been acknowledged by the tag. 4 – Tag has acknowledged the Update Interval Low update command, but the value is not yet verified. 5 – System has verified that the Update Interval Low value configured into the tag matches the Desired value set by the user.	5
Keyword “NO_R”	“NO_R” – the keyword that specifies the meaning for the next three values. To enable future compatibility, the client should parse all the parameters following the “Tag’s Alias” by searching the keyword “NO_R”. When found, the following three values should be associated with that keyword. Unknown keywords should be skipped when parsing.	NO_R
Tag’s Desired Update Interval No Response	A value in milliseconds for the tag’s Update Interval No Response that the user has set by the SET_TAG_SAMPLE_INTERVALS request. Note that this might not yet be the value actually configured into the tag, but is a value that the system tries to configure into the tag as soon as possible.	10000
Tag’s Configured Update Interval No Response	A value in milliseconds that is actually configured into the tag as Update Interval No Response. Depending on the UWB radio load, tag’s actual update intervals and radio link quality, it may take some time for this information to reach the system. In case this value is different from the Tag’s Desired Update Interval No Response, the system tries to configure the tag as soon as possible to match the Desired value set by the SET_TAG_SAMPLE_INTERVALS request.	10000
Tag’s Update Interval No Response Status	An integer that allows to get information about Tag’s Update Interval No Response Status: 0 – No Desired value has been set by the user. 1 – Desired value has been set, but the Tag’s Configured Update Interval No Response is not yet known. This might happen if the tag is offline or after it has come online, but the value has not yet been queried. 2 – User has set a new Desired value, but the system has not yet sent the command to the tag. 3 – System has sent the command to the tag, but this has not yet been acknowledged by the tag. 4 – Tag has acknowledged the Update Interval No Response update command, but the value is not yet verified. 5 – System has verified that the Update Interval No Response value configured into the tag matches the Desired value set by the user.	5

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

$PEKIO,TAG_SAMPLE_INTERVALS,0x000453,MyTag,HIGH,100,200,3,LOW,1000,2000,3,NO_R,10000,15000,3

$PEKIO,TAG_SAMPLE_INTERVALS,0x000462,,HIGH,200,200,5,LOW,2000,2000,5,NO_R,5000,5000,5

...

$PEKIO,EOF

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

$PEKIO,NOT_GOOD,<error ID>

Possible values for the <error ID> field are defined in chapter “Tag Addressing”.

A full example of error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_TAG

REMOVE_TAGS

This request allows to remove tags from the database. Tags are added into the database automatically when they first appear online. When a tag is not needed anymore, it can be removed from the database with REMOVE_TAGS. This may be the case when a tag was used in the system just for testing purposes or when a tag is not used in the system any more. Note that when removing a tag that is currently online, it will be removed from the database, but added back automatically when the next ranging report from that tag arrives to the system. Depending on the tag’s update interval, this might happen virtually at once. Also note that by removing a tag from the database, the settings done previously by requests SET_TAG_ALIAS, SET_TAG_PARAMS, and SET_TAG_SAMPLE_INTERVALS will be lost.

Client sends:

$PEKIO,REMOVE_TAGS,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Examples

Tag’s Serial Number

Tag group ID

The keyword “ALL”

Can be one of the following:

Tag’s serial number to be removed.
Tag group ID preceded by the flag “TG” and a semicolon
Keyword “ALL” to remove all the tags from the database.

0x123464

TG;1

ALL

Some full examples of client requests would be:

$PEKIO,REMOVE_TAGS,0x003464

$PEKIO,REMOVE_TAGS,ALL

$PEKIO,REMOVE_TAGS,TG;2

If the removal was successful, the system responds:

$PEKIO,OK

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

$PEKIO,NOT_GOOD,<error ID>

Possible values for the <error ID> field are defined in chapter “Tag Addressing”.

A full example of error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_TAG

Tag groups

Introduction to tag groups

Tags can be grouped in the Eliko RTLS, so that the parameter changes can be simultaneously applied to all the tags belonging to a particular group. This feature can be useful when configuring different settings for different categories of tags: for example, to set up different fixed height values for tags on humans and vehicles.

Like anchor groups, tag groups also have priorities. There is a limitation in the Eliko RTLS: one tag can belong to multiple tag groups with different priorities but it cannot belong to multiple tag groups with equal priority.

ADD_TAG_GROUP

This request is used to create a new tag group in the RTLS.

Client sends:

$PEKIO,ADD_TAG_GROUP,<parameter list>

<parameter list> contains the following fields:

Field name	Explanation	Example
Tag group ID	Tag group ID. The ID value must be unique within the RTLS. Can be omitted, in this case it is generated automatically by the RTLS. The value 0 cannot be used, it is reserved for the default tag group “ALL”.	1
Alias name	A human-readable alias name, mandatory parameter. Cannot contain quotes or spaces. Must be unique within the RTLS.	Players
Priority	A numeric float value. Higher value means higher priority. NB! A tag can belong to multiple tag groups with different priorities but it cannot belong to multiple tag groups with equal priority.	1.5

Some full examples of client requests would be:

$PEKIO,ADD_TAG_GROUP,,Vehicles,1

$PEKIO,ADD_TAG_GROUP,5,Team5,2

If processing the request was successful, the system responds:

$PEKIO,OK,<parameter>

<parameter> has the following meaning:

Field name	Explanation	Example
Tag group ID	The unique numeric ID of the tag group in the RTLS	1

An example of the system’s response would be:

$PEKIO,OK,5

In case there was an error when 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
ID_ALREADY_EXISTS	The given tag group ID value is already in use
CANNOT_PARSE_ID	Problem with the ID field (e.g. the ID was given in a non-integer format)
NAME_ALREADY_EXISTS	The given tag group name value is already in use
NAME_INCOMPATIBLE	The tag group name contains unaccepted symbols (e.g. quotes or spaces)
NAME_MISSING	The mandatory tag group name value is missing
PRIORITY_MISSING	The mandatory priority value is missing
CANNOT_PARSE_PRIORITY	Problem with the priority field (e.g. a non-numeric value given)

A full example of error response would be:

$PEKIO,NOT_GOOD,PRIORITY_MISSING

GET_TAG_GROUPS

This request allows to query the list of known tag groups from the system.

Client sends:

$PEKIO,GET_TAG_GROUPS,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Tag group ID

The keyword “ALL”

Can be one of the following:

Tag group ID (numeric value)
Keyword “ALL” to query all the tag groups in the database. NB! The same can be achieved by just omitting this parameter.

ALL

Some full examples of client requests would be:

$PEKIO,GET_TAG_GROUPS,1

$PEKIO,GET_TAG_GROUPS,ALL

If processing the request was successful, the system responds with a TAG_GROUP message:

$PEKIO,TAG_GROUP,<parameter list>

<parameter list> contains the same fields as used in ADD_TAG_GROUP request:

Field name	Explanation	Example
Tag group ID	Tag group ID, unique within the RTLS.	1
Alias name	A human-readable alias name, unique within the RTLS.	Players
Priority	Tag group priority, real number. Higher value means higher priority.	1.5

An example of the system’s response would be:

$PEKIO,TAG_GROUP,5,Team5,2.000000

If there was an error when 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_GROUP_ID	Problem with parsing the ID field (e.g. the ID was given in a non-integer format)
UNKNOWN_ID	The group with given ID does not exist

A full example of error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_ID

GET_TAG_GROUPS_WM

This request is an extension of the regular GET_TAG_GROUPS command and allows to query the list of known tag groups with the list of tag belonging to each group from the system.

Client sends:

$PEKIO,GET_TAG_GROUPS_WM,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Tag group ID

The keyword “ALL”

Can be one of the following:

Tag group ID (numeric value)
Keyword “ALL” to query all the tag groups in the database. NB! The same can be achieved by just omitting this parameter.

ALL

Some full examples of client requests would be:

$PEKIO,GET_TAG_GROUPS_WM,1

$PEKIO,GET_TAG_GROUPS_WM,ALL

If processing the request was successful, the system responds with a TAG_GROUP message:

$PEKIO,TAG_GROUP,<parameter list>

<parameter list> contains the same fields as used in the TAG_GROUP response to the GET_TAG_GROUPS request plus additional fields related to group members (tags):

Field name	Explanation	Example
Tag group ID	Tag group ID, unique within the RTLS.	1
Alias name	A human-readable alias name, unique within the RTLS.	Team1
Priority	Tag group priority, real number. Higher value means higher priority.	1.5
Keyword “MEMBERS”	This keyword is used as a flag to indicate the beginning of a semicolon-separated list of the tags belonging to the group	MEMBERS
Member list	A semicolon-separated list of the serial numbers of the tags belonging to the group	0x001234;0x005678;0x00ABCD

An example of the system’s response would be:

$PEKIO,TAG_GROUP,4,Team4,2.000000,MEMBERS,0x000125;0x000210;0x0003C2;

If there was an error when 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_GROUP_ID	Problem with parsing the ID field (e.g. the ID was given in a non-integer format)
UNKNOWN_ID	The group with given ID does not exist

A full example of error response would be:

$PEKIO,NOT_GOOD,NO_GROUP_ID

REMOVE_TAG_GROUP

This request allows to remove tag groups from the system. Please note that removing a tag group would also automatically remove any tag’s membership information with regards to that group.

Client sends:

$PEKIO,REMOVE_TAG_GROUP,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Tag group ID

The keyword “ALL”

Can be one of the following:

Tag group ID (numeric value)
Keyword “ALL” to remove all the tag groups from the system

ALL

A client request example would be:

$PEKIO,REMOVE_TAG_GROUP,5

If processing the request was successful, the system responds:

$PEKIO,OK,<parameter>

<parameter> has the following meaning:

Field name	Explanation	Example
Tag group ID	The unique numeric ID of the tag group in the RTLS	1

An example of the system’s response would be:

$PEKIO,OK,5

If there was an error when 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
WRONG_NUMBER_OF_PARAMETERS	The command was given without any tag group addressing
NO_SUCH_GROUP	No group with a given ID exists in the system
NO_GROUP_ID	There was a problem with parsing of the id field, e.g. due to wrong format
ALWAYS_PRESENT	This error code appears when trying to remove the default group with ID 0 aka automatic “ALL”-group

A full example of error response would be:

$PEKIO,NOT_GOOD,NO_SUCH_GROUP

ADD_TAG_TO_GROUP

This request is used to add a new tag to a group in the RTLS.

Client sends:

$PEKIO,ADD_TAG_TO_GROUP,<parameter list>

<parameter list> contains the following fields:

Field name

Explanation

Example

Tag’s Serial Number

Tag’s serial number, mandatory parameter. The value “ALL” cannot be used. One tag can be added to a group at a time with this request.

NB! A tag can belong to multiple tag groups with different priorities but it cannot belong to multiple tag groups with equal priority. If a tag already belongs to another group with the same priority, it will be automatically removed from that group with this command.

0x1234

Tag group ID

Tag group ID, mandatory parameter. The value 0 cannot be used, it is reserved for the default tag group “ALL”.

A client request example would be:

$PEKIO,ADD_TAG_TO_GROUP,0x1A2B,3

If processing the request was successful, the system responds:

$PEKIO,OK

If there was an error when 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_MEMBER_ID	Tag serial number is either missing or there are problems with parsing this field, e.g. when 'ALL' is provided instead of a serial number.
UNKNOWN_TAG	The tag with the given serial number does not exist in the RTLS
NO_GROUP_ID	The group ID is missing
NO_SUCH_GROUP	The tag group with the given ID does not exist in the RTLS
GROUP_ID_PARSING	Cannot parse the tag group id field normally
ALREADY_IN_GROUP	The given tag already belongs to the group

A full example of error response would be:

$PEKIO,NOT_GOOD,NO_SUCH_GROUP

REMOVE_TAG_FROM_GROUP

This request is used to remove a tag from a group in the RTLS.

Client sends:

$PEKIO,REMOVE_TAG_FROM_GROUP,<parameter list>

<parameter list> contains the following fields:

Field name

Explanation

Example

Tag’s Serial Number

The keyword “ALL”

Can be one of the following:

Tag’s serial number to be removed.
Keyword “ALL” to remove all the tags from the group

0x1A2B

ALL

Tag group ID

Tag group ID, mandatory parameter. The value 0 cannot be used, it is reserved for the default tag group “ALL”.

A client request example would be:

$PEKIO,REMOVE_TAG_FROM_GROUP,0x01AC,3

If processing the request was successful, the system responds:

$PEKIO,OK

If there was an error when 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_MEMBER_ID	Tag serial number missing or there are problems with parsing this field
UNKNOWN_TAG	The anchor with the given serial number does not exist in the RTLS
NO_GROUP_ID	The group ID is missing
NO_SUCH_GROUP	The tag group with the given ID does not exist in the RTLS
GROUP_ID_PARSING	Cannot parse the tag group id field normally
ALWAYS_IN_GROUP	This error code appears when trying to remove a tag from the default group with ID 0 aka automatic “ALL”-group
WAS_NOT_A_MEMBER	The given tag was not a member of the group

A full example of error response would be:

$PEKIO,NOT_GOOD,ALWAYS_IN_GROUP

GET_TAG_IN_GROUPS

This request is used to query all the tag groups in the RTLS that a given tag belongs to.

Client sends:

$PEKIO,GET_TAG_IN_GROUPS,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Tag’s serial number

The keyword “ALL”

Can be one of the following:

Tag’s serial number

Keyword “ALL” to query groups for all the tags in the RTLS.

NB! This field cannot be omitted

0x001B

ALL

Some full examples of client requests would be:

$PEKIO,GET_TAG_IN_GROUPS,0x001B

$PEKIO,GET_TAG_IN_GROUPS,ALL

If processing the request was successful, the system responds with an IN_GROUPS message (or a list of IN_GROUPS messages with one row per tag in case of addressing the request to ‘ALL’) terminated by the special EOF marker:

$PEKIO,IN_GROUPS,<parameter list>

<parameter list> contains the following fields:

Field name

Explanation

Example

Tag’s serial number

0x001B

Tag group ID-s

A comma-separated list of the ID-s of all tag groups that the given tag belongs to.

NB! The default tag group with ID 0 is not returned in the IN_GROUPS response. If a tag does not belong to any group, its serial number appears in the IN_GROUPS response without any group ID

1,4,8

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

$PEKIO,IN_GROUPS,0x000025,3,5,7

$PEKIO,IN_GROUPS,0x00002B

$PEKIO,EOF

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

$PEKIO,NOT_GOOD,<error ID>

<error ID> has the following meaning:

Error ID	Explanation
UNKNOWN_TAG	The given tag ID was either left empty in the request or missing in the system

A full example of error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_TAG

GET_TAGS_IN_AG

This request is used to query all the tags in the given anchor group area.

Client sends:

$PEKIO,GET_TAGS_IN_AG,<parameter>

<parameter> has the following meaning:

Field name

Explanation

Example

Anchor group ID

Anchor group ID, mandatory parameter. The value 0 cannot be used, it is reserved for the default anchor group “ALL”.

Only one anchor group ID can be used with this command.

A full example a of client request would be:

$PEKIO,GET_TAGS_IN_AG,5

If processing the request was successful, the system responds with a TAG_AG message (or a list of TAG_AG messages with one row per tag in case of multiple tags located in an anchor group) terminated by the special EOF marker:

$PEKIO,TAG_AG,<parameter list>

<parameter list> contains the following fields:

Field name	Explanation	Example
Tag’s serial number	Tag’s serial number	0x001B
Anchor group ID	The ID of the queried anchor group	5

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

$PEKIO,TAG_AG,0x001591,1769598284.654039,5

$PEKIO,TAG_AG,0x0017F2,1769598284.257325,5

$PEKIO,EOF

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

$PEKIO,NOT_GOOD,<error ID>

<error ID> has the following meaning:

Error ID	Explanation
REDUNDANT_PARAMETERS	Either no anchor group ID was given or there were more than one anchor group ID-s given with the command.
GROUP_ID_PARSING	There was an error parsing the anchor group ID, most likely due to a wrong format (other than integer).
UNKNOWN_GROUP	The anchor group ID addressing field was successfully parsed, but there is no such anchor group in the RTLS’s database.

A full example of error response would be:

$PEKIO,NOT_GOOD,UNKNOWN_GROUP