SteamVR ================ This guide provides step-by-step instructions to download, set up, and run the AMFITRACK SteamVR driver. Prerequisites ------------- Before you begin, ensure you have the following installed on your system: - **AMFITRACK Viewer**: Install the `AMFITRACK Viewer `_. - **SteamVR**: Install `SteamVR `_. Steps to Download, Setup, and Run --------------------------------- 1. Download the Driver ^^^^^^^^^^^^^^^^^^^^^^^^ 1. Go to the `AMFITRACK_SteamVR Releases page `_. 2. Download the latest release ZIP file. 3. Extract the contents of the ZIP file to a location on your system. 2. Copy the Driver to SteamVR ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Locate the extracted `AMFITRACK_SteamVR` folder from the downloaded release. 2. Copy the `AMFITRACK_SteamVR` folder to your SteamVR `drivers` directory. The typical location is: ``` C:\Program Files (x86)\Steam\steamapps\common\SteamVR\drivers ``` 3. Configure AMFITRACK devices for SteamVR ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Use the AMFITRACK Viewer to configure device IDs for the AMFITRACK system: ================ =================== **AMFITRACK ID** **device-type** ================ =================== 2 Left Controller 3 Right Controller 4 Generic Tracker 01 5 Generic Tracker 02 6 Generic Tracker 03 7 Generic Tracker 04 9 HMD Src Tracker ================ =================== 4. Verify Operation ^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Ensure your AMFITRACK hardware is properly connected and powered on. 2. Open SteamVR and verify that the AMFITRACK system appears in the list of tracking devices. 3. Test the tracking functionality within a VR environment. How to use AMFITRACK SteamVR driver ------------------------------------ The AMFITRACK SteamVR driver supports multiple applications, including: - **Unity**: Compatible with Unity-based applications. - **Unreal Engine**: Compatible with Unreal Engine-based applications. - **SteamVR-based games**: Fully supported for general VR use. How to use AMFITRACK SteamVR driver ------------------------------------ GPIO pins of the AMFITRACK sensors have 4 Digital and 1 analog input. The button on the AMFITRACK sensor is connected to Digital #1 ================ ===================== ===================== **AMFITRACK ID** **Left Controller** **Right Controller** ================ ===================== ===================== Digital #1 B click A click Digital #2 A click B click Digital #3 Trackpad touch Trackpad touch Digital #4 System touch System touch Analog Trigger Value Trigger Value ================ ===================== ===================== These input bindings are prone to change in future updates. It should be noted that the button of the AMFITRACK sensor is conencted to Digital #1. Additionally the default state of Digital #2, Digital #3, and Digital #4 is high. The Analog will report a value of around 0.15 Volt about euqvalent to 4% of the maximum value. If the button is used in this way it is the parameter **options->Use Button for startup** must be disabled. Otherwise pressing the button will corrupt the tracking. This is easily done through the AMFITRACK viewer. It must be noted however, that in order for **options->Use Button for startup** to be visible **options->Config mode (0:2)** must be 1 or 2. Pressing "O" on the key board will press the system button on the right controller. Configure AMFITRACK SteamVR Settings - Source Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The AMFITRACK SteamVR driver supports three modes of operation describbing how the AMFITRACK system is locked to the rest of the SteamVR tracking. To change the mode settings, open SteamVR and locate the AMFITRACK settings. Select the desired mode using the dropdown menu. Mode 1: Static Source """""""""""""""""""""""""""""""""""""""""""""""""" The Source is placed statically relative to the origin of the play area. Mode 2: HMD SOURCE """""""""""""""""""""""""""""""""""""" The source is mounted on headset. This setup is ideal for VR applications where VR controllers are the primary input devices. It leverages the HMD for movement, such as with the HTC Vive Focus 3 or Oculus Quest 3. Mode 3: SOURCE FREE MOVING - PREVIEW """""""""""""""""""""""""""""""""""""""""""""" This mode is mode is fully functional and as can be used like any of the other modes. However, this mode has a significant amount of positional noise so it is only considered a preview of what will be possible in the future. The **HMD Src Tracker** is mounted on the headset. The source is able to move completely freely. This setup is ideal for VR applications where VR controllers are the primary input devices. It leverages the HMD for movement, such as with the HTC Vive Focus 3 or Oculus Quest 3. The main advantage over **HMD SOURCE** is the reduced weight on the headset. Rotations and fast movements of the source may temporaly cause the sensors to appear to be moving (and rotate). It is therefore recommed limiting movement of the source. While in this mode the **HMD Src Tracker** will report the pose of the source in SteamVR rather than its own pose. Configure AMFITRACK SteamVR Settings - Attachment pose ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Driver needs to know how it relates to the rest of the SteamVR tracking. Depending on the **Source Mode** selected either the source or **HMD Src Tracker** is selected as the hardware linking the two tracking systems, this refered to as the **attachment**. When using **HMD SOURCE** or **SOURCE FREE MOVING** the **attachment** pose is described relative to the HMD. The default pose is the origin of the HMD. The origin of most HMDs are placed inside the HMD or between the eyes, Since the **attachment** and headset cannot physically occupy the same the location and offset is required. To compensat for this three settings allow for moving the attachment point relative to the HMD ``AMFITRACK attachment X/Y/Z postion offset to HMD [meters]``. Additionally the orientation of the **attachment** can also be defined relative to the HMD using euler angles (``AMFITRACK attachment X/Y/Z orientation offset to HMD [degrees]``). The euler angles are aplied in the z-y-x sequence all relative to the **attachment**. When using **Static Source** the attachment is defined relative to the origin of the play area (rather than the HMD). In many cases measuring the position and orientation offsets of the attachment may be difficult. To minimize this annoyance the attachment point can be vizulalized inside steamVR (and anything using data from steamVR). This can be done by enabling ``Display Attachment pose``, this will cause all sensors to report the pose of the **attachment** rather what they would normally report. This naturally also means that ``Display Attachment pose`` must be disbaled for normal tracking purposes. Utilizing the visualization in Steam VR makes it much simpler to set the correct **attachment** pose offset. The simplest way of doing this physically mounting the **attachment** hardware where it needs to be. Then using the steamVR settings moving the visualization into view, by changing the position offset. Then finding the correcting orientation offset. Then moving the **attachment** into the correct location inside the VR space. When using a VR headset it should occupy the same virtual location as the physical **attachment** does in real life. Lastly remeber to disabled ``Display Attachment pose``. The picture below shows how both the sensor and sources are orientated relative to an HTC vive controller, which is used as the visual represensentation in steamVR. It should be noted that the coordinate definations used in steamVR are different from the one normally used in AMFITRACK. .. image:: VR_coords_Source01.png :width: 600 :alt: Alternative text The steamVR interface is limited in terms of both resolution and range. It is possibel to set the values preciesely and go beyond the maximum values, by setting them manually inside ``C:\Program Files (x86)\Steam\config\steamvr.vrsettings``. It should be noted that the values will only apear in the file once they have been set atleast once through the steamVR interface. It should also be noted that each **Source Mode** has its own set of six variables which can be set. Guidelines for mounting AMFITRACK HW on VR-headsets --------------- Some general advice and design considerations are listed below, but it is worth Enquire with Amfitech about advice for making an optimal design or getting a bracket for a particular HMD. The **attachment** must be mounted in such a way that it is physically locked relative to the displays inside the HMD. In most casses this means that the **attachment** can not be mounted on the headstrap of the HMD, on top of the head or other similiar placements. even a small rotation will result in massive positional displacements. The **attachment** must not be mounted in such a way that it obstructs the tracking of the HMD. Either by blocking or partially obscuring HMD sensors and/or emitters. The HMD contains large amounts of metal which negatively affects the AMFITRACK tracking. To minimize the impact the coil of the **attachment** should be placed as far as possible away from the HMD as possible, while still being locked to it. Troubleshooting --------------- - **Driver Not Found:** Ensure the `SteamVRDriver` folder is correctly copied to the SteamVR `drivers` directory. - **Connection Problems:** Verify that the AMFITRACK hardware is correctly connected to your PC and powered on. - **SteamVR Issues:** Restart SteamVR and check for updates. Support ------- For further assistance, refer to the `Amfitrack_SteamVR GitHub Issues page `_ to report or view known issues.