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.

Creating new profile

For most of supported games there are already built-in profiles. However in case a custom profile is needed, one can start from cloning existing profile or start from scratch.

1. Open main program window and click on existing profile.
2. Click Clone

3. Enter name for new profile and click OK.

4. The Profile Editor will be opened.
5. For purpose of this exercise, remove all scripts except the one for Any platform.

5. Click Save to apply changes.
6. Click View - it will open a directory contains the script.

7. Finally open the script (*.js) in text editor (e.g. Notepad, Notepad++).

NOTE: ForceSeatPM monitors for changes in script file. It means that when the script file is modified in e.g Notepad, there is no need to reactive the profile. ForceSeatPM will automatically reload the script as long as the profile the script belongs to is still active.

Input and effects plug-ins

Before moving to script modification, here is explanation of Input and Effects plug-ins role in motion profiles.

Input plug-in

Input plug-in defines source of main telemetry data. Below is a list of plug-ins and their purposes. Please notice that this list can change in next version of the software.

Besides game specific plug-ins there are also more generic plugins:

Some plug-ins require a connector (a different type of plug-in, usually DLL library) to be installed in a game folder, other just need game reconfiguration.

In most cases all these tasks (connector installation and game reconfiguration) are done by ForceSeatPM semi-automatically – they appear as issues in Action Center and one just has to click Install or Configure.

However if for some reason ForceSeatPM is not able to find game installation folder, manual connector installation has to be performed via Games Integration.

Effects plug-in

Effects plug-in defines second source of data, usually effects data like bumps and hits. Currently there is only one plug-in which captures ForceFeedback data sent from a game to the game controller. This requires the game to use ForceFeedback protocol and send some useful information to the game controller, please notice that not all games do it.

From technical point of view, the plug-in transforms captured force feedback related information into single value called Force0. Additionally there is Force1 introduced for convenience - it is an absolute value of Force0.

Please notice Force0 and Force1 parameters can change in a very abrupt way. If they are not properly scaled, it is possible that the device will perform very rapid movements, which could ultimately damage the delicate components of the simulator or harm the user.

ForceFeedback plug-in requires specific system configuration. ForceSeatPM can find all installed controllers and create an Action Center issues for them so they can be configured with a single click. Please notice that capturing ForceFeedback changes registry and installs a monitor next to the game controller driver.

It is possible that the monitor will affect driver's normal operation. In that case, it is necessary to disable monitor for specific game controller.

In order to enable or disable ForceFeedback monitor for selected game controller you should:

  1. Open profile that uses Forcefeedback as effects plug-in (this profile does not have to be active)
  2. Click Configure next to Effects plug-in
  3. Go to Shared section
  4. Check which game controller should be monitored
  5. Click Ok.
  6. UAC (User Account Control) will be displayed as changing registry requires higher privileges level.

Motion cueing

Motion system moves according to the parameters specified in the motion profile. Input parameters come from input plug-in and/or effect plug-in and they can have different names depending on selected plug-ins. The final position of a platform is a result of combination and transformation of different values received from the game. This transformation can be performed by a mapping mechanism or by a script mechanism.

The first one calculates final position of the platform by applying list of defined transformations of input values. It is easy in use but it is limited to predefined algorithms and transformations.

The second one uses Javascript custom code that gets values from the game as input and outputs desired platform position.

Please notice that instead of direct actuator positions, it is recommended to use axes. In this approach e.g. left-right rotation can be transformed by firmware into motion of two actuators for 2-dof platform but also for six actuators movement for 6-dof platform. It makes the profile more independent to the platform configuration. 

Following axes are used by ForceSeatPM and the platform firmware:

For both motion cueing mechanisms, it is very important to understand the relation between output values (axis values) and the actual platform motion:

The system therefore can move to 65535 possible positions on each of the motion axis and it is important to scale parameters from the game to the range of (-32767, 32767). Additionally every platform has some latency, so it is also important to scale and filter all parameters to reduce visible effect of delay.

The whole trick is to figure out how to use limited actuators operating range and G-force to make a player thinks that he or she is affected by the same forces as in real world when e.g. he or she is driving a car.

Data mapping transformation

After selecting input and effects plug-in, it is time to define mapping between telemetry received from the game and platform movements. Let’s start with defining generic parameters:

 

Next step is mapping definition. Click Add Mapping and first item will be added to a list. There are following fields that need configuration:

The final equation for single axis looks as follows:

 

 

You can use the same source a few times and you can also use the same axis a few times. In this case final value for axis is just a sum.

In theory data mapping looks simple, but the trick is to find the best parameters values and the best combination of different source signals. Usually it takes hours of experiments and diagnostic module can be useful here.

Typical scenario looks as follows:

  1. Create a basic profile for the game.
  2. Activate the profile and open diagnostic for input/effects plug-in. It can be done from Profile Editor (by clicking Diagnostic button) or from a main program window in profile details view.
  3. Start the game in a windowed mode (if it is possible), otherwise use second display.
  4. Play the game and observe platform movements and also values in diagnostic window.
  5. Adjust the profile.
  6. Repeat steps 4 and 5 until results are as expected.

Please notice that is it not necessary to reactivate the profile, it is enough to just click Save.

Script transformation

If the data mapping is not enough and additional processing has to be performed, the solution is script transformation mechanism. It uses Javascript to define a small program that transforms input data into platform’s axis: http://doc.qt.io/qt-5/ecmascript.html

When the built-in profile is cloned, it already has an script. Most of script for racing games uses MoSy_DefaultProcessor and usually it is enough to tune its parameters. For flight simulators usually combination of low pass filters is used. You can always check default scripts for reference.

Please notice that the script execution time is crucial. No delays, waits or long operations are allowed, otherwise it will introduce extra latency.

The script itself has to define a function called process(), all other functions and variables are optional.

The default script file contains a list of all available input fields (defined as global variables) and output axes that have to be set (also defined as global variables). It is up to a user to write a code that maps input fields into output fields. Usually it is good to use low pass and high pass filters to catch bump and hits and at the same time slightly smooth normal movements (left-right rotations).

For purpose of this tutorial, we will focus on racing games and adjusting parameters of "default processor".

Signal filters for racing games

Parameters that configure motion platform moves are grouped into 6 categories. Each category is mapped to one axis.

For each of axis there is 7 parameters that configure low-pass and high-pass filters. Low-pass filter is used to get main trend from input signal and high-pass filter to get bumps, vibrations and other irregular and rapid signal changes.

Please check following script fragment for reference:

var rollLowPassFactor        = 45;
var rollHighPassFactor       = 10;
var rollOutputFactor         = 12;
var rollHighOutputFactor     = -7;
var rollMax                  =  90;
var rollHighPassFilterCutOff = 90;
var rollBumpMin              = 5;
 
var heaveLowPassFactor        = 25;
var heaveHighPassFactor       = 10;
var heaveOutputFactor         = 15;
var heaveHighOutputFactor     = -12;
var heaveMax                  = 25;
var heaveHighPassFilterCutOff = 30;
var heaveBumpMin              = 15;
 
// ...
 
function process() {
  var rollValue  = -in_FieldAccGX * 10;
  var pitchValue =  in_FieldAccGZ * 10;
  var heaveValue =  in_FieldAccGY * 10;
  var yawValue   =  -in_FieldHeadingChange / 10;
  var surgeValue =  in_FieldAccGZ * 10;
  var swayValue  = -in_FieldAccGX * 10;
 
  MoSy_DefaultProcessor(rollValue, pitchValue, heaveValue, yawValue, surgeValue, swayValue);
}

The meaning of parameters is as follows:

Flight simulators - FSX and P3D

Both plug-ins use SimConnect interface. Each field in script is mapped to SimConnect variable. The mapping is as follows:

Detailed description of SimConnect variables can be found on following pages:

Additionally the script calculates bank ratio and pitch ratio:

A helper class is used for it - MoSy_ChangeRatioCalculator(interval, ratioFactor, prevSmoothValue):

The script has also access to following fields:

Flight simulators - X-Plane

Each field in script is mapped to DataRef variable. The mapping is as follows:

Detailed description of variables can be found on following pages:

The script has also access to following fields:

Predefined functions in scripts

Beside standard Javascript functions, following predefined functions are also available in scripts: