Developer documentation

UART API

Talk directly to the hardware over UART — read device properties, stream distances, and upload or download config files.

1. Before you start

The UART API is a firmware build option and works with RTLS firmware. Firmware built for the Ethernet API does not listen for these commands, so check this first:

  1. Connect at 115200 baud, 8N1, no flow control.
  2. Restart the device. It sends a 50-byte PROPERTIES frame once it has started.
  3. Send 23 23 00 00 24 03. The device replies with the same PROPERTIES frame.

If neither frame appears, the cause is the firmware build or the connection, not your message format. The serial port depends on the hardware, and some builds use the USB port instead. Contact support@rtloc.com with your hardware type to confirm which port and firmware to use.

2. Message format

Every message starts with a 6-byte header. All multi-byte values are little-endian. Frames have no CRC of their own.

FieldTypeBytesDescription
preambleuint162Two '#' characters (23 23)
lengthuint162See below. It has a different meaning in each direction.
cmduint81Command number
versionuint81Command protocol version

The length field differs per direction:

  • To the device: payload bytes only. A command without payload has length 0.
  • From the device: the complete message, including the 6-byte header.

A command sent with length 6 and no payload is not processed: the device keeps waiting for 6 more bytes, and the next command is lost.

Rules for the host

  • Send one command and wait for its reply before you send the next one.
  • A frame can be at most 128 bytes. A longer frame with a length up to 200 blocks the receiver until the device restarts.
  • Read the serial data as a stream and select frames by cmd. Distance frames can arrive between replies.
  • The device does not answer unknown commands. Use a timeout: we suggest 1 second, and 10 seconds for upload part 0.
  • A reply can be lost while the stream is on. Retry after a timeout, or stop the stream first.

3. Command overview

CmdNameDirectionReply
36PROPERTIES (GET)To device24 PROPERTIES
24PROPERTIESFrom device—
3UNIQUE ID (GET)To device4 UNIQUE ID
4UNIQUE IDFrom device—
7BATTERY (GET)To device8 BATTERY
8BATTERYFrom device—
44TX POWER (GET)To device46 TX POWER
46TX POWERFrom device—
48HAIRS (SET)To device49 HAIRS ACK
49HAIRS ACKFrom device—
5STREAM (START)To device51 STREAM (STATUS)
6STREAM (STOP)To device51 STREAM (STATUS)
50STREAM (GET)To device51 STREAM (STATUS)
51STREAM (STATUS)From device—
2DISTANCESFrom device—
10CONFIG UPLOADTo device11 CONFIG UPLOAD REPLY
11CONFIG UPLOAD REPLYFrom device—
12CONFIG DOWNLOADTo device11 CONFIG DOWNLOAD REPLY
11CONFIG DOWNLOAD REPLYFrom device—
37RESETTo deviceNone; 24 PROPERTIES after restart

4. Commands

The stream is off after every start of the device. Send STREAM (START) to receive DISTANCES.

PROPERTIES (GET) TO DEVICE cmd 36

Request the device properties.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint8136
versionuint813Send 3. The device does not check it.

PROPERTIES FROM DEVICE cmd 24

Device properties. Also sent once, unrequested, after the device has started.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint16250Complete message, including this header
cmduint8124
versionuint812Command protocol version
runmodeuint813Obsolete. Ignore.
inner lengthuint162—Internal size value. It is not the number of bytes sent. Ignore.
uptimeuint324100Uptime of the device, in seconds
antenna delay (RX)uint16216500RX antenna delay of the device
antenna delay (TX)uint16216500TX antenna delay of the device
reserveduint81—Not filled in. Ignore.
hw versionuint811Hardware version
reserveduint324—Not filled in. Ignore.
FW versionuint162566Firmware version: major * 100 + minor. 566 means 5.66.
FW CRCuint162—Firmware CRC
config versionuint1621Version stored inside the active config file. 0 or 0xFFFF means there is no valid config. Frame offset 27.
tagspeed versionuint1621Tagspeed version
FW version (sub)uint811Firmware patch number
reservedbytes6—Not filled in. Ignore.
uiduint648—Unique ID. Frame offset 38.
bootloader versionuint162—Bootloader version
bootloader CRCuint162—Bootloader CRC

UNIQUE ID (GET) TO DEVICE cmd 3

Request the short device ID.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint813
versionuint813Send 3. The device does not check it.

UNIQUE ID FROM DEVICE cmd 4

The short device ID.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1628Complete message, including this header
cmduint814
versionuint813Command protocol version
iduint162101Short device ID

BATTERY (GET) TO DEVICE cmd 7

Request the battery value.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint817
versionuint813Send 3. The device does not check it.

BATTERY FROM DEVICE cmd 8

The battery value.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1628Complete message, including this header
cmduint818
versionuint813Command protocol version
batteryuint162—Battery voltage value. The unit depends on the hardware.

TX POWER (GET) TO DEVICE cmd 44

Request the current TX power.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint8144
versionuint813Send 3. The device does not check it.

TX POWER FROM DEVICE cmd 46

The current TX power.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1628Complete message, including this header
cmduint8146
versionuint813Command protocol version
tx poweruint16233TX power amplification, in dB

HAIRS (SET) TO DEVICE cmd 48

Configure the hairs: the broadcast of the config over UWB.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1624Payload bytes only
cmduint8148
versionuint813Send 3. The device does not check it.
enableuint8110 = disable, 1 = enable
saveuint8101 = save to permanent storage
sizeuint8100 = small (128 bytes), 1 = big (512 bytes)
continuousuint8101 = always transmit, instead of only on request

HAIRS ACK FROM DEVICE cmd 49

Confirms that HAIRS (SET) was received. It does not report the settings.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1628Complete message, including this header
cmduint8149
versionuint813Command protocol version
ackuint1626666Always 6666

STREAM (START) TO DEVICE cmd 5

Start the distance stream.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint815
versionuint813Send 3. The device does not check it.

STREAM (STOP) TO DEVICE cmd 6

Stop the distance stream.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint816
versionuint813Send 3. The device does not check it.

STREAM (GET) TO DEVICE cmd 50

Request the stream status.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint8150
versionuint813Send 3. The device does not check it.

STREAM (STATUS) FROM DEVICE cmd 51

The stream status.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1627Complete message, including this header
cmduint8151
versionuint813Command protocol version
statusuint8110 = not streaming, 1 = streaming

DISTANCES FROM DEVICE cmd 2

Measured distances, sent while the stream is on. Devices in the anchor role and tags in TWR3 mode send these.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint16211 + nb_distances * 6Complete message, including this header
cmduint812
versionuint814Command protocol version
nb distancesuint815Number of distance reports that follow
frameuint32412345Current frame of the system
repeat nb_distances times
iduint162101ID of the other device
distanceuint162167Distance to that device, in cm. Only values from 1 to 9999 are reported.
quality 1uint8143Link quality indicator. Use it as a relative value.
quality 2uint8144Link quality indicator. Use it as a relative value.

CONFIG UPLOAD TO DEVICE cmd 10

Send one part of a config file to the device. See Config transfer.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint16219 or 51Payload bytes only
cmduint8110
versionuint813Send 3. The device does not check it.
targetuint8111 = config
file versionuint162—Version of the config
crc totaluint162—CRC-16 of the complete config file
sizeuint3244096Size of the complete config file, in bytes
partuint1621Number of this part
parts totaluint162128Number of data parts
part sizeuint16232Always 32
crc partuint162—CRC-16 of the data bytes in this part
hw versionuint810Send 0
flagsuint810Send 0
databytes0 or 32—Empty in part 0, 32 bytes in every other part

CONFIG UPLOAD REPLY FROM DEVICE cmd 11

Says which part the device wants next.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint16221Complete message, including this header
cmduint8111
versionuint813Command protocol version
targetuint811Copied from the request
part requint1622Next part to send. Anything other than the sent part + 1 means the part failed.
file versionuint162—Copied from the request
hw versionuint810Copied from the request
reservedbytes8—Ignore
enduint81124End marker, '|'

CONFIG DOWNLOAD TO DEVICE cmd 12

Request one 32-byte part of the config file on the device. See Config transfer.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint16215Payload bytes only
cmduint8112
versionuint813Send 3. The device does not check it.
targetuint8111 = config
part requint1620Requested part. The first part is 0.
reservedbytes110Send 0
enduint81124End marker, '|'

CONFIG DOWNLOAD REPLY FROM DEVICE cmd 11

One part of the config file. It uses the same cmd as the upload reply, but is 57 bytes long.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint16257Complete message, including this header
cmduint8111
versionuint813Command protocol version
targetuint8111 = config
file versionuint162—Version of the stored config
crc totaluint162—CRC-16 of the complete config file
sizeuint3244096Size of the complete config file, in bytes
partuint1620Number of this part
parts totaluint162128Size divided by 32, rounded down. Use size to find the end.
part sizeuint16232Always 32
crc partuint162—CRC-16 of the 32 data bytes
reservedbytes2—Ignore
databytes32—The data of this part

RESET TO DEVICE cmd 37

Restart the device.

FieldTypeBytesExampleDescription
preambleuint162'##'Two '#' characters
lengthuint1620Payload bytes only
cmduint8137
versionuint813Send 3. The device does not check it.

5. Config transfer

A config file is transferred in parts of 32 data bytes. Treat the file as binary data: its contents are the same as what a download returns. The largest possible file depends on the hardware, because the config area ranges from 8 KB to 32 KB.

CRC

Both CRC fields use CRC-16/CCITT-FALSE: polynomial 0x1021, initial value 0xFFFF, no reflection and no final XOR. The check value for the text 123456789 is 0x29B1.

Upload

  1. Send STREAM (STOP) and wait for the status. The upload also stops ranging.
  2. Send CONFIG UPLOAD part 0 without data (length 19). The device erases its stored config, which can take seconds, and then asks for part 1.
  3. Send parts 1 up to and including parts total (length 51), and wait for each reply. Fill the last part up to 32 bytes with 0xFF. crc part covers all 32 bytes; crc total and size cover the file without the fill bytes.
  4. If part req is not the sent part + 1, or a reply does not arrive, start again from part 0. Do not resend a single part.
  5. Send RESET and wait for the PROPERTIES frame after the restart.
  6. Check config version in that frame. It must match the version stored inside your config file. This is the only confirmation: the last reply looks the same when the total CRC is wrong. In that case the device reports version 0.

Download

  1. Send STREAM (STOP) and wait for the status.
  2. Request PROPERTIES. Only continue if config version is not 0 or 0xFFFF: on some hardware, reading an empty config area crashes the device.
  3. Send CONFIG DOWNLOAD with part req 0. The reply contains size and crc total.
  4. Request the next parts until you have received size bytes. Never request a part beyond that point. The device does not signal the end of the file.
  5. Cut the result to size bytes, and check it against crc total.
  6. Send RESET. This is required: the device sends no distances after a download until it restarts.

6. Not available over UART

The device does not reply to any of these:

ItemStatus
HeartbeatThe UART API has no heartbeat, in either direction. Use PROPERTIES (GET) to check that a device is responding.
'@CX@' framesThis is the Ethernet format. Over UART, the device only accepts frames that start with ## and discards all others.
cmd 45Setting the TX power is not supported. It can only be read, with cmd 44.
cmd 47Reading the hairs configuration is not supported.
cmd 28, 38–42Not usable. Do not use these.

Firmware upload is not covered on this page. Contact support@rtloc.com if you need it.

7. Examples

ActionBytes to send (hex)
Request properties23 23 00 00 24 03
Start the stream23 23 00 00 05 03
Stop the stream23 23 00 00 06 03
Request the stream status23 23 00 00 32 03
Request TX power23 23 00 00 2C 03
Enable small hairs, without saving23 23 04 00 30 03 01 00 00 00
Request config part 023 23 0F 00 0C 03 01 00 00 00 00 00 00 00 00 00 00 00 00 00 7C
Restart the device23 23 00 00 25 03