Real-time data from our desktop applications is served over a UDP and/or TCP server in a compact binary format — position data, tag and anchor status, sensor data and more.
Set up data transmission over UDP, TCP or WebSocket in the desktop application (cxRTLS or cxParser), then connect to your computer or server using the matching IP address and port number.
Every message starts with the same four-field header. The command byte selects how the remainder of the payload is decoded.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'D' | Command type — selects the payload layout below |
| version | uint8 | 1 | 0 | Command protocol version |
Rows marked repeat denote a block that occurs the indicated number of
times. Within DATA, each type field opens a
sub-block — 'D' distances, 'Q' quaternions,
'R' raw IMU, 'P' positions, 'U' user data,
'I' impulse response.
The GET commands are sent to request the corresponding data; the rest are received.
'S'
Assign tags to a speed group.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'S' | |
| version | uint8 | 1 | 0 | command protocol version |
| repeat x times | ||||
| id | uint16 | 2 | 101 | tag id - 100..65536 |
| speed | uint8 | 1 | 1 | speed group of tag. list given via other command (to specify) |
6 fields
'D'
The main stream: distances, positions, quaternions, raw IMU, user data and impulse response.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'D' | |
| version | uint8 | 1 | 0 | command protocol version |
| length | uint8 | 1 | 12 + 13 * timeCnt | length of (sub)header that follows |
| msg id | uint32 | 4 | 5423 | message count for the distances (absolute count) |
| frame nr | uint32 | 4 | 145 | number of the current frame frame count goes from 0 to 10.000.000 |
| frame size | uint16 | 2 | 5000 | frame size in microseconds, divided by 10 default frame size = 50000 us |
| timeCnt | uint8 | 1 | 1 | amount of timestamps that will follow |
| repeat timeCnt times | ||||
| source id | uint16 | 2 | 9000 | ID of the node that serves the time |
| year | uint8 | 1 | — | .. |
| month | uint8 | 1 | 1 | month |
| day | uint8 | 1 | 1 | day |
| hour | uint8 | 1 | 1 | hour |
| minute | uint8 | 1 | 1 | minute |
| second | uint8 | 1 | 1 | second |
| millisecond | uint16 | 2 | 123 | millisecond |
| timeflag | uint8 | 1 | 131 | flag for time - 0 = CPU, otherwise bit1 = GPS time, bit6 = leap second validated, bit7 = time validated, bit8 = date validated. |
| spare | uint16 | 2 | 0 | spare bytes |
| tagCnt | uint8 | 1 | 10 | amount of tags indicates how many tag measurements will follow |
| repeated tagCnt times | ||||
| tag id | uint16 | 2 | 101 | tag id - 100..65536 |
| tag offset | uint16 | 2 | 45000 | offset for timestamp in microsec, divided by 10 |
| tagSize | uint16 | 2 | 100 | amount of bytes connected to this tag that will follow sum of all the type blocks |
| type | uint8 | 1 | 68 | ‘D’ for distances |
| anchorCnt | uint8 | 1 | 10 | amount of anchors indicates how many anchor measurements will follow |
| anchor id | uint16 | 2 | 10 | anchor id - 10..99 |
| distance | uint16 | 2 | 1500 | distance in cm |
| LOS1 | uint8 | 1 | 1 | tag to anchor LOS status 0 = LOS, 1 = NLOS |
| RSSI1 | uint8 | 1 | 45 | tag to anchor RSSI [dB] |
| LOS2 | uint8 | 1 | 1 | anchor to tag LOS status 0 = LOS, 1 = NLOS |
| RSSI2 | uint8 | 1 | 45 | anchor to tag RSSI [dB] |
| anchor offset | uint16 | 2 | 45000 | offset for timestamp in microsec, divided by 10 |
| type | uint8 | 1 | 81 | ‘Q’ for quaternions |
| q0 | float | 4 | 0.9913 | q0 |
| q1 | float | 4 | 0.0014 | q1 |
| q2 | float | 4 | 0.2341 | q2 |
| q3 | float | 4 | 0.1958 | q3 |
| type | uint8 | 1 | 82 | ‘R’ for raw |
| sampleCnt | uint8 | 1 | 1 | amount of samples that will follow |
| ts | uint16 | 2 | 25 | ts offset in us, divided by 10 |
| ax | uint16 | 2 | 123 | raw accel x value |
| ay | uint16 | 2 | 123 | raw accel y value |
| az | uint16 | 2 | 123 | raw accel z value |
| gx | uint16 | 2 | 123 | raw accel x value |
| gy | uint16 | 2 | 123 | raw accel y value |
| gz | uint16 | 2 | 123 | raw accel z value |
| mx | uint16 | 2 | 123 | raw accel x value |
| my | uint16 | 2 | 123 | raw accel y value |
| mz | uint16 | 2 | 123 | raw accel z value |
| type | uint8 | 1 | 80 | ‘P’ for positions |
| x | uint32 | 4 | 1363 | x coordinate in cm |
| y | uint32 | 4 | -7348 | y coordinate in cm |
| z | uint32 | 4 | 201 | z coordinate in cm |
| type | uint8 | 1 | 85 | ‘U’ for userdata out |
| count | uint16 | 2 | 6 | amount of bytes that will follow |
| bytestream | uint8 | count | [1 2 3 4 5 6] | |
| type | uint8 | 1 | 73 | 'I' for Impulse Response |
| length | uint16 | 2 | 6 | Amount of bytes that will follow |
| source | uint16 | 2 | 101 | source of IR |
| index | uint16 | 2 | 6 | index in accumulator |
| left | uint8 | 1 | 5 | samples left of index |
| right | uint8 | 1 | 15 | samples right of index |
| real | int16 | 2 | -12 | real part of complex number |
| complex | int16 | 2 | 75 | complex part of complex number |
64 fields
'U'
Send a raw byte stream to one or more tags.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'U' | |
| version | uint8 | 1 | 0 | command protocol version |
| idCnt | uint8 | 1 | 2 | amount of id’s that will follow |
| repeated idCnt times | ||||
| id | uint16 | 2 | 101 | node id |
| count | uint16 | 2 | 6 | |
| bytestream | uint8 | count | [1 2 3 4 5 6] | |
8 fields
'T'/84
Request the list of known tags.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'T'/84 | |
| version | uint8 | 1 | 0 | command protocol version |
4 fields
'T'/84
Reply to GET TAGLIST.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'T'/84 | |
| version | uint8 | 1 | 0 | command protocol version |
| block length | uint8 | 1 | 5 | length of blocks to follow |
| tagCnt | uint16 | 2 | 2 | amount of id’s that will follow |
| repeated tagCnt times | ||||
| id | uint16 | 2 | 101 | node id |
| speed | uint8 | 1 | 1 | |
| z-coords | int16 | 2 | 1234 | height of the tag in cm |
9 fields
’A’/65
Request the list of known anchors.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | ’A’/65 | |
| version | uint8 | 1 | 0 | command protocol version |
4 fields
’A’/65
Reply to GET ANCHORLIST, including anchor coordinates.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | ’A’/65 | |
| version | uint8 | 1 | 0 | command protocol version |
| block length | uint8 | 1 | 8 | length of blocks to follow |
| anchorCnt | uint16 | 2 | 2 | amount of id’s that will follow |
| repeated anchorCnt times | ||||
| id | uint16 | 2 | 101 | node id |
| x-coord | int16 | 2 | 1234 | x-coordinate of the anchor in cm |
| y-coord | int16 | 2 | 1234 | y-coordinate of the anchor in cm |
| z-coord | int16 | 2 | 1234 | z-coordinate of the anchor in cm |
10 fields
'E'/69
An external trigger event, timestamped to a frame.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'E'/69 | |
| version | uint8 | 1 | 0 | command protocol version |
| length | uint8 | 1 | 15 | amount of bytes that follows |
| type | uint8 | 1 | 101 | type information |
| frame | uint32 | 4 | 1234 | frame number in which the event has happened |
| offset | uint16 | 2 | 1234 | offset in ms within the frame |
| gps | uint8[8] | 8 | see up (add link) | time in GPS format |
| spare | uint16 | 2 | 1234 | spare bytes |
10 fields
'X'/88
Per-node health: uptime, firmware versions, voltage, last seen.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'X'/88 | |
| version | uint8 | 1 | 0 | command protocol version |
| block length | uint8 | 1 | 48 | length of each block that follows |
| nodeCnt | uint16 | 2 | 3 | amount of blocks that will follow |
| repeated nodeCnt times | ||||
| nodeid | uint16 | 2 | 100 | tag id - 100..65536 |
| node kind | uint8 | 1 | 1 | kind of FW running at the moment <\br> (see list of node kind) |
| frame_off_micro | uint16 | 2 | 1000 | offset inside frame in microsec/10 |
| uptime | uint32 | 4 | 10000 | uptime in seconds |
| reset reason | uint8 | 1 | 1 | reson of last boot <\br> (see list of boot reasons) |
| config ver | uint16 | 2 | 10 | config file version |
| tagspeed ver | uint16 | 2 | 10 | tagspeed file version |
| ant delay | uint16 | 2 | 16475 | antenna delay |
| last seen | uint32 | 4 | .. | time last seen |
| last user data | uint32 | 4 | .. | time of last seen user data |
| voltage | uint16 | 2 | 40000 | raw ADC value (formula = (3.3 x value)/(2ˆ15) ) |
| hw number | uint8 | 1 | 2 | hardware number see HW list |
| loader ver | uint16 | 2 | 24 | loader fw version |
| loader crc | uint16 | 2 | 12345 | loader fw crc |
| anchor ver | uint16 | 2 | 473 | anchor fw version |
| anchor crc | uint16 | 2 | 12345 | anchor fw crc |
| tag ver | uint16 | 2 | 473 | tag fw version |
| tag crc | uint16 | 2 | 12345 | tag fw crc |
| tag subver | uint8 | 1 | 13 | tag fw subversion |
| deca64 | uint64 | 8 | 0xDECA1234 | the long ID of the tag |
26 fields
'R'/82
Live ranking per tag.
| Field | Type | Bytes | Example | Description |
|---|---|---|---|---|
| preamble | uint16 | 2 | '##' | Preamble bytes (2x '#') |
| length | uint16 | 2 | 16 | Length of the complete message |
| cmd | char | 1 | 'R'/82 | A single character indicating the command type. |
| version | uint8 | 1 | .. | A uint8 value representing the command protocol version. |
| length | uint16 | 2 | .. | A uint16 value indicating the amount of bytes that will follow. |
| frame | uint32 | 4 | .. | A uint32 value representing the frame number. |
| gps time | uint8[8] | 8 | .. | An array of uint8[8] representing the time in GPS format. |
| tagCnt | uint16 | 2 | .. | A uint16 value indicating the amount of tags that will follow. |
| The following block is repeated tagCnt times: | ||||
| id | uint16 | 2 | .. | A uint16 value representing the tag id. |
| horseNr | uint16 | 2 | .. | A uint16 value representing the horse number. |
| rank | uint16 | 2 | .. | A uint16 value representing the rank. |
| extra | uint16 | 2 | .. | A uint16 value representing extra information. |
12 fields
Reference parsers in C, Python and JavaScript are published at github.com/RT-LOC/APIs.
Last updated 27 September 2023.