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.

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)

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. Please note that the identifier is also little endian, so the least significant byte will be sent into the stream first.

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

By convention, 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 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 information

These messages shall be sent at the beginning of an exercise.

• 0xF009 (variable-length) - Curve
  • This message contains an array of 3D 32-bit float vectors representing the curve used for the current exercise.
  • The message structure is [ [X, Y, Z], [X, Y, Z], [X, Y, Z], ... ], where X, Y, and Z are 3D coordinates of the curve's points.

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 is [X, Y, Z, U], where X, Y, and Z are 3D coordinates, and U is an unused value.

• 0x4007 (128 bits) - Current direction vector

  • This message contains a vector of three 32-bit float values representing the current direction vector of actuation, as generated by the patient interacting with the actuator.
  • The message structure is [X, Y, Z, U], where X, Y, and Z are 3D coordinates, and U is an unused value.

• 0x4008 (128 bits) - Desired direction vector

  • This message contains a vector of three 32-bit float values representing the desired direction vector of actuation, i.e. it shows in which direction the patient should try to move the actuator.
  • The message structure is [X, Y, Z, U], where X, Y, and Z are 3D coordinates, and U is an unused value.

Message example

The following is an example of a protocol version message (0x2002):

Binary   |0000 0010|0010|0000|0000 0001 0000 0000 0000 0000 0000 0000|
Hexadec. |   0    2|   2|   0|   0    1    0    0    0    0    0    0|
         |---------.---------.---------.---------.---------.---------|
Section  |Type     |Size|Type| Message contents (32 bits)            |
         |ident.   |id. |id. |                                       |
         |---------|----|----|                                       |
         | Message ident.    |                                       |

NOTE: The seemingly strange order is caused by the use of Little endian values in the protocol - least significant bytes are transferred first. For example, 0x2002 will be transferred as 02 20, 0x123F will be transferred as 3F 12 etc.

Glossary

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