search

risa2000 / hmdq

HMDQ Tools - the tools for VR headsets and other hardware introspection
BSD 3-Clause "New" or "Revised" License
38 stars 3 forks source link
hardware-introspection openvr vr vr-headset

readme

hmdq hmdv

HMDQ Tools

HMDQ Tools is a set of two command line tools for VR headsets and other hardware introspection with support for both OpenVR and Oculus runtimes. The tools are also used to collect the data for and build the HMD Geometry Database.

hmdq

is a main tool, which connects to a VR subsystem and collects all available data about the connected devices (tracked devices in OpenVR world, headsets, trackers and controllers in Oculus world).

It can either display the info in the console, or save all the collected information plus some additional calculated data to a file in JSON format.

One needs to have either OpenVR or Oculus runtime plus the corresponding hardware installed and connected to use the tool.

hmdv

is a complementary tool, whose only purpose is to process the data files created by hmdq and display them in a human friendly way.

Both tools use very similar command line interface. The only (major) difference is that hmdq reads the data it shows (and stores) from actual VR runtime, while hmdv reads the data from already stored file. The following paragraphs address both tools, unless it is explicitly specified otherwise.

Installation

Get the latest binary ZIP from releases and unzip it wherever you want to run it. The package should contain both hmdq and hmdv tools, this README file, LICENSE file, OpenVR API JSON file and some additional files to ease the use.

Operation

Since both tools are command line tools, it is better to run them from Windows console or any terminal (window) which supports standard I/O.

When the tools run the first time, they create a configuration file <tool_name>.conf.json in the same directory.

Another file which is necessary (and is present in the archive) is OpenVR API description file (openvr_api.json). This file can be updated independently of HMDQ tools.

Commands

help

Shows all the commands and options with short descriptions.

geom

Displays the headset geometry which is normally advertised by VR subsystem to the application. It includes:

Additionally to that, it also shows:

Example (excerpt):

Total FOV:
    horizontal: 108.77 deg
    vertical:   111.48 deg
    diagonal:   113.18 deg
    overlap:     93.45 deg

View geometry:
    left view rotation:     0.0 deg
    right view rotation:    0.0 deg
    reported IPD:           63.0 mm

props

Prints out all different properties for all currently detected devices. For OpenVR it includes not only the headset and the controllers, but also the lighthouses and the additional (not lighthouse tracked) devices as the gamepads. The number of properties shown depends on the verbosity level specified by the user, which, by default, is set to 0.

Example (excerpt):

Device enumeration:
    Found dev: id=0, class=1, name=HMD
    Found dev: id=1, class=4, name=TrackingReference
    Found dev: id=2, class=4, name=TrackingReference

[0:HMD]
    1000 : TrackingSystemName = "lighthouse"
    1001 : ModelNumber = "Vive. MV"
    1002 : SerialNumber = "anon@1B02287EBB399418DC264E14"
    1003 : RenderModelName = "generic_hmd"
    1004 : WillDriftInYaw = false
    1005 : ManufacturerName = "HTC"
    1006 : TrackingFirmwareVersion = "1462663157 steamservices@firmware-win32 2016-05-08 FPGA 262(1.6/0/0) BL 0"
    1007 : HardwareRevision = "product 128 rev 2.1.0 lot 2000/0/0 0"
    1008 : AllWirelessDongleDescriptions = "anon@E0274499D83512E548FB4966"
    2001 : SecondsFromVsyncToPhotons = 0.0111111
    2002 : DisplayFrequency = 90

version

Shows the tool version info plus some additional information about the build and the used libraries.

verify (only in hmdv)

Verifies the data file checksum.

all (default)

Processes both geom and props. This is the default command.

Options

--api_json <filename>

Allows specifying a custom/different/new JSON file with OpenVR API definitions. Normally, you should not need that. The one included comes directly from OpenVR repository.

You can update this file independently from the tools to let them recognize new properties (if there were any).

--out_json <filename>

When specified, all the information collected by the tool (not only what is actually displayed in the console, but all possible retrievable information), plus some additional information calculated by the tool in the process (e.g. different FOV points, HAM mesh optimized layout, etc.) is stored in the specified file in JSON format.

This file is mostly useful for additional processing, evaluation, and future reference.

NOTE: The amount of the information stored in the file, is not controlled by the verbosity level. Every time the file is created, all the available information plus the additionally computed data are stored in the file. The reason for that is to have a well defined set of data, which is guaranteed to be present.

When this option is used with hmdv it just rewrites the information from the input file to the output file. It is useful to anonymize the input file or to update the data content to the latest version (see the Changelog file for the details).

-v <level>, --verb <level>

Verbosity level of the output (to the console). There are five levels defined:

The levels can be redefined in the configuration file. The values listed above are the default ones.

-n, --anonymize

If specified, it will anonymize values of some "sensitive" properties defined in the configuration file. Others can be added to the config file if needed.

The anonymization happens in both the console output and in the output JSON file.

This could be useful when sharing the output data publicly, without disclosing the unique identifiers.

The anonymized values are computed by using the secure hash function Blake2 set with 96-bit wide output. The hash is computed over three properties: manufacturer name (#1005 Prop_ManufacturerName_String in OpenVR), concatenated with model name (#1001 Prop_ModelNumber_String in OpenVR), and finally with the incriminated value to anonymize. The manufacturer and model names are used to pre-seed the hash with distinct values, so the same serial numbers from different manufacturers will not anonymize into the same values.

--openvr

Will only show data collected from OpenVR runtime (if one is present and any hardware is connected).

--oculus

Will only show data collected from Oculus runtime (if one is present and a headset is connected).

Both options are meant to only control the program output, but the data are logged and saved into the data file (if requested by --out_json option) for both subsystems.

--ovr_max_fov

Shows also data for Oculus headset Maximum FOV.

Configuration

The configuration file <tool_name>.conf.json is always created with the default values, and can be changed later by the user. The tool will not "touch" the configuration file as long as it exists and only create a new one if none is present.

It has a consequence when updating the tool to the newer version. It may happen that the new version of the tool introduces new config values, which are not present in the old configuration file, or remove some old ones. When it happens the tool will refuse to run and ask the user to manually update the configuration file.

One way how to do it is letting the tool to create a new (default) config file (e.g. by renaming the old one) and then manually copy any custom setting from the old config to the new one.

Configuration options:

Theory behind the FOV calculations

While listing the properties of (tracked) devices is a mundane task, the rendered FOV calculation is an interesting topic which deserves its own space and is in detail dissected here VR headset rendered FOV calculation.

Building the tool from the source code

The tools are being developed as a fun project, so they are probably overdone on many levels, but should never the less be buildable.

Required external libraries

On top of that you will also need cmake version 3.15 or higher.

Optional external libraries

Building

Building with CMake

The project is developed as a CMake project in Visual Studio 2022, while using ninja as a build driver. The binaries can be successfully built by native MSVC compiler cl or by LLVM clang-cl (Clang drop in replacement for MSVC compiler).

To have the automatic versioning working correctly, CMake scripts expect the build to happen in a locally cloned git repository.

Building with Conan

This is a preferred and also the easiest way. The local conan/packages folder contains the conan recipes and build scripts for packages which are not in conan-center (or have older/incompatible versions there). In order to be able to initialize the conan build environment you need to run the batch files in the corresponding subfolders first to build and install the missing packages into the local conan cache.

Then you need to run conan/conan_install_all.cmd batch to build and install the remaining packages. The conan files are installed into specific directories, where the Visual Studio CMake integration (using CMakeSettings.json) expects them. After that you can use VS IDE to build the binaries as you would for any other CMake project.

The only dependency which does not have a public or local conan package or recipe is LibOVR as it needs to be downloaded from the Oculus website and set up manually, by setting OVR_SDK environment variable to the library root folder (e.g. OVR_SDK=C:\ovr_sdk_win_32.0.0).