RavenAPI Overview

Version 1.1
Protocol version identifier: 0xFFFEFFFE

Introduction

The RavenAPI is used to control Iris Dynamics 6DOF motion platforms from an application like a simulator or game.

The application initiates RavenAPI messages by sending a UDP datagram containing a frame of simulator data, or a behavior command. The platform responds to every valid package it receives according to the package contents.

Messages begin with the protocol version identifier, followed by the message ID. The following data is context-specific. Finally all messages conclude with an 8-bit CRC calculation.

Multiple messages can be sent in one datagram, and messages can be split between consecutive datagrams.

All numerical representations are in a signed 32-bit format and sent most-significant-byte first.

Connection

API commands can be carried out via UDP datagrams. Typical IP settings are 10.0.0.2. Incoming data (from an application to the platform) uses port 9200, and outgoing data uses port 9201.

Degrees of Freedom (DoF)

RavenAPI commands acceleration cueing of 6 degrees of freedom: surge, sway, heave, roll, pitch, and yaw.

Surge is a forward-backward motion such as a car accelerating. Positive surge motion is forward motion. Sway is a side-to-side motion such as a car cornering fast (not to be confused with yaw). P Heave is an up-down motion such as a helicopter lifting off. Roll is a rotation about the surge axis, such as a barrel roll. Pitch is a rotation about the sway axis such as a nose dive. Yaw is a rotation about the heave axis, such as spinning on an office chair.

Frames of Reference (FoR)

The world FoR refers to a virtual fixed space.

The avatar FoR is that experienced by the simulated craft in the virtual world. It is with respect to this FoR that applications package and send data to RavenAPI.

The rider FoR is that experienced by the physical rider.

The platform FoR is with respect to the platform base. It is with respect to this FoR that the platform's position and orientation are reported from RavenAPI.

Anticipated format

Mantis expects acceleration data passed to it to be in the avatar's FoR. This means that depending on how the application calculates accelerations, middleware or a plugin may be required to rotate the accelerations appropriately.

Types of Platform Control

Acceleration Cueing

The avatar's accelerations in the virtual environment are measured and reported to the platform which makes an effort to replicate those accelerations for the physical rider. Accordingly, the accelerations provided by the application to the platform should be in the avatar FoR.

The response of the platform to indicated avatar accelerations is controlled by the 'Mantis' kinematic and washout controller.

Washout Positions

Washout positions are surge, sway, and heave translations, and roll, pitch, and yaw rotations that the platform will tend toward and settle to. The washout positions are requested with respect to the platform FoR.

These positions are measured from the center resting position when all actuators are at half of their maximum extension.

The path used to return a DoF to the washout positions is a function of the DoF's settling time setting, and the incoming accelerations.

Using non-zero settling positions for surge and sway can result in excess power consumption and actuator temperatures and is typically not recommended.

Mode of Operation Control

Mode of operation can be controlled with the "Mode change request" type message.

See Mantis kinematic and washout controller for a description of valid mode transitions and a description of each mode of operation

Gravity

Forces due to gravity must be accounted for when cueing motions for the rider. By using different message types, the application can add the force of gravity to the accelerations of the avatar, or instead pass a value for the acceleration due to gravity.

When adding the force of gravity prior to the accelerations, an application should project the force of gravity onto the user's surge, sway, and heave accelerations according to the avatar's pitch and roll orientation.

Message Construction

Framing Data

Message framing- Application to Platform

	Byte
	1	2	3	4	5	6	...	N
from app	VersionID				MessageID		Payload	CRC

Message framing - Platform to Application

	Byte
	1	2	3	4	5	6	...	N
to app	VersionID				MessageID		Payload	CRC

Units

Data format

Name	DoFs	Format	Unit	Maximums
Positions	Surge, Sway, Heave	2s compliment signed 32-bit	micrometers (um)	+- 2,000,000
Position Speeds			millimeters per second (mm/s)	+- 4,000
Position Accelerations			millimeters per second squared (mm/s^2)	+- 60,000
Rotations	Roll, Pitch, Yaw		milldegrees (mdeg)	+- 360,000
Rotation Speeds			degrees per second (deg/s)	+- 250
Rotation Acceleration			degrees per second squared (deg/s^2)	+- 4,000

Vocabulary

Application to Platform

Application to Platform messages

MessageID	Payload Size (Words / Bytes)	Total Package Length (Bytes)	Description
5	6 / 24	31	Acceleration only frame transmit the accelerations of each dof (x6) from the avatar FoR. Mantis assumes gravity has been added to these values. A coordinated turn in an aircraft should result in zero sway acceleration.
21	8 / 32	39	Acceleration and attitude frame transmit the accelerations of each dof (x6), and the attitude of the rider (roll and pitch) from the avatar FoR. Mantis assumes a typical gravity acceleration of 9800 m/s^2 and projects this onto the surge, sway, and heave accelerations according to the roll and pitch angle. A coordinated turn in an aircraft should result in a sway acceleration equal to -9800 * sin (bank angle) mm/s^2.
85	9 / 36	43	Acceleration and attitude plus gravity frame transmit the accelerations of each dof (x6), and the attitude of the rider (roll and pitch) from the avatar FoR, as well as the force due to gravity. Mantis projects the gravity onto the surge, sway, and heave accelerations according to the roll and pitch angle. A coordinated turn in an aircraft should result in a sway acceleration equal to -gravity * sin (bank angle).
170	6 / 24	31	Washout targets frame transmit the washout position of each dof (in the platform FoR). This frame can be used to implement offsets for dof positions during cueing depending on specific simulator behaviors. Also provides a way to move the platform in loading mode.
682	1 / 4	11	Mode change request frame request to change to a new mode of operation.
2730	0 / 0	7	Actuator Forces Request Frame Requests current actuator force data.
10922	0 / 0	7	Actuator Temperature Request Frame Requests current actuator temperature data.
65535	0 / 0	7	All DoFs Position Request Frame Requests current position/angle for all DoFs.
65534	0 / 0	7	All Actuators Target Position Request Frame Requests current target position for all actuators.
65533	0 / 0	7	All Actuators Commanded Force Request Frame Requests current commanded force for all actuators.
65532	0 / 0	7	All Actuators Position Request Frame Requests current position for all actuators
3780	0 / 0	7	Firmware Release Request Frame Requests current Super Eagle firmware information

Application to Platform payloads

MessageID	Words (32-bits)
	1	2	3	4	5	6	7	8	9
5	Surge acc	Sway acc	Heave acc	Roll acc	Pitch acc	Yaw acc
21	Surge acc	Sway acc	Heave acc	Roll acc	Pitch acc	Yaw acc	Roll angle	Pitch angle
85	Surge acc	Sway acc	Heave acc	Roll acc	Pitch acc	Yaw acc	Roll angle	Pitch angle	Gravity
170	Surge pos	Sway pos	Heave pos	Roll ang	Pitch ang	Yaw ang
682	Mode request

Platform to Application

Platform to Application responses

ResponseID	Payload Size (Words / Bytes)	Total Package Length (Bytes)	Description
5, 21, 85, 170, 65531	7 / 28	35	Platform status frame Returns the position and orientation of the platform with respect to the platform FoR, and a status word containing flags that describe the platform state.
682	1 / 4	11	Mode change response frame Returns the status word, which contains the mode of operation.
2730	7 / 28	35	Forces request response frame Returns the force of each actuator, a timestamp, and a status word containing flags that describe the platform state.
10922	7 / 28	35	Temperatures request response frame Returns the temperature of each actuator, and a status word containing flags that describe the platform state.
65535	8 / 32	39	Platform DoF request response frame Returns the position or angle(um or millidegrees) of each DoF, a timestamp, and a status word containing flags that describe the platform state.
65534	8 / 32	39	Target positions request response frame Returns the target position (um) of each actuator, a timestamp, and a status word containing flags that describe the platform state.
65533	8 / 32	39	Actuator force request response frame Returns the commanded force (-32k to + 32k) of each actuator, a timestamp, and a status word containing flags that describe the platform state.
65532	8 / 32	39	Actuator positions request response frame Returns the actual position of each actuator (um), a timestamp, and a status word containing flags that describe the platform state.
3780	8 / 32	39	Firmware version request frame Returns the firmware version, release state, revision number, year of release, months of release, day of release, commit hash, and a status word containing flags that describe the platform state.

Platform to Application payloads

MessageID	Words (32-bits)
	1	2	3	4	5	6	7	8
5, 21, 85, 170, 65531	Surge pos	Sway pos	Heave pos	Roll ang	Pitch ang	Yaw ang	Status Word
682	Status Word
2730	Force 0 Data	Force 1 Data	Force 2 Data	Force 3 Data	Force 4 Data	Force 5 Data	Status Word
10922	Temp 0 Data	Temp 1 Data	Temp 2 Data	Temp 3 Data	Temp 4 Data	Temp 5 Data	Status Word
65535	Surge pos	Sway pos	Heave pos	Roll ang	Pitch ang	Yaw ang	Timestamp	Status Word
65534	Act 0 Target	Act 1 Target	Act 2 Target	Act 3 Target	Act 4 Target	Act 5 Target	Timestamp	Status Word
65533	Act 0 Force	Act 1 Force	Act 2 Force	Act 3 Force	Act 4 Force	Act 5 Force	Timestamp	Status Word
65532	Act 0 Pos	Act 1 Pos	Act 2 Pos	Act 3 Pos	Act 4 Pos	Act 5 Pos	Timestamp	Status Word
3780	Firmware Version	Release State	Revision Number	Release Year	Release Month	Release Day	Commit Hash	Status Word

Status Word

The last word in all platform to application frames. Contains information on the current state of the platform.

Status Word Composition

Bit
31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
**RESERVED**																				Motor 0 OK	Motor 1 OK	Motor 2 OK	Motor 3 OK	Motor 4 OK	Motor 5 OK	Thermal Mode		Operational Mode

Operational Mode

Mode	Value
OFF	0
LEVEL BRAKE	1
LOADING	2
CUEING	3

Thermal Mode

Mode	Value
NORMAL	0
OVERHEAT PROTECTION	1

Actuator OK Status

Status	Value
Not OK (has errors)	0
OK (no errors)	1

CRC Class

The CRC byte of each message can be constructed using the following code:

 
/*
The following CRCFast class was adapted from
https://barrgroup.com/Embedded-Systems/How-To/CRC-Calculation-C-Code
and can be found here:
Barr, Michael. "Slow and Steady Never Lost the Race," Embedded Systems Programming, January 2000, pp. 37-46.

Big thank you for this!
*/
#define CRC_POLYNOMIAL	0xD5
class CRCFast {

  public:
    static uint8_t table [256];

    static uint8_t generate (uint8_t const message[], int nBytes) {
      uint8_t data;
      uint8_t remainder = 0;

      // Divide the message by the polynomial, a byte at a time.
      for (int byte = 0; byte < nBytes; ++byte)
      {
          data = message[byte] ^ remainder;
          remainder = table[data] ^ (remainder << 8);
      }

      // The final remainder is the CRC.
      return (remainder);
    }
    static void build_table() {
      uint8_t remainder;

      for (int dividend = 0; dividend < 256; ++dividend)
      {
        remainder = dividend;

        // Perform modulo-2 division, a bit at a time.
        for (uint8_t bit = 8; bit > 0; --bit)
        {
          if (remainder & 0x80)
            remainder = (remainder << 1) ^ CRC_POLYNOMIAL;
          else
            remainder = (remainder << 1);
         }

         //Store the result into the table.
         table [dividend] = remainder;
      }
    }
};

See Also

Mantis kinematic and washout controller