diff --git a/Readme.md b/Readme.md new file mode 100644 index 00000000..878a6854 --- /dev/null +++ b/Readme.md @@ -0,0 +1,269 @@ +![language](https://img.shields.io/badge/Language-C%2B%2B11-green.svg) ![dependencies](https://img.shields.io/badge/Dependencies-Boost%201.63-green.svg) ![license_gpl3](https://img.shields.io/badge/License-GPL%203.0-green.svg) + +# OpenVR-InputEmulator + +An OpenVR driver that allows to create virtual controllers, emulate controller input, manipulate poses of existing controllers and remap buttons. A client-side library which communicates with the driver via shared-memory is also included. + +The OpenVR driver hooks into the HTC Vive lighthouse driver and allows to modify any pose updates or button/axis events coming from the Vive controllers. Due to the nature of this hack the driver may break when Valve decides to update the driver-side OpenVR API. + +The motivation of this driver is that I want to make myself a tracked gun that is guaranteed to work in any SteamVR game regardless of whether the original dev wants to support tracked guns or not. To accomplish this I need some way to add translation and rotation offsets to the poses of the motion controllers so that I can line up my tracked gun and the gun in the game. Additionally I need a way to easily switch between the tracking puck on my gun and my motion controller with the game thinking it's still the same controller (Throwing grenades with a tracked gun is not fun). But this driver should also support other use cases. + +There is also a client-side API which other programs can use to communicate with the driver. This API should be powerful enough to also support the development of full-fledged motion-controller drivers. + +# Features + +- Create virtual controllers and control their positions and rotations. +- Emulate controller input. +- Remap controller buttons. +- Add translation and rotation offsets to the pose of existing controllers. +- Mirror the pose from one controller to another. +- ... + +# Notes: + +This is a work-in-progress. + +# Usage + +## Driver + +Download the newest driver archive from the [release section](https://github.com/matzman666/OpenVR-InputEmulator/releases) and copy the contained directory into "\drivers". + +The **activateMultipleDrivers** setting must be set to true, otherwise SteamVR will not load the driver. + +## Client + +Currently there is only a command line client available. Download the newest client archive from the [release section](https://github.com/matzman666/OpenVR-InputEmulator/releases) and unpack it. Enter client_commandline.exe help on the command line for usage instructions. + + +# Documentation + +## client_commandline commands: + +### listdevices + +Lists all openvr devices. + +### buttonevent + +``` +buttonevent [press|pressandhold|unpress|touch|touchandhold|untouch] +``` + +Emulates a button event on the given device. See [openvr.h](https://github.com/ValveSoftware/openvr/blob/master/headers/openvr.h#L600-L626) for available button ids. + +### axisevent + +``` +axisevent +``` + +Emulates an axisevent on the given device. Valid axis ids are 0-4. + +### proximitysensor + +``` +proximitysensor [0|1] +``` + +Emulates a proximity sensor event on the given device. + +### getdeviceproperty + +``` +getdeviceproperty scan +``` + +Scans the given device for all available device properties. + +``` +getdeviceproperty [int32|uint64|float|bool|string] +``` + +Returns the given device property. See [openvr.h](https://github.com/ValveSoftware/openvr/blob/master/headers/openvr.h#L235-L363) for valid property ids. + +### listvirtual + +Lists all virtual devices managed by this driver. + +### addcontroller + +``` +addcontroller +``` + +Creates a new virtual controller. Serialnumber needs to be unique. When the command is successful the id of the virtual controller is written to stdout. + +### publishdevice + +``` +publishdevice +``` + +Tells OpenVR that there is a new device. Before this command is called all device properties should have been set. + +### setdeviceproperty + +``` +setdeviceproperty [int32|uint64|float|bool|string] +``` + +Sets the given device property. See [openvr.h](https://github.com/ValveSoftware/openvr/blob/master/headers/openvr.h#L235-L363) for valid property ids. + +### removedeviceproperty + +``` +removedeviceproperty +``` + +Removes the given device property. See [openvr.h](https://github.com/ValveSoftware/openvr/blob/master/headers/openvr.h#L235-L363) for valid property ids. + +### setdeviceconnection + +``` +setdeviceconnection [0|1] +``` + +Sets the connection state of the given virtual device. Default value is disconnected. + +### setdeviceposition + +``` +setdeviceposition +``` + +Sets the position of the given virtual device. + +### setdevicerotation + +``` +setdeviceposition +``` + +setdevicerotation . + +### devicebuttonmapping + +``` +devicebuttonmapping [enable|disable] +``` + +Enables/disables device button mapping on the given device. + +``` +devicebuttonmapping add +``` + +Adds a new button mapping to the given device. See [openvr.h](https://github.com/ValveSoftware/openvr/blob/master/headers/openvr.h#L600-L626) for available button ids. + +``` +devicebuttonmapping remove [|all] +``` + +Removes a button mapping from the given device. + +### devicetranslationoffset + +``` +devicetranslationoffset [enable|disable] +``` + +Enables/disables pose translation offset on the given device. + +``` +devicetranslationoffset set +``` + +Sets the pose translation offset on the given device. + +### devicerotationoffset + +``` +devicerotationoffset [enable|disable] +``` + +Enables/disables pose rotation offset on the given device. + +``` +devicerotationoffset set +``` + +Sets the pose rotation offset on the given device. + +### devicemirrormode + +``` +devicemirrormode off +``` + +Turns mirror mode off on the given device. + +``` +devicemirrormode [mirror|redirect] +``` + +Mirrors/Redirects the pose of the given device to another device. + +## Client API + +ToDo. See [vrinputemulator.h](https://github.com/matzman666/OpenVR-InputEmulator/blob/master/lib_vrinputemulator/include/vrinputemulator.h). + +# Examples + +## Create virtual controller + +``` +# Create virtual controller +client_commandline.exe addcontroller controller01 # Writes virtual device id to stdout (Let's assume it is 0) +# Set device properties +client_commandline.exe setdeviceproperty 0 1000 string lighthouse +client_commandline.exe setdeviceproperty 0 1001 string "Vive Controller MV" +client_commandline.exe setdeviceproperty 0 1003 string vr_controller_vive_1_5 +client_commandline.exe setdeviceproperty 0 1004 bool 0 +client_commandline.exe setdeviceproperty 0 1005 string HTC +client_commandline.exe setdeviceproperty 0 1006 string "1465809478 htcvrsoftware@firmware-win32 2016-06-13 FPGA 1.6/0/0 VRC 1465809477 Radio 1466630404" +client_commandline.exe setdeviceproperty 0 1007 string "product 129 rev 1.5.0 lot 2000/0/0 0" +client_commandline.exe setdeviceproperty 0 1010 bool 1 +client_commandline.exe setdeviceproperty 0 1017 uint64 2164327680 +client_commandline.exe setdeviceproperty 0 1018 uint64 1465809478 +client_commandline.exe setdeviceproperty 0 1029 int32 2 +client_commandline.exe setdeviceproperty 0 3001 uint64 12884901895 +client_commandline.exe setdeviceproperty 0 3002 int32 1 +client_commandline.exe setdeviceproperty 0 3003 int32 3 +client_commandline.exe setdeviceproperty 0 3004 int32 0 +client_commandline.exe setdeviceproperty 0 3005 int32 0 +client_commandline.exe setdeviceproperty 0 3006 int32 0 +client_commandline.exe setdeviceproperty 0 3007 int32 0 +client_commandline.exe setdeviceproperty 0 5000 string icons +client_commandline.exe setdeviceproperty 0 5001 string {htc}controller_status_off.png +client_commandline.exe setdeviceproperty 0 5002 string {htc}controller_status_searching.gif +client_commandline.exe setdeviceproperty 0 5003 string {htc}controller_status_searching_alert.gif +client_commandline.exe setdeviceproperty 0 5004 string {htc}controller_status_ready.png +client_commandline.exe setdeviceproperty 0 5005 string {htc}controller_status_ready_alert.png +client_commandline.exe setdeviceproperty 0 5006 string {htc}controller_status_error.png +client_commandline.exe setdeviceproperty 0 5007 string {htc}controller_status_standby.png +client_commandline.exe setdeviceproperty 0 5008 string {htc}controller_status_ready_low.png +# Let OpenVR know that there is a new device +client_commandline.exe publishdevice 0 +# Connect the device +client_commandline.exe setdeviceconnection 0 1 +# Set the device position +client_commandline.exe setdeviceposition 0 -1 -1 -1 +``` + +## Map the grip-button to the trigger-button and vice-versa on the controller with id 3 + +``` +client_commandline.exe devicebuttonmapping 3 add 2 33 +client_commandline.exe devicebuttonmapping 3 add 33 2 +client_commandline.exe devicebuttonmapping 3 enable +``` + + +# Known Bugs + +- The shared-memory message queue is prone to deadlock the driver when the client crashes or is exited ungracefully. + +# License + +This software is released under GPL 3.0.