Deltarobot VR communication protocol

This communication protocol serves the purpose of continuous transfer of data about the current state of an exercise from the Deltarobot C++/Qt application to the Unity VR visualizer application. The Qt application is the leader and is responsible for the correct operation of the exercise robot. The Unity application is the follower and connects to the Qt application as a client.

Messages

The protocol is binary. Its data is transferred in the form of messages. Each message begins with a 16-bit message identifier, followed by the message's contents.

The message identifier is split into two parts, beginning with a 4-bit size identifier and ending with a 12-bit type identifier (in the order from MSB to LSB). The size identifier specifies the length of the message's contents. The type identifier specifies the message's semantic meaning.

Unless stated otherwise:

• All values in the protocol are represented as little endian
• All non-integer numeric values in the protocol are represented as IEEE-754 floating-point numbers (single precision for 32-bits, double precision for 64-bits)

Message content length

The first four bits of the message identifier represent a size identifier. The protocol defines 6 lengths of a message's contents:

• 0x0 - 8-bit contents
• 0x1 - 16-bit contents
• 0x2 - 32-bit contents
• 0x3 - 64-bit contents
• 0x4 - 128-bit contents
• 0xF - variable-length contents
• (behaviour undefined if other values are used)

If the size identifier has the value of 0xF, the message identifier is followed by a 32-bit unsigned integer, whose value specifies the number of 8-bit bytes representing the message's contents. This may be used for string values in the protocol.

This system allows for a degree of forward compatibility, since every implementation of a client and/or server can always determine the length of a message. This way messages unknown to a particular implementation may simply be skipped without affecting any subsequent messages. Furthermore, implementations may simply choose to ignore any messages they do not have a use for, without having to accomodate for every existing message type in its codebase.

Message types

Conventionally, the type identifiers start with 0x001, reserving 0x000 as invalid null values. Null values are currently unused but may have a use associated with them in the future.

System messages

These two messages shall always be sent by both the client and the server right after the connection is established. Should any of the sides fail to do so (either by sending a different message or by sending nothing at all for some amount of time), the other side should close the connetion.

• 0x3001 (64 bits) - Protocol magic

  • Value will always be 0x44656C7461525672 (DeltaRVr in ASCII)

• 0x2002 (32 bits) - Protocol version

  • For this protocol version, the value will always be 1

• 0x3004 (64 bits) - Ping

  • Sent by the server to let the client know that the connection is active
  • Contains a randomly generated number

• 0x3005 (64 bits) - Pong

  • Sent by the client as an answer to each ping message
  • Contains the identifier of the answered ping

• 0xF006 (variable-length) - End of transmission

  • Sent by either the client or the server to let the other side know that the connection is about to be closed
  • May contain an optional human-readable ASCII-encoded reason message

Exercise progress

These messages shall be sent continuously during the exercise.

• 0x4003 (128 bits) - Current actuator position
  • This message contains a vector of three 32-bit float values representing the current position of the actuator.
  • The message structure shall be [X, Y, Z, U], where X, Y, and Z are 3D coordinates, and U is an unused value.

Glossary

• LSB - Least significant bit
• MSB - Most significant bit