Live Positioning Data, Notifications and History

Field name

Explanation

Example

Sequence Number

An 8-bit media access sequence number of ranging, expressed as a decimal value from 0 to 255. Value is incremented by the tag during the ranging process.

If the client needs to simultaneously handle multiple live positioning reports (whether the built-in RR_L, COORD, COORD_E or custom-defined), this Sequence Number can be used to match them in the data feed.

042

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

Serial Number of the first anchor

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.

A value of 0 may appear here If no anchor participated in this slot or If measuring the distance to this anchor was not successful.

0x128345

First distance

Distance from the tag to the first anchor in centimeters.

A value of 0 may appear here If no anchor participated in this slot or If measuring the distance to this anchor was not successful.

3245

Serial Number of the second anchor

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.

A value of 0 may appear here If no anchor participated in this slot or If measuring the distance to this anchor was not successful.

0x128346

Second distance B

Distance from tag to the second anchor in centimeters.

A value of 0 may appear here If no anchor participated in this slot or If measuring the distance to this anchor was not successful.

123

...

Serial Number and distance pairs for all the other anchors that participated in the ranging process (up to 20 pairs may be reflected here).

Tag’s Timestamp

Tag’s Timestamp in units of milliseconds. This is a relative timestamp, which is not related to wall clock or other tags.

00004810

Anchor’s information and error flags

Currently may be considered as Eliko’s internal debug information, one byte per anchor, separated by commas. The example on the right is valid If 4 anchors participated in the ranging process.

0x00,0x00,0x00,0x00

Tag’s information and error flags

A hexadecimal value that should be used as bitfield. Currently only the lowest bit has been defined and its meaning is as follows: value of 0 means the tag is moving and thus using the High Update Interval. Value of 1 means the tag is standstill and thus using the Low Update Interval.

NOTE that though currently no other bits have been advertised, the user should NOT assume they are always zeros. These might be used for development purposes and/or be defined for some future functionality. To get the lowest bit for deciding if the tag is moving or not, a bitwise AND between this value and 0x01 is necessary.

0x01

Field name

Explanation

Example

Sequence Number

An 8-bit media access sequence number of ranging, expressed as a decimal value from 0 to 255. Value is incremented by the tag during the ranging process.

If the client needs to simultaneously handle multiple live positioning reports (whether the built-in RR_L, COORD, COORD_E or custom-defined), this Sequence Number can be used to match them in the data feed.

123

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 Position

The calculated X, Y and Z coordinates for the tag (in meters). May be empty fields when coordinates could not be calculated.

10,-1.12,9.8

Information String

A human readable information string. Possible messages are explained in the next table.

Error: too few anchors in input.

Calculation’s Timestamp

Unix Timestamp when the coordinate calculation was started, with millisecond precision.

1563453225.876

Message

Explanation

Info: unregistered anchor detected (0x245224).

Anchor with the specified serial number has not been registered in the system. This means that the anchor is powered up and participates in the positioning process, but does not have a communication link with the current RTLS Server. This may mean that the communication link is broken or the anchor belongs to another system/server.

Error: no usable anchors in input.

The Range Report received from an anchor did not contain any usable distance between the tag and anchors. This may happen in case the distances to the anchors could not be measured or that the coordinates for the (otherwise usable) anchors are missing.

Note that this exact error message is used from software version 2.5.2. Earlier software versions use message “Error: too few anchors in input.” to reflect the same situation (which means the error message was not accurate for the situation).

Math: Bad geometry.

The anchor network is not properly set up. This may mean that the anchor coordinates have not been properly measured and entered into the system or that the positions of reported anchors do not provide sufficient information to make any calculations (for example the anchors are located too close to each other, located all on one line, etc).

Math: Not enough data.

The Range Report received from an anchor did not provide sufficient information to calculate the tag’s position and the missing parts could not be even estimated by previous measurements. This may mean that the anchor positions and/or roles have not been selected optimally or radio signals from some of the important anchors are blocked by thick objects.

Math: Lsq solver did not converge.

There were sufficient amount of distance measurements in the Range Report, but they do not converge at one point. This may mean that the anchors’ coordinates have not been properly measured and entered into the system or that the radio signal from some of the anchors are prolonged too much by the objects between the tag and anchors.

Math: Fallback to shorter lsq.

This message indicates that the measured distances do not meet at one point, but after approximations, some coordinate estimation could still be done. Note: this is just a warning, not an error.

<any other message>

Other messages are considered as server’s internal errors. Please report them to Eliko.

Field name

Explanation

Example

...

Same parameters as with simple COORD report: Sequence Number, Tag’s Serial Number, Tag’s Position, Information String, Calculation’s Timestamp

IP address

IP address of anchor that received the underlying distance measurements.

192.168.1.45

X confidence,

Y confidence,

Z confidence

Estimates for accuracy of the X, Y, Z coordinates, in meters. Should be treated as a ± value.

5.1,1.0,0.214

Field name

Explanation

Example

Custom report name

A unique name for the user-defined report. Should start with “CR_”, but otherwise the user is free to choose. If a name without “CR_” prefix is chosen, this prefix will be added automatically. If an existing name is chosen, the previously defined custom report type is overwritten.

CR_MY_REPORT

Field identifiers ON/OFF

This parameter allows the user to choose if the custom report will include also the field identifiers or not. This is an “ON” or “OFF” switch, which will affect the live positioning data reports as follows:

• “ON” – the data reports will contain the selected fields as a key and value pair. This allows parsing the values by knowing the field identifier names.

• “OFF” – the data reports will contain only the selected data fields, but not the identifiers. This avoids some overhead in the transmission, but the values must be parsed by knowing their position in the report.

ON

List of field identifiers

A variable length, comma separated list of field identifiers, which correspond to the data fields that will be included in the custom report. The list with all of the possible field identifiers is presented in the next table.

X,Y,TAG_SN

Field identifier

Explanation

Example value in custom report

SEQ_NR

An 8-bit media access sequence number of ranging, expressed as a decimal value from 0 to 255. Value is incremented by the tag during the ranging process.

If the client needs to simultaneously handle multiple live positioning reports (whether the built-in RR_L, COORD, COORD_E or custom-defined), this Sequence Number can be used to match them in the data feed.

042

TAG_SN

Tag’s unique serial number.

0x003431

X

Tag’s X coordinate (in meters).

15.21

Y

Tag’s Y coordinate (in meters).

-3.98

Z

Tag’s Z coordinate (in meters).

2.15

A_SN

B_SN

...

J_SN

Anchor’s unique serial number, which participated in the coordinate calculation process. Please note that there are 10 different field identifiers, which correspond to anchors that simultaneously participated in the ranging.

0x005412

SNS

An alternative method to include the anchors that participated in the coordinate calculation in the custom report. All the anchors will be listed on a single field, separated by semicolons.

0x005412;0x0012E4;0x0023EB

A_DIST

B_DIST

...

J_DIST

Distance to the anchor (in meters), which participated in the coordinate calculation process. Please note that there are 10 different field identifiers, which correspond to anchors that simultaneously participated in the ranging.

15.22

DISTS

An alternative method to include the distances to the anchors (in meters), which participated in the coordinate calculation process. All the distances will be listed on a single field, separated by semicolons.

1.56;32.77;11.7

TAG_TIMESTAMP

Tag’s Timestamp in units of milliseconds. This is a relative timestamp, which is not related to wall clock or other tags.

00004810

TAG_FLAGS

Tag’s information and error flags. This is a hexadecimal value that should be used as bitfield. Currently only the lowest bit has been defined and its meaning is as follows: value of 0 means the tag is moving and thus using the High Update Interval. Value of 1 means the tag is standstill and thus using the Low Update Interval.

NOTE that though currently no other bits have been advertised, the user should NOT assume they are always zeros. These might be used for development purposes and/or be defined for some future functionality. To get the lowest bit for deciding if the tag is moving or not, a bitwise AND between this value and 0x01 is necessary.

0x01

IS_MOVING

YES or NO (corresponds to the bit in TAG_FLAGS, but is easier to handle).

YES

INFO_STR

A human readable information or error string.

Less than 3 anchors detected

ARRIVAL_TIME

Unix Timestamp when the coordinate calculation was started, with millisecond precision.

1563453225.876

CALC_TIME

Unix Timestamp when the the coordinate calculation was finished, with millisecond precision. Note that usually this value should be slightly larger than ARRIVAL_TIME. If it is smaller, this indicates the coordinate calculation failed this time and the coordinates in this packet are a copy of previous successful calculation.

1563453225.936

IP_FIRST

IP address of first anchor that reported the current distance measurements.

192.168.1.45

X_CONF

Y_CONF

Z_CONF

Estimates for accuracy of the X, Y, Z coordinates, in meters. Should be treated as a ± value.

5.1,1.0,0.214

PROXIMITY_ANCHOR_SN

If the proximity detection mode is used for an anchor and the tag is near that anchor, this field represents the unique serial number of the anchor.

0x00128A

COORD_TYPE

A string which gives information about which method was used for the current coordinate estimation output. Can be:

• 2D or 3D – if the coordinate was calculated according to the regular X, Y, Z coordinate calculation method.

• 1D – if the coordinate was calculated by the “1D Mode” subsystem.

• PROXIMITY – if the coordinate was randomized inside an anchor’s proximity detection area.

2D

NR_ANCHORS

Number of usable anchors from input (ie number of anchors, for which both the anchor’s serial number and distance to the tag were reported).

4

NR_ANCHORS_USED

Number of anchors that the math module used when calculating the tag’s position. Note that this can be more than in the field NR_ANCHORS, because the math module can use some buffered and filtered values from previous measurements, if necessary.

5

IN_ZONES

When the geofencing subsystem is used, this field contain the list of Zone IDs, where the tag currently is.

2;8;23

IN_AGS

When the anchor groups are used, this field contains the list of anchor groups, where the tag currently is.

1;2

IN_TGS

When the tag groups are used, this field contains the list of tag groups, where the tag belongs to.

3;4

INTERVAL_R

The time (in milliseconds) elapsed from last distance measurement result.

292

INTERVAL_C

The time (in milliseconds) elapsed from last coordinate calculation.

293

Field name

Explanation

Examples

Tag’s Serial Number

OR

The keyword “ALL”

Selects a single tag for which the skip duration is applied. Alternatively, there are three special cases:

• The keyword “ALL” may be specified to select all of the tags (both currently online and appearing online in the future).

• The tilde prefix (“~”) may be used with a tag’s serial number to select all the tags, except the mentioned one. Note that “all the tags” means both these currently online and also those appearing online in the future.

• The exclamation mark prefix (“!”) may be used with a tag’s serial number to select this particular tag, i.e. all the other tags will be skipped.

0x0002E3

ALL

~0x0002E3

!0x0002E3

Skip duration

Skip duration in milliseconds. There are two special cases:

• A value of “0” disables the skip functionality for the selected tag or group of tags, which means all the live positioning reports, which were selected by the SET_REPORT_LIST, will be sent to the client.

• Any negative value will disable sending any data for the selected tag or group of tags (which means everything is skipped). The same behavior may be achieved also by setting the value to a very large positive number.

500

0

-1

Error ID

Explanation

CANNOT_PARSE_ID

The tag’s serial number field could not be parsed.

EMPTY_ID

The tag’s serial number field was empty (since software version 2.6.0).

INCORRECT_SKIP

The skip duration field could not be parsed (since software version 2.6.0).

UNKNOWN_ID

No such tag in the database (since software version 2.6.0).

CANNOT_PARSE_VALUES

Could not find two parameters from the request (this error is present up to software versions 2.5.x; from 2.6.0, the general error WRONG_NUMBER_OF_PARAMETERS is used instead).

Field name

Explanation

Example

Tag’s Serial Number

OR

The keyword “ALL”

Selects the tag for which history is queried. Alternatively, keyword “ALL” may be specified to get the historic data for all the tags.

0x000226

Start Timestamp

Specifies the start timestamp, for which period the history is queried, in Unix Timestamp format.

1563803000

End Timestamp

Specifies the end timestamp, for which period the history is queried, in Unix Timestamp format.

1563803002

Field name

Explanation

Example

ARRIVAL_TIME

Unix Timestamp when the coordinate calculation was started, with millisecond precision.

1563453225.876

CALC_TIME

Unix Timestamp when the the coordinate calculation was finished, with millisecond precision. Note that usually this value should be slightly larger than ARRIVAL_TIME. If it is smaller, this indicates the coordinate calculation failed this time and the coordinates in this packet are a copy of previous successful calculation.

1563453225.936

TAG_SN

Tag’s unique serial number.

0x003431

TAG_TIMESTAMP

Tag’s Timestamp in units of milliseconds. This is a relative timestamp, which is not related to wall clock or other tags.

00004810

SEQ_NR

An 8-bit media access sequence number of ranging, expressed as a decimal value from 0 to 255. Value is incremented by the tag during the ranging process.

042

TAG_FLAGS

Tag’s information and error flags. This is a hexadecimal value that should be used as bitfield. Currently only the lowest bit has been advertised and its meaning is as follows: value of 0 means the tag is moving and thus using the High Update Interval. Value of 1 means the tag is standstill and thus using the Low Update Interval.

NOTE that though currently no other bits have been advertised, the user should NOT assume they are always zeros. These might be used for development purposes and/or be defined for some future functionality.

0x0001

X

Tag’s X coordinate (in meters).

15.21

Y

Tag’s Y coordinate (in meters).

-3.98

Z

Tag’s Z coordinate (in meters).

2.15

COORD_TYPE

A string which gives information about which method was used for the current coordinate estimation output. Can be:

• 2D or 3D – if the coordinate was calculated according to the regular X, Y, Z coordinate calculation method.

• 1D – if the coordinate was calculated by the “1D Mode” subsystem.

• PROXIMITY – if the coordinate was randomized inside an anchor’s proximity detection area.

2D

IS_MOVING

YES or NO (corresponds to the bit in TAG_FLAGS, but is easier to handle).

YES

IN_ZONES

When the geofencing subsystem is used, this field contains the list of Zone IDs, where the tag currently is.

2;8;23

IN_AGS

When the anchor groups are used, this field contains the list of anchor groups, where the tag currently is.

 1;2

IN_TGS

When the tag groups are used, this field contains the list of tag groups, where the tag belongs to.

 3;4

IMU_EVENTS

Reserved for future functionality, can be ignored for now.

IMU_DATA

Reserved for future functionality, can be ignored for now.

NR_ANCHORS

Number of usable anchors from input (i.e. number of anchors, for which both the anchor’s serial number and distance to the tag were reported).

4

NR_ANCHORS_USED

Number of anchors that the math module used when calculating the tag’s position. Note that this can be more than in the field NR_ANCHORS, because the math module can use some buffered and filtered values from previous measurements, if necessary.

5

SNS

List of anchor serial numbers that participated in the coordinate calculation, separated by semicolons.

0x005412;0x0012E4;0x0023EB

DISTS

List of measured distances (in meters) to the anchors, which participated in the coordinate calculation process, separated by semicolons. The list is in the same order as the anchors were listed in the SNS field.

1.56;32.77;11.7

INTERVAL_R

The time (in milliseconds) elapsed from last distance measurement result.

292

INTERVAL_C

The time (in milliseconds) elapsed from last coordinate calculation.

293