openhmd/openhmd

Free and Open Source API and drivers for immersive technology.

UNMAINTAINED ⛔️

OpenHMD is currently NOT ACTIVELY MAINTAINED. If you are interested in maintaining OpenHMD, please open a github issue.

Oculus Rift CV1 positional tracking support is developed in this OpenHMD fork https://github.com/thaytan/OpenHMD.

Open Source XR driver development has largely moved to the Monado project:

• https://monado.freedesktop.org/
• https://gitlab.freedesktop.org/monado/monado

OpenHMD

This project aims to provide a Free and Open Source API and drivers for immersive technology, such as head mounted displays with built in head tracking.

License

OpenHMD is released under the permissive Boost Software License (see LICENSE for more information), to make sure it can be linked and distributed with both free and non-free software. While it doesn't require contribution from the users, it is still very appreciated.

Supported Devices

For a full list of supported devices please check https://github.com/OpenHMD/OpenHMD/wiki/Support-List

Supported Platforms

• Linux
• Windows
• OS X
• Android
• FreeBSD

Requirements

• Option 1: Meson + Ninja
  • http://mesonbuild.com
  • https://ninja-build.org
• Option 2: GNU Autotools (if you're building from the git repository)
• Option 3: CMake
• HIDAPI
  • http://www.signal11.us/oss/hidapi/
  • https://github.com/signal11/hidapi/

Language Bindings

• GO bindings by Marko (Apfel)
  • https://github.com/Apfel/OpenHMD-GO
• Java bindings by Joey Ferwerda and Koen Mertens
  • https://github.com/OpenHMD/OpenHMD-Java
• .NET bindings by Jurrien Fakkeldij
  • https://github.com/jurrien-fakkeldij/OpenHMD.NET
• Perl bindings by CandyAngel
  • https://github.com/CandyAngel/perl-openhmd
• Python bindings by Lubosz Sarnecki
  • https://github.com/lubosz/python-rift
• Rust bindings by The_HellBox
  • https://github.com/TheHellBox/openhmd-rs

Other FOSS HMD Drivers

• libvr - http://hg.sitedethib.com/libvr

Compiling and Installing

Using Meson:

With Meson, you can enable and disable drivers to compile OpenHMD with. Current available drivers are: rift, deepon, psvr, vive, nolo, wmr, xgvr, vrtek, external, and android. These can be enabled or disabled by adding -Ddrivers=... with a comma separated list after the meson command (or using meson configure ./build -Ddrivers=...). By default all drivers except android are enabled.

meson ./build [-Dexamples=simple,opengl]
ninja -C ./build
sudo ninja -C ./build install

Using CMake:

With CMake, you can enable and disable drivers to compile OpenHMD with. Current Available drivers are: OPENHMD_DRIVER_OCULUS_RIFT, OPENHMD_DRIVER_DEEPOON, OPENHMD_DRIVER_PSVR, OPENHMD_DRIVER_HTC_VIVE, OPENHMD_DRIVER_NOLO, OPENHMD_DRIVER_WMR, OPENHMD_DRIVER_XGVR, OPENHMD_DRIVER_VRTEK, OPENHMD_DRIVER_EXTERNAL and OPENHMD_DRIVER_ANDROID. These can be enabled or disabled adding -DDRIVER_OF_CHOICE=ON after the cmake command (or using cmake-gui).

mkdir build
cd build
cmake ..
make
sudo make install

Configuring udev on Linux

To avoid having to run your applications as root to access USB devices you have to add a udev rule (this will be included in .deb packages, etc).

A full list of known usb devices and instructions on how to add them can be found on: https://github.com/OpenHMD/OpenHMD/wiki/Udev-rules-list

After this you have to unplug your device and plug it back in. You should now be able to access the HMD as a normal user.

Compiling on Windows

CMake has a lot of generators available for IDE's and build systems. The easiest way to find one that fits your system is by checking the supported generators for you CMake version online. Example using VC2013.

cmake . -G "Visual Studio 12 2013 Win64"

This will generate a project file for Visual Studio 2013 for 64 bit systems. Open the project file and compile as you usually would do.

Cross compiling for windows using mingw

Using CMake:

For MinGW cross compiling, toolchain files tend to be the best solution. Please check the CMake documentation on how to do this. A starting point might be the CMake wiki: http://www.vtk.org/Wiki/CmakeMingw

Static linking on windows

If you're linking statically with OpenHMD using windows/mingw you have to make sure the macro OHMD_STATIC is set before including openhmd.h. In GCC this can be done by adding the compiler flag -DOHMD_STATIC, and with msvc it can be done using /DOHMD_STATIC.

Note that this is only if you're linking statically! If you're using the DLL then you must not define OHMD_STATIC. (If you're not sure then you're probably linking dynamically and won't have to worry about this).

Pre-built packages

A list of pre-built backages can be found on http://www.openhmd.net/index.php/download/

Using OpenHMD

See the examples/ subdirectory for usage examples. The OpenGL example is not built by default, to build it use the --enable-openglexample option for the configure script. It requires SDL2, glew and OpenGL.

An API reference can be generated using doxygen and is also available here: http://openhmd.net/doxygen/0.1.0/openhmd_8h.html

openhmd's Issues

No rule to make target `drv_dummy/dummy.c', needed by `libopenhmd_la-dummy.lo'.

This source file doesn't seem to be in the git repo -- was it skipped accidentally? An earlier version ( 2a551b8 ) did work for me OK (with the addition of the -lpthread to build the examples on Ubuntu).

Detect which display port the Rift is connected to and render on it automatically

Could be useful when not in clone mode. Like the -xineramascreen <0-...> command in MPlayer, which is quite useful to display Rift-ready videos on the correct output.

Somewhat equivalent to the -adapter command switch of the Unity engine but automatic instead.

Add functions to determine length of ohmd_device_getf() / ohmd_device_geti() writes.

Utilize the camera on DK2

Add example using OpenHMD with Qt/QML

In theory, using Scene3D, it should be really simple for someone who knows what they are doing to create an example of using OpenHMD with Qt/QML.

https://doc.qt.io/qt-5/qt3d-scene3d-example.html

Ubuntu PPA

Need help about building windows version

I use the source code build a windows version on win7 with vs2013 manually.

firstly, I found the buffer size check on decode_tracker_sensor_* functions on packet.c file are all wrong. For example: on decode_tracker_sensor_msg, the buffer size on linux is 62 but it's 64 on windows.And I change all the size check value to match it and get the program run normally.

But when I test the simple demo with DK2, I found that DK2's gyro data is not as accurate as run on linux.
And the DK2's rotation data shows that it drift very quickly, but on linux it's very stable.

Thx for any advice.

User reserved error code.

Also include error code reserved for user.

Neck model

Add a configurable neck model.

PSVR - Each data block contains 2 sets of acc/gyro data

You can decode 2 sets of acc/gyros from the PSVR data, each is time stamped.

See:
https://github.com/mungewell/pyPSVR/blob/master/example1_hidapi/read_hid.py

-lthr missing on FreeBSD12

Hi

I need to do
export LDFLAGS='-lthr'
in order to link successfully.

Please add this flag for FreeBSD.

Missing config.h file for building drv_htc_vive directory?

Hi,

I have added options to cmake to build drv_htc_vive directory because I would like to read rotational data from the Vive.
I am on the htc-vive branch and getting the error below. I cannot locate the "config.h" file in the project. Is this file and any others missing from the branch?
Thanks in advance for your help.

---

Changes to CMakeLists.txt
if(OPENHMD_DRIVER_VIVE)
set(openhmd_source_files ${openhmd_source_files}
${CMAKE_CURRENT_LIST_DIR}/src/drv_htc_vive/vive.c
${CMAKE_CURRENT_LIST_DIR}/src/drv_htc_vive/packet.c
)
add_definitions(-DDRIVER_VIVE)

find_package(HIDAPI REQUIRED)
include_directories(${HIDAPI_INCLUDE_DIRS})
set(LIBS ${LIBS} ${HIDAPI_LIBRARIES})

endif(OPENHMD_DRIVER_VIVE)

Error:
C:\workplace\OpenHMD>make
Scanning dependencies of target openhmd
[ 8%] Building C object CMakeFiles/openhmd.dir/src/drv_htc_vive/packet.c.obj
C:\workplace\OpenHMD\src\drv_htc_vive\packet.c:2:20: fatal error: config.h: No such file or directory
#include "config.h"
^
compilation terminated.
make[2]: *** [CMakeFiles\openhmd.dir\build.make:238: CMakeFiles/openhmd.dir/src/drv_htc_vive/packet.c.obj] Error 1
make[1]: *** [CMakeFiles\Makefile2:67: CMakeFiles/openhmd.dir/all] Error 2
make: *** [Makefile:83: all] Error 2

On htc-vive: simple.exe cannot connect to HTC-VIVE

Hi,

I would like to use the "simple" example provided to read IMU data from the HTC-VIVE.
I've added the snippet below to the CMakeLists.txt in the package root to build the source in drv_htc_vive, however simple.exe does not connect to it. It always connects to a "dummy device" regardless of what driver is built. Can you please provide some steps on how to connect to the htc-vive using the simple example?

Thanks

>simple.exe
num devices: 1
device 0
  vendor:  OpenHMD
  product: Dummy Device
  path:    (none)

OpenHMD/CMakeLists.txt code to build /src/drv_htc_vive

if(OPENHMD_DRIVER_VIVE)
	set(openhmd_source_files ${openhmd_source_files}
			${CMAKE_CURRENT_LIST_DIR}/src/drv_htc_vive/vive.c
			${CMAKE_CURRENT_LIST_DIR}/src/drv_htc_vive/packet.c
			)
	add_definitions(-DDRIVER_VIVE)
	find_package(HIDAPI REQUIRED)
	include_directories(${HIDAPI_INCLUDE_DIRS})
	set(LIBS ${LIBS} ${HIDAPI_LIBRARIES})
endif(OPENHMD_DRIVER_VIVE)

Doxygen Documentation

Linker needs -lm on Debian and -lpthread on Debian kfreebsd-{amd64|i386}

The needed additional linker flags are passed from Debian's packaging scripts:
https://sources.debian.net/src/libopenhmd/0.2.0-3/debian/rules/

You may want to add them to configure.ac instead.
The GNU triplet for kfreebsd-amd64 is:
DEB_HOST_MULTIARCH=x86_64-kfreebsd-gnu

Please add metadata about which hardware devices are supported

As suggested by Paul Wise, Isenkram on Debian could recommend installing the libopenhmd package
when a supported device is attached to the computer.
Please help by shipping the needed xml files.

Please see details at:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=845272#10

Add predictive tracking

See : http://www.oculusvr.com/blog/the-latent-power-of-prediction/

Especially method 3 as it seems to give the best results by far, and which is expected to appear in an upcoming releasing of the Oculus SDK.

Detect hot plugging of the Oculus Rift after application start

Not necessarily very important, but could be useful to switch to Rift mode after an application has already been started but with the Rift not connected on startup.

Irregular order of devices make PSVR on Mac untrustworth

Note the following output as the right HID devices are being found on a Mac:

054c:09af IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/PRT2@14200000/PlayStation®VR@14200000/PS VR Control@5/IOUSBHostHIDDevice@14200000,5
opening
054c:09af IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/PRT2@14200000/PlayStation®VR@14200000/PS VR Sensor@4/IOUSBHostHIDDevice@14200000,4
054c:09af IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/PRT2@14200000/PlayStation®VR@14200000/PS VR Control2@8/IOUSBHostHIDDevice@14200000,8
054c:09af IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/PRT2@14200000/PlayStation®VR@14200000/PS VR Sensor@4/IOUSBHostHIDDevice@14200000,4
054c:09af IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/PRT2@14200000/PlayStation®VR@14200000/PS VR Control2@8/IOUSBHostHIDDevice@14200000,8
opening
054c:09af IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/PRT2@14200000/PlayStation®VR@14200000/PS VR Control@5/IOUSBHostHIDDevice@14200000,5

The first 3 lines (+opening) are finding the sensor device, the next 3 finding the control device.
First time around its control, sensor and control2
Second time around its sensor, control2 and control

Needless to say the control is now used as sensor, and control2 as control...

Support for Closing Devices

Add a function to close an open device.

iOS Tracking Support

Support for using the native iOS API sensors as input for OpenHMDs head tracking.

Unable to fetch library version information

Library lacks calls for fetching version information of the library, so clients cannot check minimum version requirements or implement backwards compatibility.

API support for multiple displays

Make it possible to get information for more than one display, if the HMD has multiple displays.

del

del

Make the (a) dummy device "look around" for testing purposes

I do a lot of development where I am not able to move my HMD device around i.e. at a different location.

It would be neat, if of very limited usefulness (that I can think of), to either have another dummy device that "looks around", have a setf (axis bitmap?) which causes the dummy device to look around or the existing dummy device to look around.

This has come about because I am trying to detect if the user is facing up/down/left/right but can't check if my "quaternion -> euler angles" calculations are correct while being unable to move my Rift to simulate use.

Rotation Drifting with DK2

So I've been testing out my DK2 I got recently, and one application I was looking to port to the DK2 was xLava's Jedi Academy VR port. However, after correcting all the resolution values and getting everything going, I started to notice that my camera has a constant "spin" to it, and it was especially noticable in cutscenes. Just to make sure it wasn't the fault of xLava, I went into the 'simple' demo bundled in OpenHMD, and lo and behold it had a constant spin there as well when I set my HMD down.

The rotation values still change when I look around, so it's definitely not an issue of retrieving them. But regardless, something is causing this spin to occur on DK2 devices. Is it some sort of correctional measure for the DK1 which was never removed for DK2 devices, or is it the DK2 itself outputting these values?

I should also add that I tested this with the 0.4.3 SDK and the Tuscany demo, and no drifting was present.

Optionally make OpenHMD act as a client to the official Oculus server process.

API for VR-focused controllers

OpenHMD currently does not expose an API for VR-focused controllers, such the Vive controllers or the P5 Glove (#51).

autogen does not work with Mingw32 under windows.

I have the latest autotools. I was able to build hidapi without issue. I cannot complete OpenHMD's autogen. See below.

$ ./autogen.sh #
libtoolize: putting auxiliary files in `.'.
libtoolize: copying file `./ltmain.sh'
libtoolize: Consider adding `AC_CONFIG_MACRO_DIR([m4])' to configure.ac and
libtoolize: rerunning libtoolize, to keep the correct libtool macros in-tree.
libtoolize: Consider adding `-I m4' to ACLOCAL_AMFLAGS in Makefile.am.
configure.ac:55: error: possibly undefined macro: AC_CHECK_LIB
      If this token and others are legitimate, please use m4_pattern_allow.
      See the Autoconf documentation.
configure.ac:59: error: possibly undefined macro: AC_MSG_ERROR
configure.ac:69: error: possibly undefined macro: AC_CHECK_HEADER
autoreconf: /usr/local/bin/autoconf failed with exit status: 1

These errors are normally caused by having the wrong version of one of the autotools, but I'm fairly certain I have the latest of each.
autoconf: 2.69; automake: 1.14; libtool: 2.4.2; gettext: 0.18.3

API to enable/disable features.

ohmd_enable / ohmd_disable ?

Things like config file loading and enable/disabling the neck model.

/usr/lib32/libGL.so: could not read symbols: File in wrong format

On Debian/unstable 64 bits using a NVIDIA GPU with the proprietary driver when compiling the OpenGL examples.

OpenGL example doesn't work in windows

Outputs a black window.

Windows dev package.

Including .dll and .lib file working in visual studio and mingw.

Running `simple` or `openglexample` Fails with HTC Vive

After compiling with

cmake . -DOPENHMD_DRIVER_HTC_VIVE=ON
make

and then running simple, I get the following error (on Arch Linux):

ArchBox:/home/george/OpenHMD/examples/simple
$ ./simple 
num devices: 3

device 0
  vendor:  HTC/Valve
  product: HTC Vive
  path:    0

device 1
  vendor:  OpenHMD
  product: External Device
  path:    (none)

device 2
  vendor:  OpenHMD
  product: Dummy Device
  path:    (none)

0bb4:2c87 0003:000e:00
opening
28de:2000 0003:000a:00
opening
28de:2000 0003:000a:01
manufacturer: 'HTC'
product: 'HTC Vive'
serial number: '205B38755548'
power on magic: 64
Getting feature report 16 to 39
got -1 bytes

The HTC Vive itself is dark (with a red light on).

EDIT: The same error occurs with openglexample (this time compiling with autotools):

$ cd examples/opengl
$ ./openglexample 
0bb4:2c87 0003:000e:00
opening
28de:2000 0003:000a:00
opening
28de:2000 0003:000a:01
manufacturer: 'HTC'
product: 'HTC Vive'
serial number: '205B38755548'
power on magic: 64
Getting feature report 16 to 39
got -1 bytes

The Vive light remains red with the screen off.

Add support for Oculus Rift DK2

As far as I know, the Developer's Kit 2 actually changed the APIs to the point where games designed for the original Dev Kit 1 won't work unless they've updated to the SDK version 0.4.
.
I'm assuming that a similar problem would exist for OpenHMD, since the Dev Kit 2 was released a few days after the last update to OpenHMD's source code.

Android Tracking Support

Support for using the native Android API sensors as input for OpenHMDs head tracking.

this maybe a cute bug.

when i init my hmd,I see the code in function ohmd_create_oculus_rift_drv, this situation in the similar function(ohmd_create_external_drvm/ohmd_create_android_drv/ohmd_create_dummy_drv)

    drv->get_device_list = get_device_list;//1
    drv->open_device = open_device;//2
    drv->ctx = ctx;//3
    drv->get_device_list = get_device_list;//4
    drv->open_device = open_device;//5
    drv->destroy = destroy_driver;//6

1 and 4 are the same.2and 5 are same,I think these are not big bug,but why?

CV1 Port ?

Project http://hg.sitedethib.com/libvr contains CV1 implementation, should be nice to have CV1 working with OpenHMD.

API to query hardware capabilities

Eg. if the HMD requires shader for output.

how to use OpenHMD to work with HTC vive?

Hello everybody

I am new to OpenHMD ,so someone can give to some information and tutotials.Thank you.

I am using OpenVR to get the rotation and position datas of HTC vive. However ,it forces me to install steamVR. I don't want to use steamVR. So I want to know how to use OpenHMD.Does it also need steamVR? Thank you.

HTC Vive driver is not implemented

Problems setting up OpenHMD - Windows 10

When I run cmake I get this:
`c:\OpenHMD>cmake . -G "Visual Studio 12 2013 Win64"
-- The C compiler identification is unknown
-- The CXX compiler identification is unknown
CMake Error at CMakeLists.txt:3 (project):
No CMAKE_C_COMPILER could be found.

CMake Error at CMakeLists.txt:3 (project):
No CMAKE_CXX_COMPILER could be found.

-- Configuring incomplete, errors occurred!
See also "C:/OpenHMD/CMakeFiles/CMakeOutput.log".
See also "C:/OpenHMD/CMakeFiles/CMakeError.log".`

What is my problem?

I have set System Variables to:
HIDAPI_LIBRARY = C:\hidapi-externals\zlib\include
HIDAPI_INCLUDE_DIR = C:\hidapi-externals\zlib\include

I running Windows 10
I have updated to Microsoft Visual Studio 2012 (KB2781514)

Essential Reality P5 Glove driver not implemented

Essential Reality's P5 Glove is very appropriate for VR environments.

Global configuration file

Akin to .asoundrc, .openalrc and SDL's environment variables, this configuration file will contain global settings relevant to the end user.

Some possible configuration entries

• Default HMD
• IPD
• Neck model settings
• Rift Cup (A, B, C)

Vulkan Support?

While there's a few items that could/would use OpenGL on Linux, etc. Vulkan seems to be the path forward.

It exposes Direct Mode rendering as part of the API.
It is what Valve and Croteam are using for SteamVR support on the Vive for Linux.

The shader code shouldn't change TOO much, I'd think and it'd get things moving even further forward with OpenHMD actually moving into a driver layer with Valve's actual stuff with the plugin work being done.

Incorporate magnetometer / compass drift-mitigation

this maybe a cute bug.

newbie question?

I'm trying to use OpenHMD and simple.c to understand the tracking information. My oculus is connected to my ubuntu 15.10 system via usb. the output of simple is only 0.0 coordinates. The vendor/device/path is OpenHMD/Dummy Device/path (none).

I enabled usb support across different users, althought i'm doing this via 'root' (please withhold judgement).

i'm not seeing the samples track any headset movement - they always registering 0.00 0.00 0.00 1.00

any help is appreciated.

Reset Tracking

Add a function to reset the tracking vectors to 0.

OS X Build not working (using DK2)

Working through the instructions in the README.md currently doesn't end up with a working build that the user can run the simple test app to see orientation quaternions from a connected DK2 device.

Out of the box following the instructions using either the autopen or cmake route to build, both fail.
The configure script doesn't find the hidapi library (I didn't dig further into this)
Using cmake it creates make files which include have -lrt which isn't available on OSX.

I tweaked the links.txt file that the makefile references and removed the -lrt, and both the library and simple app compile ok.

Upon trying to run simple it crashes with this reply:

num devices: 3

device 0
  vendor:  Oculus VR, Inc.
  product: Rift (DK2)
  path:    IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/HS01@14100000/Rift DK2@14100000/AppleUSB20Hub@14100000/AppleUSB20HubPort@14110000/Rift DK2@14110000/IOUSBHostInterface@0/IOUSBHostHIDDevice@14110000,0

device 1
  vendor:  OpenHMD
  product: External Device
  path:    (none)

device 2
  vendor:  OpenHMD
  product: Dummy Device
  path:    (none)

Abort trap: 6

The path for the DK2 looked very suspicious so I tried the version of hidapi from brew rather than the GitHub one the instructions specify, this produced a different path

device 0
  vendor:  Oculus VR, Inc.
  product: Rift (DK2)
  path: USB_2833_0021_14110000

But with the same resulting Abort trap: 6

I think there is some issue with the way OpenHMD is using whatever hidapi is returning for the device, and it is unable to open the device correctly and crashing out.