MotionSystems

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Liability

THE MOTION SYSTEMS COMPANY AND ITS DISTRIBUTORS ARE NOT LIABLE FOR ANY DAMAGE, INJURIES OR EVEN DEATH RESULTING FROM ANY ELEMENTS NOT PROVIDED BY THE MOTION SYSTEMS COMPANY AND/OR INCORRECT USE OR ASSEMBLY OF THE PRODUCT.

All trademarks, brands and logos are copyright of their respective owners.

Introduction

ForceSeatMI is an easy to use yet powerful interface that allows to add a motion platforms support to any application or game (referred as SIM in next sections). In most applications there is no need to control the hardware directly from the SIM. Because of that ForceSeatMI is used only to send telemetry or positioning request to ForceSeatPM. This approach delegates responsibility of transforming telemetry data to an actual platform motion from the SIM to ForceSeatPM. It also simplifies error handling that the SIM has to implement.

With the latest version of the ForceSeatMI, it is possible to control the hardware with usage of Inverse Kinematics. The SIM sends required top frame position and ForceSeatPM calculates required arms (or actuators) positions. This feature can be used in application where precise positioning is required instead of forces simulation.

This documentation applies only to ForceSeatMI 2.63 or newer. Older version of the API is not covered by this documment. ForceSeatMI 2.63+ is also not backward compatible on interface and binary levels with 2.61 and previous versions. Switching from older ForceSeatMI to 2.63+ will require changes in your application source code.

Main features:

The package contains following files:

ForceSeatMI uses DLL which is installed as part of the ForceSeatPM software. Make sure that you have ForceSeatPM installed on your computer.

Requirements

Native API dll is compiled with Visual Studio 2013 - static linking with MSVC is used.

Unity 3D examples require Unity 5.x

Unreal Engine examples require Unreal Engine 4.14 or 4.15

C# examples require at least Visual Studio 2013 Express for Windows Desktop and .NET Framework 4.0.

C/C++ examples require at least Visual Studio 2013 Express for Windows Desktop.

Operation modes

ForceSeatMI works in one of modes described below. For first time users it is recommended to start from Logical Table Position as it is the simplest example and works with built-in profile SDK - Positioning.

ModeDescriptionApplications Recommended profile
Telemetry data In this mode the SIM sends information about vehicle position, g-forces and accelerations in vehicle coordination system directly to ForceSeatPM. The whole transformation from forces to top frame movements is done inside ForceSeatPM scripting engine. It allows to easy change mapping and filter parameters without the need to change anything in the SIM. Games and vehicle physics simulations SDK - Vehicle Telemetry
SDK - Plane Telemetry
Logical table position In this mode the SIM sends top frame position (yaw, pitch, roll, heave, sway and surge) in abstract units (percents of maximum rotation/translation). This allows the SIM to take full control over top frame position, but it is up to the SIM to calculate correct angles and offsets. For applications that want to have better control over frame position SDK - Positioning
SDK - Pos - Low FPS
Precise table position This module uses top frame transformation matrix delivered by SIM and calculates positions of all arms/actuators in real world units. Equipment testing applications SDK - Positioning
SDK - Pos - Low FPS

ForceSeatMI library in your projects

Implementation details

structSize is a mandatory field which MUST be filled. It is used to handle backward/forward compatibility between DLL and the SIM.

telemetry.structSize = sizeof(ForceSeatMI_Telemetry);

mask indicates what other fields are set. For example, if the SIM provides roll in FSMI_TopTablePositionLogical structure, then mask field has to contains FSMI_POS_BIT_POSITION bit. It is required to always include state field in the mask (FSMI_POS_BIT_STATE or FSMI_TEL_BIT_STATE).

#define FSMI_POS_BIT_STATE       (1 << 1)
#define FSMI_POS_BIT_POSITION    (1 << 2)
#define FSMI_POS_BIT_MATRIX      (1 << 2)
#define FSMI_POS_BIT_MAX_SPEED   (1 << 3)
#define FSMI_POS_BIT_TRIGGERS    (1 << 4)
#define FSMI_POS_BIT_AUX         (1 << 5)
 
#define FSMI_TEL_BIT_STATE                         (1 << 1)
#define FSMI_TEL_BIT_RPM                           (1 << 2)
#define FSMI_TEL_BIT_SPEED                         (1 << 3)
 
#define FSMI_TEL_BIT_YAW_PITCH_ROLL                (1 << 4)
#define FSMI_TEL_BIT_YAW_PITCH_ROLL_ACCELERATION   (1 << 5)
#define FSMI_TEL_BIT_YAW_PITCH_ROLL_SPEED          (1 << 6)
#define FSMI_TEL_BIT_SWAY_HEAVE_SURGE_ACCELERATION (1 << 7)
#define FSMI_TEL_BIT_SWAY_HEAVE_SURGE_SPEED        (1 << 8)
 
#define FSMI_TEL_BIT_PEDALS_POSITION               (1 << 9)
#define FSMI_TEL_BIT_GEAR_NUMBER                   (1 << 10)
#define FSMI_TEL_BIT_GROUND_TYPE                   (1 << 11)
#define FSMI_TEL_BIT_COLLISION                     (1 << 12)
 
#define FSMI_TEL_BIT_GLOBAL_POSITION               (1 << 13)
#define FSMI_TEL_BIT_TIME                          (1 << 14)
#define FSMI_TEL_BIT_TRIGGERS                      (1 << 15)
 
#define FSMI_TEL_BIT_MAX_RPM                       (1 << 16)
#define FSMI_TEL_BIT_FLAGS                         (1 << 17)
#define FSMI_TEL_BIT_AUX                           (1 << 18)
 

If ForceSeatMI is used in the SIM, the SIM has to call ForceSeatMI_BeginMotionControl at least once, otherwise there will be pause state present all the time. After first call, you can choose how to handle pause. One option is to call ForceSeatMI_EndMotionControl and another option is to set state bit. Our recommendation is as follows:

  1. When the SIM enters runtime mode (it is going to send telemetry data), it calls ForceSeatMI_BeginMotionControl
  2. When the SIM exists runtime mode (it is not going to send telemetry data for a while), it calls ForceSeatMI_EndMotionControl
  3. When during runtime, there is a short pause event (e.g. user presses pause on a keyboard), the SIM should use state field
In other words, is is recommended to use ForceSeatMI_BeginMotionControl/ForceSeatMI_EndMotionControl to handle runtime - main menu transitions and state to handle short time pause events.

state fields consists of 8 bits, but in current version only the first bit is used.

  1. BIT no. 0 --- 1 (FSMI_STATE_PAUSE) means that runtime mode in SIM is paused, 0 (FSMI_STATE_NO_PAUSE) means that runtime mode in SIM is running.

Remember to add FSMI_POS_BIT_STATE or FSMI_TEL_BIT_STATE to mask if state field is going to be set. Make sure to set state at least once to unpause the motion platform after ForceSeatMI_BeginMotionControl is called.

Examples

Following examples are provided together with the SDK. Please make sure to use correct profile for each example.

ExampleDescriptionRequired profile
TableLogPos_CPP
TableLogPos_CS
TableLogPos_Unity
TableLogPos_Unreal
Shows how to control top table position by specifing roll, pitch, yaw, heave, sway and surge in percent of maxiumum movements. It can be used to control all kind of motion platforms. SDK - Positioning
SDK - Pos - Low FPS
TablePhyPos_CPP
TablePhyPos_CS
TablePhyPos_Unity
TablePhyPos_Unreal
Shows how to specify precise top table position by providing roll, pitch, yaw, heave, sway and surge in real world units. It works only with 3DoF and 6DoF machines. SDK - Positioning
SDK - Pos - Low FPS
TableMatrixPos_CPP
TableMatrixPos_CS
Shows how to specify precise top table position by providing transformation matrix. It recommended only for 6DoF machines. SDK - Positioning
SDK - Pos - Low FPS
Telemetry_Veh_Unity
Telemetry_Veh_Unreal
Shows how to send vehicle telemetry data from the SIM to ForceSeatPM. SDK - Vehicle Telemetry
Telemetry_Fly_Unity
Telemetry_Fly_Unreal
Shows how to send aeroplane telemetry data from the SIM to ForceSeatPM. SDK - Plane Telemetry

Final thoughts