SRS OpenXR Motion Compensation Guide

** THIS GUIDE IS STILL IN DEVELOPMENT AND IS NOT COMPLETE **

This guide provides guidance on how to install, setup, and use OpenXR Motion Compensation with Sim Racing Studio. WARNING: OpenXR Motion Compensation is still in early development and setup and functionality is subject to change. OpenXR Motion Compensation is considered an experimental feature within Sim Racing Studio and support is not provided. Use at your own risk. Topics include: Supporting the OpenXR Motion Compensation Developer OpenXR Discord Supported VR Headsets, Games, and Trackers

Requirements

Setup Guide (In Progress) Example Settings (Coming Soon)

Troubleshooting (Coming Soon)

Supporting the OpenXR Motion Compensation Developer

OpenXR Motion Compensation is being developed primarily by a single individual. His Discord name is BuzzteeBear, but his real name is Sebastian Veith. He is doing everyone an incredible service by getting OpenXR MC to work with the help of others for free. Please donate to his Paypal donation link here.

He deserves anything you can send his his way. THANK YOU BUZZTEEBEAR!

OpenXR Motion Compensation Discord

Join the OpenXR Motion Compensation Discord Server here. Please use this Discord to obtain assistance, feedback, monitor for new releases, report bugs, and provide success-reports. Please join the Discord and apply to become an **@Alpha Tester**.

If you are (or know someone) willing and able to support the software development (mostly C++ and GUI), feel free to contact **@BuzzteeBear** on the Discord server about ways to contribute.

Supported VR Headsets, Games, and Trackers

The following VR Headsets, Games, and Trackers have been listed in the success-reports channel in the OpenXR Motion Compensation Discord. If your headset, game, or tracker is not listed, please follow this guide to test OpenXR MC and report your finding in either the bugs or success-reports channel. Both Windows 10 and Windows 11 have been confirmed to work.

VR Headsets

• Varjo Aero

• Reverb G2

• Pimax 8KX

Games

• DCS

• DCS Open Beta

• MS Flight Simulator (2020)

• IL-2 Sturmovik

• IL-2 Sturmovik: Flying Circus

• Assetto Corsa Competizione

Trackers

• Witmotion Sensor with SRS (2.24.0.20)

• Sim Racing Studio Virtual Tracker

Requirements

The following items are required to use SRS OpenXR Motion Compensation:

1. Windows 64-bit

2. SRS Premium Subscription

3. OpenXR Supported Game

4. OpenXR Motion Compensation (OXRMC)

5. Witmotion WT901C (RS232) Sensor and Witmotion RS232 USB Cable

Windows 64-bit

The OpenXR Motion Compensation API Layer is made for Windows 64-bit only.

SRS Premium Subscription

A SRS Premium Subscription is required to enable Motion Compensation in Sim Racing Studio. A SRS Premium Subscription can be purchased here or from within SRS by going to SETUP > License and clicking the Premium purchase button. This subscription enables SRS to continue development on new and experimental projects and provides additional features including:

• Joystick Telemetry Maker

• Premium Shaking Effects

• Mobile Companion to access SRS from Phone or Tablet

• Pro-Tune Profile Downloads

• Cloud Tune Sharing and Importing

• Intellitune WIzard for Motion Platforms

• Cloud Backup and Restore

OpenXR Supported Game

OpenXR is new and still in development. Games are being updated frequently to support OpenXR. The list above in Supported Games will be updated once new games are verified to be working with OXRMC. You can find more information about OpenXR on the Khronos website here or via Wikipedia here.

OpenXR Motion Compensation

OpenXR Motion Compensation (OXRMC) works with the OpenXR API layer to enable motion compensation within the OpenXR runtime. Download the latest version of OpenXR Motion Compensation via the release channel on the OpenXR Discord Server here. The zip file will contain the binary and scripts needed for OpenXR Motion Compensation to work.

The latest version as of August 14th, 2022 is OpenXR-MotionCompensation_V_0_1_4.zip (138.96 KB)

Witmotion WT901C (RS232) Sensor and Witmotion RS232 USB Cable

The Witmotion WT901C sensor and its required Witmotion RS232 USB Cable are utilized by SRS to know the precise movements of the motion platform. The specific model Witmotion sensor and cable are the only ones officially tested and supported.

The Witmotion sensor can be purchased from the following locations:

• Aliexpress link here. IMPORTANT: When purchasing from Aliexpress, different models will be available on the product detail page. Only the WT901C (RS232) + RS232 Cable have been verified to work with SRS Motion Compensation. Ensure you purchase the correct Witmotion sensor and cable. An image of the correct bundle that includes both the WT901C (RS232) sensor and RS232 Cable is below:

• Amazon link for the Witmotion WT901C (RS232) sensor can be found here and the link for the Witmotion RS232 USB Cable can be found here. NOTE: If purchasing the Witmotion Sensor or Cable from different Amazon country websites (ie. amazon.ca, amazon.uk.co, amazon.de, etc), ensure the exact model of the Witmotion Sensor and Cable are purchased. Images of the correct WT901C (RS232) sensor and RS232 Cable are below:

DISCLAIMER: Sim Racing Studio Motion Compensation is an experimental feature and might stop working if there are updates to SteamVR or if OpenVR Motion Compensation (OVRMC) ends development. Sim Racing Studio is not responsible for any expenses you incurred related to the Sim Racing Studio Motion Compensation feature.

Setup Guide

SRS OpenXR Motion Compensation is still in development and this setup guidance is likely to change in the near future. The below guidance is taken directly from the OpenXR-MotionCompensation_User_Guide.md found in the OpenXR Motion Compensation install zip file.

NOTE: Sim Racing Studio is unable to guarantee support resolution for the experimental feature of motion compensation. If support is needed, join the Sim Racing Studio Motion Compensation Discord channel here or the OpenXR Motion Compensation Discord here.

Text copied from the OpenXR-MotionCompensation_User_Guide (v014) and reorganized below. A proper Installer is planned for a future release.

This Setup Guide will cover the following topics:

1. Extracting the OpenXR Motion Compensation Zip File

2. Execute the Install Script

3. Optional: Confirm Correct Installation

4. OpenXR Motion Compensation Update Process

5. How to uninstall OpenXR Motion Compensation

6. OXRMC Configuration

7. Modifications of the OXRMC Configuration File

8. Sections in the OXRMC Configuration File

9. Using the Virtual Tracker

10. Calibrating the Virtual Tracker

11. Saving the Center of Rotation Location (Experimental)

12. Running your Application

13. Additional Notes

14. Logging

15. List of Keyboard Bindings

Extracting OpenXR Motion Compensation Zip File

Copy the files contained in the OpenXR-MotionCompensation.zip archive to a subdirectory (name it as you like) in your **Program Files** location. The directory should not have any special write access restrictions since the binary creates a configuration file for each application it is loaded from.

Execute the Install Script

1. Right click on the file `Install-OpenXR-MotionCompensation.ps1` and select the option **Run with PowerShell**

2. Confirm the UAC dialog

This will create a Windows Registry Entry making it possible for to load the API Layer on OpenXR initialization.

Optional: Confirm Correct Installation

The following step is optional and not required to use OpenXR Motion Compensation. You can use the application OpenXR Explorer that can be downloaded here to verify the installation was correct:

1. Install OpenXR Explorer

2. Connect your headset

3. Start your corresponding VR runtime application (e.g. SteamVR, Oculus App, Mixed Reality Portal, Varjo Base, PiTool, etc.)

4. Start OpenXR explorer

5. Search for the section `xrEnumerateApiLayerProperties` (should be in the middle column at the bottom by default)

6. Check if the entry `XR_APILAYER_NOVENDOR_motion_compensation` with version `v1` exists

OpenXR Motion Compensation Update Process

Since OpenXR Motion Compensation is under development, updates will occur often. To use an updated version of OXRMC, it is sufficient to just replace the binary (OpenXR-MotionCompensation.dll) in the installation directory. Replacing the user guide with the latest version upon updating is also highly recommended. It is not necessary to uninstall OXRMC for each new release unless you want to use a another/different directory.

How to Uninstall OXRMC

To remove the OpenXr Motion Compensation layer:

1. Execute the script `Uninstall-OpenXR-MotionCompensation.ps1` located in your OXRMC installation folder. Note: This only works correctly when executed from the same directory the installation script was executed from.

2. Optional: Delete the files in the OXRMC installation directory.

Note: You can check if your uninstall worked correctly in the Windows Registry. The path `Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1\ApiLayers\Implicit` should always only contain one entry ending on `XR_APILAYER_NOVENDOR_motion_compensation.json`. If there is more than one entry present, delete the ones pointing to the directories you're not using.

OXRMC Configuration

The OXRMC zip archive contains the default configuration file `OpenXR-MotionCompensation.ini`. You can make changes to that file to configure options you want to be the same for all OpenXR applications.

Upon starting an OpenXR application with the API layer active for the first time, a configuration file named after the application is created in the installation directory. You can use it to copy (partial) sections from the default configuration file whenever you want to make changes only for that application specifically.

Modifications of the OXRMC Configuration File

The following can be modified in a configuration file:

1. The tracker to use for motion compensation

2. The strength and the number of filtering stages for both translational and rotational filters

3. Keyboard inputs (e.g. to activate/deactivate or re-calibrate motion compensation during runtime)

Sections in the OXRMC Configuration File

- `tracker`: The following tracker `type` keys are available:

- `controller`: use either the left or the right motion controller as reference tracker. Valid options for the key `side` are `left` and `right` (this is also used for motion controller based debug mode)

Note: Verification needed if required for SRS MC.

- `srs`: use the virtual tracker data provided by SRS motion software when using a Witmotion sensor on the motion rig.

- the keys `offset_...`, `use_cor_pos` and `cor_...` are used to handle the configuration of the center of rotation (cor) for all available virtual trackers.

- `translational_filter` and `rotational_filter`: set the filtering magnitude (key `strength` with valid options between **0.0** and **1.0**) number of filtering stages (key `order`with valid options: **1, 2, 3**).

- `shortcuts`: can be used to configure shortcuts for different commands (See [List of keyboard bindings](appendix:_list-of-keyboard-bindings) for valid values):

- `activate`- turn motion compensation on or off. Note that this implicitly triggers the `center` action if that hasn't been executed before.

- `center` - re-calibrate the neutral reference pose of the tracker

- `translation_increase`, `translation_decrease` - modify the strength of the translational filter. Changes made during runtime can be saved by using a save command (see below).

- `rotation_increase`, `rotation_decrease` = see above, but for rotational filter

- `offset_forward`, `offset_back`, `offset_up`, `offset_down`, `offset_right`, `offset_left` - move the center of rotation (cor) for a virtual tracker. The directions are aligned with the forward vector set with the `center` command. Changes made during runtime can be saved by using a save command (see below)

- `rotate_right`, `rotate_left` - rotate the aforementioned forward vector around the gravitational (yaw-)axis. Note that these changes cannot be saved. Therefore changing the offset position AFTER rotating manually and saving the offset values will result in the cor being a different offset position after reloading those saved values

- `cor_debug_mode` - since OXRMC is lacking a visual feedback of the position of the cor, you can activate this mode to be able to rotate the virtual world around the cor. Translations of the motion tracker are ignored in this mode.

**Beware that this can be a nauseating experience because your eyes suggest that your moving inside the virtual world, while your inner ear tells your brain otherwise. You can stop motion compensation at any time by pressing the activation shortcut again!**

- `save_config` - write current filter strength and cor offsets to global config file

- `save_config_app` - write current filter strength and cor offsets to application specific config file. Note that values in this file will precedent values in the global config file.

- `reload_config` - read in and apply configuration for current app from config files. For technical reasons motion compensation is automatically deactivated and the reference tracker pose is invalidated upon configuration reload.

- `debug`: For debugging reasons you can check, if the motion compensation functionality generally works on your system without using tracker input from the motion controllers at all by setting `testrotation` value to `1` and reloading the configuration. You should be able to see the world rotating around you after pressing the activation shortcut.

**Beware that this can be a nauseating experience because your eyes suggest that your head is turning in the virtual world, while your inner ear tells your brain otherwise. You can stop motion compensation at any time by pressing the activation shortcut again!**

Using the Virtual Tracker

To use a virtual tracker set parameter `tracker_type` to `srs`: Sim Racing Studio (experimental)

Note: Verification that the signum of the positional and rotational values within Sim Racing Studio is set correctly is needed. Any feedback on this is highly appreciated and should be posted in the OXRMC Discord.

Calibrating the Virtual Tracker

To enable OXRMC to correlate translation and rotation of the rig to the virtual space correctly when using a virtual tracker, you have to provide the information where the Center of Rotation (COR) of your motion rig is positioned and which way is forward. This is done with the following steps:

1. Calculate, measure or estimate the distance between your headset and the center of rotation of your motion rig in forward/backward, up/down and left/right direction (Most 6DOF rigs rotate around the bottom of the seat; however, many motion platforms are different so the actual Center of Rotation might vary).

2. Enter the offset values in the config file

3. Start the OpenXR application of your choice

4. Bring your motion rig in neutral position

5. Sit in your rig

6. Put your headset on and face forward (~ direction surge). Potential rotation of the HMD on roll and pitch angle is ignored for the calculation

7. Issue the `center` command by activating the corresponding shortcut. You can also do this implicitly by activating motion compensation if you haven't (re)centered since last loading of the configuration.

Saving the Center of Rotation Location (Experimental)

The current position and orientation of the COR is part of the configuration and can be saved to the (global or app-specific) config file. When your satisfied with the current setting you can set the config key `use_cor_pos` to `1`. This causes the cor position to be loaded from the config file when calibrating instead of being determined using the HMD position and the offset values.

Note that this functionality is still experimental and may not work with all HMD vendors. Setting up the play-space in the VR runtime configuration of your HMD might help to get this working correctly. Some HMDs may need to be started/initialized at the exact same location for the play-space coordinates to be consistent in between uses.

Feedback on success or failure of this functionality using different VR systems is required and should be posted in the feedback channel of OXRMC Discord.

Running your Application

1. Make sure your using OpenXR as runtime in the application you wish to use motion compensation in

2. Start the application

3. Center the in-app view

4. Activate the motion controller you configured and mount it on your motion rig

5. Bring your motion rig to neutral position

6. Reset the in-game view if necessary

7. Press the `activate` shortcut (**CTRL** + **INSERT** by default). This implicitly sets the neutral reference pose for the tracker

Notes:

• If necessary you can re-calibrate the tracker by pressing the `center` shortcut (**CTRL** + **DEL** by default) while the motion rig is in neutral position

• You can increase or decrease the filter strength of translational and rotational filters

• You can modify the cor offset when currently using a virtual tracker

• After modifying filter strength or cor offset for virtual tracker you can save your changes to the default configuration file

• After modifying the config file(s) manually you can use the `reload_config` shortcut (**CTRL** + **SHIFT** + **L** by default) to restart the OXRMC software with the new values.

Additional Notes

Upon activating a shortcut you get audible feedback, using either the confirmation, warning or error sound configured in your windows system control, depending on whether the execution of the action was successful.

If you recenter the in-app view during a session the reference pose is reset by default. Therefore you should only do that while your motion rig is in neutral position. It is possible (depending on the application) that this automatic re-calibration is not triggered, causing the view and reference pose to be out of sync and leading to erroneous motion compensation. You should do the following steps to get this corrected again:

1. Deactivate motion compensation by pressing the `activate` shortcut

2. Bring your motion rig to neutral position. Face forward if your using a virtual tracker

3. Press the `center` shortcut

4. Reactivate motion compensation by pressing the `activate` shortcut

If the motion controller cannot be tracked for whatever reason (or if the memory mapped file containing the motion data for a virtual tracker cannot be found or accessed) when activating motion compensation or re-calibrating the tracker pose, the API layer is unable to set the reference pose and motion compensation is (or stays) deactivated.

Logging

The motion compensation layers logs rudimentary information and errors in a text file located at **...\Users\<Your_Username>\AppData\XR_APILAYER_NOVENDOR_motion_compensation.log**. After unexpected behavior or a crash you can check that file for abnormalities or error reports.

If you encounter repeatable bugs or crashes you can use the Windows Performance Recorder Profile (WPRP) tracelogging in `scripts\Tracing.wprp` to create a more detailed protocol. Tracelogging, found here, can become very useful to investigate user issues.

To capture a trace for the API layer:

1. Start the OpenXr application

2. Open a command line prompt or powershell in administrator mode and in a folder where you have write permissions

3. Begin recording a trace with the command: `wpr -start path\to\Tracing.wprp -filemode`

4. Leave that command prompt open

5. Reproduce the crash/issue

6. Back to the command prompt, finish the recording with: `wpr -stop arbirtary_name_of_file.etl`

Note: These files are highly compressible.

List of Keyboard Bindings

To combine multiple keys for a single shortcut they need to be separated by '+' with no spaces in between the key descriptors. List of supported shortcut key names:

- `SHIFT`: shift key

- `CTRL`: ctrl key

- `ALT`: alt key

- `LSHIFT`: left shift key

- `RSHIFT`: right shift key

- `LCTRL`: left ctrl key

- `RCTRL`: right ctrl key

- `LALT`: left alt key

- `RALT`: right alt key

- `0`- `9`: numerical key

- `A`- `Z`: alphbetical key

- `BACKQUOTE`: `~ key (US)

- `TAB`: tabulator key

- `CAPS`: caps lock key

- `PLUS`: + key (any country)

- `MINUS`:- key (any country)

- `OPENBRACKET`: [{ key (US)

- `CLOSEBRACKET`: ]} key (US)

- `SEMICOLON`: ;: key (US)

- `QUOTE`: '" key (US)

- `BACKSLASH`: \\| key (US)

- `COMMA`: , key (any country

- `PERIOD`: . key (any country)

- `SLASH`: /? key (US)

- `BACK`: backspace key

- `CLR`: clr key

- `RETURN`: return key

- `ESC`: esc key

- `SPACE`: space key

- `LEFT`: cursor left key

- `UP`: cursor up key

- `RIGHT`: cursor right key

- `DOWN`: cursor down key

- `INS`: ins key

- `DEL`: del key

- `HOME`: home key

- `END`: end key

- `PGUP`: page up key

- `PGDN`: page down key

- `NUM0`: 0 key on NUM

- `NUM1`: 1 key on NUM

- `NUM2`: 2 key on NUM

- `NUM3`: 3 key on NUM

- `NUM4`: 4 key on NUM

- `NUM5`: 5 key on NUM

- `NUM6`: 6 key on NUM

- `NUM7`: 7 key on NUM

- `NUM8`: 8 key on NUM

- `NUM9`: 9 key on NUM

- `NUMLOCK`: numlock key

- `NUMDIVIDE`: / key on NUM

- `NUMMULTIPLY`: * key on NUM

- `NUMSUBTRACT`:- key on NUM

- `NUMADD`: + key on NUM

- `NUMDECIMAL`: . key on NUM

- `NUMSEPARATOR`: separator key on NUM

- `F1`: F1 key

- `F2`: F2 key

- `F3`: F3 key

- `F4`: F4 key

- `F5`: F5 key

- `F6`: F6 key

- `F7`: F7 key

- `F8`: F8 key

- `F9`: F9 key

- `F10`: F10 key

- `F11`: F11 key

- `F12`: F12 key

- `PRTSC`: print screen key

- `SCROLL`: scroll lock key

- `PAUSE`: pause key

- `SELECT`: select key

- `PRINT`: print key

- `HELP`: help key

- `EXEC`: execute key

- `GAMEPAD_A`: A button on gamepad

- `GAMEPAD_B`: B button on gamepad

- `GAMEPAD_X`: X button on gamepad

- `GAMEPAD_Y`: Y button on gamepad

- `GAMEPAD_RIGHT_SHOULDER`: right shoulder button on gamepad

- `GAMEPAD_LEFT_SHOULDER`: left shoulder button on gamepad

- `GAMEPAD_LEFT_TRIGGER`: left trigger button on gamepad

- `GAMEPAD_RIGHT_TRIGGER`: right trigger button on gamepad

- `GAMEPAD_DPAD_UP`: digital pad up on gamepad

- `GAMEPAD_DPAD_DOWN`: digital pad down on gamepad

- `GAMEPAD_DPAD_LEFT`: digital pad left on gamepad

- `GAMEPAD_DPAD_RIGHT`: digital pad right on gamepad

- `GAMEPAD_START`: start button on gamepad

- `GAMEPAD_VIEW`: view button on gamepad

- `GAMEPAD_LEFT_THUMBSTICK_BUTTON`: left thumbstick pressed on gamepad

- `GAMEPAD_RIGHT_THUMBSTICK_BUTTON`: right thumbstick pressed on gamepad

- `GAMEPAD_LEFT_THUMBSTICK_UP`: left thumbstick up on gamepad

- `GAMEPAD_LEFT_THUMBSTICK_DOWN`: left thumbstick down on gamepad

- `GAMEPAD_LEFT_THUMBSTICK_RIGHT`: left thumbstick left on gamepad

- `GAMEPAD_LEFT_THUMBSTICK_LEFT`: left thumbstick right on gamepad

- `GAMEPAD_RIGHT_THUMBSTICK_UP`: right thumbstick up on gamepad

- `GAMEPAD_RIGHT_THUMBSTICK_DOWN`: right thumbstick down on gamepad

- `GAMEPAD_RIGHT_THUMBSTICK_RIGHT`: right thumbstick left on gamepad

- `GAMEPAD_RIGHT_THUMBSTICK_LEFT`: right thumbstick right on gamepadAA