Information
RTTrPM is the protocol that is used to stream to third party listeners that are interested in the position and orientation of a tracking point, relative to the origin of the coordinate system (as defined by the user). The RTTrPM protocol should be sent at a fixed rate. However, if there is no motion data available, then RTTrPM should stop sending (unless a form of heartbeat is implemented).
Data Structures
Each packet is comprised of the RTTrP header and if tracking information is available, should contain at least one Trackable module. Each Trackable module should contain a number of sub-modules each of which contain specific types of information about a tracked object or point, including:
- Centroid Position (X, Y, Z co-ordinates)
- Individual Tracked point position (X, Y, Z co-ordinates)
- Orientation in Euler (X, Y, Z rotation) or Quaternion format (X, Y, Z Q)
General Information
RTTrPM packets should always be sent at an implementation specific fixed rate. In some scenarios, it is possible to implement a heart beat mechanism by sending RTTrPM packets which contain just an empty RTTrP packet, with an RTTrPM signature.
Versions and Backwards Compatibility
A protocol version number is included in the RTTrP packet header. Users of previous versions of the protocol should always check the “type” field of modules, and ignore new or unrecognized module types. There can be multiple levels of modules within modules and the order of module types within a module is not guaranteed.
The current RTTrPM version is 2.4.2.0(compatible with BlackTrax version 2.6.0), however some previous versions have different modules available, but the same overall packet structure. The differences between legacy versions of the protocol are as follows:
- February 2020 (for version 2.4.2.0): Zone Collision Detection module was re-designed to include Sub-Modules and removed the delimitation. The 2.4.1.0 method of sending Zones is no longer supported.
- November 2018 (for version 2.4.1.0): Zone Collision Detection module was added. All prior versions do not have this module present.
- June 2015 (for version 1.8.7.0): A heartbeat was added to allow the header to always be sent, so long as timestamps are present in the sending system
- Jan 2015 (for version 1.8.2.0): First addition of LED and Centroid Acceleration and Velocity. All prior versions do not have these modules present
Downloads
The RTTrP Repository has stub code available which contains packet definitions of RTTrPM. Please visit the following for Python and C++ code respectively:
Modules and Packet Structure
Packet Modules
| Enumerated Type | Value |
|---|---|
| Trackable (without Timestamp) | 0x01 |
| Trackable (with Timestamp) | 0x51 |
| Centroid Position | 0x02 |
| Orientation (Quaternion) | 0x03 |
| Orientation (Euler) | 0x04 |
| Tracked Point Position | 0x06 |
| Centroid Acceleration and Velocity | 0x20 |
| Tracked Point Acceleration and Velocity | 0x21 | Zone Collision Detection | 0x22 |
Real-Time Tracking Protocol (RTTrP) Header
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Header / Integer Signature | UInt16 | 2 | Big Endian: 0x4154, Little Endian: 0x5441 |
| 1 | Header / Float Signature | UInt16 | 2 | Big Endian: 0x4334, Little Endian: 0x3443 |
| 2 | Header Version | UInt16 | 2 | Value = 0x0002, will increase if header changes |
| 3 | Packet ID | UInt32 | 4 | Packet sequence number |
| 4 | Packet Format | UInt8 | 1 | Value = 0x00 (Raw), 0x01 (Protobuf), 0x02 (Thrift) |
| 5 | Size | UInt16 | 2 | Size of packet in bytes including header |
| 6 | Context | UInt32 | 4 | User definable |
| 7 | Number of Packet Modules | UInt8 | 1 | |
| 8 | Packet Module 0 | Packet Module | Variable | |
| 9 | Packet Module 1 | Packet Module | Variable | |
| ... | ... |
For more in-depth details on the RTTrP packet header see RTTrP.
Packet Module - Trackable (without Timestamp)
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x01 |
| 1 | Size | UInt16 | 2 | Size of packet module including type and size |
| 2 | Name | UInt8 | 1 | Length of Trackable Name |
| 3 | Name | UTF8 | Variable | Trackable Name |
| 4 | Number of Packet Modules | UInt8 | 1 | Total number of sub-modules |
| 5 | Packet Module 0 | Packet Module | Variable | |
| 6 | Packet Module 1 | Packet Module | Variable | |
| ... | ... |
Packet Module - Trackable (with Timestamp)
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x51 |
| 1 | Size | UInt16 | 2 | Size of packet module including type and size |
| 2 | Name | UInt8 | 1 | Length of Trackable Name |
| 3 | Name | UTF8 | Variable | Length is equal to Trackable Name Length |
| 4 | Timestamp | UInt32 | 4 | Sequence number (Frame ID) |
| 5 | Number of Packet Modules | UInt8 | 1 | Total number of sub-modules |
| 6 | Packet Module 0 | Packet Module | Variable | |
| 7 | Packet Module 1 | Packet Module | Variable | |
| ... | ... |
Packet Module - Centroid Position
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x02 |
| 1 | Size | UInt16 | 2 | Size of packet module including type and size = 29 (0x1D) |
| 2 | Latency | UInt16 | 2 | Approximate time in milliseconds since last measurement, if equal to 0xFFFF, overflow |
| 3 | X | Double | 8 | Position of the X coordinate |
| 4 | Y | Double | 8 | Position of the Y coordinate |
| 5 | Z | Double | 8 | Position of the Z coordinate |
Packet Module - Tracked Point Position
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x06 |
| 1 | Size | UInt16 | 2 | Size of packet module including type and size = 30 (0x1E) |
| 2 | Latency | UInt16 | 2 | Approximate time in milliseconds since last measurement, if equal to 0xFFFF, overflow |
| 3 | X | Double | 8 | Position of the X coordinate |
| 4 | Y | Double | 8 | Position of the Y coordinate |
| 5 | Z | Double | 8 | Position of the Z coordinate |
| 6 | Index | UInt8 | 1 | Tracked Point Index (0x00, 0x01, 0x02 etc.) |
NOTE: When outputting Tracked Point position/acceleration/velocity, there is a single module for each point
Packet Module - Orientation (Quaternion)
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x03 |
| 1 | Size | UInt16 | 2 | Size of packet module including type and size = 37 |
| 2 | Latency | UInt16 | 2 | Approximate time in milliseconds since last measurement, if equal to 0xFFFF, overflow |
| 3 | Qx | Double | 8 | X component of tracked object using quaternions |
| 4 | Qy | Double | 8 | Y component of tracked object using quaternions |
| 5 | Qz | Double | 8 | Z component of tracked object using quaternions |
| 6 | Qw | Double | 8 | Complex component of tracked object using quaternions |
Packet Module - Orientation (Euler)
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x04 |
| 1 | Size | UInt16 | 2 | Size of packet module including type and size = 31 |
| 2 | Latency | UInt16 | 2 | Approximate time in milliseconds since last measurement, if equal to 0xFFFF, overflow |
| 3 | Order | UInt16 | 2 | Value = see order table below |
| 4 | R1 | Double | 8 | Rotation in Rad along first axis |
| 5 | R2 | Double | 8 | Rotation in Rad along second axis |
| 6 | R3 | Double | 8 | Rotation in Rad along third axis |
For a list of Euler Angle Order values, please see Euler Order
Packet Module - Centroid Acceleration and Velocity
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x20 |
| 1 | Size | UInt16 | 2 | Size of packet module including the type and size |
| 2 | X | Double | 8 | Position of the X coordinate |
| 3 | Y | Double | 8 | Position of the Y coordinate |
| 4 | Z | Double | 8 | Position of the Z coordinate |
| 5 | Acceleration X | Float | 4 | Calculated centroid acceleration in the X direction |
| 6 | Acceleration Y | Float | 4 | Calculated centroid acceleration in the Y direction |
| 7 | Acceleration Z | Float | 4 | Calculated centroid acceleration in the Z direction |
| 8 | Velocity X | Float | 4 | Calculated centroid velocity in the X direction |
| 9 | Velocity Y | Float | 4 | Calculated centroid velocity in the Y direction |
| 10 | Velocity Z | Float | 4 | Calculated centroid velocity in the Z direction |
Packet Module - Tracked Point Acceleration and Velocity
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x21 |
| 1 | Size | UInt16 | 2 | Size of packet module including the type and size |
| 2 | X | Double | 8 | Position of the X coordinate |
| 3 | Y | Double | 8 | Position of the Y coordinate |
| 4 | Z | Double | 8 | Position of the Z coordinate |
| 5 | Acceleration X | Float | 4 | Calculated tracked point acceleration in the X direction |
| 6 | Acceleration Y | Float | 4 | Calculated tracked point acceleration in the Y direction |
| 7 | Acceleration Z | Float | 4 | Calculated tracked point acceleration in the Z direction |
| 8 | Velocity X | Float | 4 | Calculated tracked point velocity in the X direction |
| 9 | Velocity Y | Float | 4 | Calculated tracked point velocity in the Y direction |
| 10 | Velocity Z | Float | 4 | Calculated tracked point velocity in the Z direction |
| 11 | Index | UInt8 | 1 | Tracked Point Index (0x00, 0x01, 0x02 etc.) |
Packet Module - Zone Collision Detection
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Type | UInt8 | 1 | Value = 0x22 |
| 1 | Size | UInt16 | 2 | Size of packet module including the type and size |
| 2 | Number of Zones | UInt8 | 1 | Total number of Zones Sub-Modules included in this packet |
| 3 | Zone Sub-Module 1 | Zone Sub-Module | Variable | When present, Trackable is colliding with the Zone object defined in the Zone Sub-Module |
| 4 | Zone Sub-Module 2 | Zone Sub-Module | Variable | When present, Trackable is colliding with the Zone object defined in the Zone Sub-Module |
| ... | ... |
Zone Sub-Module - Zone Object
| Field | Name | Type | Size (bytes) | Description |
|---|---|---|---|---|
| 0 | Size | Uint8 | 1 | Size of the Sub-Module including the name and size |
| 1 | Length | Uint8 | 1 | Length of the Zone Name |
| 2 | Zone Name | UTF8 | Variable | The name of the Zone itself |