Anchor addressing
There are several anchor-related requests that are meant to manipulate or read back parameters of certain anchors. The most basic way of addressing the anchors is to use its 24-bit unique serial number, which is expressed in a 6-digit hexadecimal format. Another way is to address a request using an anchor group ID with the keyword “AG” followed by a semicolon (instead of the anchor’s serial number) to indicate that the request should be applied to all the anchors belonging to a particular group. Additionally, some requests allow to use the keyword “ALL” (instead of the anchor’s serial number or group ID), to indicate the request should be applied to all the anchors present in the RTLS’s database.
The different options to address the anchor(s) via these requests are as follows:
|
Method |
Description |
Example |
|
Single anchor addressing |
The anchor’s 24-bit unique serial number, in 6-digit hexadecimal format is used to address the anchor. |
0x001A75 |
|
Anchor group addressing |
The anchor group numeric (integer) ID is used to address all the anchors belonging to a given group. Preceded by the flag “AG” and a semicolon. |
AG;1 |
|
ALL |
The keyword “ALL” is used to address all the anchors present in the RTLS’s database. |
ALL |
When using the requests listed above, there are some common error messages related to anchor 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 anchor 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 anchor(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 anchor addressing field looks like an anchor’s serial number, but there was an error parsing this. |
|
UNKNOWN_ANCHOR |
The anchor addressing field was successfully parsed as an anchor’s serial number, but there is no such anchor in the RTLS’s database. |
|
GROUP_ID_MISSING |
The field that should address the anchor 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 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. |
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 anchor addressing.
Main commands
GET_ANCHORS
This request allows to query the list of known anchors from the system. Anchors are added into the database automatically after they first time appear online.
When an anchor is powered up and connected to the RTLS Server machine’s anchor network, it automatically creates a TCP connection to the system. The anchor’s parameters are then queried by the system and stored into the database.
When the client uses the GET_ANCHORS request, the system responds with list of known anchors. These are anchors that the server has seen online after the initial system setup or the last flush of the database. If needed, the client may also remove anchors from the database. This can be done one-by-one or all at once. See request REMOVE_ANCHORS for more information.
Client sends:
$PEKIO,GET_ANCHORS,<optional parameter>
<optional parameter> has the following meaning:
|
Field name |
Explanation |
Examples |
|
Anchor’s Serial Number OR Anchor group ID OR The keyword “ALL” |
Can be one of the following:
|
0x123464 AG;1 ALL |
Some full examples of client requests would be:
$PEKIO,GET_ANCHORS
$PEKIO,GET_ANCHORS,AG;1
$PEKIO,GET_ANCHORS,ALL
$PEKIO,GET_ANCHORS,0x001E38
If processing the request was successful, the system responds with one NMEA sentence per anchor and terminates the list with special EOF marker:
$PEKIO,ANCHOR_COORD,<parameter list>
$PEKIO,ANCHOR_COORD,<parameter list>
...
$PEKIO,EOF
For <parameter list>, please see the separate chapter for ANCHOR_COORD response/report.
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 “Anchor Addressing”.
A full example of error response would be:
$PEKIO,NOT_GOOD,ID_PARSING
ANCHOR_COORD
This is a response sent back by the system after receiving the GET_ANCHORS request. ANCHOR_COORD is also an asynchronous report sent by the system, when the client has asked this by the NOTIFICATIONS request and the connection state with that anchor changes.
The system sends:
$PEKIO,ANCHOR_COORD,<parameter list>
<parameter list> is a comma-separated list with the following fields:
|
Field name |
Explanation |
Example |
|
Anchor’s Radio ID |
This is a 16-bit identifier that is used to identify the anchor in the radio protocol. The system is responsible for assigning these IDs in a way they would be unique in one RTLS and may change them during operation, whenever needed. Generally, the outside entities should NOT use the Radio ID for identifying the anchors. They should use the Serial Number field instead! |
0x100F |
|
Anchor’s Role |
One capital letter that identifies the anchor role. Note that from RTLS Server software version 2.5.4, the concept of roles is not used any more. In such case, all the anchors will be shown as having the role “A”. |
A |
|
Anchor’s Serial Number |
A 24-bit identifier that is unique among all the produced RTLS anchors, in 6-digit hexadecimal format. The Serial Number does not change during the whole life cycle of the anchor and can thus be used to uniquely identify it. |
0x123464 |
|
Anchor’s Position |
The X, Y and Z coordinates of the anchor, expressed in meters. In case the user has not yet set these values, empty fields will be sent. |
21.00,-12.08,2.08 |
|
Anchor’s last connection established time |
Unix Timestamp when the connection to that anchor was last established. In case the anchor was never seen online after the last flush of the database, a value of 0 will be sent. |
15123213123 |
|
Anchor’s last connection lost time |
Unix Timestamp when the connection to that anchor was lost for the last time. In case the anchor was never seen online after the last flush of the database or in case the anchor is currently online, a value of 0 will be sent. |
15232344223 |
|
Anchor’s connection state |
A one-digit number:
|
3 |
Some full examples of the system responses:
$PEKIO,ANCHOR_COORD,0x100F,A,0x123464,21.00,12.08,2.08,15123213123,0,3
$PEKIO,ANCHOR_COORD,0x1010,A,0x123467,23.73,2.16,0.62,15123231232,15232344223,0
$PEKIO,ANCHOR_COORD,0x0023,A,0x123473,,,,0,0,0
GET_ANCHORS_E
This request allows to query the list of known anchors from the system. The request is similar to GET_ANCHORS, but retrieves more information for the anchors. Anchors are added into the database automatically after they first time appear online.
When an anchor is powered up and connected to the RTLS Server machine’s anchor network, it automatically creates a TCP connection to the system. The anchor’s parameters are then queried by the system and stored into the database.
When the client uses the GET_ANCHORS_E request, the system responds with list of known anchors. These are anchors that the system has seen online after its initial setup or last flush of the database. If needed, the client may also remove anchors from the database. This can be done one-by-one or all at once. See the request REMOVE_ANCHORS for more information.
Client sends:
$PEKIO,GET_ANCHORS_E,<optional parameter>
<optional parameter> has the following meaning:
|
Field name |
Explanation |
Examples |
|
Anchor’s Serial Number OR Anchor group ID OR The keyword “ALL” |
Can be one of the following:
|
0x123464 AG;1 ALL |
Some full examples of client requests would be:
$PEKIO,GET_ANCHORS_E
$PEKIO,GET_ANCHORS_E,AG;1
$PEKIO,GET_ANCHORS_E,ALL
$PEKIO,GET_ANCHORS_E,0x001E38
If processing the request was successful, the system responds with one NMEA sentence per anchor and terminates the list with special EOF marker:
$PEKIO,ANCHOR_COORD_E,<parameter list>
$PEKIO,ANCHOR_COORD_E,<parameter list>
...
$PEKIO,EOF
For <parameter list>, please see the separate chapter for ANCHOR_COORD_E response.
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 “Anchor Addressing”.
A full example of error response would be:
$PEKIO,NOT_GOOD,ID_PARSING
ANCHOR_COORD_E
This is a response sent back by the system after receiving the GET_ANCHORS_E request.
The system sends:
$PEKIO,ANCHOR_COORD_E,<parameter list>
<parameter list> is a comma-separated list with the following fields:
|
Field name |
Explanation |
Example |
|
Anchor’s Radio ID |
This is a 16-bit identifier that is used to identify the anchor in the radio protocol. The system is responsible for assigning these IDs in a way they would be unique in one RTLS and may change them during operation, whenever needed. Generally, the outside entities should NOT use the Radio ID for identifying the anchors. They should use the Serial Number field instead! |
0x100F |
|
Anchor’s Role |
One capital letter that identifies the anchor role. Note that from RTLS Server software version 2.5.4, the concept of roles is not used any more. In such case, all the anchors will be shown as having the role “A”. |
A |
|
Anchor’s Serial Number |
A 24-bit identifier that is unique among all the produced RTLS anchors, in 6-digit hexadecimal format. The Serial Number does not change during the whole life cycle of the anchor and can thus be used to uniquely identify it. |
0x123464 |
|
System’s Cell Size |
In general, Cell Size is a system-wide parameter from 4 to 10. But as all the anchors need to know the cell size, this value here allows to check if the specific anchor has been correctly configured. |
4 |
|
Anchor’s Hardware Version |
Hardware version number of the anchor. |
3 |
|
Anchor’s Software Version |
Software version number of the anchor. |
3.2.0-abd10df0 |
|
Anchor’s Model String |
Model string of the anchor. |
KA334UE |
|
Anchor’s Position |
The X, Y and Z coordinates of the anchor, expressed in meters. In case the user has not yet set these values, empty fields will be sent. |
21.00,-12.08,2.08 |
|
Anchor’s last connection established time |
Unix Timestamp when the connection to that anchor was last established. In case the anchor was never seen online after the last flush of the database, a value of 0 will be sent. |
15123213123 |
|
Anchor’s last connection lost time |
Unix Timestamp when the connection to that anchor was lost for the last time. In case the anchor was never seen online after the last flush of the database or in case the anchor is currently online, a value of 0 will be sent. |
15232344223 |
|
Anchor’s connection state |
A one-digit number:
|
3 |
Some full examples of the system responses:
$PEKIO,ANCHOR_COORD_E,0x100F,A,0x123464,4,3,3.2.0-abd10df0,KA334UE, 21.00,12.08,2.08,15123213123,0,3
$PEKIO,ANCHOR_COORD_E,0x1010,A,0x123467,4,3,3.2.0-abd10df0,KA334UE, 23.73,2.16,0.62,15123231232,15232344223,0
SET_ANCHOR
This request allows to set the anchor coordinates during initial system setup or after the anchor was physically moved to a new location. Note that it is not possible to add a new anchor into the database with the SET_ANCHOR request, only modify its position. The anchor must be present in the database before using this request. Anchors are added into the database automatically after they first time appear online.
Client sends:
$PEKIO,SET_ANCHOR,<parameter list>
<parameter list> is a comma-separated list with the following fields:
|
Field name |
Explanation |
Examples |
|
Anchor’s Serial Number OR Anchor group ID OR The keyword “ALL” |
Can be one of the following:
|
0x123464 AG;1 ALL |
|
Anchor’s Position |
The X, Y and Z coordinates of the anchor, expressed in meters. When the values are left empty (i.e. the request contains only commas with nothing in between them), the request is meant to remove the existing coordinates from the anchor. This may be useful in case the anchor has or will be moved to a new location, but its new coordinates are not yet known. In such case, the distances measured by this anchor are not used for coordinate calculation (and thus, the anchor does not disturb the overall positioning mechanism). |
21.00,-12.08,2.08 ,, |
Some full examples of client requests would be:
$PEKIO,SET_ANCHOR,0x001234,3,4,5.2
$PEKIO,SET_ANCHOR,AG;1,,,
$PEKIO,SET_ANCHOR,ALL,,,
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_X_COORDINATE |
The X coordinate could not be parsed from the request. |
|
NO_Y_COORDINATE |
The Y coordinate could not be parsed from the request. |
|
NO_Z_COORDINATE |
The Z coordinate could not be parsed from the request. |
|
MUST_ADDRESS_BY_DEVICE |
Trying to address ALL the anchors or an anchor group to set the coordinates. This is allowed only for removing the coordinates, not for setting them. |
|
<anchor addressing errors> |
In case there was a problem with anchor addressing, the common error messages described in chapter “Anchor Addressing” may also appear. |
Some full examples of the system’s error responses would be:
$PEKIO,NOT_GOOD,NO_Y_COORDINATE
$PEKIO,NOT_GOOD,UNKNOWN_ANCHOR
REMOVE_ANCHORS
This request allows to remove one or more anchors from the database. Anchors are added into the database automatically when they first appear online. When an anchor is not needed any more, it can be removed from the database with REMOVE_ANCHORS. This may be the case when some anchors were used in the system just for testing purposes or when the anchor layout is modified and some anchors are not needed in the system anymore. Note that only offline anchors can be removed with this request!
Client sends:
$PEKIO,REMOVE_ANCHORS,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor’s Serial Number OR Anchor group ID OR The keyword “ALL” |
Can be one of the following:
|
0x123464 AG;1 ALL |
Some full examples of client requests would be:
$PEKIO,REMOVE_ANCHORS,0x112233
$PEKIO,REMOVE_ANCHORS,AG;1
$PEKIO,REMOVE_ANCHORS,ALL
If processing the request was successful, the response described below will be sent. The response contains one line for each anchor previously present in the system, which indicate their removal status. The list is terminated by the EOF marker:
$PEKIO,REMOVING,<parameter list>
$PEKIO,REMOVING,<parameter list>
...
$PEKIO,EOF
<parameter list> contains the following fields:
|
Field name |
Explanation |
Example |
|
Anchor’s Serial Number |
The Anchor’s serial number that was attempted to be deleted. |
0x123464 |
|
Removal status |
“OK” if removing the anchor succeeded, “NOT_GOOD” otherwise. |
NOT_GOOD |
|
Error IDs |
Error IDs is a comma-separated list of error messages that appeared when trying to remove the anchor. This field is optional – present only in case the removal status was NOT_GOOD. |
UNKNOWN_ID |
<error ID> can be one of the following:
|
Error ID |
Explanation |
|
ANCHOR_STILL_ONLINE |
The anchor can’t be removed because it is still online. |
|
ANCHOR_PRESENT_IN_RADIUS_MAP |
The anchor can’t be removed because it is present in the radius map. |
|
ANCHOR_PRESENT_IN_1D_AREA_MAP |
The anchor can’t be removed because it is present in the 1D area map. |
|
ANCHOR_PRESENT_IN_CORRIDOR |
The anchor can’t be removed because it is used for corridor mode functionality. |
Note that when the system encounters the ANCHOR_STILL_ONLINE error, other errors are not checked. This means the ANCHOR_STILL_ONLINE error would appear in the response alone. The last three errors described in the table above act differently – they can appear simultaneously and if they do, will be included in the response as a comma-separated list.
A full example of the system’s response would be:
$PEKIO,REMOVING,0x0067AB,OK
$PEKIO,REMOVING,0x000988,NOT_GOOD,ANCHOR_STILL_ONLINE
$PEKIO,REMOVING,0x0009B7,NOT_GOOD,ANCHOR_PRESENT_IN_1D_AREA_MAP, ANCHOR_PRESENT_IN_CORRIDOR
$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 “Anchor Addressing”.
A full example of error response would be:
$PEKIO,NOT_GOOD,ID_PARSING
Anchor groups
Introduction to anchor groups
Anchors can be grouped in the Eliko RTLS, so that different ranging settings can be applied to the tags served by each anchor group. This feature can be useful in multi-floor deployment scenarios, when the anchors are grouped by their floors and the tags positioning in 2D mode need to adjust their fixed height according to their floor level (i.e. to the group of anchors they are currently ranging with).
The tag settings are adjusted by the API commands associated with a particular anchor group. These API commands are configured by user and automatically executed by the system when a tag starts or finishes ranging with the anchors belonging to the group. The same command execution concept is used in the geofencing subsystem (see “RTLS Zones and Geofencing” section for more details).
ADD_ANCHOR_GROUP
This request is used to create a new anchor group in the RTLS.
Client sends:
$PEKIO,ADD_ANCHOR_GROUP,<parameter list>
<parameter list> contains the following fields:
|
Field name |
Explanation |
Example |
|
Anchor group ID |
Anchor group ID. The ID value must be unique within the RTLS. If omitted, it will be generated automatically by the RTLS. The value 0 cannot be used, it is reserved for the default anchor group “ALL”. |
1 |
|
Alias name |
A human-readable alias name, mandatory parameter. Cannot contain quotes or spaces. Must be unique within the RTLS. |
Floor1 |
|
Priority |
Anchor group priority, mandatory parameter. Real number. Higher value means higher priority. |
1 |
|
Floor number |
An optional parameter for the floor number, integer. If given, it must be unique within the RTLS, i.e. no other anchor group can be associated with this floor number. |
1 |
Some full examples of client requests would be:
$PEKIO,ADD_ANCHOR_GROUP,,Floor1,1
$PEKIO,ADD_ANCHOR_GROUP,100,Floor100,2.5,100
If processing the request was successful, the system responds:
$PEKIO,OK,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor group ID |
The unique numeric ID of the anchor 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 |
|
ID_ALREADY_EXISTS |
The given anchor 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 anchor group name value is already in use |
|
NAME_INCOMPATIBLE |
The anchor group name contains unaccepted symbols (e.g. quotes or spaces) |
|
NAME_MISSING |
The mandatory anchor 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) |
|
FLOOR_INDICATION_CONFLICT |
There is already an anchor group with the given floor indication value |
|
FLOOR_INDICATION_ERROR |
The floor value could not be parsed: either missing or given in a wrong format other than integer |
A full example of error response would be:
$PEKIO,NOT_GOOD,NAME_MISSING
GET_ANCHOR_GROUPS
This request allows to query the list of known anchor groups from the system.
Client sends:
$PEKIO,GET_ANCHOR_GROUPS,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor group ID OR The keyword “ALL” |
Can be one of the following:
|
1 ALL |
Some full examples of client requests would be:
$PEKIO,GET_ANCHOR_GROUPS,1
$PEKIO,GET_ANCHOR_GROUPS,ALL
If processing the request was successful, the system responds with an ANCHOR_GROUP message:
$PEKIO,ANCHOR_GROUP,<parameter list>
<parameter list> contains the same fields as used in ADD_ANCHOR_GROUP request:
|
Field name |
Explanation |
Example |
|
Anchor group ID |
Anchor group ID, unique within the RTLS. |
1 |
|
Alias name |
A human-readable alias name, unique within the RTLS. |
Floor1 |
|
Priority |
Anchor group priority, real number (hloat). Higher value means higher priority. |
1.5 |
|
Floor number |
An optional parameter for the floor number, integer. Displayed only if configured. |
1 |
An example of the system’s response would be:
$PEKIO,ANCHOR_GROUP,10,Floor10,1.000000,10
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_ANCHOR_GROUPS_WM
This request is an extension of the regular GET_ANCHOR_GROUPS command and allows to query the list of known anchor groups with the list of anchors belonging to each group from the system.
Client sends:
$PEKIO,GET_ANCHOR_GROUPS_WM,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor group ID OR The keyword “ALL” |
Can be one of the following:
|
1 ALL |
Some full examples of client requests would be:
$PEKIO,GET_ANCHOR_GROUPS_WM,1
$PEKIO,GET_ANCHOR_GROUPS_WM,ALL
If processing the request was successful, the system responds with an ANCHOR_GROUP message:
$PEKIO,ANCHOR_GROUP,<parameter list>
<parameter list> contains the same fields as used in the ANCHOR_GROUP response to the GET_ANCHOR_GROUPS request plus additional fields related to group members (anchors):
|
Field name |
Explanation |
Example |
|
Anchor group ID |
Anchor group ID, unique within the RTLS. |
1 |
|
Alias name |
A human-readable alias name, unique within the RTLS. |
Floor1 |
|
Priority |
Anchor group priority, real number. Higher value means higher priority. |
1.5 |
|
Floor number |
An optional parameter for the floor number, integer. Displayed only if configured. |
1 |
|
Keyword “MEMBERS” |
This keyword is used as a flag to indicate the beginning of a semicolon-separated list of the anchors belonging to the group |
MEMBERS |
|
Member list |
A semicolon-separated list of the serial numbers of the anchors belonging to the group |
0x001234;0x005678;0x00ABCD |
An example of the system’s response would be:
$PEKIO,ANCHOR_GROUP,4,Serveriruum,1.000000,MEMBERS,0x000005;0x000910;0x000C93;0x000C94;0x000CD5;0x0016D1
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
REMOVE_ANCHOR_GROUP
This request allows to remove anchor groups from the system. Please note that removing an anchor group would also automatically remove any anchor’s membership information with regards to that group.
Client sends:
$PEKIO,REMOVE_ANCHOR_GROUP,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor group ID OR The keyword “ALL” |
Can be one of the following:
|
1 ALL |
A client request example would be:
$PEKIO,REMOVE_ANCHOR_GROUP,5
If processing the request was successful, the system responds:
$PEKIO,OK,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor group ID |
The unique numeric ID of the anchor 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 anchor 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 the 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_ANCHOR_TO_GROUP
This request is used to add a new anchor to a group in the RTLS.
Client sends:
$PEKIO,ADD_ANCHOR_TO_GROUP,<parameter list>
<parameter list> contains the following fields:
|
Field name |
Explanation |
Example |
|
Anchor’s Serial Number |
Anchor’s serial number, mandatory parameter. The value “ALL” cannot be used. One anchor can be added to a group at a time with this request. |
0x1234 |
|
Anchor group ID |
Anchor group ID, mandatory parameter. The value 0 cannot be used, it is reserved for the default anchor group “ALL”. |
1 |
A client request example would be:
$PEKIO,ADD_ANCHOR_TO_GROUP,0x00FC,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 |
Anchor 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_ANCHOR |
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 anchor group with the given ID does not exist in the RTLS |
|
GROUP_ID_PARSING |
Cannot parse the anchor group id field normally |
|
ALREADY_IN_GROUP |
The given anchor already belongs to the group |
A full example of error response would be:
$PEKIO,NOT_GOOD,NO_SUCH_GROUP
REMOVE_ANCHOR_FROM_GROUP
This request is used to remove an anchor from a group in the RTLS.
Client sends:
$PEKIO,REMOVE_ANCHOR_FROM_GROUP,<parameter list>
<parameter list> contains the following fields:
|
Field name |
Explanation |
Example |
|
Anchor’s Serial Number OR The keyword “ALL” |
Can be one of the following:
|
0x123464 ALL |
|
Anchor group ID |
Anchor group ID, mandatory parameter. The value 0 cannot be used, it is reserved for the default anchor group “ALL”. |
1 |
A client request example would be:
$PEKIO,REMOVE_ANCHOR_FROM_GROUP,0x00FC,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 |
Anchor serial number is either missing or there are problems with parsing this field |
|
UNKNOWN_ANCHOR |
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 anchor group with the given ID does not exist in the RTLS |
|
GROUP_ID_PARSING |
Cannot parse the anchor group ID field normally |
|
ALWAYS_IN_GROUP |
This error code appears when trying to remove an anchor from the default group with ID 0 aka automatic “ALL”-group |
|
WAS_NOT_A_MEMBER |
The given anchor was not a member of the group |
A full example of error response would be:
$PEKIO,NOT_GOOD,ALWAYS_IN_GROUP
GET_ANCHOR_IN_GROUPS
This request is used to query all the anchor groups in the RTLS that a given anchor belongs to.
Client sends:
$PEKIO,GET_ANCHOR_IN_GROUPS,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor’s serial number OR The keyword “ALL” |
Can be one of the following:
|
0x0001 ALL |
Some full examples of client requests would be:
$PEKIO,GET_ANCHOR_IN_GROUPS,0x00AB
$PEKIO,GET_ANCHOR_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 anchor 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 |
|
Anchor’s serial number |
Anchor’s serial number |
0x00AB |
|
Anchor group ID-s |
A comma-separated list of the ID-s of all anchor groups that the given anchor belongs to. NB! The default anchor group with ID 0 is not returned in the IN_GROUPS response. If an anchor 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,0x000005,4,5,10
$PEKIO,IN_GROUPS,0x0000AB
$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_ANCHOR |
The given anchor 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_ANCHOR
ADD_ANCHOR_GROUP_COMMAND
This request can be used to define a command that will be automatically emitted and executed by the RTLS Server when the specified tag enters or leaves an area served by the specified anchor group. The main purpose of this functionality is to control some of the tag’s settings, according to the anchor group serving in the area that the tag currently resides (for example changing the tag’s fixed height according to the floor). More information about the specific commands that change the tag settings can be found in the section “RTLS Tag Management”.
Client sends:
$PEKIO,ADD_ANCHOR_GROUP_COMMAND,<parameter list>
<parameter list> is a comma-separated list with the following fields:
|
Field name |
Explanation |
Example |
|
Anchor group ID |
A unique numeric value to identify the anchor group area, to which the tag should enter for the command to be executed. For tags leaving the specified anchor group area the tilde (“~”) symbol is used in front of the numeric anchor group area 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 anchor group area. The same format as for anchors is used (6 hexadecimal digits, 24 bits). Alternatively, the keyword “ALL” may be used to specify a command that will be executed for every tag which enters the specified anchor group area. More information about tag addressing can be found in the chapter “Tag addressing”. |
0x003434 |
|
Command ID |
A numeric ID for the command that can later be used to read back or remove the command. Can 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 anchor group area, the RTLS automatically emits and executes this command. The most common tag settings controlled by these commands include:
Each command is followed by its parameters. When specifying a command, there are two differences, compared to the regular commands entered directly via the communication protocol:
|
SET_TAG_ALARM,THIS,ON,0 |
A full example of client request would be:
$PEKIO,ADD_ANCHOR_GROUP_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 |
|
WRONG_NUMBER_OF_PARAMETERS |
Some parameters were missing from the request, most likely the command or its parameters. |
|
UNKNOWN_GROUP_ID |
The anchor group with the given ID does not exist in the RTLS |
|
GROUP_ID_NOT_GIVEN |
Either the anchor group ID was not given or there was a problem with parsing of the anchor group ID field |
|
TARGET_NOT_GIVEN |
Indicates a problem with the target, i.e. tag serial number value: either it was not given, its value was incorrectly parsed or the given serial number is missing in the RTLS |
|
COMMAND_ID_PARSE_FAIL |
Problem with parsing the command ID field value |
|
COMMAND_ID_CONFLICT |
This anchor group already has an associated command with the given ID |
|
UNACCEPTED_SYMBOLS |
The command contains quotes |
Important! The error messages listed above are only related to the ADD_ANCHOR_GROUP_COMMAND request itself but not to the “internal” command sent with the ADD_ANCHOR_GROUP_COMMAND request. The only error message related to the “internal” command is COMMAND_NOT_GIVEN, which appears if a command is not given at all, i.e. the command field is left empty. The command itself, as well as its parameters and their values, however, are not controlled by the system when sending ADD_ANCHOR_GROUP_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 a non-existing command (i.e. use any string inside the command field, like “blablabla”) or an empty SET_TAG_SAMPLE_INTERVALS command without any arguments inside the ADD_ANCHOR_GROUP_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,GROUP_ID_NOT_GIVEN
LIST_ANCHOR_GROUP_COMMANDS
This request allows to read back the previously defined anchor group commands.
Client sends:
$PEKIO,LIST_ANCHOR_GROUP_COMMANDS,<parameter>
<parameter> has the following meaning:
|
Field name |
Explanation |
Example |
|
Anchor group ID OR The keyword “ALL” |
The anchor group ID, for which the commands will be queried. Alternatively, the keyword “ALL” may be specified to request the zone commands for all of the anchor groups. |
2 |
A full example of client request would be:
$PEKIO,LIST_ANCHOR_GROUP_COMMANDS,2
If processing the request was successful, the system responds:
$PEKIO,ANCHOR_GROUP_COMMAND,<parameter list>
$PEKIO,ANCHOR_GROUP_COMMAND,<parameter list>
...
$PEKIO,EOF
<parameter list> has exactly the same fields as with the ADD_ANCHOR_GROUP_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_GROUP_ID |
Either the anchor group ID was not given or there was a problem with parsing of the anchor group ID field |
|
UNKNOWN_GROUP_ID
|
The anchor group with the given ID does not exist in the RTLS |
A full example of the system’s error response would be:
$PEKIO,NOT_GOOD,UNKNOWN_GROUP_ID
REMOVE_ANCHOR_GROUP_COMMANDS
This request allows to remove the previously defined anchor group commands.
Client sends:
$PEKIO,REMOVE_ANCHOR_GROUP_COMMANDS,<parameter list>
<parameter list> is a comma-separated list with the following fields:
|
Field name |
Explanation |
Example |
|
Anchor group ID OR The keyword “ALL” |
The anchor group ID, for which the zone command(s) should be removed. Alternatively, the keyword “ALL” may be used to remove all the commands for all of the anchor groups |
2 |
|
Command ID OR The keyword “ALL” |
The Command ID, which will be removed. Alternatively, the keyword “ALL” may be used to remove all the commands for the specified anchor group. This field may be omitted – in this case the behavior is exactly as with the “ALL” keyword. |
15 |
Some full examples of client request would be:
$PEKIO,REMOVE_ANCHOR_GROUP_COMMANDS,ALL
$PEKIO,REMOVE_ANCHOR_GROUP_COMMANDS,2
$PEKIO,REMOVE_ANCHOR_GROUP_COMMANDS,2,ALL
$PEKIO,REMOVE_ANCHOR_GROUP_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_GROUP_ID |
Either the anchor group ID was not given or there was a problem with parsing of the anchor group ID field |
|
UNKNOWN_GROUP_ID |
The anchor group with the given ID does not exist in the RTLS |
|
UNKNOWN_COMMAND_ID |
There is command with the given ID in the group |
|
COMMAND_ID_PARSE_FAIL |
Problem with parsing the command id field value |
A full example of the system’s error response would be:
$PEKIO,NOT_GOOD,NO_GROUP_ID