SDK – For companies looking to integrate our platform with their software
MOTION PLATFORM SDK
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 Next Level Racing Platform Manager. This approach delegates responsibility of transforming telemetry data to an actual platform motion from the SIM to Next Level Racing Platform Manager. 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 Next Level Racing Platform Manager 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 document. 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. |
Features
- SIM can choose between operation modes: forces simulation (telemetry), fast top frame positioning and precise top frame positioning
- SIM does not have to translate telemetry data to an actual motors position – it is done by Next Level Racing Platform Manager
- SIM does not depend on specific motion platform hardware, hardware related adjustments are done inside Next Level Racing Platform Manager
- All diagnostic and processing features of Next Level Racing Platform Manager are still available and may be used
Package content
- ForceSeatMI32.dll, ForceSeatMI64.dll – the API dlls, installed by Next Level Racing Platform Manager
- ForceSeatMI32.lib, ForceSeatMI64.lib – a library related to API dlls
- ForceSeatMI_Loader.c – a wrapper that forwards functions calls to real DLL (required for runtime loading)
- ForceSeatMI_Common.h, ForceSeatMI_Common.cs – header with types and enums
- ForceSeatMI_Functions.h – pure C/C++ API
- ForceSeatMI.cs – C# and Unity 3D API
- ForceSeatMI_Telemetry.h, ForceSeatMI_Telemetry.cs – structures for telemetry data
- ForceSeatMI_Positioning.h, ForceSeatMI_Positioning.cs – structures for positioning data
- ForceSeatMI_TactileTranscuders.h, ForceSeatMI_TactileTranscuders.cs – structures for tactile transducers effects
- ForceSeatMI_Status.h, ForceSeatMI_Status.cs – structures for current motion platform status data
- Plugins/UnrealEngine – dedicated Unreal Engine plug-in with helper class for vehicle and plane telemetry extraction
- Examples – examples
| ForceSeatMI uses DLL which is installed as part of the Next Level Racing Platform Manager software. Make sure that you have Next Level Racing Platform Manager installed on your computer. |
Requirements
- Following languages and frameworks are supported out of the box: C, C++, C#, Unity 3D(C#) , Unreal Engine (C++)
- 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, 4.15 or 4.18+
- 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.
- It supports only Windows PC
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.
| Mode | Description | Applications | Recommended profile |
| Telemetry data | In this mode the SIM sends information about vehicle position, g-forces and accelerations in vehicle coordination system directly to Next Level Racing Platform Manager. 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 |
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 ... #define FSMI_POS_BIT_POSITION ... #define FSMI_POS_BIT_MATRIX ... #define FSMI_POS_BIT_MAX_SPEED ... #define FSMI_POS_BIT_TRIGGERS ... #define FSMI_POS_BIT_AUX ... #define FSMI_TEL_BIT_STATE ... #define FSMI_TEL_BIT_RPM ... #define FSMI_TEL_BIT_SPEED ... #define FSMI_TEL_BIT_YAW_PITCH_ROLL ... #define FSMI_TEL_BIT_YAW_PITCH_ROLL_ACCELERATION ... #define FSMI_TEL_BIT_YAW_PITCH_ROLL_SPEED ... #define FSMI_TEL_BIT_SWAY_HEAVE_SURGE_ACCELERATION ... #define FSMI_TEL_BIT_SWAY_HEAVE_SURGE_SPEED ... #define FSMI_TEL_BIT_PEDALS_POSITION ... #define FSMI_TEL_BIT_GEAR_NUMBER ... #define FSMI_TEL_BIT_GROUND_TYPE ... #define FSMI_TEL_BIT_COLLISION ... #define FSMI_TEL_BIT_GLOBAL_POSITION ... #define FSMI_TEL_BIT_TIME ... #define FSMI_TEL_BIT_TRIGGERS ... #define FSMI_TEL_BIT_MAX_RPM ... #define FSMI_TEL_BIT_FLAGS ... #define FSMI_TEL_BIT_AUX ...
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:
- When the SIM enters runtime mode (it is going to send telemetry data), it calls ForceSeatMI_BeginMotionControl
- When the SIM exists runtime mode (it is not going to send telemetry data for a while), it calls ForceSeatMI_EndMotionControl
- When during runtime, there is a short pause event (e.g. user presses pause on a keyboard), the SIM should use statefield
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.
- 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.
| Example | Description | Required profile |
| TableLogPos_CPP TableLogPos_CS TableLogPos_Unity TableLogPos_Unreal |
Shows how to control top table position by specifying roll, pitch, yaw, heave, sway and surge in percent of maximum 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 Next Level Racing Platform Manager. | SDK – Vehicle Telemetry |
| Telemetry_Fly_Unity Telemetry_Fly_Unreal |
Shows how to send aeroplane telemetry data from the SIM to Next Level Racing Platform Manager. | SDK – Plane Telemetry |
Final thoughts
- When platform does not move or the system is in pause state, then:
- Check if correct profile is active in Next Level Racing Platform Manager
- Check if correct profile has been imported in Next Level Racing Platform Manager (different operation modes require different profiles)
- Check ForceSeatMI diagnostic to see if Next Level Racing Platform Managerreceives data from the SIM.
- Check if paused indicator is on or off
- Remember to configure mask field
- Remember to set correct state value to leave pause mode.
- ForceSeatMI32.dll/ForceSeatMI64.dll have been designed for high performance, so there is no logging available and the DLL does only minimal necessary data consistency checks.
