RTLOC Documentation

# Local Binary Data (TCP & UDP)

Access to real-time data is facilitated through our API. Our desktop application incorporates a UDP and/or TCP server that transmits this data in a binary format for efficient communication. The transmitted data encompasses various information such as position data, status of tags/anchors, sensor data, among others.

# 1. Connection Protocol

  1. Set up data transmission via UDP, TCP, or WebSocket using our desktop application (cxRTLS or cxParser).

  2. Establish a connection to your computer/server using the appropriate IP address and port number.

# 2. Data Structure

The data format is a structured binary format designed for efficient transmission and parsing. It consists of a preamble, length, command, version, and other fields depending on the command type.

# Commands

Depending on the command indicated in he preamble, the rest of the message will be decoded as indicated below.

COMMAND
PARAMS
TYPE
BYTES
EXAMPLE
DESCRIPTION
TAGSPEED
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)
DATA
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
repeated anchorCnt times
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
repeated sampleCnt times
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
repeated (left + right + 1) times
real
int16
2
-12
real part of complex number
complex
int16
2
75
complex part of complex number
TO TAG RAW
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]
GET TAGLIST
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
TAGLIST
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
GET ANCHORLIST
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
ANCHORLIST
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
EXTERNAL IMPULSE
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
DEVICE STATUSES
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
RANKING
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.

the "GET" commands can be sent to retrieve the corresponding data

# Code examples

Check out basic code examples at https://github.com/RT-LOC/APIs (opens new window) (C, Python, Javascript)

Last Updated: 9/27/2023, 3:47:33 PM

Local JSON data (MQTT) →