├── Developing ├── stub.md ├── OSVRhdk.md ├── EpsonMoverio.md ├── cmake.md ├── boost.md ├── interfaces.md ├── resources.md ├── Windows-Build-Environment.md ├── creating.md └── Creating-an-OSVR-Project.md ├── Getting-Started ├── Running │ └── stub.md ├── Installing │ ├── stub.md │ ├── windows.md │ ├── linux.md │ ├── osx.md │ └── Linux-Build-Instructions.md ├── Troubleshooting │ └── stub.md ├── HDK │ ├── HDK11.jpg │ ├── HDK13-ID.jpg │ ├── ircamera-updater.png │ ├── camera-context-menu.png │ ├── camera-needs-upgrade.png │ ├── HDK-optics-adjustment.pdf │ ├── HDK-optics-adjustment.png │ ├── HDK-1.2-Firmware-Update.md │ ├── Video-Based-Tracking-Calibration.md │ └── HDK-Unboxing-and-Getting-Started-ES.md └── Configuring │ └── stub.md ├── Integrating-Game-Engines ├── Unity │ └── stub.md ├── Blender │ └── stub.md ├── Monogame │ └── stub.md ├── OpenGL │ └── stub.md ├── SteamVR │ └── stub.md ├── Unreal │ ├── stub.md │ └── multires.md ├── WebVR │ ├── WebVRConfig.PNG │ └── webvr.md └── CryEngine │ └── ForceOSVR.md ├── Utilities ├── Control-1.png ├── Control-2.png ├── Control-3.png ├── Control-4.png ├── Control-5.png ├── AboutScreen.PNG ├── ToolsScreen.PNG ├── DevToolsScreen.PNG ├── ConnectedDevicesScreen.PNG ├── OSVRCentral.md ├── OSVRControl.md ├── UpdateHDKLinux.md └── HDKUpgradeIRBoardFirmware.md ├── Configuring ├── multiServer.PNG ├── images │ ├── hdk_puck.jpg │ ├── overfill.png │ ├── OSVRControl.png │ ├── ideal_lens.png │ ├── undistortion.png │ ├── sensicstray │ │ ├── play.png │ │ ├── devices.png │ │ ├── plugins.png │ │ ├── profile.png │ │ ├── settings.png │ │ └── server-not-found.png │ ├── without_lenses.png │ ├── cylindrical_screen.png │ ├── osvr-config │ │ ├── tools.png │ │ ├── displays.png │ │ ├── plugins.png │ │ ├── samples.png │ │ ├── render-preview.png │ │ ├── missing-variable.png │ │ ├── render-advanced.png │ │ └── render-directmode.png │ ├── determine_canonical.png │ ├── image_based_undistort.png │ ├── Bootloader │ │ ├── Programming.jpg │ │ ├── ICEConnection.jpg │ │ └── InterfaceSetting.jpg │ ├── distorted_screen_coords.png │ ├── undistorted_screen_coords.png │ └── chromatic_radial_distortion.png ├── oculus-rift.md ├── HDKBootloader.md ├── LocalAndRemote.md ├── PredictiveTracking.md ├── OSVR-RenderManager.md ├── SensicsTray.md ├── OSVR-Config.md ├── HTC-Vive.md └── osvrhdk.md ├── Troubleshooting ├── images │ ├── bds_command.png │ ├── hdk_cubes_1.png │ ├── hdk_cubes_2.png │ ├── fixed_tracker.png │ └── skewed_tracker.png ├── Razer-Hydra.md ├── FAQ.md ├── SkewedTracker.md ├── OSVRServer.md ├── DeviceSpecific.md └── RenderManager.md ├── VR-Knowledge-Nuggets ├── README.md ├── tracking.md └── displays.md ├── Introduction ├── Linux.md ├── OSX.md └── Android.md ├── .gitignore ├── Roadmap ├── waffle.md └── additional.md ├── featurelist.md ├── Extending-OSVR ├── Adding-a-New-Device.md ├── Device-Descriptor-Practices.md ├── AddingHMD.md └── ConfiguringHDKViveTracking.md ├── Installing └── RenderManager.md ├── LICENSE └── README.md /Developing/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Getting-Started/Running/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Getting-Started/Installing/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Integrating-Game-Engines/Unity/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Getting-Started/Troubleshooting/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Integrating-Game-Engines/Blender/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Integrating-Game-Engines/Monogame/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Integrating-Game-Engines/OpenGL/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Integrating-Game-Engines/SteamVR/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Integrating-Game-Engines/Unreal/stub.md: -------------------------------------------------------------------------------- 1 | ## Stub to fill -------------------------------------------------------------------------------- /Utilities/Control-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/Control-1.png -------------------------------------------------------------------------------- /Utilities/Control-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/Control-2.png -------------------------------------------------------------------------------- /Utilities/Control-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/Control-3.png -------------------------------------------------------------------------------- /Utilities/Control-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/Control-4.png -------------------------------------------------------------------------------- /Utilities/Control-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/Control-5.png -------------------------------------------------------------------------------- /Utilities/AboutScreen.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/AboutScreen.PNG -------------------------------------------------------------------------------- /Utilities/ToolsScreen.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/ToolsScreen.PNG -------------------------------------------------------------------------------- /Configuring/multiServer.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/multiServer.PNG -------------------------------------------------------------------------------- /Getting-Started/HDK/HDK11.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Getting-Started/HDK/HDK11.jpg -------------------------------------------------------------------------------- /Utilities/DevToolsScreen.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/DevToolsScreen.PNG -------------------------------------------------------------------------------- /Configuring/images/hdk_puck.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/hdk_puck.jpg -------------------------------------------------------------------------------- /Configuring/images/overfill.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/overfill.png -------------------------------------------------------------------------------- /Configuring/images/OSVRControl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/OSVRControl.png -------------------------------------------------------------------------------- /Configuring/images/ideal_lens.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/ideal_lens.png -------------------------------------------------------------------------------- /Getting-Started/HDK/HDK13-ID.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Getting-Started/HDK/HDK13-ID.jpg -------------------------------------------------------------------------------- /Configuring/images/undistortion.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/undistortion.png -------------------------------------------------------------------------------- /Utilities/ConnectedDevicesScreen.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Utilities/ConnectedDevicesScreen.PNG -------------------------------------------------------------------------------- /Configuring/images/sensicstray/play.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/sensicstray/play.png -------------------------------------------------------------------------------- /Configuring/images/without_lenses.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/without_lenses.png -------------------------------------------------------------------------------- /Troubleshooting/images/bds_command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Troubleshooting/images/bds_command.png -------------------------------------------------------------------------------- /Troubleshooting/images/hdk_cubes_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Troubleshooting/images/hdk_cubes_1.png -------------------------------------------------------------------------------- /Troubleshooting/images/hdk_cubes_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Troubleshooting/images/hdk_cubes_2.png -------------------------------------------------------------------------------- /Configuring/images/cylindrical_screen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/cylindrical_screen.png -------------------------------------------------------------------------------- /Configuring/images/osvr-config/tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/tools.png -------------------------------------------------------------------------------- /Getting-Started/HDK/ircamera-updater.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Getting-Started/HDK/ircamera-updater.png -------------------------------------------------------------------------------- /Troubleshooting/images/fixed_tracker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Troubleshooting/images/fixed_tracker.png -------------------------------------------------------------------------------- /Troubleshooting/images/skewed_tracker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Troubleshooting/images/skewed_tracker.png -------------------------------------------------------------------------------- /Configuring/images/determine_canonical.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/determine_canonical.png -------------------------------------------------------------------------------- /Configuring/images/image_based_undistort.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/image_based_undistort.png -------------------------------------------------------------------------------- /Configuring/images/osvr-config/displays.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/displays.png -------------------------------------------------------------------------------- /Configuring/images/osvr-config/plugins.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/plugins.png -------------------------------------------------------------------------------- /Configuring/images/osvr-config/samples.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/samples.png -------------------------------------------------------------------------------- /Configuring/images/sensicstray/devices.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/sensicstray/devices.png -------------------------------------------------------------------------------- /Configuring/images/sensicstray/plugins.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/sensicstray/plugins.png -------------------------------------------------------------------------------- /Configuring/images/sensicstray/profile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/sensicstray/profile.png -------------------------------------------------------------------------------- /Configuring/images/sensicstray/settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/sensicstray/settings.png -------------------------------------------------------------------------------- /Getting-Started/HDK/camera-context-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Getting-Started/HDK/camera-context-menu.png -------------------------------------------------------------------------------- /Getting-Started/HDK/camera-needs-upgrade.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Getting-Started/HDK/camera-needs-upgrade.png -------------------------------------------------------------------------------- /Configuring/images/Bootloader/Programming.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/Bootloader/Programming.jpg -------------------------------------------------------------------------------- /Configuring/images/distorted_screen_coords.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/distorted_screen_coords.png -------------------------------------------------------------------------------- /Getting-Started/HDK/HDK-optics-adjustment.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Getting-Started/HDK/HDK-optics-adjustment.pdf -------------------------------------------------------------------------------- /Getting-Started/HDK/HDK-optics-adjustment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Getting-Started/HDK/HDK-optics-adjustment.png -------------------------------------------------------------------------------- /Integrating-Game-Engines/WebVR/WebVRConfig.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Integrating-Game-Engines/WebVR/WebVRConfig.PNG -------------------------------------------------------------------------------- /Configuring/images/Bootloader/ICEConnection.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/Bootloader/ICEConnection.jpg -------------------------------------------------------------------------------- /Configuring/images/osvr-config/render-preview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/render-preview.png -------------------------------------------------------------------------------- /Configuring/images/undistorted_screen_coords.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/undistorted_screen_coords.png -------------------------------------------------------------------------------- /Configuring/images/Bootloader/InterfaceSetting.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/Bootloader/InterfaceSetting.jpg -------------------------------------------------------------------------------- /Configuring/images/chromatic_radial_distortion.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/chromatic_radial_distortion.png -------------------------------------------------------------------------------- /Configuring/images/osvr-config/missing-variable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/missing-variable.png -------------------------------------------------------------------------------- /Configuring/images/osvr-config/render-advanced.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/render-advanced.png -------------------------------------------------------------------------------- /Configuring/images/sensicstray/server-not-found.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/sensicstray/server-not-found.png -------------------------------------------------------------------------------- /Configuring/images/osvr-config/render-directmode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OSVR/OSVR-Docs/HEAD/Configuring/images/osvr-config/render-directmode.png -------------------------------------------------------------------------------- /VR-Knowledge-Nuggets/README.md: -------------------------------------------------------------------------------- 1 | These are short, bite-sized, usable snippets of information, preferably with a reference to published research, useful in VR development. Categorized by general subject, then internally with headings. 2 | 3 | Each nugget should get its own paragraph (so that means a blank line between them in Markdown) - and be only a paragraph. 4 | -------------------------------------------------------------------------------- /Introduction/Linux.md: -------------------------------------------------------------------------------- 1 | ## Notes on Linux Support 2 | 3 | ### RenderManager status on Linux 4 | 5 | RenderManager compiles and links under Linux using the same CMakeLists.txt 6 | file that is used on other platforms. The OpenGL library is currently 7 | the only supported library. 8 | 9 | As of 2/16/2016, RenderManager does not support DirectMode on Linux 10 | because vendor drivers do not provide this support. 11 | 12 | -------------------------------------------------------------------------------- /Troubleshooting/Razer-Hydra.md: -------------------------------------------------------------------------------- 1 | 2 | - **Having trouble with a Razer Hydra** 3 | - If you're running the Razer Hydra tray-icon, close it, then unplug/replug. (Consider removing it if you don't have other uses for it - OSVR does not require it) If you're using SixenseSDK-based applications, you may need to unplug/replug or reboot to put the Hydra back in a known state, especially if server startup appears to detect two Hydra devices. -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # See http://help.github.com/ignore-files/ for more about ignoring files. 2 | # 3 | # If you find yourself ignoring temporary files generated by your text editor 4 | # or operating system, you probably want to add a global ignore instead: 5 | # git config --global core.excludesfile ~/.gitignore_global 6 | 7 | # Ignore bundler config 8 | /.bundle 9 | 10 | # Ignore the build directory 11 | /build 12 | 13 | # Ignore cache 14 | /.sass-cache 15 | /.cache 16 | 17 | # Ignore .DS_store file 18 | .DS_Store 19 | 20 | /vendor 21 | /tmp -------------------------------------------------------------------------------- /Introduction/OSX.md: -------------------------------------------------------------------------------- 1 | ## Notes on OSX Support 2 | 3 | ### RenderManager status on OSX 4 | 5 | RenderManager compiles and links under OSX using the same CMakeLists.txt 6 | file that is used on other platforms. The OpenGL include file structure 7 | is different, so there are #defines in the code to let this compile on 8 | the mac. 9 | 10 | As of 2/22/2016, only one RenderManager example program runs on the mac 11 | because the mac does not provide a Compatibility profile for OpenGL, but 12 | any application that uses only the Core profile should work on OSX. 13 | 14 | -------------------------------------------------------------------------------- /Getting-Started/HDK/HDK-1.2-Firmware-Update.md: -------------------------------------------------------------------------------- 1 | # Frequently Asked Questions 2 | This is an ad-hoc page to answer most frequently asked questions regarding the use of the OSVR HDK. 3 | 4 | **Note that we've a very important firmware update for HDK v1.2 (thumbscrew-adjusters for lenses). Please see the point directly below.** 5 | 6 | **My tracker seems to be disconnecting, help!** 7 | 8 | > We've released a firmware update for the HDKs that make the tracking significantly more stable, along with other features. Download the zip file [here](https://www.dropbox.com/s/z17ahfev7yzvol0/HDK-Upgrade-Bundle.zip?dl=0) 9 | -------------------------------------------------------------------------------- /VR-Knowledge-Nuggets/tracking.md: -------------------------------------------------------------------------------- 1 | # Predictive tracking 2 | 3 | Ron Azuma showed with user testing that even with true acceleration and angular rotation measurements, prediction starts making things worse after 60ms. (_per Russ Taylor, citation needed_) 4 | 5 | > Russ Taylor, personal conversation: The two things to look out for with the predictor are: (1) overshoot and bounce-back when the user stops moving their head (predicting too far ahead), and (2) Jittery behavior even when sitting still (too much noise in the tracking system for dead-reckoning prediction without a Kalman or other filter). 6 | 7 | # Effect of latency 8 | 9 | Rich Holloway's "For a standard task, you get about 1mm of position offset for every 1ms of tracker latency." (_per Russ Taylor, citation needed_) 10 | -------------------------------------------------------------------------------- /Integrating-Game-Engines/CryEngine/ForceOSVR.md: -------------------------------------------------------------------------------- 1 | ## CryEngine OSVR Documentation 2 | OSVR is a supported VR platform in [CryEngine](https://www.cryengine.com/). Official documentation can be found [here](http://docs.cryengine.com/display/CEPROG/VR+-+OSVR). 3 | 4 | ## Force CryEngine to use OSVR 5 | By default, CryEngine will try to automatically detect and activate one of the supported VR SDK's. In some instances, a CryEngine game may crash if it attempts to use another VR platform and fails before attempting to use OSVR. In order to force OSVR only, and skip other platforms, users can add a configuration file named _user.cfg_ to the root directory of the game's build. 6 | 7 | _user.cfg_ should contain the following lines to force OSVR support: 8 | ``` 9 | sys_vr_support = 1 10 | hmd_driver = 3 11 | ``` -------------------------------------------------------------------------------- /Configuring/oculus-rift.md: -------------------------------------------------------------------------------- 1 | 2 | # Oculus Rift plugin 3 | 4 | The Oculus Rift plugin provides access to Oculus Rift trackers from OSVR applications. It makes use of the [Oculus VR SDK][https://developer.oculus.com/]. This plugin currently supports Oculus VR SDK versions 0.4.4-beta through 1.6.0-public. 5 | 6 | ## Installing the Oculus Rift plugin 7 | 8 | You may either [download the plugin](http://access.osvr.com/binary/oculus) for your version of the Oculus SDK or [build it yourself](https://github.com/osvr/OSVR-Oculus-Rift#readme). 9 | 10 | Copy the resulting plugin file to the `osvr-plugins-0` directory. 11 | 12 | ## Using the Oculus Rift plugin 13 | 14 | First, ensure that the Oculus runtime service is running. 15 | 16 | Start the OSVR server using the provided `osvr_server_config.oculusrift.sample.json` configuration file or add `"display": "displays/Oculus_Rift_DK2.json"` to your current server configuration file. 17 | 18 | 19 | -------------------------------------------------------------------------------- /Getting-Started/Installing/windows.md: -------------------------------------------------------------------------------- 1 | # Installing OSVR for Windows 2 | 3 | Minimum recommended version : Windows Vista SP1 or later 4 | 5 | [Compatible GPU Drivers](/Troubleshooting/RenderManager.md#compatible-gpu-drivers) 6 | 7 | 8 | #### There are 32 and 64 bit installers available for OSVR Runtime and OSVR SDK. 9 | 10 | ## OSVR Runtime 11 | 12 | OSVR Runtime includes the OSVR Core, Render Manager (Direct Mode), OSVR Tracker Viewer and other necessary utilities to get you up and running with OSVR 13 | 14 | [Download OSVR Runtime][runtime-link] 15 | [runtime-link]:http://access.osvr.com/binary/osvr-runtime-installer 16 | 17 | ## OSVR SDK (For development) 18 | 19 | OSVR SDK contains a full snapshot of latest version of OSVR Core, API headers, OSVR libraries, Render Manager including SDK parts and samples, OSVR Tracker Viewer and other necessary utilities. Depending on the bitness of your application (32 or 64 bit), select the corresponding installer version. 20 | 21 | [Download OSVR SDK][sdk-link] 22 | [sdk-link]:http://access.osvr.com/binary/osvr-sdk-installer 23 | -------------------------------------------------------------------------------- /Utilities/OSVRCentral.md: -------------------------------------------------------------------------------- 1 | #OSVR-Central 2 | 3 | OSVR-Central is an application that serves as a main hub for controlling OSVR. 4 | 5 | It includes the following features : 6 | 7 | - Device Detection (hotplugging) : OSVR continues to add support for new devices and hotplugging feature detects when a user plugs in or removes an OSVR compatible device. 8 | - Ability to detect and launch OSVR server : OSVR-Central detects if there is an OSVR server running already and allows to launch it on demand 9 | - OSVR Tools : useful tools that allow to Enable/Disable direct mode, re-center the game/demo and many others 10 | - Developer Tools : provide access to Render Manager utilities and demos as well as OSVR tools useful to developers. 11 | 12 | 13 | Auto updating feature and on-demand plugin downloads are coming soon. OSVR-Central comes bundled with the latest 14 | runtime and SDK installers, which can be downloaded from [OSVR website](http://osvr.github.io/using). 15 | 16 | ##Screenshots 17 | 18 | ![ConnectedDevicesScreen](ConnectedDevicesScreen.PNG "Connected devices") 19 | ![DevToolsScreen](DevToolsScreen.PNG "Developer Tools") 20 | ![ToolsScreen](ToolsScreen.PNG "Tools") 21 | ![AboutScreen](AboutScreen.PNG "About OSVR-Central") -------------------------------------------------------------------------------- /Roadmap/waffle.md: -------------------------------------------------------------------------------- 1 | # OSVR Waffle Board 2 | The [OSVR Waffle Board](https://waffle.io/osvr/osvr-core) contains an overview of issues currently in GitHub issue trackers for all OSVR framework projects. It summarizes the issues in a number of lists: 3 | 4 | - Those under "Contributions Wanted" are likely to be the easiest entry points into contributing, though in some cases they may simply be tasks that require skills that existing contributors do not have. 5 | - Those under "Ready" are not blocked by any other issues and are approved for development for integration. 6 | - Those under "In Progress" should typically show a user who is working on them - if you want to take on a task, move it here and assign yourself. 7 | - The "Done" list should be self-explanatory - it contains closed issues from the past 7 days (automatically removed). 8 | - All issues not otherwise assigned to a list end up in "Backlog". You're welcome to work on these (whether through verification, triage, or development), though please use the issue thread to communicate your plans and progress. 9 | - Of course, the issue lists are not all-encompassing: if you've got a contribution you'd like to make, we'd love to see it! Filing an issue on the right project would be a great first step. -------------------------------------------------------------------------------- /Introduction/Android.md: -------------------------------------------------------------------------------- 1 | ## Notes on Android Support 2 | ### What does it mean to have OSVR support for Android? 3 | OSVR support for Android means that you can run OSVR on Android devices such as: 4 | 5 | - Android phones 6 | - Android tablets 7 | - [Razer Forge](http://www.razerzone.com/gaming-systems/razer-forge-tv) game console 8 | - Other types of hardware that supports Android 9 | 10 | ### Can I use OSVR to run Google Cardboard applications? 11 | 12 | Not as-is. Applications need to be ported to take advantage of the OSVR software capabilities 13 | 14 | ### Can I connect the OSVR HDK to an Android device? 15 | 16 | Yes. Users have successfully run OSVR on a Razer Forge and then connected the Forge via the HDMI output and USB port to the OSVR HDK. The same could be done with other HMDs. 17 | 18 | ### Can I run OSVR on a Samsung Gear VR? 19 | 20 | Yes. For instance, see [this video](https://www.facebook.com/Reviatech/videos/892157687538115/?fallback=1) for a user that used OSVR to get positional tracking support for Gear VR. 21 | 22 | ### RenderManager support on Android 23 | 24 | As of 2016-02-22, the RenderManager code compiles and links for Android in a 25 | branch of the [OSVR-Android-Build project](https://github.com/OSVR/OSVR-Android-Build). 26 | There is not yet a working GLES example program to compile, and the code has 27 | not yet been tested. 28 | 29 | -------------------------------------------------------------------------------- /Configuring/HDKBootloader.md: -------------------------------------------------------------------------------- 1 | #Preparing HDK2 board to enter bootloader mode 2 | 3 | This guide is useful in case the HDK is completely unresponsive, does not appears as a USB device and there is a desire to re-flash its bootloader so that new application software can be loaded 4 | 5 | ## Step 1: Connect programmer to HDK2 board 6 | 7 | Connect progammer such as [Atmel JTAGIce3](http://www.atmel.com/tools/JTAGICE3.aspx) to the programming port on the HDK board. 8 | 9 | ![](images/Bootloader/ICEConnection.jpg) 10 | 11 | ## Step 2: Prepare for bootloader programming 12 | 13 | - Enter device programming dialog (enter through Tools/Device Programming) in Atmel Studio 14 | - Select “Interface settings” 15 | - Select tool and JTAG interface. 16 | - Select “ATxmega256A3BU” as device 17 | - Click “Apply” 18 | - Click “Read” in the “device signature” area. If interface is connected correctly and board is powered on, the device signature will appear 19 | 20 | ![](images/Bootloader/InterfaceSetting.jpg) 21 | 22 | 23 | ## Step 3: Program bootloader 24 | 25 | - Enter ‘Memories’ tab 26 | - Select bootloader file (atxmega256a3bu_104.hex) which you can obtain from the "AVR1916: USB DFU Boot Loader for Atmel XMEGA" application note [here](http://www.atmel.com/devices/atxmega256a3u.aspx?tab=documents) 27 | - Click program 28 | 29 | ![](images/Bootloader/Programming.jpg) 30 | 31 | The HDK will now be ready for regular firmware update using the OSVR Control tool 32 | -------------------------------------------------------------------------------- /VR-Knowledge-Nuggets/displays.md: -------------------------------------------------------------------------------- 1 | # Projection Matrix for HMDs 2 | 3 | Sorry for these not really being nuggets, but more of citations/link lists. 4 | 5 | - Warren Robinett and Jannick P. Rolland. 1992. A computational model for the stereoscopic optics of a head-mounted display. Presence: Teleoper. Virtual Environ. 1, 1 (January 1992), 45-62. See [citation](http://dl.acm.org/citation.cfm?id=128951), the UNC tech report version [TR 91-009](http://www.cs.unc.edu/techreports/91-009.pdf) 6 | 7 | - Follow-up tech report, with more full documentation of the UNC Vlib design, etc: Robinett, W., & Holloway, R. (1994). The Visual Display Transformation for Virtual Reality. Chapel Hill, NC, USA: University of North Carolina at Chapel Hill. Retrieved from http://www.cs.unc.edu/techreports/94-031.pdf 8 | 9 | - Posts by Oliver Kreylos: 10 | - [How to Measure Your IPD](http://doc-ok.org/?p=898) - just follow the "TL;DR" version at the top. 11 | - Importance of correct calibration of HMDs: [post 1](http://doc-ok.org/?p=756), [post 2 - followup](http://doc-ok.org/?p=764) The video in the first post is also quite interesting and useful. 12 | 13 | - Robert Kooima, "Generalized Perspective Projection." - primarily regarding non-head-worn displays, which are somewhat simpler because there's not much in the way of optics between display and eye. 14 | 15 | ## Rendering 16 | - "Fast Stereo Rendering for VR" - covers software techniques to reduce the overhead of rendering in stereo. -------------------------------------------------------------------------------- /Integrating-Game-Engines/WebVR/webvr.md: -------------------------------------------------------------------------------- 1 | #How to use OSVR in Firefox: 2 | 3 | 1. Download the latest Firefox Nightly build available here - 4 | 2. Go to the address bar and type "about:config", which will bring up a list of Firefox settings 5 | 3. Search for `dom.vr.osvr.enabled` and set that field to true which will enable OSVR support. 6 | 4. Fill in the paths for OSVR libraries (DLLs available both in Runtime and SDK installer) for the following settings: 7 | `gfx.vr.osvr.clientKitLibPath` 8 | `gfx.vr.osvr.clientLibPath` 9 | `gfx.vr.osvr.commonLibPath` 10 | `gfx.vr.osvr.utilLibPath` 11 | 12 | These paths are located either in the Runtime/SDK or in the snapshot build. For example, if OSVR Runtime is installed in "C:\Program Files\OSVR\Runtime\", then you would find OSVR DLLs in "bin" subdirectory. 13 | 14 | Make sure that you are using the correct bitness of OSVR DLLs, 32 bit OSVR DLLs if you're using 32-bit Firefox Nightly and 64 bit DLLs if you're using 64-bit Firefox Nightly. 15 | 16 | Open Firefox Nightly, and in the address bar type "about:config" which will bring up a list of all settings. In the search bar type "gfx.vr.osvr" and it will bring up those settings. Enter the full path for each of the corresponding DLL in the "Value" column. 17 | 18 | A screenshot below provides reference on how it is configured on a sample system. 19 | 20 | ![](WebVRConfig.PNG) 21 | 22 | 5. Start OSVR server with a device of your choice plugged in. 23 | 6. Restart Firefox. 24 | 7. Check out for some of the WebVR demos. 25 | 26 | Note: The current implementation supports extended mode. 27 | -------------------------------------------------------------------------------- /Getting-Started/Configuring/stub.md: -------------------------------------------------------------------------------- 1 | # Managing OSVR Server 2 | 3 | ### GUI 4 | OSVR Central is easy to use gui that has many useful tools and features that help manage your vr experience. 5 | 6 | You will find the .exe for osvr_central in the `bin` directory where osvr software is installed too. The default location is C:\Program Files\OSVR\Runtime\bin\ 7 | 8 | 9 | ### CLI 10 | 11 | To launch server open a command prompt window and navigate to the `bin` directory of where your osvr software is installed and run `osvr_server`. Doing this from a fresh osvr install will launch the sample-config file "osvr_server_config.HDKversionDirectMode.sample.json" which has been saved as osvr_server_config.json in C:\Program Files\OSVR\Runtime\bin\ 12 | 13 | You can launch osvr server using different sample-configs or custom configs several ways. One easy way is to use windows explorer to navigate to the bin directory and make a shortcut for osvr server .exe. Save where you need to or just use the suggested desktop location. You could rename it Direct. Make a copy of that shortcut and rename it Extended. Using windows explorer navigate to the sample-configs folder and copy the "osvr_server_congHDKforyourversionExtendedLandscape.sample.json" and paste into the bin folder. Next open properties for the Extended shortcut and refer to the "Shortcut" tab and make the target path read like `"C:\Program Files\OSVR\Runtime\bin\osvr_server.exe" osvr_server_config.HDK13ExtendedLandscape.sample.json` 14 | Doing this would be helpful for many reasons like being able to show what file is actualy being launched as osvr servr config json and it allows easy management of a custom config. Custom configs can be made by using a text editor like notepad to edit the contents of .json files. 15 | 16 | 17 | More ... 18 | -------------------------------------------------------------------------------- /Getting-Started/Installing/linux.md: -------------------------------------------------------------------------------- 1 | # Installing OSVR for Linux 2 | 3 | ## Building OSVR from source 4 | 5 | Note: These are fairly generic build instructions that require you to know how to install libraries and their developer packages on your disribution. Full instructions for building OSVR from scratch on Linuxes resembling Ubuntu 14.04 or Debian 8 [can be found here](Linux-Build-Instructions.md) 6 | 7 | 1. *Prerequisites.* Many of the prerequisites may be available in your Linux distributions repositories. If you prefer to install them manually, the list of prerequisites follows: 8 | * [CMake](https://cmake.org/) 9 | * [Boost](http://www.boost.org/) 10 | * [OpenCV](http://opencv.org/) 11 | * [Python 2](https://www.python.org/) 12 | * [libfunctionality](https://github.com/osvr/libfunctionality) 13 | * [libusb](http://libusb.info) 14 | 15 | 2. *Acquire the source code.* Check out the source code from the [OSVR-Core repository](<%=repo_url 'OSVR-Core' %>). 16 | 17 | 3. *Create a build directory.* To keep the source repository clean of temporary and generated build files, create a separate directory to contain the build. We usually create a directory named `build` inside the OSVR-Core directory. 18 | 19 | ``` 20 | $ mkdir build 21 | $ cd build 22 | ``` 23 | 24 | 4. *Generate a Makefile.* Run CMake to generate a Makefile. Set the `CMAKE_INSTALL_PREFIX` variable to the location where you would like the OSVR files to be installed: 25 | 26 | ``` 27 | $ cmake .. -DCMAKE_INSTALL_PREFIX=~/osvr 28 | ``` 29 | 30 | 5. *Compile OSVR.* Navigate to the build directory you created in step 3 and run `make` to build OSVR. Optionally run `make install` to install the OSVR programs, libraries, and sample configuration files. 31 | 32 | ``` 33 | $ make 34 | $ make install 35 | ``` 36 | -------------------------------------------------------------------------------- /Developing/OSVRhdk.md: -------------------------------------------------------------------------------- 1 | ## OSVR HDK 2 | ### Head tracker format 3 | The head tracker shows as a generic HID device, and input reports are continuously supplied at a high rate (400/sec except on early hardware not capable of that rate) except during device transitions (HDMI state transitions, etc.) that may temporarily suspend tracker reporting. 4 | 5 | Protocol for it is as follows (in byte offsets): 6 | 7 | - 0: 8 | - Bits 0:3 : Report version number, currently 3 9 | - Version 3 only: bit 4: "1" if video is detected and "0" if not. 10 | - Version 3 only: bit 5: "1" if portrait mode (1080x1920 video) is detected and "0" if landscape (1920x1080). 11 | - 1: message sequence number (8 bit) 12 | - 2: Unit quaternion i component LSB 13 | - 3: Unit quaternion i component MSB 14 | - 4: Unit quaternion j component LSB 15 | - 5: Unit quaternion j component MSB 16 | - 6: Unit quaternion k component LSB 17 | - 7: Unit quaternion k component MSB 18 | - 8: Unit quaternion real component LSB 19 | - 9: Unit quaternion real component MSB 20 | 21 | Each quaternion is presented as signed, 16-bit fixed point, 2’s complement number with a Q point of 14 22 | 23 | In version 1 reports: 24 | 25 | - 10-31: reserved for future use 26 | 27 | In version 2 and 3 reports: 28 | - 10-11: Gyroscope X axis velocity in radians/seconds 29 | - 12-13: Gyroscope Y axis velocity in radians/seconds 30 | - 14-15: Gyroscope Z axis velocity in radians/seconds 31 | - 16-31: reserved for future use or not transmitted 32 | 33 | Each velocity is presented as signed, 16-bit fixed point, 2’s complement number with a Q point of 9. These angular velocities should be treated as "exponential coordinates" and are local/body-relative, not global or room/world-relative. 34 | 35 | Version 2 reports: 36 | - Add angular velocity data. 37 | 38 | Version 3 reports: 39 | - Repurposes high-order bits in byte 0 (see above) for video detection/status 40 | -------------------------------------------------------------------------------- /Configuring/LocalAndRemote.md: -------------------------------------------------------------------------------- 1 | # Local and Distributed Client/Server Configuration 2 | 3 | OSVR employs a client/server architecture. Multiple clients and servers can co-exist. The server(s) interface with the sensors and run the analysis plugins. The client(s) provide services to the application. 4 | 5 | The __most common__ configuration is the client and server residing on the same machine. For instance, an _OSVR server_ and then a game both running on the same Windows machine. 6 | 7 | Even in this configuration, you can run **multiple clients with one server**. For instance, the _OSVR Tracker Viewer_ tool helps ensure that all the trackers are working. It is actually an OSVR application that connects to an OSVR server. Developers often run the *Tracker Viewer* alongside the application under development. 8 | 9 | Connecting a **single client to multiple servers** allows accessing shared resources. For instance, imagine a wide-area tracking system that tracks multiple users and then a computer that generates the scene for each player. An *OSVR server* could be installed on the machine that manages the wide-area tracking system. Each *OSVR client* on the player's PC can access local data (such as buttons from a locally-connected game controller) via the local *OSVR server* and then remote data from the remote *OSVR server* 10 | 11 | In the OSVR-Core binary shapshot, there are a couple of sample configurations for this. They're in /bin/sample-configs. One is named osvr_server_config.externalvrpn.sample.json and the other is osvr_server_config.externalvrpn.G4.sample.json. Here is the former which shows how to configure the server: 12 | 13 | ![](multiServer.PNG) 14 | 15 | One can have as many items as one wants, all pointing at various servers. 16 | 17 | Clients and servers do not necessarily need to run on the same operating system. The client/server architecture of OSVR allows you to mix and match operating systems as required 18 | -------------------------------------------------------------------------------- /Configuring/PredictiveTracking.md: -------------------------------------------------------------------------------- 1 | # Predictive Tracking 2 | 3 | ## Overview 4 | In the context of AR and VR systems, predictive tracking refers to the process of predicting the future orientation and/or position of an object or body part. This document will cover configuring prediction parameters in OSVR. More information about why prediction is useful, how it works, and common prediction algorithms, see: http://vrguy.blogspot.com/2016/05/understanding-predictive-tracking.html 5 | 6 | ## Server-side prediction 7 | Server-side prediction is turned on by default for the HDK. To turn off server-side prediction, add the following to the server config: 8 | ```json 9 | "aliases": {"/me/head":"/com_osvr_Multiserver/OSVRHackerDevKit0/semantic/hmd"} 10 | ``` 11 | The path differs for other devices. Use osvr_print_tree.exe to find the unpredicted path for your device. 12 | 13 | ## Client-side prediction 14 | Enabling both client and server-side prediction at the same time will likely result in poor performance. Client-side prediction works best with server-side prediction disabled (see above), but it only works with Direct Mode enabled in RenderManager. The following JSON enabled client-side prediction in RenderManager: 15 | ```json 16 | "prediction": { 17 | "enabled": true, 18 | "staticDelayMS": 22, 19 | "leftEyeDelayMS": 7.5, 20 | "rightEyeDelayMS": 0, 21 | "localTimeOverride": true 22 | }, 23 | ``` 24 | "staticDelayMS" sets how many milliseconds ahead to predict. Adjust this value to balance perceived latency and noise/accuracy. 25 | 26 | For HMDs with one physical display, it is often the case that the image for one eye appears with a delay of half a frame relative to the other eye. This is the case for HDK 1.4 or earlier. If each eye has its own display, as is the case with HDK 2.0, set each eye delay to 0. 27 | 28 | ## Rendering optimzations 29 | For more information on rendering optimizations, see: https://github.com/sensics/OSVR-RenderManager/blob/master/doc/renderingOptimization.md -------------------------------------------------------------------------------- /Troubleshooting/FAQ.md: -------------------------------------------------------------------------------- 1 | # Frequently Asked Questions (FAQ) 2 | 3 | Below you will answers to some common problems that users experience when they use OSVR for the first time. 4 | 5 | Q. When I plug in HDK, the screen is black and doesn't turn on after plug/unplug multiple times. 6 | 7 | A. There are a few things that may be causing the screen to remain black : 8 | 9 | 1. Verify that both USB and HDMI cables are connected to the computer and make sure that HDK cable is connected securely to the beltbox. 10 | 2. Your device may be in direct mode (DM). When DM is enabled, the screen will turn off, but once you launch a game, it will turn back on. You will not be able to see the desktop background. 11 | 12 | Q. How to enable or disable Direct Mode 13 | 14 | A. Direct Mode allows us to directly send input (games, video) to the headset. Extended mode is equivalent to mirroring your monitor on HDK display (act as a second monitor). Download the latest [OSVR Runtime](www.osvr.github.io/using) and launch OSVR-Central where you can enable and disable Direct Mode. 15 | 16 | Q. Every time I launch osvr_server, it exits out immediately. Why is this happening? 17 | 18 | A. There can only be one (highlander) instance of osvr_server running. Check if there is another one already opened (check Task Manager for running apps). 19 | 20 | Q. I see the same image in two eyes. How can I fix this? 21 | 22 | A. Download and install OSVR Control: http://sensics.com/software/OSVRControl-SW/publish.htm. Make sure your HDK is connected to your computer. Run OSVR Control. Click "connect" in the top right, then click "Toggle side-by-side". 23 | 24 | Q. How can I upgrade firmware of my HDK? 25 | 26 | A. Download and install OSVR Control from this [link](http://sensics.com/software/OSVRControl-SW/publish.htm). Then you can refer to this [article](https://github.com/OSVR/OSVR-Docs/blob/master/Utilities/OSVRControl.md) on how to upgrade firmware using OSVR-Control. 27 | 28 | Q. Where can I download OSVR? 29 | 30 | A. You can download OSVR Runtime, SDK and plugins from our website [OSVR Downloads](www.osvr.github.io/using). -------------------------------------------------------------------------------- /Troubleshooting/SkewedTracker.md: -------------------------------------------------------------------------------- 1 | # Skewed Tracker Orientation 2 | If the HDK tracker is skewed in a normal resting position, even after running osvr_reset_yaw.exe, it’s possible that the accelerometer is not well calibrated. 3 | 4 | ![Skewed Tracker](./images/skewed_tracker.png) 5 | 6 | One parameter of accelerometers is called the Zero G Offset (ZGO). This can vary from unit to unit and can change over time. If you have a poorly calibrated accel ZGO, then it could look to the algorithm like it is slightly tilted. The BNO070 has dynamic accelerometer calibration, but you have to induce certain motions for it to fully take effect. 7 | 8 | The accelerometer will be calibrated after the device is moved into 4-6 unique orientations and held in each orientation for ~3-4 seconds. One way to think about this is the “cube” method. Imagine that the headset is a standard cube with 6 faces (Front, Back, Left, Right, Top, Bottom). 9 | 10 | ![HDK Cubes](./images/hdk_cubes_1.png) 11 | 12 | Orient the headset so that it is sitting on each face of the cube sequentially. For example, start with the device positioned normally (bottom face of the cube down). Then orient it so that the right side of the cube is facing down. Then continue through the rest of the faces of the cube. Here’s a quick example: 13 | 14 | ![HDK Cubes](./images/hdk_cubes_2.png) 15 | 16 | Hold the headset in each orientation for about 3-4 seconds. It doesn’t have to be perfectly aligned with the cube – just 4-6 unique orientations (the more variation in orientations between those 4-6 the better, so faces of a cube is a good way to think about it). And it doesn’t matter what order you move them into. 17 | When finished, try running OSVRTrackerView.exe. 18 | 19 | ![Fixed Tracker](./images/fixed_tracker.png) 20 | 21 | If the issue has gone away you can run the following COM port command via OSVR Control to force the calibration to save to flash (this will happen automatically after 5 minutes but it’s not a bad idea to force it to do so). 22 | 23 | "#BDS" 24 | 25 | It should say “DCD Saved” if successful. 26 | 27 | ![BDS Command](./images/bds_command.png) 28 | 29 | -------------------------------------------------------------------------------- /Configuring/OSVR-RenderManager.md: -------------------------------------------------------------------------------- 1 | ## Configuring OSVR-RenderManager 2 | 3 | OSVR-RenderManager config defines options that will be used to render to your HMD. Most of OSVR supported HMDs such as OSVR HDK, Sensics dSight, HTC Vive, Oculus Rift and others, already have pre-configured settings that come with OSVR Runtime installer and are optimized for best performance. If you're adding a new HMD, then you can re-use existing RenderManager and display configs to write a new one. 4 | 5 | There are two parts to adding RenderManager config : 6 | 7 | * `renderManagerConfig` : specifies rendering settings such as enabling/disabling DirectMode, rotation of display, client-side prediction and many others. See RenderManager documentation below for detailed explanations. 8 | * `display` : specifies HMD display settings such as resolution, distortion, field of view, and others. 9 | 10 | General documentation on OSVR-RenderManager that describes available config options is available here - [RenderManager Documentation](https://github.com/sensics/OSVR-RenderManager/blob/master/doc/renderManagerConfig.md) 11 | 12 | #### Dual screen displays / Two video inputs 13 | For dual screen displays HMDs such as [Sensics dSight](http://sensics.com/portfolio-posts/dsight/), which can be configured with 2 video inputs, there are additional instructions on orienting rendering picture. 14 | While some HMDs like dSight accept both portrait and landscape video, other HMDs may only accept portrait mode video, and you will need to specify display rotation in the config to get proper aspect ratio. 15 | In OSVR Server config for your HMDs, you will need to specify the correct resolution for your displays. Under `display` config, make sure to set `resolutions` to landscape (For example if your display is `1440 x 2560` , set the `resolutions` in display config as `2560 x 1440 ` for width and height accordingly), and set display rotation setting in RenderManager config to `90` or `270` degrees. Also specify the number of `video_inputs` and `num_displays`, and set `display_mode: full_screen`. 16 | 17 | It is required because rendering happens in the un-rotated display resolution and then RenderManager rotates it (swapping aspect ratio) when rendering. 18 | -------------------------------------------------------------------------------- /featurelist.md: -------------------------------------------------------------------------------- 1 | # Key OSVR Features 2 | 3 | # open-source 4 | - Free and open-source 5 | - Apache 2.0 license 6 | - Supports closed-source plugins 7 | 8 | # Universal device support 9 | OSVR supports over 100 devices. The OSVR philosophy is to define an **interface**, essentially a pipe of data that provides reports of a certain type. The following interface types are available: 10 | - Display 11 | - Tracker 12 | - Analog 13 | - Button 14 | - Config 15 | - Eye tracker 16 | - Imager 17 | - Gesture 18 | - Locomotion 19 | - Skeleton 20 | - Poser 21 | 22 | Just like a multi-function printer can be viewed by Windows as one physical device that has multiple software interfaces (e.g. printer, fax, scanner), a physical device such as a Razer Hydra can map into one or more OSVR interfaces. 23 | 24 | # Semantic Paths 25 | - Flexible remapping of buttons from different hardware to the same application function. 26 | - Configuration of tracker-sensor position to provide consistent coordinate systems between devices. 27 | - Compile-free conversion from tracker-based to controller-based head tracking. 28 | 29 | # High-performance rendering support 30 | - Time warp 31 | - Direct render 32 | - Front-buffer rendering 33 | - Distortion correction 34 | - Predictive tracking 35 | - Vsync timing reports 36 | 37 | # Plugin architecture 38 | - Plugins loaded at runtime 39 | - Supports both open-source and closed-source plugin 40 | 41 | # Portable 42 | - Cross-platform code that can compile on multiple operating systems: Windows, Linux, Android, OS X and others. 43 | - Cross-library rendering that can display using Direct3D11, OpenGL, Unity, Unreal, WebGL, Blender Game Engine, and others. 44 | - Cross-display configuration that can enable an application to run on different HMDs without change, and also run in debug mode on a mono window. 45 | 46 | # Programming model 47 | OSVR supports both: 48 | - Synchronous (blocking) calls 49 | - Asynchronous (callback) 50 | 51 | # Distributed 52 | - OSVR can run on a single machine, but can also be distributed over a network. This allows many-to-many relationship between OSVR clients (applications) and OSVR servers (sensor processors). Clients and servers may also reside on different operating systems. 53 | -------------------------------------------------------------------------------- /Developing/EpsonMoverio.md: -------------------------------------------------------------------------------- 1 | # Developing with Epson Moverio AR Devices 2 | The Moverio series of AR glasses from Epson are supported by the latest OSVR-Android source. Deploying an OSVR application to this device requires a few steps: 3 | 4 | 1. Build the latest [OSVR-Android-Build](https://github.com/osvr/osvr-android-build) (preferably) or download a binary [here](https://drive.google.com/file/d/0B-Y4Yl2OeYOQd2xpWnZYLWFFbzA/view?usp=sharing). 5 | 1. Add the [osvr_server_config.moverio_highfov.json](https://github.com/OSVR/OSVR-Core/blob/master/apps/sample-configs/osvr_server_config.moverio_highfov.json) file to your Android project's assets folder. Verify that the file is bundled into the assets folder of the final packaged application .apk. 6 | 1. At runtime, check if `/sdcard/osvr/osvr_server_config.json` exists, and if not copy `osvr_server_config.moverio_highfov.json` from your application's bundle to `/sdcard/osvr/osvr_server_config.json` (note the file rename). This must be done before initializing any OSVR client contexts. See sample code [here](https://github.com/OSVR/OSVR-Android-Samples/blob/master/OSVROpenGL/osvrcommon/src/main/java/com/osvr/common/util/OSVRFileExtractor.java) for an easy-to-use utility to do this with one call to `extractFiles()`. 7 | 1. Call `osvrClientAttemptServerAutoStart()` to start the OSVR server before creating any OSVR client contexts. Make sure to call `osvrClientReleaseAutoStartedServer()` before your app shuts down. 8 | 9 | One additional step that is specific to the Moverio is to use the Epson Moverio SDK to put the Moverio display into 3D mode when the application starts. Please see the [Moverio SDK Documentation](https://tech.moverio.epson.com/en/bt-300/pdf/developers_guide.pdf) for details on how to do this. Without this step, the user will need to put the display in 3D mode manually before running your app, or else they will see a side-by-side picture. Here is where to get the SDK for the Moverio BT-300 (some items are shared between multiple Moverio models, however please see the latest documentation for your device): 10 | - [Developer downloads, including SDK](https://tech.moverio.epson.com/en/bt-300/sdk_download.html) 11 | - [Developer Documentation PDF](https://tech.moverio.epson.com/en/bt-300/pdf/developers_guide.pdf) 12 | -------------------------------------------------------------------------------- /Integrating-Game-Engines/Unreal/multires.md: -------------------------------------------------------------------------------- 1 | # Using Multi-Resolution Shading with Unreal 2 | 3 | 4 | 5 | Multi-resolution shading is a technique to increase performance of VR rendering. It provides high resolution at the center of the image and lower resolution at the peripheral areas. By doing so, rendering performance can increase by up to 50% with little or no noticeable quality degradation. 6 | 7 | 8 | 9 | NVIDIA has a fork of the UnrealEngine targeting their VRWorks SDK. Among other features, this fork includes support for multi-resolution shading on NVIDIA hardware. In this implementation, each eye is split up into viewports. The center viewport is rendered at a higher resolution than the outer viewports. 10 | 11 | The OSVR plugin works out of the box on the NVIDIA fork of the Unreal engine. 12 | 13 | - Visit this page to download the fork for the 4.12 version of the engine: https://developer.nvidia.com/nvidia-vrworks-and-ue4 14 | 15 | - You will need access to the Unreal source code, which you obtain through Epic Games in the same way you would for the mainline branch of the engine. Once you've downloaded the fork, you should update the source code for the OSVR plugin, as the version included in the NVIDIA fork is out of date. The latest source for the OSVR-Unreal plugin is located here: https://github.com/osvr/osvr-unreal 16 | 17 | - The source code for the OSVR plugin in the engine is located in several places, and differs from the layout in the OSVR-Unreal project: 18 | 19 | - UnrealEngine/Engine/Binaries/ThirdParty/OSVRClientKit (update with latest DLLs from the OSVR SDK) 20 | 21 | - UnrealEngine/Engine/Source/ThirdParty/OSVRClientKit (update with latest source from /OSVRUnreal/Plugins/OSVR/Source/OSVRClientKit) 22 | 23 | - UnrealEngine/Engine/Plugins/Experimental/OSVR (update with latest source from /OSVRUnreal/Plugins/OSVR, except leave out /OSVRUnreal/Plugins/OSVR/Source/OSVRClientKit) 24 | 25 | 26 | 27 | - Once you've updated the source code for the OSVR plugin, build the Unreal engine as usual. To enable MultiRes rendering in your project, find the MultiRes setting in the Rendering page of of your project settings. You may also want to turn on instanced rendering. You will also need to set the vr.MultiResRendering variable to 1, as it defaults to 0. You can set this variable from a blueprint or from a C++ module in your game. -------------------------------------------------------------------------------- /Roadmap/additional.md: -------------------------------------------------------------------------------- 1 | # OSVR Development Priorities 2 | 3 | Please feel free to suggest additional ideas and priorities. 4 | 5 | ## Interfaces 6 | 7 | OSVR is built on **interfaces**. An interface is a pipe of data. A device exposes one or more interfaces, which fit into predefined interface classes. For instance, a Razer Hydra controller exposes several interfaces: a tracker interface, with two full-pose (position and orientation) sensors/channels, a button interface, an analog interface with channels for the analog triggers and the joystick axes. 8 | 9 | A **device** - a physical entity - implements one or more interfaces classes to present those interfaces. 10 | 11 | Our primary focus is in integrating additional devices, including: 12 | 13 | - Intel Realsense 14 | - Nod Ring 15 | - MM-One and D-Box motion platforms 16 | - Additional HMDs 17 | 18 | 19 | A Github repository (https://github.com/OSVR/OSVR-Specs-and-Proposals) provides work area for interface definition as well as factoring of specific devices into the interfaces. 20 | 21 | ## Analysis Plugins 22 | A plugin is a software module that can be dynamically identified, loaded, and connected to OSVR. Plugins contain modules that implement interface classes. Though there may be more than one module in a plugin, we often refer to the individual device support, etc. in a plugin as simply a plugin. There are two types of these modules: 23 | 24 | - **Device drivers** that implement interfaces for one or more physical devices 25 | - **Analysis modules**, sometimes called **analysis plugins**, that implement interfaces, such as gesture engines, that do not connect directly to devices but instead receive and process data. 26 | For instance, a data smoothing plugin receives data from a device interface and converts it into smoothed data. A face detection plugin receives images from a camera interface and can generate an event when a face has been identified. 27 | 28 | 29 | We would like to see work on several analysis plugins: 30 | 31 | - An augmented reality plugin 32 | - Gesture engines 33 | 34 | ## Game Engines 35 | 36 | We would love to see completed integrations with: 37 | 38 | - CryEngine 39 | - WebVR (currently in process) 40 | - Bohemia VBS3 41 | - Persagis 42 | - WorldViz Vizrd (Python wrapper already available) 43 | 44 | ## Platforms 45 | 46 | OSVR distributions are desired for: 47 | - iOS 48 | - Tizen 49 | - PlayStation 50 | - Windows Mobile 51 | 52 | 53 | 54 | -------------------------------------------------------------------------------- /Troubleshooting/OSVRServer.md: -------------------------------------------------------------------------------- 1 | ## OSVR Server hangs upon startup 2 | - Check your anti-virus software to ensure that OSVR server is allowed 3 | 4 | ## OSVR Server takes up lots of CPU resources 5 | The OSVR server continously polls the various sensors. When a client (e.g. application) is connected, this happens in a main loop with no delay, and thus could take up a CPU core. 6 | 7 | As of commit 1be6530920d278982ab20f0647c415821a1c2f1b (Jan 21, 2016) to OSVR-Core, when a client is disconnected, the server inserts a 1 mSec yield in the main loop and thus substantially reduces the CPU requirements. 8 | 9 | It is possible to configure the server to insert a yield even when a client is connected. This is done through the server JSON file. For instance, the following config fragment... 10 | 11 | ```json 12 | { 13 | "server": { 14 | "sleep": 1 15 | } 16 | } 17 | ``` 18 | 19 | ...would cause a sleep of 1 mSec in the main loop. The reason why this is not the default configuration is that the Windows scheduler "cannot be trusted" to really provide 1 mSec (which is in the definition of the sleep functions used), but more troubling, it can insert unnecessary latency of 10 mSec to as high as 20 mSec. 20 | 21 | However, if the OSVR server takes up too much of your CPU, you can work with this parameter. 22 | 23 | ## Common error messages 24 | *Warning: Have received several video tracker reports without receiving one from the IMU, which shouldn't happen. Please try disconnecting/reconnecting and restarting the server, and if this re-occurs, double-check your configuration files.* 25 | 26 | If you see this message on startup, and you haven't modified your config files (you're using a basic config file for video-based tracking on the HDK), it means that the HDK's internal tracker (IMU), which runs at four times the rate of the video tracker, hasn't sent any reports, but the video-based tracker has seen the HDK for an extended period of time, so the Video-IMU fusion plugin determined the HDK's internal tracker has stopped reporting. **In short, the HDK just needs to be rebooted.** Unplug and replug the power connector, or the wide connector from the belt box, to do the power cycle. It may "just work" without having to restart the server, but if not, just close the server and start it again. 27 | 28 | Make sure that you've got the latest firmware on your HDK (see [OSVR Control instructions](../Utilities/OSVRControl.md) for info) to help avoid this issue. 29 | -------------------------------------------------------------------------------- /Developing/cmake.md: -------------------------------------------------------------------------------- 1 | # CMake 2 | 3 | [cmake](http://www.cmake.org/) is an open-source, cross-platform build system and project generator. It's used by OSVR and its dependencies, and is recommended for both client and plugin use. 4 | 5 | Version 3.0.2 (included in the Boxstarter packages as of this writing) is recommended as a minimum. 6 | 7 | This is a good http://www.cmake.org/cmake/help/v3.1/manual/cmake-buildsystem.7.html|overall, reasonably complete description of CMake usage from the CMake documentation. 8 | 9 | Note that if you're writing an OSVR plugin, there is a wrapper function around ''add_library'' that handles default linking, naming, build directories, and install directories: see the example for details. The first argument, however, is a target name just like ''add_library'' so your build system can be extended beyond the example as far as needed. 10 | 11 | ## Writing Find Modules 12 | 13 | If you're writing a new driver that has to link against external software, you'll need to tell CMake how to find it. (If you're writing a client, you can probably skip this section unless you'd like to learn more about using CMake) 14 | 15 | If you control the external software and/or it's built with CMake, the preferred route is to export targets with a "config"/package file (this is what OSVR-Core does). 16 | 17 | * http://www.cmake.org/cmake/help/v3.1/manual/cmake-packages.7.html - from the CMake documentation 18 | * https://github.com/OSVR/OSVR-Core/blob/master/CMakeLists.txt - This is the OSVR-Core main build file - at the bottom, you'll find the exported target stuff. 19 | 20 | If you don't control the external software, you can write a "Find Module." The style for these has evolved over time, but the latest recommendations are to mimic the behavior of config-file mode closely. 21 | 22 | * [CMake developer documentation on find_modules](http://www.cmake.org/cmake/help/v3.1/manual/cmake-developer.7.html#module-documentation) - this is how you make one. 23 | * https://github.com/Kitware/CMake/blob/master/Source/Modules/FindJsonCpp.cmake - while this module itself is effectively obsolete (jsoncpp can make its own config files), it is an excellent example for a clean, simple, and modern Find module. 24 | 25 | ## Other Resources 26 | 27 | * [How to build software using CMake](http://academic.cleardefinition.com/2012/05/07/how-to-build-software-using-cmake/) - Screencast 28 | * [CMake manual for 3.0 series](http://www.cmake.org/cmake/help/v3.0/) 29 | * [CMake tutorial](http://www.cmake.org/cmake-tutorial/) - excerpted from the Mastering CMake book. -------------------------------------------------------------------------------- /Utilities/OSVRControl.md: -------------------------------------------------------------------------------- 1 | # OSVR Control 2 | 3 | OSVR Control is a simple interactive utility for Windows that allows controlling various aspects of the OSVR HDK, including upgrading the main firmware. 4 | 5 | **Note:** To upgrade the firmware on Linux or other operating systems, [see these instructions](UpdateHDKLinux.md) 6 | 7 | ## Installation 8 | OSVR Control uses Atmel software Flip which needs java. Flip and java bundled download is available at http://www.atmel.com/tools/FLIP.aspx 9 | OSVR Control is available at [this link](http://sensics.com/software/OSVRControl-SW/publish.htm) on the Sensics Website. It is a one-click Windows installer. 10 | 11 | ## Connecting to an OSVR HDK 12 | An OSVR HDK provides a virtual COM port interface to Windows. When launching OSVR control, the available COM ports that have been detected (according to VID/PID combination) as OSVR HDK will be displayed at the top right corner. Click 'connect' to select the desired HDK. 13 | 14 | ![](Control-1.png) 15 | 16 | ## Firmware upgrade 17 | The OSVR Control program includes a wizard for firmware upgrade. The firmware is different for HDK versions 1.x and HDK version 2. **Make sure the hardware version is correctly set in the main window** 18 | 19 | ![](Control-2.png) 20 | 21 | If you want to determine the current firmware version of the HDK, click the 'get version num' button and see the result on the right side 22 | 23 | ![](Control-3.png) 24 | 25 | Once the HDK is connected, select 'firmware upgrade' and follow the step-by-step instructions. The wizard will walk you through the various stages of obtaining the right software to perform the upgrade as well as allow you to select the appropriate firmware version 26 | 27 | ![](Control-4.png) 28 | 29 | ![](Control-5.png) 30 | 31 | ## Persistence setting 32 | Use the OSVR control utility to select one of many persistence settings. Requires firmware version 1.91 and above. 33 | 34 | ## Selecting side-by-side mode 35 | To switch between regular mode (accepts SBS content) and a mode that replicates the video input on both eyes - useful for looking at your desktop - click the 'toggle side-by-side' button. 36 | 37 | **Note:** this option is only available on HDK 1.x models. 38 | 39 | ## Command line utility 40 | The terminal window at the right side of the application allows you to enter and view manual commands for the OSVR HDK. For instance, the command `#?v` returns the version number and compilation data of the OSVR firmware. 41 | 42 | ## Auto updates 43 | The OSVR Control utility automatically checks for updates when launched. Updates include new firmware and control features 44 | -------------------------------------------------------------------------------- /Getting-Started/Installing/osx.md: -------------------------------------------------------------------------------- 1 | # Installing OSVR for OS X 2 | 3 | There are two wasys of installing OSVR-Core in OS X: using Homebrew or compiling it manually. Unless you're planning to contribute code to OSVR-Core itself, installing with Homebrew is the easier method. 4 | 5 | ## Installing using Homebrew 6 | 7 | If you don't already have Homebrew installed, install it first following the instructions at http://brew.sh/. 8 | You may install OSVR for OS X using our Homebrew repository: 9 | 10 | ```bash 11 | $ brew tap OSVR/osvr 12 | $ brew install osvr-core --HEAD 13 | ``` 14 | 15 | Once you've installed OSVR-Core using Homebrew, you don't need to build it from source. 16 | 17 | ## Building OSVR from source 18 | 19 | 1. *Prerequisites.* The prerequisites may be installed using Homebrew. If you prefer to install them manually, the list of prerequisites follows: 20 | * [CMake](https://cmake.org/) 21 | * [Boost](http://www.boost.org/) 22 | * [OpenCV](http://opencv.org/) 23 | * [Python 2](https://www.python.org/) 24 | * [libfunctionality](https://github.com/osvr/libfunctionality) 25 | * [libusb](http://libusb.info) 26 | 27 | 2. *Acquire the source code.* Check out the source code from the [OSVR-Core repository](<%=repo_url 'OSVR-Core' %>). 28 | 29 | 3. *Create a build directory.* To keep the source repository clean of temporary and generated build files, create a separate directory to contain the build. We usually create a directory named `build` inside the OSVR-Core directory. 30 | 31 | ``` 32 | $ mkdir build 33 | $ cd build 34 | ``` 35 | 36 | 4. *Generate a Makefile.* Run CMake to generate a Makefile. Set the `CMAKE_INSTALL_PREFIX` variable to the location where you would like the OSVR files to be installed: 37 | 38 | ``` 39 | $ cmake .. -DCMAKE_INSTALL_PREFIX=~/osvr 40 | ``` 41 | 42 | 5. *Compile OSVR.* Navigate to the build directory you created in step 3 and run `make` to build OSVR. Optionally run `make install` to install the OSVR programs, libraries, and sample configuration files. 43 | 44 | ``` 45 | $ make 46 | $ make install 47 | ``` 48 | 49 | ## Next steps 50 | 51 | 58 | 59 | ## Support 60 | 61 | If you need further assistance with installing OSVR, email us at [`support@osvr.org`](mailto:support@osvr.org). 62 | 63 | 64 | -------------------------------------------------------------------------------- /Developing/boost.md: -------------------------------------------------------------------------------- 1 | # Boost C++ libraries 2 | 3 | 4 | * The DEV Boxstarter package takes care of installing a suitable version of Boost. It uses [these Windows boost binaries](http://sourceforge.net/projects/boost/files/boost-binaries/) which are very nice, official, and also well hidden - the only way I've found to discover that page (besides surfing SourceForge) is by clicking the little "More downloads" link on the Boost homepage 5 | 6 | * [Boost Homepage](http://www.boost.org/) - with documentation online. Note that you can edit the version number in doc URLs to look at past version documentation, in case you're targeting an older version of Boost than the latest. 7 | 8 | * http://theboostcpplibraries.com/ is a freely-available eBook (with a dead-tree version available) on their usage. 9 | 10 | ## Usage: Internal code in OSVR-Core 11 | 12 | Within OSVR-Core, we use C++11 and a relatively recent version of Boost, including some of the compiled libraries (which are statically linked, at least on Windows). We do this because not reinventing the wheel makes us more productive, and the C APIs we export mean that we can be somewhat pickier in what compiler/libraries are required for the core since they're by default not required by the consumers of the library. 13 | 14 | Rather than write outdated, duplicated documentation, you can look at the [CMake build file here](https://github.com/OSVR/OSVR-Core/blob/master/CMakeLists.txt) to find the line starting with ''find_package(Boost'': that will tell you the current requirements. 15 | 16 | We're not opposed to using more of the library, especially if it's the header-only stuff. If it's a compiled library, and compelling, that should also be fine. Bumping the minimum required version is OK if needed and if you can show how it impacts compilation requirements on the various required platforms: we're not bent on sticking in the stone age (see: usage of C++11), but we do want to make it easy to compile on platforms people are using. 17 | 18 | 19 | ## Usage: OSVR-Core API Consumers 20 | Applications using the PluginKit or ClientKit C APIs do not need Boost. 21 | 22 | However, for the recommended and provided C++ header-only wrappers around these APIs, some Boost is required. We only use header-only libraries in PluginKit/ClientKit C++ API wrappers, and fairly old, widespread functionality at that. (Think ''shared_ptr'' for instance.) This is because of, and in line with, our decision not to require C++ API consumers to have C++11 available. The C++ API wrappers are header-only, so all the implementation is easily visible, and the C API backs it all, so if someone really wanted to write C++-style code without using Boost, they could do so, but such an old version, and header-only, seems a reasonable request. 23 | 24 | We haven't bothered to see how old of Boost actually works with the wrappers, but it should handle "pretty old". -------------------------------------------------------------------------------- /Configuring/SensicsTray.md: -------------------------------------------------------------------------------- 1 | # Using the SensicsTray Utility 2 | SensicsTray is a utility installed separately from the OSVR SDK or the OSVR Runtime installers, and requires one of those to be installed to work. Once installed, simply launch SensicsTray.exe from the Start menu to start the utility. SensicsTray is Windows-only at the moment. 3 | 4 | * [Download here](https://github.com/sensics/SensicsTray/releases) 5 | 6 | ### OSVR_SERVER_ROOT Environment Variable 7 | In order for SensicsTray to work, you need to define the `OSVR_SERVER_ROOT` environment variable to point to the `bin` folder of your current OSVR Runtime or OSVR SDK install directory. If you see this page, it means the environment variable is not set, and you'll need to set it before continuing: 8 | 9 | ![Missing Environment Variable](./images/sensicstray/server-not-found.png) 10 | 11 | 12 | This environment variable is set by the the OSVR Runtime or SDK installers, but you can also set it yourself. 13 | 14 | ### Advanced vs Basic Mode 15 | At the top of the screen is a toggle that switches between advanced and basic modes. Various tabs may show more or less settings or options based on which mode you are in. 16 | 17 | ### Play Tab 18 | The Play tab has utilities to start, stop, or restart the OSVR server; enable or disable direct mode on your HMD; run the Tracker Viewer utility to test your setup; or run the Reset-Yaw utility to calibrate your HMD's forward direction. In addition, it contains a list of test or sample applications that run in OSVR supported HMDs to help you test your configuration. 19 | 20 | ![Play Tab](./images/sensicstray/play.png) 21 | 22 | ### Devices Tab 23 | The OSVR runtime comes with a set of sample configurations to get you started. Using a pre-made sample configuration is the easiest way to get started. To use a sample configuration, click the Devices tab: 24 | 25 | ![Devices Tab](./images/sensicstray/devices.png) 26 | 27 | Once here, review the list of sample configurations on the right (some of which have descriptions). You can view a sample by clicking View, or click Use to set that sample configuration as the current server configuration. 28 | 29 | The devices tab also shows you a list of USB devices connected to your system. Some OSVR supported devices will also show up with a name and description. 30 | 31 | ### Plugins Tab 32 | The plugins tab allows you to enable or disable optional plugins from a list of available plugins. These are plugins that are not auto-loaded by the OSVR server on startup, but instead must be explicitly enabled. Simply check or uncheck plugins from the list, and then click Save to save your changes. If the checkbox next to a plugin is disabled, that means the plugin is configured to automatically load, and will always be enabled. 33 | 34 | ![Plugins](./images/sensicstray/plugins.png) 35 | 36 | ### Settings Tab 37 | The settings tab allows you to view or modify the current OSVR render manager settings. Note that some advanced settings are hidden by default. Enable advanced mode by clicking Advanced at the top of the screen to see all settings, or use Basic mode to view only basic settings. When you're done changing settings, click Save at the bottom of the page. 38 | 39 | ![Advanced Settings](./images/sensicstray/settings.png) 40 | 41 | -------------------------------------------------------------------------------- /Extending-OSVR/Adding-a-New-Device.md: -------------------------------------------------------------------------------- 1 | ## "Factoring" 2 | 3 | Factoring refers to identifying aspects of your device and associating them with existing (ideally) or new (if required) interface classes. Think of your device like a number or polynomial: factoring breaks it down into the aspects that are combined (multiplied) to provide full functionality. It's an important task that affects how easy it is for applications (new and old) to use the capabilities of your device. 4 | 5 | Some useful reference material includes https://github.com/vrpn/vrpn/wiki/Writing-a-device-driver#adding-new-capabilities-to-existing-devices 6 | 7 | This is hardest for very novel devices, while it may very well be trivial for the vast majority of cases. It's important to resist the urge to add new interface classes for each device and instead try to find a way to factor them into existing classes if possible: not only is it faster, but it also makes the device more useful in existing and new software. If every device has its own "generic interface", then really there are no generic interfaces. 8 | 9 | ### Factoring, the easy way 10 | 11 | Get in touch with the OSVR community: we can help you figure out how best to factor your device into interface classes in a "Device Integration Proposal". 12 | 13 | ## Writing the device driver itself 14 | All devices, whether or not they will require new interface class(es) or messages added to existing interface classes, will need a driver themselves. For this, we refer you to another document, [Getting Started Writing a Device Plugin](http://wiki.osvr.com/doku.php?id=startingdevice). Note that if you need a new interface class or a new message type, there will obviously not be the API to write against yet for that particular interface/message, but you can still generally make progress in the rest of the plugin and any other interfaces. 15 | 16 | ## Adding a new interface class or message 17 | This step, before code is written, requires a good deal of discussion. We'll assume that has already taken place and you've got a good interface class specification you think will serve the community well. There are a few basic pieces of this: 18 | 19 | - Add methods/types to API headers (ClientKit, PluginKit, and the report and state types in Util) 20 | - There's one PluginKit method per interface class, plus at least one per message type (a few overloads for convenience are usually provided). 21 | - There's two ClientKit methods per message type (a callback registration and a state getter), but these are relatively mechanically generated with the preprocessor, so this is simple. 22 | - You'll need to add a state type and a report type (usually contains a sensor number and the state type) to a Util header. 23 | - Internal implementation in OSVR-Core: For a new interface class, you'll need a new `DeviceComponent` class (see `ImagingComponent` for a good example) to handle serialization and callbacks. To add a message, you'll just need to edit the existing `Component` class (in the case of interfaces that aren't supported natively by VRPN - backward-compatible wrapping of VRPN messages is more complex and beyond the scope of this high-level overview) 24 | - Wire up the PluginKit and ClientKit APIs to the internals you just wrote. 25 | - Add an example application for display the data, and an example plugin showing how to transmit it. -------------------------------------------------------------------------------- /Configuring/OSVR-Config.md: -------------------------------------------------------------------------------- 1 | # Using the OSVR-Config Utility 2 | OSVR-Config is a utility installed along with the OSVR SDK or the OSVR Runtime installers, and requires one of those to be installed to work. Once installed, simply launch OSVR-Config.exe from the SDK directory to start the utility in your browser. OSVR-Config is Windows-only at the moment, but Mac and Linux versions are planned. 3 | 4 | ### Tutorial Video 5 | A YouTube video demonstrating OSVR-Config exists [here](https://www.youtube.com/watch?v=yuTSr8JMPUI). 6 | 7 | ### OSVR_SERVER_ROOT Environment Variable 8 | In order for OSVR-Config to work, you need to define the `OSVR_SERVER_ROOT` environment variable to point to the `bin` folder of your current OSVR Runtime or OSVR SDK install directory. If you see this page, it means the environment variable is not set, and you'll need to set it before continuing: 9 | 10 | ![Missing Environment Variable](./images/osvr-config/missing-variable.png) 11 | 12 | This environment variable is set by the the OSVR Runtime or SDK installers, but you can also set it yourself. 13 | 14 | ### Samples Tab 15 | The OSVR runtime comes with a set of sample configurations to get you started. Using a pre-made sample configuration is the easiest way to get started. To use a sample configuration, click the Samples tab: 16 | 17 | ![Samples Tab](./images/osvr-config/samples.png) 18 | 19 | Once here, review the list of sample configurations (some of which have descriptions). You can view a sample by clicking View, or click Use to set that sample configuration as the current server configuration. 20 | 21 | ### Devices Tab 22 | The devices tab allows you to select a display configuration from a list of included displays. Review the list of displays available along with their descriptions, vendors, and version numbers. View a display config by clicking Show Display, or select one by clicking Use. The currently selected display will be highlighted in green: 23 | 24 | ![Displays](./images/osvr-config/displays.png) 25 | 26 | ### Plugins Tab 27 | The plugins tab allows you to enable or disable optional plugins from a list of available plugins. These are plugins that are not auto-loaded by the OSVR server on startup, but instead must be explicitly enabled. Simply check or uncheck plugins from the list, and then click Save to save your changes. 28 | 29 | ![Plugins](./images/osvr-config/plugins.png) 30 | 31 | ### Render Tab 32 | The rendering tab allows you to enable or disable direct mode, and view or modify the current OSVR render manager settings. 33 | 34 | Use the Direct Mode Enable or Disable buttons to enable or disable direct mode: 35 | 36 | ![Direct Mode](./images/osvr-config/render-directmode.png) 37 | 38 | The rest of the page allows you to view render manager settings. Note that some advanced settings are hidden by default. At the bottom, there is a checkbox to view these advanced settings: 39 | 40 | ![Advanced Settings](./images/osvr-config/render-advanced.png) 41 | 42 | You can preview the render manager config json on the right as you change settings: 43 | 44 | ![Render Preview](./images/osvr-config/render-preview.png) 45 | 46 | When you're done changing settings, click Save at the bottom of the page: 47 | 48 | ![Advanced Settings](./images/osvr-config/render-advanced.png) 49 | 50 | ### Tools Tab 51 | The tools tab contains a couple of OSVR utilities. You can launch the OSVR server from here, or launch the Tracker Viewer utility to help test your configuration: 52 | 53 | ![Tools](./images/osvr-config/tools.png) 54 | -------------------------------------------------------------------------------- /Utilities/UpdateHDKLinux.md: -------------------------------------------------------------------------------- 1 | # Updating the HDK firmware from Linux 2 | 3 | This will describe the process to update the HDK firmware from CLI in Linux. This guide expects a certain familiarity with Linux and comfort with CLI usage. 4 | 5 | **Note: This process has some risk associated with it. If instructions are not entered properly it may result in bricking the device.** 6 | 7 | ## Requirements 8 | 9 | - [dfu-programmer](https://dfu-programmer.github.io/) - version 0.72 or newer: if your distribution does not include a suitable version, you can build the master branch. 10 | - [AUR package](https://aur.archlinux.org/packages/dfu-programmer/) - For Arch Linux users 11 | - [screen](https://www.gnu.org/software/screen/) - Included in many base installs 12 | - sha1sum - Included in many base installs 13 | 14 | ## Checking the current firmware version 15 | 16 | Use `screen` to connect to the HDK device. *It may not be on exactly `/dev/ttyACM0` depending on your system.* 17 | 18 | **Note: Remember to run this with root privileges(sudo or root shell).** 19 | 20 | ```bash 21 | screen /dev/ttyACM0 22 | ``` 23 | 24 | Once connected you should have a blank screen with the terminal cursor flashing in the upper left corner. 25 | 26 | Enter the following exactly and press enter to execute (the '#' symbol is NOT a prompt): 27 | 28 | ``` 29 | #?v 30 | ``` 31 | 32 | It will show you your current firmware version, as well as the onboard tracker version (non-upgradeable). 33 | 34 | To exit the screen session: 35 | 36 | 1. Press `ctrl+a` 37 | 2. Then `shift+k` 38 | 3. It will prompt for y/n to quit, select 'y' 39 | 40 | ## Download and Verify the New Firmware 41 | 42 | See [the firmware page](HDKFirmwareVersions.md) for the latest version and checksum of firmware. Note that different firmwares apply for different versions of the HDK, so choose carefully. 43 | 44 | **Note: Do not use a file if the checksum does not match.** 45 | 46 | Verify the checksum of the file (replace firmware.hex with the name of the file you downloaded) for SHA-1 hash: 47 | ```bash 48 | sha1sum firmware.hex 49 | 3d7f8ac7412fb9f8c11ae082c4c27e550dad8012 firmware.hex 50 | ``` 51 | or for SHA-256 hash 52 | ```bash 53 | sha256sum firmware.hex 54 | 36c7eb20dec518c400b8cd8eda0189c9c1622be05c4fb87ced2359f9667593a0 firmware.hex 55 | ``` 56 | 57 | ## Updating Firmware 58 | 59 | **Note: All commands in this section require root privileges.** 60 | 61 | I recommend you watch `dmesg` or use `journalctl -f` in a separate terminal to see activity of the device attaching and changing state. 62 | 63 | ### Put the HDK MCU into bootloader mode 64 | 65 | Use `screen` to connect to the HDK (substituting the correct device path as needed) 66 | 67 | ```bash 68 | screen /dev/ttyACM0 69 | ``` 70 | 71 | Enter the following exactly and press enter to execute: 72 | 73 | ``` 74 | #?B1948 75 | ``` 76 | 77 | **Note: The screen session should exit, this is expected as the device is rebooting into bootloader mode.** 78 | 79 | ### Uploading the new firmware 80 | 81 | With the HDK MCU in bootloader mode (After the usb activity in the logs stops) the new firmware can be uploaded. 82 | 83 | Use the `dfu-programmer` utility to upload the new firmware (replace 'firmware.hex' with the name of the file that was downloaded earlier): 84 | 85 | ```bash 86 | dfu-programmer atxmega256a3bu flash --force --suppress-bootloader-mem firmware.hex 87 | ``` 88 | 89 | Reboot the HDK MCU to normal operation using the new firmware: 90 | 91 | ```bash 92 | dfu-programmer atxmega256a3bu launch 93 | ``` 94 | **Note: The device should again disconnect and reconnect. The device is ready to use once the logs stop.** 95 | 96 | -------------------------------------------------------------------------------- /Configuring/HTC-Vive.md: -------------------------------------------------------------------------------- 1 | # HTC Vive and Vive PRE 2 | 3 | OSVR supports using your HTC Vive and its controllers to use any OSVR software, whether in direct or extended mode, with distortion correction, with full tracking and input support. 4 | 5 | The [OSVR-Vive](https://github.com/OSVR/OSVR-Vive) plugin and tools provide for access to the Vive hardware through OSVR. 6 | 7 | [Download pre-compiled OSVR-Vive plugin binaries here!](http://access.osvr.com/binary/vive) 8 | 9 | ## Compatibility 10 | While the drivers should be compatible with all Vive family devices, it has only been tested so far on the HTC Vive and Vive PRE (not the earlier Developer Edition). If you have one of these early devices, please consider helping out by testing and reporting back how it works! 11 | 12 | The OSVR-Vive driver interacts with the SteamVR driver for the Vive (`driver_lighthouse`), so the version of SteamVR matters as well. The pace of releases has slowed since earlier this year, but typically the driver is only compatible with the latest stable release of SteamVR as Valve usually makes incompatible changes to the betas shortly after each new stable. The version, listed below, can be seen in a number of places, including the SteamVR "System Report" dialog. 13 | 14 | Known-good stable release, for the current build as of the time of this writing: 15 | - 1467410709 (released as stable on July 5) 16 | 17 | ## Setup 18 | You'll need to first make sure the Vive is working well in SteamVR and that you have a room setup, preferably a standing or room-scale calibration, for your space. Then, download the plugin binaries that match your OSVR server in bits. 19 | 20 | You'll have files as follows in your extracted download: 21 | - A plugin file - on Windows, this is a `.dll` file in something like `bin/osvr-plugins-0`. Put that file in the same directory of your OSVR server as the other plugins. 22 | - In `bin`, a `ViveDisplayExtractor` tool - copy to the `bin` directory of your OSVR server. 23 | - A sample `osvr_server_config` config file that you'll want to start with (as well as some pre-made display descriptor and mesh files, which we'll be replacing shortly.) 24 | 25 | You should be able to run an OSVR application on your Vive HMD in direct mode without having to change any settings in SteamVR. If Vive works in direct mode in SteamVR, but won't open in direct mode in OSVR, make sure SteamVR has exited before starting the OSVR application. On some systems, it may be necessary to disable direct mode in the SteamVR menu before exiting SteamVR. 26 | 27 | One time setup: Your Vive needs a custom display descriptor and mesh distortion data file, which can be extracted using the included `ViveDisplayExtractor` tool. Making sure that `ViveDisplayExtractor` is alongside `osvr_server`, that your Vive is plugged in, and that SteamVR has exited, run `ViveDisplayExtractor`. 28 | 29 | When successful, you'll see something like: 30 | 31 | ``` 32 | [DisplayExtractor] Writing distortion mesh data file: 33 | C:/Users/Ryan/Desktop/OSVR/bin/displays/HTC_Vive_PRE_meshdata.json 34 | 35 | [DisplayExtractor] Writing display descriptor file: 36 | C:/Users/Ryan/Desktop/OSVR/bin/displays/HTC_Vive_PRE.json 37 | 38 | [DisplayExtractor] Press enter to quit... 39 | ``` 40 | 41 | **Note**: The resulting configs contain an absolute path to the mesh data, so if you move where your OSVR Server is located, just run `ViveDisplayExtractor` again. 42 | 43 | That's all there is to it! You can now use the sample `osvr_server_config.vive.sample.json` as your server config file (rename it to `osvr_server_config.json` to make it the default) and you'll be ready to run OSVR-powered applications on your Vive! 44 | 45 | (When you want to run a SteamVR app, no problem: just close the OSVR Server and any OSVR apps running in direct mode.) 46 | -------------------------------------------------------------------------------- /Developing/interfaces.md: -------------------------------------------------------------------------------- 1 | # OSVR interfaces 2 | An interface is a pipe of data. A device exposes one or more interfaces. For instance, a Razer Hydra controller exposes several interfaces: 3 | 4 | - Two XYZ position interfaces (one for the left hand, one for the right) 5 | - Two orientation interfaces (one for the left hand, one for the right) 6 | - Two buttons sets, one for each hand 7 | - A set of analog interfaces for the variable-position triggers and joysticks 8 | 9 | An interface is an instance of an interface class. 10 | An interface class defines properties that can be set or queried as well as a set of events that the class generates. A property might be the last obtained XYZ position from an XYZ position interface. An event could be the press of a particular button in a button set interface. 11 | 12 | Interface class specifications [are here](https://github.com/OSVR/OSVR-Specs-and-Proposals/tree/master/Interface%20Class%20Specifications) 13 | 14 | OSVR supports the following types of interfaces: 15 | 16 | ## Tracker interface 17 | 18 | This interface represents a device with a 3D position and orientation. For example, the HMD typically exposes a tracker interface for head tracking, and hand trackers like the Razor Hydra expose tracker interfaces for each hand. 19 | 20 | Example: /me/head maps to the user's head tracker 21 | 22 | Example: /me/hands/left and /me/hands/right map to the user's hand trackers 23 | 24 | ## Button interface 25 | A general purpose button interface, usable for controllers and other devices with buttons. 26 | 27 | Example: /controller/left/1 maps to the left controller's button 1, if using split controllers like the Razor Hydra. 28 | 29 | ## Analog interface 30 | A general purpose analog value interface. This can be used for any device which provides an analog value. The analog sticks of gamepads are typically exposed as a pair of analog values. 31 | 32 | Example: /controller/left/trigger maps to the left controller's trigger analog value. 33 | 34 | ## Imaging interface 35 | Some VR devices have a built-in camera and can provide a video stream or individual images. For example, the Leap Motion plugin implements the imaging interface and gives applications access to the grayscale IR camera. OSVR also has a plugin that gives you access to the user's webcam. 36 | 37 | Example: /camera maps to the user's web cam. 38 | 39 | ## Eye Tracking interface 40 | This interface allows the developer to see the user's eye position and orientation in 3D space, or as a 2D point on a virtual plane in front of the user (as if looking at a screen). The 2D location interface is shared with other device types that support any kind of 2D location tracking, such a mouse pointer. 41 | 42 | Example: /me/eyes maps to the user's eye tracker. 43 | 44 | ## Locomotion interface 45 | This interface exposes devices such as the Virtuix Omni or a treadmill to provide relative movement on a 2D plane in world space. 46 | 47 | Example: /me/feet/both maps to the user's default ## locomotion interface. 48 | 49 | ## Skeletal tracking interface (draft spec) 50 | This interface supports skeletal trackers that support just the hands (such as the Leap Motion) all the way up to full body skeletal trackers (Kinect and others). 51 | 52 | Example: /me/skeleton maps to the user's full-body skeleton. 53 | 54 | ## Gesture interface 55 | Some devices can provide gesture recognition. This interface supports those types of devices and supports gestures such as swipe left/right/up/down, tap/double-tap, pinch/zoom, open/closed hand and so on. 56 | 57 | ## Poser interface 58 | This is sort of a reverse tracker interface. A chair that moves into a particular position or orientation can be manipulated with the Poser interface. An old-style arcade machine with moveable seat might use this interface to control the seat movement. 59 | -------------------------------------------------------------------------------- /Configuring/osvrhdk.md: -------------------------------------------------------------------------------- 1 | # OSVR HDK 1.x 2 | ## OSVR Server Configs 3 | 4 | The default server configuration on Windows is suitable for an HDK 1.3 or 1.4, optionally using video-based (positional) tracking fused with IMU (orientation-only) sensor data, running in direct mode: it's a copy of the `osvr_server_config.HDK13DirectMode.sample.json` file from the `sample-configs` directory. 5 | 6 | ### Improved distortion correction 7 | If you're using applications that have been built with RenderManager versions 0.6.40 or newer, you may choose to use `osvr_server_config.HDK13DirectModeMesh.sample.json` instead - it is the same except it uses a built-in mesh distortion rather than a polynomial function for distortion correction, which results in a more accurate display. 8 | 9 | ### Non-direct mode 10 | The similarly named sample configs 11 | 12 | - `osvr_server_config.HDK13ExtendedPortrait.sample.json` 13 | - `osvr_server_config.HDK13ExtendedPortraitMesh.sample.json` 14 | - `osvr_server_config.HDK13ExtendedLandscape.sample.json` 15 | 16 | will work if you cannot use Direct Mode - the same caveat as with direct mode above applies if you wish to use the "mesh" config. Note that you may need to modify the `sample-configs/renderManager.extended.portrait.json` or `sample-configs/renderManager.extended.landscape.json` configuration files, respectively, to set `xPosition` and `yPosition` of where the HDK screen starts on your desktop. 17 | 18 | ### HDK 1.2 and earlier 19 | HDK versions 1.2 and earlier can use the config files named identically to those for the 1.3 except with `12` replacing `13`: 20 | 21 | - `osvr_server_config.HDK12DirectMode.sample.json` 22 | - `osvr_server_config.HDK12ExtendedPortrait.sample.json` 23 | - `osvr_server_config.HDK12ExtendedLandscape.sample.json` 24 | 25 | There is no mesh variant for the 1.2 and earlier as the optics module on these versions does not require it. 26 | 27 | ## Video modes 28 | ### Input resolutions 29 | The OSVR HDK supports two input resolutions: 30 | - 1080x1920 @ 60 FPS. This is the native video mode and carries the lowest latency with it 31 | - 1920x1080 @ 60 FPS. When the HDK detects this video mode, it automatically performs 90 degree rotation in hardware, to bring this to the native screen resolution of 1080x1920. This 90 degree rotation carries 1 frame (16 mSec) of latency because an entire frame needs to be stored in the HDK memory before being sent to screen. However, this mode is useful in two main use cases: 32 | - When you want to mirror the desktop 33 | - When you want to use a wireless video link that does not support 1080x1920 resolution 34 | 35 | The HDK reports back using an HID message whether it is detecting video at all, and whether it is receiving 1920x1080 or 1080x1920. See report format in the [HID protocol definition for the OSVR HDK](../Developing/OSVRhdk.md). There is also a ["HDK Video Status Tool"](https://github.com/sensics/OSVR-HDK-Video-Status#readme) utility ([Windows binaries here](https://github.com/sensics/OSVR-HDK-Video-Status/releases)) that can display this data when OSVR Server is running. 36 | 37 | ### Side by side 38 | The OSVR HDK is usually driven by applications that generate different left and right eye imagery in side-by-side mode. However, it is sometimes useful to replicate the entire image over both eyes. For instance: 39 | - When viewing the regular desktop from within the HMD 40 | - When using an application that does not render side-by-side 41 | 42 | The user can control which of these modes is being used using the [OSVR HDK Configuration utility](../Utilities/OSVRControl.md). In the utility, use the "Toggle side-by-side" button 43 | 44 | ### Persistence settings 45 | 46 | You can configure the OLED persistence settings through a terminal port or the [OSVR Control utility](../Utilities/OSVRControl.md) 47 | 48 | ![](images/OSVRControl.png) 49 | -------------------------------------------------------------------------------- /Troubleshooting/DeviceSpecific.md: -------------------------------------------------------------------------------- 1 | # Device-specific information 2 | 3 | ## Razer Hydra 4 | 5 | - The Razer Hydra driver package from Razer is NOT required, and in fact can sometimes conflict. 6 | - If you have difficulties and have installed the Razer driver for the Hydra, try closing the tray application or uninstalling it—it has been known to switch the Hydra from motion controller mode back into game controller mode while in use or otherwise interfere with the OSVR server's Hydra support. 7 | - The OSVR server should automatically detect if the Hydra is connected when it starts, and print some messages if it is. 8 | - To calibrate the Hydra, you need to put both controllers on the base, on the appropriate sides (look at the triggers to see which is left and which is right). This will ensure hemisphere tracking is correct and will re-set the rotation, as shown below (only one controller shown for clarity). Note that this is the non-Unity coordinate system - Unity should be equivalent but with the Z (blue) pointing the opposite direction. 9 | 10 | ## YEI 3-Space Sensor 11 | 12 | - [Driver here](http://opengoggles.org/preview/3-Space_Driver_Install.zip) 13 | - YEI does not have a signed driver, so follow these instructions for install on Windows 8 or 8.1: http://forum.yeitechnology.com/viewtopic.php?f=3&t=24 14 | - Note the COM port assigned to the USB-Serial device created by the driver, you will need to configure this in osvr_server_config.json. 15 | - High COM ports (above around 8 or 10) may require specifying the port as \\.\COM13 for the time being. (GitHub issue reference: https://github.com/sensics/OSVR-Core/issues/7) 16 | - Useful link about hidden com ports, if your numbers are getting very high: [How to Find Hidden COM Ports](https://learn.adafruit.com/how-to-find-hidden-com-ports/overview) 17 | 18 | ## HDK 19 | ### Skewed Tracker Orientation 20 | If the HDK tracker is skewed in a normal resting position, even after running osvr_reset_yaw.exe, it’s possible that the accelerometer is not well calibrated. 21 | 22 | ![Skewed Tracker](./images/skewed_tracker.png) 23 | 24 | One parameter of accelerometers is called the Zero G Offset (ZGO). This can vary from unit to unit and can change over time. If you have a poorly calibrated accel ZGO, then it could look to the algorithm like it is slightly tilted. The BNO070 has dynamic accelerometer calibration, but you have to induce certain motions for it to fully take effect. 25 | 26 | The accelerometer will be calibrated after the device is moved into 4-6 unique orientations and held in each orientation for ~3-4 seconds. One way to think about this is the “cube” method. Imagine that the headset is a standard cube with 6 faces (Front, Back, Left, Right, Top, Bottom). 27 | 28 | ![HDK Cubes](./images/hdk_cubes_1.png) 29 | 30 | Orient the headset so that it is sitting on each face of the cube sequentially. For example, start with the device positioned normally (bottom face of the cube down). Then orient it so that the right side of the cube is facing down. Then continue through the rest of the faces of the cube. Here’s a quick example: 31 | 32 | ![HDK Cubes](./images/hdk_cubes_2.png) 33 | 34 | Hold the headset in each orientation for about 3-4 seconds. It doesn’t have to be perfectly aligned with the cube – just 4-6 unique orientations (the more variation in orientations between those 4-6 the better, so faces of a cube is a good way to think about it). And it doesn’t matter what order you move them into. 35 | When finished, try running OSVRTrackerView.exe. 36 | 37 | ![Fixed Tracker](./images/fixed_tracker.png) 38 | 39 | If the issue has gone away you can run the following COM port command via OSVR Control to force the calibration to save to flash (this will happen automatically after 5 minutes but it’s not a bad idea to force it to do so). 40 | 41 | "#BDS" 42 | 43 | It should say “DCD Saved” if successful. 44 | 45 | ![BDS Command](./images/bds_command.png) 46 | 47 | -------------------------------------------------------------------------------- /Getting-Started/Installing/Linux-Build-Instructions.md: -------------------------------------------------------------------------------- 1 | #Linux Build Instructions 2 | 3 | **Note:** These instructions have been created by building OSVR-Core on a bare bones Ubuntu 14.04. The same steps would work on other Linux distributions as well. 4 | 5 | ### Compiler: Clang or GCC/G++ 6 | Either one of those should work. You will need to build libfunctionality separately from OSVR-Core. 7 | 8 | ### Required tools/libraries: 9 | Unless specified otherwise, you can use the package manager to get the tools mentioned below 10 | 11 | - Git 12 | - CMake (3.0 or newer). Package manager had a version 2.x, so you should get the latest version from or from PPA 13 | - OpenCV - `libopencv-dev` 14 | - Boost libraries (1.44 or newer) You don't need all of them but you'll need at least : `libboost1.xx-dev, libboost-thread1.xx-dev (includes required system, date-time and chrono), libboost-program-options1.xx-dev, libboost-filesystem1.xx-dev`) 15 | - A [bug in Boost 1.58.0](http://lists.boost.org/Archives/boost/2015/05/221933.php) was previously thought to make it incompatible, but nobody's had any issues with it recently, so we might no longer be triggering the (build) error condition anymore. 16 | - libusb1 - `libusb-1.0-0-dev` 17 | 18 | **CMake notes:** If you are new to CMake then read the following guidelines that you should follow to build OSVR-Core and other libraries, otherwise you can skip this section. To build a project with CMake you need to create a build directory inside your project main directory such as OSVR-Core/build. Next from the build directory, run the following CMake command: 19 | 20 | `cmake ..` (This calls CMakelist.txt from directory above and tells it to create config files in current build folder folder) 21 | 22 | It will configure the project for you and let you know if are missing any libraries. Once configured you can run `make` to build the project 23 | 24 | ### Build these libraries first 25 | 26 | Once you have the tools above, you can build the following libraries before you begin building OSVR-Core. 27 | 28 | - libfunctionality library 29 | 30 | `git clone --recursive https://github.com/OSVR/libfunctionality.git` 31 | 32 | - jsoncpp library, if your distribution doesn't include it. If your distribution *does* include it, the package it has is probably fine, OSVR isn't too picky. If you do end up building jsoncpp, you'll want to run CMake with flags below for simplest use. 33 | 34 | `git clone --recursive https://github.com/VRPN/jsoncpp` 35 | 36 | `cmake .. -DJSONCPP_WITH_CMAKE_PACKAGE=ON -DJSONCPP_LIB_BUILD_SHARED=OFF -DCMAKE_CXX_FLAGS=-fPIC` 37 | 38 | Don't forget `make install` after building jsoncpp. 39 | 40 | This should be all the libs/tools that you will need to build OSVR-Core on Linux. CMake messages are very descriptive, if you are missing something, just install it and run `cmake ..` again 41 | 42 | ### Ready to build OSVR-Core 43 | 44 | To get OSVR-Core you'll need to clone it from the main repo (don't forget `--recursive` flag to get all submodules) 45 | 46 | `git clone --recursive https://github.com/OSVR/OSVR-Core.git` 47 | 48 | Finally just `make`, and watch it build (or grab a soda and read through more [OSVR tutorials], like how to build apps with Unity or Unreal) 49 | 50 | ### Known issues *(temporary)* 51 | 52 | If you do not get the `Added device: com_osvr_Multiserver/OSVRHackerDevKit0` when running `osvr-server` and you're using an HDK: 53 | 54 | - Make sure you're building with the latest `master` branch of the source (and that, if you've updated the source recently, that you've done a `git submodule update --recursive` to update the submodules too), since the earlier HIDAPI bug requiring the `non-windows-workaround` branch has been fixed. 55 | - If you are using one of the [HDK headsets], you will also need to run `osvr-server` as root, or you can install the following udev rules (See [issue #330] for more information): https://gist.github.com/rpavlik/98d21e14a7e6eeb52e95 56 | 57 | [OSVR tutorials]:http://osvr.github.io/build-with/ 58 | [issue #338]:https://github.com/OSVR/OSVR-Core/issues/338 59 | [HDK headsets]:http://www.razerzone.com/osvr-hacker-dev-kit 60 | [issue #330]:https://github.com/OSVR/OSVR-Core/issues/330 61 | -------------------------------------------------------------------------------- /Extending-OSVR/Device-Descriptor-Practices.md: -------------------------------------------------------------------------------- 1 | This is an ad-hoc collection of practices for setting up device descriptors, in particular good semantic alias trees for devices. 2 | 3 | **Syntax Note**: The json semantic alias syntax of the form 4 | 5 | ```json 6 | "hat": { 7 | "$target": "analog/4", 8 | "up": "button/12" 9 | } 10 | ``` 11 | 12 | indicates that the partial/relative path `hat` is an alias for `analog/4`, while `hat/up` is an alias for `button/12`. 13 | The `$target` key is intentional use of a reserved character (it cannot be in a valid path) to be able to set alias sources for both `hat` and `hat/up` (in this example). 14 | 15 | ## For controller buttons that are labeled, make the semantic alias the label, in lowercase. 16 | 17 | e.g. 18 | ```json 19 | "a": "button/0", 20 | "b": "button/1", 21 | "x": "button/2", 22 | "y": "button/3", 23 | "start": "button/6", 24 | "back": "button/7" 25 | ``` 26 | 27 | ## Give each joystick its own "directory" with a path entry for each axis. 28 | 29 | Include the button, if applicable - this means you could theoretically have, in a joystick with twist and a push-down button (a combination I've never seen but which undoubtedly exists somewhere) 30 | 31 | ```json 32 | "joystick": { 33 | "x": "analog/0", 34 | "y": "analog/1", 35 | "rotate": "analog/2", 36 | "button": "button/8" 37 | } 38 | ``` 39 | 40 | ## For Point-of-View "hat" inputs, have an entry named "hat" that points to the heading, and nest the buttons, if available, inside. 41 | 42 | Heading values are analog, and conventionally -1 if no input/centered, 0 for north/up, 45 for northeast/up and right, etc. 43 | 44 | ```json 45 | "hat": { 46 | "$target": "analog/4", 47 | "up": "button/12", 48 | "right": "button/13", 49 | "down": "button/14", 50 | "left": "button/15" 51 | } 52 | ``` 53 | ## When inputs are related, group in paths. 54 | 55 | A good example of this is taken from the descriptor of the "Futaba InterLink Elite", a controller that resembles an RC airplane controller. Its joysticks have specific meaning for their axes - throttle, rudder, etc. - and those meanings also have corresponding "trim" buttons typically used to adjust the effective resting point (yes, I know this is an oversimplification). Here's a snippet of the descriptor: 56 | 57 | ```json 58 | "rudder": { 59 | "$target": "analog/0", 60 | "trim": { 61 | "right": "button/12", 62 | "left": "button/13" 63 | } 64 | } 65 | ``` 66 | 67 | ## If your device takes two hands to operate or is otherwise not intended for multiple use, suggest automatic alias to `controller` 68 | 69 | That is, if you're configuring a generic gamepad or joystick, you probably want this general format in your descriptor: 70 | 71 | ```json 72 | "semantic": { 73 | /* your semantic aliases here */ 74 | }, 75 | "automaticAliases": { 76 | "/controller": "semantic/*" 77 | } 78 | ``` 79 | 80 | The `automaticAliases` section shown in that example will recursively mirror the semantic tree of your plugin under the "global" `/controller` path, if the user's path tree does not already have such aliases. 81 | 82 | This should **not** be done if your controller is explicitly single-handed or might be used with one in each hand - in that case, let the user/configurator set up the appropriate global aliases. 83 | 84 | ## Check similar devices' descriptors for reference 85 | 86 | While not all descriptors are guaranteed to be of the highest theoretical purity, they do give an indication of existing practice, especially when multiple descriptors are considered. 87 | 88 | See for a syndicated/aggregated list of device compatibility that includes links to the device descriptors associated with each entry. 89 | 90 | ## Use the Device Descriptor Editor at least as a validation step. 91 | While it's not a perfect editor (it's mainly auto-generated based on the JSON Schema) and you might prefer composing your descriptor in a text or JSON editor of your choosing, do at least run your descriptor through the web-based Device Descriptor editor to clean up formatting, easily update the timestamp, and catch some classes of typos. 92 | 93 | is the live version. 94 | 95 | If you'd like to help make it better, the source is at 96 | -------------------------------------------------------------------------------- /Installing/RenderManager.md: -------------------------------------------------------------------------------- 1 | # Render Manager 2 | ## What is Render Manager ? 3 | Render Manager is a software component that is part of OSVR. It provides key render capabilities in support of VR applications: 4 | - Direct mode. Allows not having the HMD show as an extended-mode display in Windows. 5 | - Time warping. Makes "just in time" adjustments to the rendered image based on latest tracking data. This reduces perceived latency between motion and image changes. 6 | - Distortion correction. Corrects for geometrical distortion and chromatic aberrations so that displayed image appears correct. 7 | 8 | The RenderManager installation includes both the binary code required to achieve this as well as many example programs illustrating the use of RenderManager in both DirectX and OpenGL environments. 9 | 10 | ## Installation 11 | Download and install Render Manager from 12 | [here](http://osvr.github.io/using/) 13 | 14 | **Important**: Using DirectMode requires nVidia driver version 361.43 or higher. 15 | 16 | - If you have multiple GPUs not in SLI mode, you need to select "Activate all displays" instead of "SLI Disabled" in the nVidia Control Panel under "Configure SLI, Surround, PhysX" to make DirectMode work. 17 | - If you get an error when running the RenderManager applications, you may need to install the Visual Studio redistributable runtime package. There is a shortcut to do this installation. This only has to be done once per computer. 18 | 19 | ## Operation 20 | 1. Run one of the servers using the installed shortcuts: 21 | - osvr_server_directmode: Displays on an OSVR HDK 1.3 in DirectMode 22 | - osvr_server_nondirectmode: Displays on an OSVR HDK 1.3 in portrait mode at 1920x0 (right screen) 23 | - osvr_server_window: Displays in a window that can be moved around. 24 | 2. Run one of the example programs: 25 | - RenderManager*: Various graphics libraries and modes of operation. 26 | - AdjustableRenderingDelayD3D: Shows the impact of timewarp with 500ms rendering delay. 27 | - RenderManagerOpenGLHeadSpaceExample: Displays a small cube in head space to debug backwards eyes. 28 | - SpinCubeD3D provides a smoothly-rotating cube to test update consistency. 29 | - SpinCubeOpenGL provides a smoothly-rotating cube with frame ID displayed to test update consistency. Timing info expects 60Hz DirectMode display device that blocks the app for vsync. 30 | 31 | #### Notes 32 | - As of version 0.6.29, DirectMode only works on nVidia cards with a driver that has been modified to white-list the display that you are using. This should be already in the driver version 361.43 for OSVR and Vuzix displays. To enable support for the 1.2 versions of OSVR, there is shortcut that will modify the registry. There is another shortcut to set it back to 1.3. Changing these requires a reboot before they take effect. 33 | - Since version 0.6.2, an osvr_server.exe must be running to open a display (this is where it gets information about the distortion correction and other system parameters). The osvr_server.exe must use a configuration that defines /me/head (implicitly or explicitly) for head tracking to work. There are shortcuts to run the server with various configuration files. You can leave the server running and run multiple different clients one after the other. All clients should work with all servers. 34 | - Since version 0.6.12, the configuration information for both the display and the RenderManager pipeline are read on the server. This file can be edited to change the behavior of the display, including turning direct_mode on and off and turning vertical sync on (set vertical_sync_block_rendering true). 35 | - Since version 0.6.3, Time Warp works on both OpenGL and Direct3D, and in version 0.6.8 a feature was added to ask it to wait until just before vsync (reducing latency by reading new tracker reports right up until vsync). The DirectMode examples have this capability turned on. 36 | - Since version 0.6.3, distortion correction works on both OpenGL and Direct3D. Since version 0.6.8, distortion correction uses an arbitrary polynomial distortion with respect to the distance from the center of projection on the screen. 37 | - Release notes and version history is in the "README.txt" file that is part of the RenderManager installation 38 | 39 | ## Source Code Access 40 | - RenderManager comes with source code of the example programs. 41 | - Source code for the Render Manager itself is not yet open because it includes portions that are licensed under NDA from NVIDIA.This is correct as of Jan 24, 2016. **Sensics is working to separate Render Manager into an open component and an NDA component**. Check back often to see if this has changed 42 | -------------------------------------------------------------------------------- /Developing/resources.md: -------------------------------------------------------------------------------- 1 | # Development Resources 2 | 3 | ## Editors 4 | 5 | General: http://notepad-plus-plus.org/|Notepad++ is the recommended general-purpose editor on Windows. (Don't use regular Notepad, it won't handle the *nix standard line endings.) On Linux or Mac, use your favorite text editor. 6 | 7 | ## JSON 8 | 9 | A recurring theme here will be comments: while they're not technically part of the JSON spec anymore, they're still supported by many tools, including the jsoncpp library used in the OSVR core. (Note, however, that json received by the client app is compacted: extra whitespace removed as well as comments removed, so an app consuming that json doesn't need to use a comment-supporting library) 10 | 11 | * http://jsoneditoronline.org/ (has a Chrome app extension) is handy, though one catch is that changes between the two sides aren't synced automatically, you must do so manually, and it doesn't handle comments. 12 | * Your text editor will also work fine here. 13 | 14 | 15 | * Going a bit "meta": https://github.com/jdorn/json-editor is a slick javascript component, used in https://github.com/OSVR/OSVR-Device-Descriptor-Editor to generate a web-based editor automatically from a JSON Schema. (Of course, some tweaking is required for an optimal experience, but it's a place to start if you're looking at making an editor) 16 | 17 | ## Markdown 18 | 19 | Lots of OSVR stuff is in Markdown - generally an expanded version similar to GitHub-Flavored Markdown, so that the documents look good on GitHub. They may also be rendered by Doxygen or by other tools (such as Discount), but the common subset is pretty comprehensive. Specifically, the items we require in addition to "base" markdown are: 20 | 21 | * Fenced code blocks delimited at top and bottom with ''```'' and labeled with the language. 22 | 23 | ### Help 24 | 25 | * [Markdown basics](https://help.github.com/articles/markdown-basics/) and [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/) describe how to write markdown text. 26 | 27 | ### Editors/tools 28 | 29 | * http://cloose.github.io/CuteMarkEd/ is a desktop Markdown editor for Windows and Linux. While you don't need a specific editor for Markdown, this is handy because it provides a live preview and export options (html and pdf) 30 | * http://sourceforge.net/projects/retext/ is a desktop Markdown editor for Linux that comes packaged with Ubuntu. It provides a nice preview mode. 31 | * http://word-to-markdown.herokuapp.com/ is an online word to markdown converter. 32 | ## Coding 33 | 34 | For all these items, there's a further wiki page if you click on the name. 35 | 36 | * **[CMake](cmake.md)** is a very good build system (generator) - it's used by all the C++ code related to OSVR, and recommended for third-party contributions as well. 37 | 38 | * The **[Boost C++ libraries](boost.md)** are valuable. They're internally used in OSVR-Core (some built libraries statically linked), and also required by the C++ wrappers for PluginKit and ClientKit (header-only libraries used). 39 | 40 | # Boxstarter 41 | 42 | [Boxstarter](http://boxstarter.org|Boxstarter) is a handy tool that builds on https://chocolatey.org/|Chocolatey, which is the closest thing Windows has to a Linux-style package manager. As the name suggests, Boxstarter is designed to get a new system fully installed in an automated way. 43 | 44 | There are OSVR Boxstarter scripts [maintained on GitHub](https://github.com/OSVR/OSVR-Boxstarter) that get automatically built and uploaded by the CI server. We bundle Boxstarter and our scripts into self-extracting compressed installers, which are uploaded to http://access.osvr.com/binary/boxstarter. 45 | 46 | As of this writing, there are three "flavors" of Boxstarter installer available to download, each designed for a different target audience. Many software packages installed are common between multiple installers. 47 | 48 | * **GENERAL**: This flavor is for those not doing C++ development (for instance, Unity developers) or for easy deployment/config of demo machines. Primarily contains "tools". 49 | * **DEV**: This flavor is for those doing C++ development, particularly on the core. It includes the external dependencies required to build the core from scratch. 50 | * **CI**: These are used to prepare Jenkins CI build nodes for the OSVR CI. They might be useful to you in setting up your own CI, though you'll have to change at least the jenkins-updater package. 51 | 52 | (The .7z file seen on access.osvr.com is the contents of the installer, but you almost certainly don't want that on its own without the corresponding command line that comes with the installer to launch the right Boxstarter script. It's uploaded for troubleshooting and testing purposes.) 53 | 54 | All these packages install Chocolatey locally on your machine, as well as add the package source entries for the re-usable packages installed, so you can use Chocolatey to install other packages or keep things up to date. -------------------------------------------------------------------------------- /Developing/Windows-Build-Environment.md: -------------------------------------------------------------------------------- 1 | **Note**: If you're just building a plugin or client application/engine integration/game, you don't actually need to compile this from source - you can (and are encouraged to) use the binary snapshots. See for downloads. 2 | 3 | ## Typical compiler: Visual Studio 2013 4 | You can use Express for Windows Desktop, or, if you meet the license criteria, Community. No matter which method you choose, you'll need to install jsoncpp and libfunctionality on your own: for pre-compiled Visual Studio binaries of these libraries, see (for jsoncpp, you're free to choose either jsoncpp or jsoncpp-0yz - the former is what is currently used in shipping snapshots, but the latter is considered more updated and reliable.) 5 | 6 | Make sure you're using the latest update to Visual Studio 2013. (If you are choosing to use Visual Studio 2015 instead, you'll need at least update 2, and the OpenCV and Boost dependencies below won't work for you - it is quite possible to build with VS2015.2 and 2015.3, but it's not as smooth yet.) 7 | 8 | ### Preferred Method: Chocolatey 9 | You can use [Chocolatey][] (aka "choco") to install the dependencies/packages required. The packages that aren't in the main choco repo are hosted on a MyGet repo [osvr-deps](https://www.myget.org/gallery/osvr-deps). Once you install choco (see their website for instructions), run the following commands at an admin `cmd`/PowerShell prompt to add the the extra repo and install the dependencies. (The second line installs CMake (3.0 or newer required) and OpenCV 2.4.x binaries into the Choco directory structure - not strictly required but needed for imaging examples as well as video-based "positional" tracking - modify as desired) 10 | 11 | [Chocolatey]: https://chocolatey.org/ 12 | 13 | ```cmd 14 | choco source add --name="osvr-deps" -s="https://www.myget.org/F/osvr-deps/" 15 | choco install -s osvr-deps -y cmake 16 | choco install -s osvr-deps -y OpenCV 17 | choco pin add -name OpenCV 18 | ``` 19 | 20 | and, depending on if you want to build 32-bit or 64-bit, add one or both of the following packages: `boost-x86-msvc2013` (32-bit), `boost-x64-msvc2013` (64-bit). i.e. : 21 | ```cmd 22 | choco install -s osvr-deps -y boost-x64-msvc2013 23 | ``` 24 | On your own, you'll want to make sure you have Git, a proper notepad replacement like notepad++ or notepad2mod, etc. 25 | 26 | ## Alternate build environment: MSYS2/MinGW64 27 | While we don't distribute binaries built with GCC from MSYS2/MinGW64, it's often a useful test of code quality: having more compilers build the same code tends to root out problems and questionable code. 28 | 29 | First, download and run the MSYS2 installer: and follow the instructions on that page to update it. 30 | 31 | Then, you'll want to install the packages for the build - the command to install packages in MSYS2 is `pacman -s [yourpackagenames]` . Not all of these are strictly necessary (some are optional deps) but it'll get you started. For a 32-bit-build, replace `x86_64` with `i686`. All you need after this is libfunctionality, which you'll have to build from source (sorry). You'll be able to then open a MinGW 32 or 64-bit shell (accordingly with your choice) and run `cmake` using either the `MSYS Makefiles` generator or the `Ninja` generator, the latter being much faster. 32 | 33 | ``` 34 | mingw-w64-x86_64-SDL2 35 | mingw-w64-x86_64-boost 36 | mingw-w64-x86_64-cmake 37 | mingw-w64-x86_64-gcc 38 | mingw-w64-x86_64-glew 39 | mingw-w64-x86_64-jsoncpp 40 | mingw-w64-x86_64-make 41 | mingw-w64-x86_64-ninja 42 | mingw-w64-x86_64-opencv 43 | ``` 44 | 45 | ## Other dev tools 46 | 47 | ### Clang-Format 48 | You will want to install `clang-format` (and let it put itself on your path): it comes with [Windows binary snapshots of LLVM](http://llvm.org/builds/) (Get the normal installer, not the 64-bit version). Periodically update this, though note that the format might slightly change between releases so don't be surprised if it suggests changes to files you recently formatted when you update. 49 | 50 | If you're using VS Community or one of the paid VS editions, install the clang-format plugin for Visual Studio from the same place. This will let you type the chord `Ctrl-R, Ctrl-F` to format the selected lines right in VS, which is handy. 51 | 52 | You can add a shortcut to `clang-format` individual files using `Send to` command on Windows. Open `run` and type in `shell:sendto` which will open a folder with current `Send to` menu items or go to `C:/Users/USERNAME/AppData/Roaming/Microsoft/Windows/SendTo` . Either copy and paste `format-file.cmd` file from `OSVR-Core/devtools` to `SendTo` folder or create a shortcut to that script and copy to that folder. Then you can right click on individual files and `Send to -> format-file.cmd` to clang-format that file. 53 | 54 | ### Other useful Choco packages 55 | 56 | There are a number of other packages you might consider installing from Chocolatey, the following is just a sampling of ones we've found useful (in many cases, useful enough to add them to the boxstarter installers): 57 | 58 | > `git git-credential-winstore 7zip notepadplusplus notepad2-mod python2 powershell4 poshgit nuget.commandline` 59 | 60 | **Note**: When installing Git, we recommend either using `choco install -y git -params '"/GitOnlyOnPath /NoAutoCrlf"'` or running `git config --global core.autocrlf false` to avoid having Git mangle line endings. See also 61 | -------------------------------------------------------------------------------- /Utilities/HDKUpgradeIRBoardFirmware.md: -------------------------------------------------------------------------------- 1 | # Upgrading the firmware on the HDK IR Board 2 | 3 | The OSVR HDK 1.2, 1.3, 1.4 and HDK 2 all have a similar electronics setup for their positional tracking infrared LEDs. There is a small circuit board inside the HMD (on the left as you look at the HMD from the front - below the external USB port) dedicated to driving these LEDs, with a separate STM8 microcontroller (also known as an MCU) that controls synchronizing the LEDs with the camera, pulse duration, pattern, and more. 4 | 5 | Unfortunately, there is no easy way to upgrade the firmware (and thus any of the parameters) on this microcontroller from the host computer over the HDK's normal USB connection : the STM8 does not even connect to the main MCU of the HDK that provides the USB interface. However, the IR board has through-holes for a standard debug/programming header, and the programming tool used to flash a new firmware on the STM8 is readily available and inexpensive, so if you aren't afraid to solder (which you'll need to do unless you buy an official, large, round-ish ST/Link v2 programming tool direct from ST Micro and have an HDK 1.4 or 2, in which case you have a cable you can use), it's an achievable task. 6 | 7 | ## Hardware Bits 8 | 9 | See the [Technique: How to add a IR board programming connector to OSVR HDK 1.2 1.3 1.4 2](https://www.ifixit.com/Guide/How+to+add+a+IR+board+programming+connector+to+OSVR+HDK+1.2+1.3+1.4+2/65821) iFixit guide for step-by-step instructions on opening your HDK and adding the programming connector. Note that this guide is community-editable, just like the documentation you're reading now, so feel free to pitch in if something can be clarified or improved! 10 | 11 | You will need an STM8 USB programmer compatible with the ST-Link v2: you can get one like that used in the instructions at the [Sensics OSVR Store](https://osvrstore.com/products/programming-tool-for-hdk-positional-tracking-ir-board). 12 | 13 | ## Software Bits 14 | On Windows, you'll need to install the [ST-Link v2 drivers](http://www.st.com/content/st_com/en/products/embedded-software/development-tool-software/stsw-link009.html). 15 | 16 | Once the driver is installed and both ends of the programmer are connected, you can download and run a firmware upgrade bundle, listed below. 17 | The executable is a self-extracting compressed file: when it opens, just double-click `Program-IRFirmware.cmd` and in a few seconds the programming process will be complete. 18 | A successful run will print messages like this: 19 | 20 | ``` 21 | Basic arguments to stm8flash: -c stlinkv2 -p stm8s003k3 22 | Arguments to stm8flash for program: -c stlinkv2 -p stm8s003k3 -w "C:\Users\Ryan\src\IR-Board-Programmer\program-tmp.hex" 23 | Determine FLASH area 24 | Writing Intel hex file 5236 bytes at 0x8000... OK 25 | Bytes written: 5236 26 | Arguments to stm8flash for eeprom: -c stlinkv2 -p stm8s003k3 -w "C:\Users\Ryan\src\IR-Board-Programmer\eeprom-tmp.hex" -s eeprom 27 | Determine EEPROM area 28 | Writing Intel hex file 85 bytes at 0x4000... OK 29 | Bytes written: 85 30 | Press any key to continue . . . 31 | ``` 32 | 33 | If you see any errors, double check your connections: make sure the order of the pins/pads on the board (3.3V, SWIM, GND, RESET) are connected to the corresponding pins on the programmer. 34 | Verify that you have the driver installed and that there are no errors in Device Manager. 35 | You may also want to consider [updating the ST-Link v2 firmware](http://www.st.com/content/st_com/en/products/embedded-software/development-tool-software/stsw-link005.html). 36 | If you saw an error, once you've double checked those items, you can just re-run `Program-IRFirmware.cmd` and see if it goes better. 37 | 38 | Once you're done programming the board, return to the guide hosted on iFixit for re-assembly tips. 39 | 40 | Note that the IR board does not need to be connected to anything but the programmer for the process to work, but it can be left attached to the rest of the HDK, so you can re-assemble the HDK and just open the faceplate and tilt out the connector for future programming if desired. 41 | 42 | ## Firmware Downloads 43 | 44 | See the [IR_LED_DRV Releases page](https://github.com/sensics/IR_LED_DRV/releases) for the latest firmware releases and changelogs. 45 | The `.zip` and the `.exe` that contain `bundle` in their names are most likely what you want (they contain both the firmware and the software required to flash it on to the microcontroller), just choose one: both contain the same files, just one is a self-extracting 7z file (smaller, executable), while the other is a common `.zip` format file (larger). 46 | 47 | The firmware is open-source (Apache 2.0 licensed): if you want to contribute, the project is here: 48 | 49 | ## Firmware Tool Details 50 | 51 | For those of you who would like to perform the reprogramming from a non-Windows operating system: we haven't made that process smooth yet but it should be feasible. To figure it out, download one of the `.zip` bundles: inside, you'll find: 52 | 53 | - the `.hex` file that contains both the program flash and the eeprom for the STM8. 54 | - Windows binaries for the `srecord` tools, which are open source and available on many operating systems. 55 | - Source (slightly modified to reduce verbosity of warning messages) and Windows binaries for the GPL `stm8flash` tool, which should also be available cross-platform. 56 | - The PowerShell script that ties them all together, splitting the single `.hex` into a program hex and an eeprom hex using `scat` from srecord then using `stm8flash` to flash those components individually. Porting this script to `sh` should be eminently doable, it just hasn't been done yet. 57 | -------------------------------------------------------------------------------- /Developing/creating.md: -------------------------------------------------------------------------------- 1 | This document is specifically about creating a project/repo within the umbrella of OSVR, not a project that uses OSVR (though you might want to follow similar guidelines). 2 | 3 | We try to follow the guidance of [Karl Fogel's Producing Open Source Software book][producingoss] in general, using the in-revision updated edition online, since it captures a good deal of valuable knowledge from a range of established projects. Questions can be directed to the [development mailing list][] for clarification or additional guidance. 4 | 5 | [producingoss]:http://producingoss.com/ 6 | [development mailing list]:http://lists.getosvr.org/listinfo.cgi/osvr-devel-getosvr.org 7 | 8 | ## Separate project vs. existing project 9 | We want people to be able to use the projects we publish. In general, if your addition is somehow separable, optional, or (especially) if it adds dependencies, the community tendency is to prefer a separate repository. This allows consuming projects to import their dependencies as Git submodules or similar "vendoring" setups, without bringing in extra baggage. 10 | 11 | ## Contents of a project 12 | Note that this section assumes that the Apache Software License, version 2.0, is being used (which is the default). 13 | 14 | For these files, the [OSVR-Core project](https://github.com/OSVR/OSVR-Core) is generally a good source of examples, though note that it might have somewhat longer/more comprehensive files due to its, well, *core*, role in the ecosystem. 15 | 16 | ### Human Docs 17 | #### `README.md` - required 18 | This shows up on the repo homepage on GitHub, and is often converted to HTML and included in binaries by build processes. There are several important parts to such a file - until we get a chance to document them, see [the starting a project section in Producing Open Source Software][producingoss-starting] and an existing one as an example. 19 | 20 | [producingoss-starting]:http://producingoss.com/en/getting-started.html#starting-from-what-you-have 21 | 22 | Note that unless it makes this file quite long, you can keep documentation directly in this file as well. 23 | 24 | Subdirectories can also have `README.md` files, which show up on GitHub when that directory is viewed, but this is less important than the main one. 25 | 26 | #### `CONTRIBUTING.md` - highly recommended 27 | Having such a file is useful because it provides instructions on how to get involved and basic expectations. Additionally, using that particular name enables [GitHub integration with issues and pull requests](https://github.com/blog/1184-contributing-guidelines). Use an existing one as a template, though be sure to review it thoroughly - worse than a missing contributing document is a misleading one. 28 | 29 | ### License-related 30 | #### `LICENSE` - required 31 | This should be a verbatim copy of the full ASL2.0 - grab from OSVR-Core. 32 | 33 | #### `NOTICE` - required (?) 34 | Start with an example, updating it for the specific project. Also, in output, such a NOTICE file should contain all incorporated projects' NOTICE files and other required notices. Trying to find a nice tool to do this automatically, possibly from Android (since "open source components" screens there look consistent like they were auto-generated). 35 | 36 | ### Tool-related 37 | #### `.gitignore` 38 | If you're on Windows, you might have to create this as `.gitignore.` to get Explorer to let you name a file that. It should ignore all system-specific and generated files: you should be able to do a full "build" (whatever that means in the context of your project) and have `git status` show that it's clean. Helpful resources are existing projects that use the same technology, as well as these site: 39 | 40 | - 41 | - 42 | 43 | #### `.clang-format` or comparable 44 | For C++-based projects, make sure to include a clang-format configuration file. You can use the one from OSVR-Core for consistency. Then, **make sure you run clang-format before each commit!** It keeps the diffs clean and readable. 45 | 46 | For projects in other languages, please make sure you have a code formatter chosen, config file in version control, and documented in `CONTRIBUTING.md`. 47 | 48 | #### `.editorconfig` 49 | This serves as a bit of a subset of the formatting config, but is also more universal (more general directives, multiple file format support, wide cross-editor support). See for details. 50 | 51 | ## Source code files 52 | ### Boilerplate generator 53 | For C headers and C++ source and header files, we have a boilerplate generator that takes care of producing include guards, stock license headers and file description headers, etc. It's somewhat crude at the moment and probably ripe for replacement, but it does work pretty well, especially if you integrate it with your send-to menu on Windows or script it on posix. 54 | 55 | ### Each source file: stock ASL2.0 copyright and license header 56 | The general format of this is as follows, note that you'll want to prefix each line (or wrap the block) in language-specific comment characters: a text editor capable of search/replace with regex is handy here (`sed 's:^:// :'` for the command-line users with C++-style comments...). Also, **do not include the brackets in the final text, they should be replaced along with their placeholder contents** 57 | 58 | ``` 59 | Copyright [yyyy] [name of copyright owner/initial author] and OSVR community 60 | 61 | Licensed under the Apache License, Version 2.0 (the "License"); 62 | you may not use this file except in compliance with the License. 63 | You may obtain a copy of the License at 64 | 65 | http://www.apache.org/licenses/LICENSE-2.0 66 | 67 | Unless required by applicable law or agreed to in writing, software 68 | distributed under the License is distributed on an "AS IS" BASIS, 69 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 70 | See the License for the specific language governing permissions and 71 | limitations under the License. 72 | ``` -------------------------------------------------------------------------------- /Developing/Creating-an-OSVR-Project.md: -------------------------------------------------------------------------------- 1 | This document is specifically about creating a project/repo within the umbrella of OSVR, not a project that uses OSVR (though you might want to follow similar guidelines). 2 | 3 | We try to follow the guidance of [Karl Fogel's Producing Open Source Software book][producingoss] in general, using the in-revision updated edition online, since it captures a good deal of valuable knowledge from a range of established projects. Questions can be directed to the [development mailing list][] for clarification or additional guidance. 4 | 5 | [producingoss]:http://producingoss.com/ 6 | [development mailing list]:http://lists.getosvr.org/listinfo.cgi/osvr-devel-getosvr.org 7 | 8 | ## Separate project vs. existing project 9 | We want people to be able to use the projects we publish. In general, if your addition is somehow separable, optional, or (especially) if it adds dependencies, the community tendency is to prefer a separate repository. This allows consuming projects to import their dependencies as Git submodules or similar "vendoring" setups, without bringing in extra baggage. 10 | 11 | ## Contents of a project 12 | Note that this section assumes that the Apache Software License, version 2.0, is being used (which is the default). 13 | 14 | For these files, the [OSVR-Core project](https://github.com/OSVR/OSVR-Core) is generally a good source of examples, though note that it might have somewhat longer/more comprehensive files due to its, well, *core*, role in the ecosystem. 15 | 16 | ### Human Docs 17 | #### `README.md` - required 18 | This shows up on the repo homepage on GitHub, and is often converted to HTML and included in binaries by build processes. There are several important parts to such a file - until we get a chance to document them, see [the starting a project section in Producing Open Source Software][producingoss-starting] and an existing one as an example. 19 | 20 | [producingoss-starting]:http://producingoss.com/en/getting-started.html#starting-from-what-you-have 21 | 22 | Note that unless it makes this file quite long, you can keep documentation directly in this file as well. 23 | 24 | Subdirectories can also have `README.md` files, which show up on GitHub when that directory is viewed, but this is less important than the main one. 25 | 26 | #### `CONTRIBUTING.md` - highly recommended 27 | Having such a file is useful because it provides instructions on how to get involved and basic expectations. Additionally, using that particular name enables [GitHub integration with issues and pull requests](https://github.com/blog/1184-contributing-guidelines). Use an existing one as a template, though be sure to review it thoroughly - worse than a missing contributing document is a misleading one. 28 | 29 | ### License-related 30 | #### `LICENSE` - required 31 | This should be a verbatim copy of the full ASL2.0 - grab from OSVR-Core. 32 | 33 | #### `NOTICE` - required (?) 34 | Start with an example, updating it for the specific project. Also, in output, such a NOTICE file should contain all incorporated projects' NOTICE files and other required notices. Trying to find a nice tool to do this automatically, possibly from Android (since "open source components" screens there look consistent like they were auto-generated). 35 | 36 | ### Tool-related 37 | #### `.gitignore` 38 | If you're on Windows, you might have to create this as `.gitignore.` to get Explorer to let you name a file that. It should ignore all system-specific and generated files: you should be able to do a full "build" (whatever that means in the context of your project) and have `git status` show that it's clean. Helpful resources are existing projects that use the same technology, as well as these site: 39 | 40 | - 41 | - 42 | 43 | #### `.clang-format` or comparable 44 | For C++-based projects, make sure to include a clang-format configuration file. You can use the one from OSVR-Core for consistency. Then, **make sure you run clang-format before each commit!** It keeps the diffs clean and readable. 45 | 46 | For projects in other languages, please make sure you have a code formatter chosen, config file in version control, and documented in `CONTRIBUTING.md`. 47 | 48 | #### `.editorconfig` 49 | This serves as a bit of a subset of the formatting config, but is also more universal (more general directives, multiple file format support, wide cross-editor support). See for details. 50 | 51 | ## Source code files 52 | ### Boilerplate generator 53 | For C headers and C++ source and header files, we have a boilerplate generator that takes care of producing include guards, stock license headers and file description headers, etc. It's somewhat crude at the moment and probably ripe for replacement, but it does work pretty well, especially if you integrate it with your send-to menu on Windows or script it on posix. 54 | 55 | ### Each source file: stock ASL2.0 copyright and license header 56 | The general format of this is as follows, note that you'll want to prefix each line (or wrap the block) in language-specific comment characters: a text editor capable of search/replace with regex is handy here (`sed 's:^:// :'` for the command-line users with C++-style comments...). Also, **do not include the brackets in the final text, they should be replaced along with their placeholder contents** 57 | 58 | ``` 59 | Copyright [yyyy] [name of copyright owner/initial author] and OSVR community 60 | 61 | Licensed under the Apache License, Version 2.0 (the "License"); 62 | you may not use this file except in compliance with the License. 63 | You may obtain a copy of the License at 64 | 65 | http://www.apache.org/licenses/LICENSE-2.0 66 | 67 | Unless required by applicable law or agreed to in writing, software 68 | distributed under the License is distributed on an "AS IS" BASIS, 69 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 70 | See the License for the specific language governing permissions and 71 | limitations under the License. 72 | ``` -------------------------------------------------------------------------------- /Troubleshooting/RenderManager.md: -------------------------------------------------------------------------------- 1 | ## Compatible GPU Drivers 2 | - NVIDIA: 3 | - **Warning**: 367-series and newer drivers have an **added limitation from NVIDIA**: they disable "multi-GPU" (when one or more is not an NVIDIA GPU) capability for direct mode on a number of HMDs, including the HDK. 4 | - This affects you if, for instance, 5 | - You use a laptop with hybrid graphics, even with an NVIDIA GPU with a direct external graphics connector as well as integrated Intel graphics that previously supported NVIDIA direct mode 6 | - You use a desktop Intel chip with the GPU enabled/in use in addition to a discrete NVIDIA card 7 | - To work around this, you'll either need to: 8 | - Disable the other GPU (if possible - e.g., on desktop) 9 | - Stay with a pre-367 driver. 10 | - For additional information on this, see, for example, the [Release notes for desktop drivers version 368.22](http://us.download.nvidia.com/Windows/368.22/368.22-win10-win8-win7-winvista-desktop-release-notes-updated.pdf) 11 | - **365.xx** should work on all systems that 362 worked on - requires that applications be built with a post-March 2016 Render Manager, but provides some additional functionality over 362. 365.10 and 365.19 (GeForce) tested. 12 | - Recommended to **skip 364.xx** releases - the earliest such release ever known to work (and capable of working - earlier versions were known to have bugs making them incompatible with direct mode) was 364.72, and it only worked on some systems. 13 | - **362.xx** works well as a fallback even with applications using very old (pre-March 2016) Render Manager versions. (362.00 for standard GeForce drivers - pre-364 for other hardware with different driver releases.) 14 | - AMD : 16.2 or earlier as of 18 March 2016. 15 | 16 | ## RenderManagerAMDD3D11::OpenDisplay(): Could not create Liquid VR device 17 | If you have previously installed an AMD card and then removed it, deleting the drivers, it sometimes leaves DLLs on the system. RenderManager uses the presence of the DLL named amdlvr64.dll, which on some systems is located in C:\Windows\System32, to determine whether AMD's Liquid VR is available on the system. If that DLL is present, it attempts to use it to open DirectMode, resulting in the error message above. Some users have reported successful resolution of this issue by removing that DLL from their system when they do not have an AMD card installed. 18 | 19 | ## General troubles with NVIDIA devices: clean install. 20 | A first line troubleshooting option is a clean-install of the NVIDIA drivers. Install the recommended NVIDIA drivers again, but choose "Custom" install, then check the box for a "Clean" install. This will remove any customized settings or profiles you may have created in the NVIDIA control panel (so if you did make any, you may want to record them or back them up), but it can also remove corrupted internal settings in the NVIDIA driver itself. When you re-install the drivers, try doing so without the HDK connected. 21 | 22 | Once you've done a clean reinstall, it will likely automatically put the HDK into direct mode when you plug it in, which means that Windows will likely not see it as a monitor and you'll only see black on the screen - use a tool to disable direct mode to check extended mode functionality. 23 | 24 | It is harmless, and in general, when possible recommended to do clean installs of NVIDIA drivers when you upgrade them as well. 25 | 26 | ## Extended desktop is visible, unable to enter direct mode 27 | - (I know this sounds boilerplate, but it works reliably on older versions of the OSVR HDK.) Unplug the USB, HDMI, and wall-power connectors from the HDK. Plug in the wall power. Plug in the USB connector. Wait 10 seconds for the devices to be recognized. Plug in the HDMI connector. 28 | - Verify that your HMD is supported by RenderManager. At present (May 2016), the OSVR HDK, Vuzix iWear 720, HTC Vive/Vive Pre, and Oculus Rift DK2 are supported. 29 | - Verify that you have a supported graphics card. At present (May 2016): 30 | - NVIDIA graphics cards with Gameworks VR/VRWorks are supported. (Generally - those that can run the latest driver series.) HMD should be connected into a video port that directly goes into the NVIDIA device. If your video port goes into an Intel chip (e.g some Intel Optimus configurations), direct mode will not work on that port. You can run the OSVR "DirectModeDebugging" tool to find out if your hardware configuration supports VRWorks - it will list near the beginning of its operation whether there are any connectors on your NVIDIA GPU. 31 | - AMD LiquidVR DirectToDisplay capable GPUs are supported - generally, AMD "GCN" GPU cores. 32 | - Run 'EnableOSVRDirectMode' from the shortcuts created by the Render Manager. 33 | - If you are using an older OSVR HDK, try whitelisting your HMD using the whitelist shortcuts in the Render Manager installation. This requires computer restart to take effect. 34 | 35 | ## Troubleshooting RenderManager in Unity 36 | If you see a “failed to load RenderManager” message print to the Unity debug console or output log, try running the RenderManager example programs from a command line to see the output. 37 | 38 | If you get an error that says something like “Could not open display (are you whitelisted?)”, try running the **CombinedWhitelist.reg** file, then restart the computer. 39 | 40 | If you see this error, then the server isn’t configured for RenderManager. 41 | 42 | ![No RenderManager Config](https://github.com/OSVR/OSVR-Unity/blob/gettingStartedDocs/images/osvr_server_norendermanager.png?raw=true) 43 | 44 | If the example programs work in direct mode, but Unity still fails to load RenderManager, make sure all DLLs are up to date. It is best to close Unity, replace the DLLs in Windows Explorer, and re-open Unity so that the new libraries are loaded. For more information, visit https://github.com/OSVR/OSVR-Unity/blob/master/GettingStarted.md#enabling-rendermanager-in-unity. 45 | 46 | ## Error Messages and Warnings 47 | In the case of all error and warning messages, the earlier they appear, the more important they likely are. If you're seeking help through a support channel, make sure to include as full of a log as you can, to ensure you don't accidentally exclude the message that contains the important information. 48 | 49 | ### Messages about `WSAStartup`, `vrpn_Endpoint`, or `vrpn_Connection` 50 | These are **not meaningful on their own** - if you see one (and usually, if you see one, you'll see several in a row right at the end of a log) it's a side-effect of an earlier error message causing an unclean shutdown. Scroll up in the log/console to see what actually went wrong. 51 | 52 | ### `OSVR RenderManager Warning: Got error from NVIDIA API: EnableDirectMode returned -187 (hex: ffffff45) [NVAPI_INVALID_DISPLAY_ID]` 53 | This message means that the NVIDIA driver doesn't recognize the display device you're trying to use in Direct Mode as being a VR display. If you're using a standard OSVR-supported device (currently including the OSVR HDK 1.3 and Vuzix iWear), try upgrading your NVIDIA drivers to make sure they have the latest list included. As of February 2016, **version 361.75** is verified to work correctly with both of those devices with no additional "whitelists" or other work. You may need to choose Custom Install, and Clean Install to clear out all driver settings and custom profiles if you have trouble. 54 | 55 | If you have an older HDK or other HMD that you think should be supported by Direct Mode but you're still seeing this message on the latest drivers, [contact support for a whitelist file](http://support.osvr.org) for your device. 56 | 57 | ### `RenderManagerNVidiaD3D11::OpenDisplay: Cannot create high-priority rendering when D3D context and device are passed in (ignoring)` 58 | 59 | If this message appears on its own and the app works fine otherwise, it can be ignored. It just indicates to a developer that the D3D device and context were passed in rather than created within RenderManager. However, if this shows up in your application, you might consider trying to eliminate the pattern that causes it, for a number of reasons, including but not limited to multi-GPU support: see the information below called out by the bolded text "passing in your own D3D device and context" for details. 60 | 61 | ### `OSVR RenderManager Warning: Got error from NVIDIA API: NVAPI call returned -103 (hex: ffffff99) [NVAPI_INVALID_COMBINATION]` 62 | This message is usually caused by having a multi-GPU system (typically with different vendors). 63 | 64 | - If you see this in someone else's app, they might be using an old version of RenderManager that didn't have multiple/heterogeneous GPU support (released January 2016), or they might be doing the code pattern below that makes their app less compatible. 65 | - If you see this when testing your own code, it's probably because you're **passing in your own D3D device and context** to the call to create RenderManager: if it's not entirely necessary to do so, leave creation of these interfaces to RenderManager, since for direct mode to work in such a system, the device and context must be created on the adapter being used for direct mode, which is often not the default adapter. If you do it yourself, instead of leaving it to RenderManager, you'll have a less compatible application. 66 | -------------------------------------------------------------------------------- /Getting-Started/HDK/Video-Based-Tracking-Calibration.md: -------------------------------------------------------------------------------- 1 | # Video-Based Tracking Calibration 2 | 3 | There are two types of calibration involved: 4 | 5 | - Calibration of the as-manufactured infrared beacon (IR LED) locations within the tracked device (HDK, etc.) - what we'll call *beacon calibration*. 6 | - Calibration of the video-based tracking coordinate system (specifically, the camera's coordinate system) with the IMU/orientation tracker's coordinate system to allow for fusion of these measurements. We'll call this *room calibration*. 7 | 8 | **Note that with the new ("Unified") video tracker plugin, calibration requirements have changed - specifically, they've simplified, and explicit _beacon pre-calibration_ is no longer recommended.** See below for details. 9 | 10 | ## Beacon calibration 11 | 12 | Tracked devices come with manufacturing specifications as to where the IR LEDs, referred to as "beacons", are located in a device-fixed coordinate system. This is important, however, there is always some degree of variation in manufacturing, and failing to account for the fact that the beacon locations aren't the same as spec can result in noisy, laggy, or unusable tracking. 13 | 14 | To the best of our knowledge, **the OSVR video-based tracking system is unique** among consumer-accessible tracking systems in that it uses an "single-constraint-at-a-time"-style algorithm that provides continuous auto-calibration of beacon locations. This means that you don't have to explicitly do any beacon calibration, beacon positions will be updated as required during runtime based on camera measurements/observations. 15 | 16 | However, when using the "old" video tracking plugin (videobasedtracker, not unifiedvideotracker), the best tracking data to get very precise autocalibration comes from when the beacons are close to the camera, and the headset is unlikely to be used at those distances, some initial conscious calibration can be helpful. This is really just explicitly exercising the autocalibration routines. 17 | 18 | ### Pre-calibration - old (non-"Unified") video tracker only 19 | 20 | **Do not follow these steps/use the `VideoTrackerCalibrationUtility` if you're using the new video tracker plugin** ("Unified Video-based/Inertial Tracker" aka "UnifiedVideoTracker" aka "uvbi") **as it will actually decrease tracking quality. If you want to see what the tracking camera and algorithm see,** add/modify the `"debugView"` line in your config file so that it reads `"debugView": true`. 21 | 22 | If you want to calibrate the IR LEDs prior, there is a separate utility that contains the same autocalibrating tracking algorithm as the plugin, but with a different interface and slightly different operation designed to help you get good measurements fed into the autocalibration system and good calibrated beacon locations saved out. 23 | 24 | You run it by starting the application, `VideoTrackerCalibrationUtility` passing the configuration file you use with `osvr_server` as a command line argument. (If you don't explicitly pass one to the server, you don't need to pass one to the calibration utility - they share that logic). 25 | 26 | For instance, a sample command line might look like this, if your osvr_server config was `config-testing.json`: 27 | 28 | ```cmd 29 | VideoTrackerCalibrationUtility.exe config-testing.json 30 | ``` 31 | 32 | This will show an image of the IR camera. 33 | 34 | There are two steps: Getting a lock within range, and performing calibration. If you were holding the device up to the camera, you probably skipped right through the first step, otherwise, bring the device to the center of view of the camera and fairly close to it until you see the LEDs and the instructions change. 35 | 36 | Follow the instructions until all LEDs enabled on your headset are green. *Note that not all HDK models and IR firmware versions have all the possible LEDs enabled, this is normal. Also note that this utility intentionally does **not** calibrate the rear beacons, since those have to be run-time calibrated only because their position varies with how you wear the headset.* Then hit S to save the calibration file. 37 | 38 | Once the config is saved, you don't need to run the calibration utility again unless you want to. The server will automatically load the calibration data every time: you'll see a message in the console to that effect. 39 | 40 | The effect of performing this calibration in practical terms is to increase range somewhat, reduce jitter, and improve reliability of tracking. You can repeat the calibration at any time: the calibration app always starts from scratch. Also, you're not forgoing the benefits of autocalibration by using the calibration utility: autocalibration is still part of the tracking algorithm, you just seed it with more accurate starting data when you have a saved calibration. 41 | 42 | See this screencast of a sample calibration to see how it looks when done by a pro (on an HDK 1.x with old IR firmware, so all possible LEDs on): 43 | 44 | [![YouTube video link for calibration screencast](https://img.youtube.com/vi/MObPn_U4IYg/0.jpg)](http://www.youtube.com/watch?v=MObPn_U4IYg) 45 | 46 | ### Notes 47 | You don't need to recalibrate the beacons if you move the camera, it's only if you switch tracked devices (HDKs), or perhaps switch cameras (in case the distortion is subtly different and somehow getting incorporated into the calibration). 48 | 49 | It's best to try to nearly fill the field of view, move slowly and also to aim not just for green, but also for consistent small black circles, and lots of beacons active at once as you calibrate (status message at the top of the window). The black circles show the size of the "residual" (error/difference between prediction and measurement) in the last frame for each beacon that's currently being measured. 50 | 51 | ## Room Calibration 52 | 53 | This aligns the internal orientation sensor of the HDK and the video-based tracking. In the new tracking system, combining IMU and video data is integrated in to the single plugin (this is why it's called "unified"), while in the old tracking plugins, this step is part of the "Video-IMU Fusion" plugin. In order to do this, both trackers' outputs must be transformed into some "room coordinate system" - some real-world-based, fixed orientation and position. 54 | 55 | For the current configuration with a single camera and a suggested location on the screen, the default is to assume that the room coordinates should be oriented so that the camera is toward the front: that is, facing the camera is facing forward. (This is a configuration option - the alternative is to let the IMU decide what forward is, then potentially use the reset yaw utility later to change the forward direction) The IMU knows ground truth for all other aspects of orientation. Defaults for position vary between the two tracking systems: 56 | 57 | - The new (unified) tracker defaults to placing the camera in the room at (0, 1.2, -0.5) (that's 1.2 meters up, and 0.5 meters back). This was chosen to place the room origin approximately on the real room floor, beneath you, if you are seated in front of the camera at roughly eye level. The camera position is configurable, however, so you may set up your room coordinates differntly if you desire. 58 | - The old tracker plugin used the position of the HMD during room calibration as the origin (0, 0, 0) with vertical position/offset configurable under the name `eyeHeight`. 59 | 60 | So, the system needs to know where the camera is relative to some starting location, and more importantly how it is oriented relative to the orientation of the IMU in the headset. Because the mounting system on the camera is flexible, this could change, so **room calibration is performed automatically every time the server starts up**. As a result, if you move the camera, just restart the server. 61 | 62 | ### Performing the calibration 63 | 64 | It's designed to be easy and essentially automatic, though there are some hints printed to the console. The HMD just needs to be reporting orientation and also be visible and tracked by the video-based tracker at the same time. Just hold the HMD still for a few moments in clear view of the camera and it will complete automatically, and positional data will start being reported by the server. 65 | 66 | The total amount of time that the algorithm needs to observe the HMD being still is 10 camera frames, which total 1/10th of a second, so this is a very fast calibration process. It's even faster with the new plugin, which does not require the HMD be entirely still (in part because it doesn't set coordinate systems up based on the HMD's location during calibration.) 67 | 68 | ### Console Messages - Old Tracker 69 | If the HMD is rather far from the camera, a hint (`NOTE: For best results, during tracker/server startup, hold your head/HMD still closer than`...) will be displayed to bring it closer, which both helps the room calibration (by reducing distance, and thus noise, it gives more stable tracking), and also serves as an aid to the automatic beacon calibration. If you bring it within a certain distance, you may see another message saying that the distance is good. 70 | 71 | When calibration has detected that the HMD has stopped moving, it will start displaying `Video-IMU fusion: Hold still, measuring camera pose`, adding dots as it collects data. It may restart this message several times as motion or noise is detected; this is harmless. 72 | 73 | When room calibration has completed, you'll see a message like `Video-IMU fusion: Camera pose acquired, entering normal run mode!`. 74 | -------------------------------------------------------------------------------- /Extending-OSVR/AddingHMD.md: -------------------------------------------------------------------------------- 1 | # Adding a New HMD to OSVR 2 | 3 | ## Introduction 4 | OSVR creates an abstration layer for many types of devices, including HMDs. This means that the same application can run on different HMDs simply by changing the configuration file that the OSVR server processes when it launches. Adding your HMD to OSVR instantly allows your customers to enjoy the OSVR applications. This note explains the key steps in adding an HMD to OSVR. These are: 5 | 6 | - Create a display descriptor. This specifies the key attributes of the HMD such as the field of view 7 | - Provide information about distortion. OSVR can apply distortion correction for the HMD. This step is optional. 8 | - Support direct rendering. When used with a supported graphics card, OSVR provides direct rendering support to HMDs and this section discusses how to add this capability to your HMD through OSVR 9 | - Integrate tracking information. Often, HMDs also include peripherals such as an orientation tracker. OSVR passes this information along to applications so they can update the view of the virtual world. 10 | - Verify your HMD is working with OSVR. Ensure that the display is free of distortion and that the tracking is working well. 11 | - Publish your HMD plugin. Release your OSVR plugin to the world so developers and gamers can use your HMD with their OSVR software and games. 12 | 13 | ## Display integration 14 | To start with OSVR, all you need to get a display going initially is just a "display descriptor" JSON file. You can start with a very simple one—the one for the [OSVR HDK 1.1](https://github.com/OSVR/OSVR-Core/blob/master/apps/displays/OSVR_HDK_1_1.json) is about as simple as they get—and modify it to suit your display. 15 | 16 | - [Display descriptor documentation](https://github.com/OSVR/OSVR-JSON-Schemas/blob/master/doc/display_descriptor_schema_v1/Structure%20of%20JSON%20descriptor%20file%20for%20HMDs.md) 17 | - [Display descriptor JSON schema](https://github.com/OSVR/OSVR-JSON-Schemas/blob/master/display_descriptor_schema_v1.json) 18 | - [Existing display descriptors for additional reference](https://github.com/OSVR/OSVR-Core/tree/master/apps/displays) 19 | 20 | The only fields you must modify are: 21 | 22 | - The metadata fields - primarily for human consumption, though Render Manager also uses `vendor`: 23 | - `hmd.device.vendor` 24 | - `hmd.device.model` 25 | - `hmd.device.Version` 26 | - `hmd.device.Note` 27 | - The basic optics: 28 | - `hmd.field_of_view.monocular_horizontal` 29 | - `hmd.field_of_view.monocular_vertical` 30 | - `hmd.field_of_view.overlap` if the screens are not aligned (gross generalization) 31 | - The basic display control/input data: 32 | - In the resolution entry, the `width` and `height`, and, if yours isn't a single input horizontal side-by-side, `display_mode` and potentially `video_inputs`. 33 | 34 | To use a display descriptor with an OSVR server config file, you add or edit the `"display": "???.json"` line. See, for example, [a server config that specifies the display descriptor for the Sensics dSight HMD](https://github.com/OSVR/OSVR-Core/blob/master/apps/sample-configs/osvr_server_config.dSight.json). (If no display line is specified, then a default is used.) A useful minimal sample to test your display descriptor (does not test distortion) would be the OpenGLSample in the OSVR-Core distribution (requires SDL), which places you in a cube. 35 | 36 | ## Correcting lens and display distortion 37 | In many cases, displays have some degree of distortion that should be compensated for ahead of time through predistortion. OSVR has a number of parameterizations of distortion, suited to different types of distortion, and different tools for measuring them. All of these modes can be specified in the server configuration files and read using the OSVR-Core libraries and several of them are implemented in the OSVR-RenderManager interface. 38 | 39 | A theoretical description of distortion correction and its relationship to projection and viewing can be found in the [distortion document](../Configuring/distortion.md) and a program to construct the distortion parameters based on a mapping from angles to screen coordinates can be found in the [AnglesToConfig documentation](https://github.com/OSVR/distortionizer/blob/master/angles_to_config/doc/anglesToConfig.md). 40 | 41 | The Core modes (implemented on a non-RenderManager path of OSVR-Unity) as of 1/25/2016 include: 42 | 43 | - K1-parameter-based distortion - Based on quadratic distortion from a center for red, green, and blue. 44 | 45 | The RenderManager modes as of 1/25/2016 include: 46 | 47 | - Chromatic General-polynomial-based distortion - Based on radial distortion around a defined center of projection for reg, green, and blue. See the description in Rendermanager.h for details on how this is specified. 48 | - Monochromatic point samples - Based on an arbitrary mapping from angles to screen-space locations, often from a lens simulation performed on the optics. See the [distortion document](../Configuring/distortion.md) for a description. 49 | - Chromatic point samples - Based on an arbitrary mapping from angles to screen-space locations for red, green, and blue, often from a lens simulation performed on the optics. See the [distortion document](../Configuring/distortion.md) for a description. 50 | 51 | The process of constructing a configuration file that uses point-sampled distortion correction is described near the end of the [AnglesToConfig documentation](https://github.com/OSVR/distortionizer/blob/master/angles_to_config/doc/anglesToConfig.md). The basic approach is to construct an appropriate server-side configuration file (with a matching client-side file if needed) and then run the standard OSVR server with that configuration file. Any RenderManager-based client will then perform the specified distortion correction during rendering. 52 | 53 | A snippet from a configuration file that specifies general-polynomial-based distortion follows: 54 | 55 | { 56 | "display": { 57 | "hmd": { 58 | "distortion": { 59 | "type": "rgb_symmetric_polynomials", 60 | "distance_scale_x": 1, 61 | "distance_scale_y": 1, 62 | "polynomial_coeffs_red": [ 0, 1, 0.25 ], 63 | "polynomial_coeffs_green": [ 0, 1, 0.32 ], 64 | "polynomial_coeffs_blue": [ 0, 1, 0.40 ] 65 | } 66 | } 67 | } 68 | } 69 | 70 | ## Supporting Direct Rendering 71 | The next step is direct-to-HMD rendering: bypassing operating system and window management overhead, removing the display from being a part of the extended desktop, and drawing directly to it using the graphics driver. OSVR's [RenderManager](https://github.com/sensics/OSVR-RenderManager) handles both non-direct advanced rendering (timewarp, advanced predistortion, etc.) available with just a regular display descriptor as above, as well as direct mode support. 72 | 73 | Using direct rendering on a new HMD requires three things: 74 | 75 | 1. Construct a RenderManager configuration file with a screen resolution and rotatation that matches one of the modes supported by the HMD. 76 | 77 | 2. Add your EDID vendor ID to [RenderManager](https://github.com/sensics/OSVR-RenderManager/blob/master/osvr/RenderKit/DirectModeVendors.h#L227) and create a pull request to have it included in RenderManager. 78 | 79 | 3. Contact the graphics card manufacturers to have your EDID vendor ID added to their direct mode whitelists. The display must be recognized as a direct-mode display by the vendor's driver. This is handled differently by each vendor, and you should contact them directly to be added to their whitelists. You'll need to contact nVidia to get them to add your device to their driver whitelist. Be aware that they have stopped direct-mode support for non-HDCP-compliant HMDs on laptops and on systems with multiple GPUs (and they are warning that we should support it on any display going forward). AMD has a different approach to getting devices registered, so you should contact them as well. Intel cards require the HMDs to add a specific registry entry to indicate that they should be used in DirectMode. 80 | 81 | ## Tracking and Status Reporting 82 | Your HMD presumably has tracking either integrated or attached. If it's an off-the-shelf tracker, then there's probably already support in OSVR for it via VRPN: see more on the [Compatibility page](http://osvr.github.io/compatibility/). A tracker for an HMD should provide the /me/head alias at the center point between the two eyes centers. 83 | 84 | If you have a custom tracking system, and/or if your device has an interface for control and status messages, you might be interested in writing a device plugin to provide more interaction with the OSVR system than just as a display device. Get in touch, and/or see the [Building a Plugin](http://osvr.github.io/build-with/#building-a-plugin) documentation. 85 | 86 | 87 | 88 | ## Verifying your HMD is working with OSVR 89 | 90 | You can verify that the tracker is working by using [OSVR Tracker Viewer](https://github.com/osvr/OSVR-Tracker-Viewer). It will display a set of axes showing the position and orientation of your HMD as you move it about. 91 | 92 | You can check that the display descriptor and distortion correction is working well by running one of the demo applications that ship with [OSVR-RenderManager](https://github.com/sensics/OSVR-RenderManager#example-programs). 93 | 94 | Finally, we also suggest using the [SteamVR-OSVR driver](https://github.com/osvr/SteamVR-OSVR) to test your HMD with SteamVR games. 95 | 96 | ## Publishing your HMD plugin 97 | 98 | To make your HMD plugin available to the widest audience of OSVR users, we recommend the following: 99 | 100 | * Create simple installer to deploy the plugin. 101 | * Add the installer to the OSVR plugin repository. 102 | * If applicable, open-source your plugin code so that the community can assist in porting it to other platforms and improve it. 103 | 104 | -------------------------------------------------------------------------------- /Extending-OSVR/ConfiguringHDKViveTracking.md: -------------------------------------------------------------------------------- 1 | # Configuring OSVR HDK2 and other OSVR-supported HMD with VIVE Puck Tracking 2 | 3 | This document outlines how to add room-scale positional tracking to HDK2 (and any other OSVR-compatible HMD) by mounting an HTC VIVE tracking puck and using the Lighthouse base stations and tracking system. 4 | 5 | Hardware Requirements: 6 | - OSVR HDK2 with mount. Sensics has provided 3D files for a Puck mount [here](https://github.com/OSVR/OSVR-Hardware-Accessories/tree/master/HDK-VIVE-Puck-Adapter). 7 | - VIVE Tracking Puck 8 | - Lighthouse base stations 9 | - USB - microUSB cable or SteamVR Wireless dongle. A wireless dongle comes with the Puck, or you can [flash firmware to a Steam Controller wireless USB receiver](https://steamcommunity.com/app/507090/discussions/0/312265473878773762/). 10 | 11 | 12 | Software Requirements: 13 | - [OSVR-Core build or SDK/Runtime installation](http://access.osvr.com/) 14 | - [OSVR-VIVE plugin build](https://github.com/OSVR/OSVR-VIVE) 15 | - Optionally SteamVR and [SteamVR-OSVR](https://github.com/OSVR/SteamVR-OSVR) 16 | 17 | ### Why? 18 | There are a few reasons this document could be useful: 19 | - To serve as a working example of how to configure a new head/positional tracker using OSVR semantic paths. 20 | - To demonstrate how easily displays and tracking systems can be swapped quickly 21 | - To demonstrate that the VIVE tracking puck (with a wireless receiver) can be used for HDK head-tracking in SteamVR 22 | 23 | ### OSVR-VIVE 24 | [OSVR-VIVE](https://github.com/OSVR/OSVR-VIVE/) is the OSVR plugin for the family of VIVE devices -- HMD, Controllers, and tracking puck. Wireless tracking of puck/controllers requires the VIVE HMD or a wireless receiver. Follow the instructions in the [Readme](https://github.com/OSVR/OSVR-Vive/blob/master/README.md) to install the plugin. Basically, download the latest binaries and copy `com_osvr_VIVE.dll` to "/osvr-core-build/bin/osvr-plugins-0/". 25 | 26 | ### Semantic Paths 27 | OSVR Developers should understand the concept of **semantic paths** within the OSVR software stack. For a good introduction, review this presentation on the [OSVR-Core Path Tree](https://osvr.github.io/presentations/20150419-osvr-software-framework-path-tree/). 28 | With the server running, you can run `osvr_print_tree.exe` (located next to osvr_server.exe) to print the current path tree. 29 | Every OSVR plugin has a **device descriptor** which factors devices into OSVR interfaces and defines semantic (human-readable) paths to access specific devices. In this experiment, we’ll need the VIVE Puck’s semantic path in order to use it as our head tracker. 30 | ### OSVR-VIVE device descriptor (([com_osvr_VIVE.json](https://github.com/OSVR/OSVR-VIVE/blob/master/com_osvr_VIVE.json))): 31 | ```json 32 | { 33 | "deviceVendor": "HTC", 34 | "deviceName": "VIVE PRE and VIVE Controllers", 35 | "author": "Georgiy Frolov ", 36 | "version": 1, 37 | "lastModified": "", 38 | "interfaces": { 39 | "tracker": { 40 | "count": 4, 41 | "bounded": true, 42 | "position": true, 43 | "orientation": true 44 | }, 45 | "analog": { 46 | "count": 7 47 | }, 48 | "button": { 49 | "count": 14 50 | } 51 | }, 52 | "semantic": { 53 | "hmd": { 54 | "$target": "tracker/0", 55 | "button": "button/0", 56 | "proximity": "button/1" 57 | }, 58 | "puck": { 59 | "$target": "tracker/3" 60 | }, 61 | "ipd": "analog/0", 62 | "controller": { 63 | "left": { 64 | "$target": "tracker/1", 65 | "system": "button/2", 66 | "menu": "button/3", 67 | "grip": "button/4", 68 | "trackpad": { 69 | "x": "analog/1", 70 | "y": "analog/2", 71 | "touch": "button/5", 72 | "button": "button/6" 73 | }, 74 | "trigger": { 75 | "$target": "analog/3", 76 | "button": "button/7" 77 | } 78 | }, 79 | "right": { 80 | "$target": "tracker/2", 81 | "system": "button/8", 82 | "menu": "button/9", 83 | "grip": "button/10", 84 | "trackpad": { 85 | "x": "analog/4", 86 | "y": "analog/5", 87 | "touch": "button/11", 88 | "button": "button/12" 89 | }, 90 | "trigger": { 91 | "$target": "analog/6", 92 | "button": "button/13" 93 | } 94 | } 95 | } 96 | }, 97 | "automaticAliases": { 98 | "/me/head": "semantic/hmd", 99 | "/me/puck": "semantic/puck", 100 | "/me/ipd": "semantic/ipd", 101 | "/controller": "semantic/controller/*", 102 | "/me/hands/left": "semantic/controller/left", 103 | "/me/hands/right": "semantic/controller/right" 104 | } 105 | } 106 | ``` 107 | 108 | Take the time to review the device descriptor to understand how the VIVE devices are factored into OSVR interfaces. The parts related to the puck are the assignment to tracker 3, and the automatic alias: 109 | ```json 110 | "/me/puck": "semantic/puck", 111 | ``` 112 | 113 | ### OSVR Server Configuration 114 | Normally for HDK2 with orientation-only tracking, we’d use a configuration file such as [/sample-configs/osvr_server_config.renderManager.HDKv2.0.direct.json](https://github.com/OSVR/OSVR-Core/blob/master/apps/sample-configs/osvr_server_config.renderManager.HDKv2.0.direct.json). 115 | 116 | Take a look at the last line in the configuration file above. The syntax is similar to how we’ll use the tracking puck: 117 | ```json 118 | "aliases": {"/me/head":"/com_osvr_Multiserver/OSVRHackerDevKit0/semantic/hmd"} 119 | ``` 120 | Instead of setting up an alias to the Multiserver plugin, we want to access the VIVE plugin. We saw earlier that there is an automatic alias in the VIVE device descriptor named “/me/puck”. Our new configuration file with puck tracking for the head is: 121 | ```json 122 | "aliases": {"/me/head":"/me/puck”} 123 | ``` 124 | That’s it! We are now able to move the puck around to change the image in our display. We probably have a little extra work to do depending on the puck's expected orientation and how it is mounted to the HDK. 125 | With the server configured this way, any OSVR clients (Unity, Unreal, etc.) requesting poses from /me/head will get poses from /me/puck, which gets poses from /com_osvr_Vive/semantic/puck, which gets poses from /com_osvr_Vive/Vive/tracker/3. 126 | 127 | ### Rotating and Translating 128 | Depending on how your puck is mounted, there may be more configuration needed for tracking to appear in the correct orientation. We decided to mount the puck on top of HDK2 with the crown pointing up and microUSB port facing the forehead, like so: 129 | 130 | ![Puck Mounted HDK2](https://github.com/OSVR/OSVR-Docs/blob/master/Configuring/images/hdk_puck.jpg) 131 | 132 | Doing so requires a -90 degree rotation about the x-axis, which is applied in the server config: 133 | ```json 134 | "aliases": { 135 | "/me/head": { 136 | "rotate": { 137 | "axis": "x", 138 | "degrees": -90 139 | }, 140 | "child": "/me/puck" 141 | } 142 | } 143 | ``` 144 | 145 | Finally, we want to translate the origin of the tracker so that it's position appears to be at the center of the eyes. It's mounted a few inches above and in-front of the eyes, so we'll need to translate it towards the head and down in the server configuration file: 146 | ```json 147 | "aliases": { 148 | "/me/head": { 149 | "posttranslate": [0.0, -0.1143, -0.0635], 150 | "rotate": { 151 | "axis": "x", 152 | "degrees": -90 153 | }, 154 | "child": "/me/puck" 155 | } 156 | } 157 | ``` 158 | Note: Units are in meters. OSVR standardizes internally on a right-handed coordinate system, with X to the right and Y up (and thus Z "near" or toward you). The posttranslate values here may need some fine-tuning depending on exact location of the tracking sensor in relation to the center of the eyes. 159 | For more information on OSVR conventions, see the [OSVR-Core documentation](http://resource.osvr.com/docs/OSVR-Core/TopicWritingClientApplication.html). 160 | 161 | All together, our configuration file with VIVE Puck tracking and HDK2 display looks like: 162 | ```json 163 | { 164 | "display": "displays/OSVR_HDK_2_0.json", 165 | "renderManagerConfig": { 166 | "meta": { 167 | "schemaVersion": 1 168 | }, 169 | "renderManagerConfig": { 170 | "directModeEnabled": true, 171 | "directDisplayIndex": 0, 172 | "directHighPriorityEnabled": true, 173 | "numBuffers": 2, 174 | "verticalSyncEnabled": true, 175 | "verticalSyncBlockRenderingEnabled": true, 176 | "renderOverfillFactor": 1.2, 177 | "renderOversampleFactor": 1.0, 178 | 179 | "window": { 180 | "title": "OSVR", 181 | "fullScreenEnabled": true, 182 | "xPosition": 1920, 183 | "yPosition": 0 184 | }, 185 | 186 | "display": { 187 | "rotation": 180, 188 | "bitsPerColor": 8 189 | }, 190 | 191 | "prediction": { 192 | "enabled": true, 193 | "staticDelayMS": 26, 194 | "leftEyeDelayMS": 0, 195 | "rightEyeDelayMS": 0, 196 | "localTimeOverride": true 197 | }, 198 | 199 | "timeWarp": { 200 | "enabled": true, 201 | "asynchronous": false, 202 | "maxMsBeforeVSync": 5 203 | } 204 | } 205 | }, 206 | 207 | "aliases": { 208 | "/me/head": { 209 | "posttranslate": [0.0, -0.1143, -0.0635], 210 | "rotate": { 211 | "axis": "x", 212 | "degrees": -90 213 | }, 214 | "child": "/me/puck" 215 | } 216 | } 217 | } 218 | ``` 219 | It's really easy to switch the HDK2 display for any other OSVR HMD -- just swap the name of the display: 220 | ```json 221 | "display": "displays/OSVR_HDK_2_0.json", 222 | ``` 223 | could be changed to work with the Sensics dSight display: 224 | ```json 225 | "display": "displays/Sensics_dSight_landscape_1input_sbs.json", 226 | ``` 227 | Reminder that if you're using OSVRTrackerView to visualize tracked devices, only /me/head, /me/hands/left, and /me/hands/right are visualized by default. To see other devices, specify their path in the command line. For example, to launch OSVRTrackerView and see four connected OSVR-VIVE devices (VIVE HMD, Controllers, Puck), launch OSVRTrackerView with the following command: 228 | ```c 229 | OSVRTrackerView.exe --pose /me/head /me/hands/left /me/hands/right /me/puck 230 | ``` 231 | However, if we are aliasing /me/head --> /me/puck like in the server configuration above, we will be able to see the puck tracking by default without this command. 232 | 233 | ### Using OSVR-VIVE with SteamVR-OSVR 234 | It is possible to use OSVR-VIVE to use the puck as a positional tracker for HDK2, and then play SteamVR games via the SteamVR-OSVR driver. We call it going through the rabbit hole twice. This is an important use case for HMD manufacturers to quickly test new HMDs with VIVE room-scale tracking by simply mounting a puck. We're still working on some issues on this path after the most recent OpenVR/SteamVR changes, but we think you'll need to make sure you have the following settings in C:\Program Files (x86)\Steam\config\steamvr.vrsettings: 235 | ```json 236 | "steamvr": { 237 | "activateMultipleDrivers": true, 238 | "requireHmd" : false 239 | } 240 | ``` 241 | To try it, run OSVR server with the configuration file from earlier, then run SteamVR (after installing the latest build of [SteamVR-OSVR](https://github.com/OSVR/SteamVR-OSVR)). If it doesn't work immediately, run SteamVR Room Setup. We will continue to update these instructions as the prcoess seems to have changed slightly in the latest releases of SteamVR. -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OSVR Developer Documentation 2 | 3 | 4 | 5 | # Introduction to OSVR 6 | - [Introduction to OSVR](http://osvr.github.io/whitepapers/introduction_to_osvr/) 7 | - [OSVR feature list](featurelist.md) 8 | - [Notes on Android support](Introduction/Android.md) 9 | - [Notes on Linux support](Introduction/Linux.md) 10 | - [Notes on OSX support](Introduction/OSX.md) 11 | - [List of supported devices, engines and operating systems ](http://osvr.github.io/compatibility/) 12 | - [List of OSVR partners](http://osvr.org/partner.html) 13 | - [OSVR presentations and speaker notes](http://osvr.github.io/presentations/) 14 | 15 | 16 | # Using OSVR 17 | ## Getting Started 18 | - [HDK Unboxing and Getting Started](Getting-Started/HDK/HDK-Unboxing-and-Getting-Started.md) 19 | - [HDK Unboxing and Getting Started (SPANISH)](Getting-Started/HDK/HDK-Unboxing-and-Getting-Started-ES.md) 20 | 21 | ## Installing OSVR 22 | 23 | - [Windows](Getting-Started/Installing/windows.md) 24 | - Minimum recommended version : Windows Vista SP1 or later 25 | - [Download pre-compiled binaries and drivers](http://osvr.github.io/using/) 26 | - [Install and test RenderManager](Installing/RenderManager.md) 27 | - [Linux](Getting-Started/Installing/Linux-Build-Instructions.md) 28 | - Minimum recommended version : Debian Jessie or equivalent ( Ubuntu 15.04+ for example ) 29 | - [Very generic instructions](Getting-Started/Installing/linux.md) 30 | - [Android](https://github.com/OSVR/OSVR-Android-Build#readme) 31 | - [OS X](Getting-Started/Installing/osx.md) 32 | - Minimum recommended version : El Capitan 33 | 34 | Note : It can be used in earlier versions but might require compilation and tweaking. 35 | 36 | ## Running the OSVR Server 37 | ### Setting the OSVR_SERVER_ROOT environment variable 38 | OSVR server auto-start functionality in ClientKit (Windows only for now) currently relies on the OSVR_SERVER_ROOT environment variable to find the server you would like to have launch. Install the [OSVR Runtime](http://osvr.github.io/using/), then set the OSVR_SERVER_ROOT environment variable to C:/Program Files/OSVR/Runtime/Server (for 64-bit) or C:/Program Files (x86)/OSVR/Runtime/Server (for 32-bit). 39 | 40 | ### Server parameters 41 | Running the OSVR server just requires passing it a configuration file. For example: 42 | **osvr_server osvr_server_config.json** 43 | 44 | if no parameter is specified, a default file is used. 45 | 46 | ## Configuring OSVR 47 | - [Using the OSVR-Config utility](Configuring/OSVR-Config.md) 48 | - [Using the SensicsTray utility](Configuring/SensicsTray.md) 49 | - [RenderManager](Configuring/OSVR-RenderManager.md) 50 | - [Calibrating the video-based tracker](Getting-Started/HDK/Video-Based-Tracking-Calibration.md) 51 | - [Local and distributed client/server configurations](Configuring/LocalAndRemote.md) 52 | - Device-specific configuration 53 | - [OSVR HDK](Configuring/osvrhdk.md) 54 | - [HTC Vive](Configuring/HTC-Vive.md) 55 | - [Oculus Rift](Configuring/oculus-rift.md) 56 | - [Integrating with VRPN devices](https://osvr.github.io/whitepapers/vrpn_in_osvr/) 57 | - [Configuring OSVR HDK2 and other OSVR-supported HMD with VIVE Puck Tracking](https://github.com/OSVR/OSVR-Docs/blob/master/Extending-OSVR/ConfiguringHDKViveTracking.md) 58 | 59 | ## Utilities 60 | - [OSVR-Central](Utilities/OSVRCentral.md) 61 | - Bundled with OSVR-Core binary snapshots/included in the OSVR-Core source tree: 62 | - [osvr_reset_yaw (e.g. "recenter")](http://resource.osvr.com/docs/OSVR-Core/OSVRResetYaw.html) 63 | - [osvr_print_tree](http://resource.osvr.com/docs/OSVR-Core/OSVRPrintTree.html) 64 | - [PathTreeExport](http://resource.osvr.com/docs/OSVR-Core/PathTreeExport.html) 65 | - [osvr_list_usbserial](http://resource.osvr.com/docs/OSVR-Core/OSVRListUSBSerial.html) 66 | - [TrackerViewer](https://github.com/OSVR/OSVR-Tracker-Viewer#readme) 67 | - [Additional Tracker Viewer documentation](http://osvr.github.io/doc/tracker-viewer/) 68 | - [OSVR Control](Utilities/OSVRControl.md) 69 | - [Updating OSVR HDK Positional Tracking IR board firmware](Utilities/HDKUpgradeIRBoardFirmware.md) 70 | - [Updating HDK Firmware from Linux](Utilities/UpdateHDKLinux.md) 71 | - [Distortionizer](https://github.com/OSVR/distortionizer#readme) helps measure distortion parameters for HMDs 72 | - [Latency tester](https://github.com/sensics/Latency-Test). Open-source Arduino-based latency tester 73 | - [OSVR HDK Video Status Tool](https://github.com/sensics/OSVR-HDK-Video-Status#readme) - Find out what video signal the HDK is receiving. 74 | - [HDK Video Status Tool Windows Binaries](https://github.com/sensics/OSVR-HDK-Video-Status/releases) - On the Releases page - often a good place to check. 75 | 76 | ## Troubleshooting 77 | - [FAQ](Troubleshooting/FAQ.md) 78 | - [OSVR server](Troubleshooting/OSVRServer.md) 79 | - [Render Manager](Troubleshooting/RenderManager.md) 80 | - HDK troubleshooting 81 | - [Skewed tracker orientation](Troubleshooting/SkewedTracker.md) 82 | - See also the HDK video status tool above in Utilities. 83 | - [Device-specific information](Troubleshooting/DeviceSpecific.md) 84 | - [Performance optimization using Event Tracing for Windows](http://osvr.github.io/presentations/20150901-Intro-ETW-OSVR/) 85 | - [Re-flash bootloader on OSVR HDK](Configuring/HDKBootloader.md) 86 | 87 | # Developing with OSVR 88 | - Setting up the development environment 89 | - [Windows](Developing/Windows-Build-Environment.md) 90 | - [Directory of projects](http://osvr.github.io/contributing/) 91 | - [Doxygen-generated developer documentation of OSVR-Core](http://resource.osvr.com/docs/OSVR-Core/) 92 | - [Doxygen-generated internal documentation of OSVR-Core](http://resource.osvr.com/internal-docs/OSVR-Core-Implementation/) 93 | - [Creating an OSVR project](Developing/creating.md) 94 | - [OSVR interfaces](Developing/interfaces.md) 95 | - [Useful resources and tools](Developing/resources.md) 96 | - Device-specific information 97 | - [OSVR HDK HID report interface](Developing/OSVRhdk.md) 98 | - [Epson Moverio AR devices](Developing/EpsonMoverio.md) 99 | 100 | # Game Engines and OSVR 101 | 102 | - [Unity](https://github.com/OSVR/OSVR-Unity/blob/master/GettingStarted.md) 103 | - [Tutorial video](https://youtu.be/xSOq3bOBPxs) 104 | - [Unity VR demos](https://github.com/OSVR/Unity-VR-Samples) are OSVR versions of the standard VR demos that ship with Unity 5.3 105 | - [Palace demo](https://github.com/OSVR/OSVR-Unity-Palace-Demo) is a Unity demo illustrating how to use the Unity OSVR plugin 106 | - [Unity version of Palace demo](http://github.com/OSVR/OSVR-Unity-Palace-Demo/blob/androidPalace/README.md) including APK and compilation notes 107 | - [Palace demo and other Unity binaries](https://github.com/OSVR/OSVR-Unity-Palace-Demo/releases) 108 | - [Migrating Oculus Unity apps to OSVR](http://access.osvr.com/binary/download/misc_assets/Migrating%20Unity%20applications%20from%20Oculus%20to%20OSVR%20Mar-11-15.pdf) 109 | - [Unreal](https://github.com/OSVR/OSVR-Unreal/blob/master/README.md) 110 | - [Tutorial Video (Unreal Engine 4.12+)](https://www.youtube.com/watch?v=Co2IiLVS3r8&feature=youtu.be) 111 | - [Tutorial video (Unreal Engine 4.11 or building from source)](https://www.youtube.com/watch?v=u4Y9pUisL1M) 112 | - [Using multi-resolution shading with OSVR](Integrating-Game-Engines/Unreal/multires.md) 113 | - [Additional Documentation](https://github.com/OSVR/OSVR-Unreal/blob/master/Documentation.md) 114 | - [OpenVR/SteamVR](https://github.com/OSVR/SteamVR-OSVR) 115 | - [Blender](https://github.com/BlendOSVR/OSVR-Blender) 116 | - [WebVR](Integrating-Game-Engines/WebVR/webvr.md) 117 | - CryEngine 118 | - [Monogame: video](https://www.youtube.com/watch?v=doOOLaIuj48) 119 | - OpenGL 120 | 121 | # Extending OSVR 122 | - [Adding a New HMD](Extending-OSVR/AddingHMD.md) 123 | - [Adding a new Device](Extending-OSVR/Adding-a-New-Device.md) 124 | - [Best practices for device descriptor](Extending-OSVR/Device-Descriptor-Practices.md) 125 | - [Writing an OSVR Plugin](http://resource.osvr.com/docs/OSVR-Core/TopicWritingDevicePlugin.html) 126 | - [Writing an OSVR Client](http://resource.osvr.com/docs/OSVR-Core/TopicWritingClientApplication.html) 127 | - Porting to a New Operating System 128 | 129 | # Roadmap 130 | - [Aug 2016 article in RoadToVR on future plans for OSVR](http://www.roadtovr.com/osvr-co-founder-on-the-future-of-open-source-virtual-reality/) 131 | - In September 2015, RoadToVR published an article by [Yuval Boger](https://twitter.com/osvrguy) of Sensics about the [OSVR roadmap](http://www.roadtovr.com/osvr-roadmap-creating-an-ecosystem-of-interoperable-vr-hardware-and-software/). It is an excellent starting point to understand the OSVR big picture and roadmap. 132 | - The [OSVR Waffle Board](Roadmap/waffle.md) contains an overview of issues currently in GitHub issue trackers for all OSVR framework projects. 133 | - Additional development priorities suggested by the core OSVR team can be [found here](Roadmap/additional.md). 134 | 135 | # Hacking the Hardware 136 | - [iFixit guides on various HDK 1.3/1.4 upgrades and repairs](https://www.ifixit.com/Device/Razer_OSVR_HDK_1.4) 137 | - [Replacement parts and other OSVR-related products](https://osvrstore.com/collections/frontpage) 138 | 139 | # Getting Support 140 | 141 | ## Search 142 | [Custom Google Search for the OSVR project](https://cse.google.com/cse/publicurl?cx=016285390483464504735:ifzwvrb3lp4) 143 | 144 | ## Free support 145 | - Post an issue on the [OSVR Github projects](https://github.com/osvr) to be addressed by the OSVR community 146 | - Open a support ticket on the [support portal](http://support.osvr.com/) (or email "support at osvr.org") to be addressed by core developers 147 | - [Visit the OSVR development chat rooms](https://gitter.im/orgs/OSVR/rooms) 148 | 149 | ## Paid support 150 | Some companies such as [Sensics](http://sensics.com/contact-us/) provide premium support services for OSVR including phone support, system engineering, authoring drivers or integration help. If you require support beyond the free support options, consider contacting the premium providers. 151 | 152 | # Participate 153 | A list of OSVR developer chat rooms is [here](https://gitter.im/orgs/OSVR/rooms) 154 | 155 | Some existing rooms: 156 | - [General subjects](https://gitter.im/OSVR/OSVR-General) 157 | - [Unity](https://gitter.im/OSVR/OSVR-Unity) 158 | - [Unreal](https://gitter.im/OSVR/OSVR-Unreal) 159 | - [SteamVR](https://gitter.im/OSVR/SteamVR-OSVR) 160 | - [OSVR Core](https://gitter.im/OSVR/OSVR-Core) 161 | 162 | [Combined OSVR issue tracker](https://waffle.io/osvr/osvr-core) 163 | 164 | [Map of OSVR projects](http://osvr.github.io/contributing/) 165 | 166 | # Useful Links 167 | ### Contributed from the OSVR community 168 | 169 | - Revive allows non Oculus headsets be used for games which only support Oculus headsets when run through steamvr runtime https://github.com/LibreVR/Revive and then potentially work on OSVR supported through the SteamVR interface 170 | - FakeVive allows non HTC headsets be used for games which only support HTC headsets when run through steamvr runtime. https://github.com/Shockfire/FakeVive 171 | - Non-Vive controllers can be used through with OSVR with Vive games. See https://github.com/OSVR/OSVR-Docs/blob/master/Extending-OSVR/ConfiguringHDKViveTracking.md . Alternatively, OpenVR-AdvancedSettings gives users access to many useful openvr and openvr apps settings. Users that do not have Vive controllers will need to access these settings from desktop or rely on using the hydra drivers and six sense SDK from steam tools to emulate Vive controllers to access the settings in an overlay running as a steamvr dashboard app https://github.com/matzman666/OpenVR-AdvancedSettings 172 | 173 | #### For Vive Controller Emulation: 174 | 175 | - FreePIE https://github.com/AndersMalmgren/FreePIE 176 | - Opentrack https://github.com/opentrack/opentrack 177 | - FreePIE-VR-Controls https://github.com/fmaurer/FreePIE-VR-Controls 178 | 179 | # Additional Information 180 | - [OSVR mailing lists and newsletters](http://osvr.github.io/mailing-lists/) 181 | - [OSVR marketing Web site](http://www.osvr.org) 182 | - VR Knowledge Nuggets 183 | - [Tracking](VR-Knowledge-Nuggets/tracking.md) 184 | - [Displays](VR-Knowledge-Nuggets/displays.md) 185 | - [The Sensics insights page](http://sensics.com/insight) often covers OSVR-related topics and includes tutorials such as: 186 | - [Key parameters in optical design](http://sensics.com/key-parameters-optical-designs/) 187 | - [Common eye tracker configurations](http://sensics.com/the-three-and-a-half-configurations-of-eye-trackers/) 188 | - [Understanding pixel density and eye-limiting resolutions](http://sensics.com/understanding-pixel-density-and-eye-limiting-resolution/) 189 | - [Predictive tracking](http://sensics.com/understanding-predictive-tracking/) 190 | - [Foveated rendering](http://sensics.com/converting-diagonal-field-of-view-and-aspect-ratio-to-horizontal-and-vertical-field-of-view/) 191 | - [Asynchrnous timewarp](http://sensics.com/time-warp-explained/) 192 | - [Geometric distortion](http://vrguy.blogspot.com/2013/07/what-is-geometric-distortion-and-why.html) 193 | - [Converting diagonal FOV and aspect ratio to horizontal and vertical FOV](http://vrguy.blogspot.com/2013/04/converting-diagonal-field-of-view-and.html) 194 | - [TV screen size vs. goggle field of view](http://vrguy.blogspot.com/2013/04/tv-screen-size-vs-goggle-field-of-view.html) 195 | - [How things work: the dual-elements optics of the OSVR HDK](http://vrguy.blogspot.com/2015/01/how-things-work-dual-element-optics-of.html) 196 | - [Binocular overlap](http://vrguy.blogspot.com/2013/05/what-is-binocular-overlap-and-why.html) 197 | - [What you should know about head trackers](http://vrguy.blogspot.com/2013/05/what-you-should-know-about-head-trackers.html) 198 | - [An overview of positional tracking technologies for VR](http://vrguy.blogspot.com/2014/05/an-overview-of-positional-tracking.html) 199 | 200 | # Sample third-party projects that integrate OSVR into them 201 | - [OSVR plugin for FreePie](https://github.com/thomasgauthier/FreePIE-OSVR) 202 | -------------------------------------------------------------------------------- /Getting-Started/HDK/HDK-Unboxing-and-Getting-Started-ES.md: -------------------------------------------------------------------------------- 1 | # Felicitaciones por tu Hacker Development Kit! 2 | 3 | Esta es una traducción de "Getting Started", y como tal puede quedar desactualizada, así que es probable que algunos datos sean inválidos en el futuro. 4 | 5 | ## Identificando tu dispositivo 6 | Las principales variedades de HDK en el mercado son HDK 1.2 y HDK 1.3 . Ambas vienen dentro de una caja de cartón con manija de transporte y logotipos de OSVR. Generalmente incluye un kit de cámara IR. 7 | 8 | > Nota: Si obtuviste tu HDK antes de mediados del 2015, particularmente si no trajo una lujosa caja ensamblada en una fábrica con una cámara IR, y/o posee una pantalla LCD en vez de una OLED, es posible que sea un prototipo anterior. Generalmente puedes tratarlo como un HDK 1.2, excepto que deberìas evitar actualizar el firmware sin contactar al soporte : No quisiéramos que instales un firmware para OLED en una unidad con LCD, y dado que el Hacker Development Kit está diseñado para ser hackeado, incluso hasta la pantalla, hacer eso es posible. 9 | La principal diferencia exterior entre el HDK 1.3 y versiones anteriores es el sistema de ajuste óptico. 10 | 11 | - El HDK 1.2 y anteriores poseen ajustes a tornillo por debajo de cada ojo, con ajuste de distancia entre pupilas (IPD) y foco. Esta imagen es de un HDK 1.1, pero el mecanismo en el HDK 1.2 es efectivamente el mismo. ![HDK pre-1.3 ajuste ocular](HDK11.jpg) 12 | - El HDK 1.3 posee ajustes deslizables debajo de cada ojo para el ajuste de foco ( óptica modificada para brindar un "eyebox" más grande ( zona tridimensional en la cual el ojo puede ver la imagen correctamente ) eliminó la necesidad para el ajuste de distancia entre pupilas (IPD) ). ![HDK 1.3 ajuste deslizante](HDK13-ID.jpg) 13 | 14 | Existen diferencias generalmente encontradas entre los chipsets de las "belt boxes" del HDK 1.2 y 1.3, así que cuando tengas el pack de drivers instalados ( usando Windows ), eso puede ayudarte a recordarlo, pero las diferencias mecánicas son las más confiables para diferenciar modelos. 15 | 16 | ## Advertencias/Limitaciones 17 | - El archivo de configuración por defecto en Windows asume un HDK 1.3, renderizado en modo directo ( direct mode ), y seguimiento por fusión de IMU y video. En HDK 1.2 o si no puedes/quieres usar modo directo, es necesario cambiar el archivo de configuración. Hay archivos de configuración con nombres autoexplicativos incluidos. 18 | - El servidor OSVR actualmente muestra una consola que puede ser minimizada, pero no debe ser cerrada mientras usas una aplicación OSVR. Una interfaz más agradable o invisible está siendo creada. 19 | 20 | ## Configuración 21 | 22 | ### Conectando el HDK y la Cámara IR. 23 | Hay un par de conexiones que hacer: HDK al beltbox, electricidad de la pared al beltbox, HDMI y USB entre el beltbox y tu PC. 24 | El orden particular no importa. Mantén la precaución de no colocar el beltbox en una posición que estrangule o estire los cables. 25 | 26 | Si usas seguimiento por video ( posicional ), asegurate de que el cable de sincronización esté conectado. 27 | 28 | Una vez conectados el HDK, HDMI y cable de poder a la pared, el HDK debe ser reconocido como un display nuevo en la PC. Los usuarios de Windows pueden necesitar elegir "extender pantalla" en "Propiedades de Pantalla". 29 | Usuarios de Linux: Pueden extender el display o ejecutar otra pantalla de X en el HDK, dependiendo del uso. 30 | 31 | Probablemente se vea como un display de 1080x1920 "Retrato" por defecto. Este es el modo de mayor rendimiento. Sin embargo , actualmente la mayoría de las aplicaciones no funcionan en este modo, así que te conviene elegir la resolución de 1920x1080. ( Esto no significa que que debas cambiar la orientación , el HDK se encarga de eso internamente.) 32 | 33 | En este punto debes tener la Cámara IR conectada, cuando menos para actualizar el firmware. Desafortunadamente al día de hoy el actualizador de firmware para la Cámara IR sólo funciona en Windows. 34 | 35 | ### Windows: Instalar el pack de drivers ( opcional pero recomendado ) 36 | Si te encuentras en Windows, hay un instalador del pack de drivers que puede mejorar tu experiencia. Si bien no es estrictamente necesario para un uso básico, provee mejores nombres para los dispositivos en el administrador de dispositivos, agrupa componentes de los dispositivos lógicamente con íconos correctos en "Dispositivos e Impresoras", y en Windows 8.1 ( y anteriores) es requerido para usar el software de control del OSVR HDK para actualizar el firmware, etc. ( Windows 10 ya posee el driver correcto, pero los otros beneficios aún se aplican). 37 | 38 | Puedes encontrar la última versión en . Descarga e instala antes de continuar. 39 | 40 | ### Drivers de Video 41 | Chequea [RenderManager Troubleshooting](../../Troubleshooting/RenderManager.md) para ver los últimos drivers testeados. 42 | 43 | ### Verifica/Actualiza el firmware 44 | 45 | Hay varias partes del sistema que tienen firmware que puede ser actualizado. 46 | El **Firmware de la Cámara IR** actualizado es esencial, ya que las actualizaciones proveen mejoras sustanciales de rendimiento como compatibilidad con Linux, OS X, y otros paquetes de software además del plugin de seguimiento por video de OSVR. En Windows, con drivers 1.2.6 o superior, desde INICIO, escribe "Dispositivos e Impresoras" y presiona Enter, y deberías ver un número de dispositivos vinculados a OSVR con íconos correspondientes a lo que tengas conectado. 47 | 48 | Si el ícono de tu Cámara IR se ve así: 49 | ![IR camara necesita actualizar](camera-needs-upgrade.png) 50 | Click derecho, y elige "Get firmware upgrade". Alternativamente puedes ir a . 51 | ![IR menu contextual camara](camera-context-menu.png) 52 | Una vez allí, debes buscar la descarga para el actualizador de firmware de la Cámara IR: va a estar marcado con este símbolo: 53 | ![IR camara simbolo actualizar](ircamera-updater.png) 54 | 55 | 56 | > ¿No usas Windows?: Si bien no puedes actualizar el firmware en tu sistema, puedes revisar y ver la versión del firmware, ya que es parte del ID del hardware USB. El ID del fabricante es 0x0bda, ID de producto es 0x57e8, y la versión del firmware es cualquiera que sea listada en el campo `bcdDevice` ( que figura como `REV_` en Windows). 57 | > En Linux, `lsusb -v -d 0bda:57e8` presenta mucha información sobre el dispositivo, y `lsusb -v -d 0bda:57e8 | grep bcdDevice` presenta sólo la revisión 0.07 para versión 7, la última al tiempo de autoría de este documento. Si es menor, el firmware necesita actualizaciones. 58 | 59 | **El procesador del HDK** también posee firmware actualizable. 60 | 61 | Si posees un HDK 1.2, el firmware más reciente que necesitas es la versión **1.84** - versiones más nuevas contienen código específico para la pantalla OLED del 1.3. Ve las instrucciones para un [HDK 1.2 upgrade procedure](HDK-1.2-Firmware-Update.md) que instalará automáticamente este software, así como también automatizar el proceso de actualización del de los VID/PID del procesador en caso de que tengas una unidad antigua donde estos estén fallados. 62 | 63 | En ambos 1.2 y 1.3 el "OSVR HDK Control utility" en Windows es el mejor lugar para actualizar el firmware y para ajustar algunas características especiales en el HDK. Puedes obtenerlo en . También puede reportar la versión actual del firmware que tienes instalado, etc. 64 | El firmware del HDK se puede actualizar en Linux o Mac OS X, pero el proceso no fue completamente documentado aún. Si necesitas instrucciones, contacta al soporte y te ayudaremos , actualizando la documentación en el proceso. 65 | 66 | ### Obtener el OSVR Server 67 | 68 | OSVR Server es parte del framework OSVR y provee un sistema para acceder a los datos del dispositivo, configurar periféricos, etc. Los drivers del HDK están incluidos en el paquete OSVR Core ( que incluye al server ), y tu HDK puede ser auto detectado, así que no vas a necesitar editar ninguna configuración, salvo que desees conectar dispositivos de entrada adicionales. 69 | 70 | Hay dos formas de obtener el OSVR Server: el instalador y las "build snapshots". Ya que actualmente el instalador no se actualiza automáticamente , la mejor manera es bajar un "snapshot" de OSVR Core, vinculado desde [Using OSVR][using]. Si usas una versión de 64 bits de Windows, tanto la de 32 o la de 64 bits funcionarán ( y serán compatibles con aplicaciones de 32 y 64 bits), así que sólo elige una. ( Usuarios de Linux: favor de ver [instrucciones de compilación](../Installing/Linux-Build-Instructions.md) en este repositorio.) 71 | 72 | En cualquier caso, ejecutar `osvr_server` debe abrir una ventana de comandos con algunos mensajes. Si todo funciona bien, verás una linea que dice : 73 | 74 | ``` 75 | Added device: com_osvr_Multiserver/OSVRHackerDevKit0 76 | ``` 77 | 78 | Si te encuentras en Linux o Mac OS X y no observas esta línea, debes referirte a [known issues]. 79 | 80 | Puedes minimizar esta ventana, pero asegúrate de mantenerla corriendo mientras uses aplicaciones para OSVR. 81 | 82 | [OSVR-Core]: https://github.com/OSVR/OSVR-Core/ 83 | [using]: http://osvr.github.io/using/ 84 | [known issues]: ../Installing/Linux-Build-Instructions.md#known-issues-temporary 85 | 86 | ### Ajuste de Óptica (HDK 1.0, 1.1, 1.2) 87 | [[assets/HDK-optics-adjustment.png]] 88 | 89 | Este diagrama del ajuste de óptica ([[printable full-page PDF here|assets/HDK-optics-adjustment.pdf]]) muestra cuales son los ajustes. Querrás hacer los ajustes mientras tengas puesto el visor con una imagen en pantalla, pero con un ojo a la vez ( cierra uno a la vez ). Puedes usar tus anteojos/gafas si los necesitas para estimar dónde quieres comenzar el control de foco, y luego ajustar el IPD hasta que las lentes se sientan centradas con tu ojo y toda la pantalla se ve igualmente nítida. 90 | 91 | ### Ajuste de Óptica (HDK 1.3) 92 | 93 | Los deslizadores bajo las lentes del HDK 1.3 ajustan el foco en diópteras. Si normalmente usas anteojos/gafas, es posible que con el ajuste de foco no las necesites y puedas lograr una imágen nítida. De lo contrario, ajusta hasta que veas una imagen nítida con ambos ojos, seguramente cuando ambos ojos se encuentren cerca de la marca etiquetada 0. 94 | 95 | 96 | ## Software 97 | 98 | ### Visor de Seguimiento ( Tracker Viewer ) 99 | La primera aplicación que sugerimos probar no es glamorosa, pero es útil para chequear y asegurarse de que las cosas funcionen. En [Using OSVR][using] encontrarás un enlace de descarga para el OSVR Tracker Viewer. Descarga y ejecutalo ( ¡Con el OSVR Server corriendo! ) y verás una pequeña ventana con unas flechas 3D. Si eres conocedor de gráficos 3D o de VR, probablemente deduzcas lo que ves y lo que significa, pero la parte importante en general es verificar que las pequeñas flechas en el centro se mueven cuando rotas el HDK. ( Puedes hacer click derecho y arrastrar para hacer zoom) 100 | 101 | Por supuesto puedes ignorar este paso, pero si tienes problemas, alguien te preguntará probablemente lo que ves en el Tracker Viewer. 102 | 103 | 104 | ### La Demo "Palace" ( Palacio ) 105 | 106 | La Demo Palace [OSVR Unity Palace Demo](https://github.com/OSVR/OSVR-Unity-Palace-Demo/releases) [(source repo)](https://github.com/OSVR/OSVR-Unity-Palace-Demo) es un entorno visualmente rico para observar y explorar usando dispositivos soportados por OSVR, incluyendo el HDK. EL primer vínculo contiene descargas para el binario para Windows: sólo descarga y ejecuta ( ¡Con el OSVR Server corriendo! ), y si lo deseas puedes usar un comando de juego o el teclado más el mouse. En la pantalla de inicio puedes decidir qué pantalla está configurada como tu HDK. 107 | 108 | Recuerda que esta aplicación, como todas las aplicaciones Unity, si la ventana pierde el foco, la aplicación se congela, la mayoría de las veces se resuelve clickeando dentro de la ventana nuevamente. 109 | 110 | ## ¡Ayuda! ( Asume que el lenguaje del soporte es el Inglés ) 111 | 112 | Si experimentas problemas de hardware o software en general, abre un ticket de ayuda en [OSVR Support](http://support.osvr.com). 113 | 114 | Si estás interesado en desarrollar software para OSVR o contribuir de alguna forma, favor de ver el [Developer Portal at osvr.github.io](http://osvr.github.io) para unirte al desarrollo/lista de correo, y ver la lista de proyectos y su información para desarrolladores. 115 | 116 | Los tickets de soporte son monitoreados por múltiples personas así que serán atendidos con cuidado por la mejor persona disponible y preparada para responder tu pregunta. GitHub y la lista de correo son las principales formas para contactarse con los desarrolladores que contribuyen con OSVR. 117 | 118 | - No es recomendado hacer preguntas sobre problemas o publicar preguntas en otros lugares ( foros/reddit, twitter, etc.) si deseas una respuesta "oficial" o de los desarrolladores, dado que no son los lugares que nosotros (desarrolladores/personas técnicas) necesariamente frecuentamos diariamente, o controlamos las cuentas "oficiales" en esos lugares. 119 | 120 | - Como una regla general de comunidades de open-source, y por ende en OSVR también, es usualmente considerado descortés enviar un email a un desarrollador personalmente con una pregunta. Entre otras razones, sólo le permite a una persona atender tu pregunta ( cuando puede haber otras que podrían hacerlo, e incluso mejor) y no produciría un intercambio útil disponible en los archivos públicos. ( No te sorprendas si tu email es republicado como un ticket de soporte ). 121 | 122 | 123 | # Obteniendo Soporte 124 | ## Soporte Gratis (Sólo Inglés) 125 | - Publica un issue en [OSVR Github projects](https://github.com/osvr) para que la comunidad lo trate. 126 | - Abre un ticket de soporte en [support portal](http://support.osvr.org) o un email a "support at osvr.org" para que los core developers lo traten. 127 | - [Visita las salas de chat del desarrollo de OSVR](https://gitter.im/orgs/OSVR/rooms) 128 | 129 | ## Soporte Pago (Sólo Inglés) 130 | Algunas compañías como [Sensics](http://sensics.com/contact-us/) proveen soporte premium para OSVR, incluyendo soporte para teléfonos, ingeniería de sistemas, creación de drivers o ayuda para la integración. Si necesitas soporte más allá de lo que puede proveer la comunidad gratuitamente, considera contactar al soporte premium. 131 | 132 | # Participar (Sólo Inglés) 133 | Una lista de salas para desarrolladores se encuentra [aquí](https://gitter.im/orgs/OSVR/rooms) 134 | 135 | Algunas salas existentes: 136 | - [General subjects](https://gitter.im/OSVR/OSVR-General) 137 | - [Unity](https://gitter.im/OSVR/OSVR-Unity) 138 | - [Unreal](https://gitter.im/OSVR/OSVR-Unreal) 139 | - [SteamVR](https://gitter.im/OSVR/SteamVR-OSVR) 140 | - [OSVR Core](https://gitter.im/OSVR/OSVR-Core) 141 | 142 | [Tracker de issues combinado OSVR](https://waffle.io/osvr/osvr-core) 143 | 144 | [Mapa de proyectos OSVR](http://osvr.github.io/contributing/) 145 | --------------------------------------------------------------------------------