ViveLighthouse

The Vive Lighthouse is a consumer VR position tracking system sold by HTC, and used by several VR HMDs (headsets), such as the original Vive, the Vive Pro, and the Valve Index. The Lighthouse tracking system provides amazing tracking capabilities at a consumer price point and was one of the products that helped usher in the modern era of VR for everyone.

One issue with Lighthouse tracking is that it has limited support for Linux and MacOS. (Not no support, mind you, which is good, but it's certainly not easy to setup Lighthouse systems on Linux.) Indeed, to date, there is only one public source with sufficient information to setup a working Lighthouse system running on Linux.

The system that best enables Lighthouse tracking on Linux is the Vrui VR Integration library developed at the University of California, Davis, by Oliver Kreylos.

The other option which has made great strides of late (2023) is the LibSurvive library, which has reverse engineered the fundamentals of the Lighthouse system. LibSurvive is open-source and can be built for Linux, MS-Windows, any maybe MacOS. As of this writing, it is not quite as robust as accessing the SteamVR Lighthouse library directly (as done with Vrui), but it generally works.

Oliver explains how to setup the Vive (and Linux itself) in a series of blog posts on his "Doc OK" blog. The first of the two listed blog entries focusses more on setting up the Lighthouses, and the second blog entry focuses mostly on connecting the HMD display to Linux.

Before we begin though, here are Oliver's key blog entries if you want to go directly to the source:

• http://doc-ok.org/?p=1737 — Set-up Instructions for Vrui with HTC Vive Head-mounted Display
  • via the Wayback Machine
• http://doc-ok.org/?p=1763 — An Illustrated Guide to Connecting an HTC Vive VR Headset to Linux Mint 19 (“Tara”)
  • via the Wayback Machine

Distilled Installation Instructions

With the help of Scott Wittenburg of Kitware, we're creating a set of basic instructions for how to make Vive tracking work on Linux. These are derived from Oliver Kreylos' instructions in the blog posts above, but hopefully more distilled to the essentials of how to make Vive Lighthouse-based tracking work using Vrui with the minimal amount of effort possible.

1. Install the needed Vive driver and configuration files that the Vrui VRDeviceDaemon will require
   • the driver_lighthouse.so shared object file
   • the matching libudev.so user-space device manager

   (Thus it might be possible to avoid this step if we have those files, and inform Vrui's build process of that — which at the moment means editing the Vrui makefile.)

   1. Install the Valve Steam package on your system
   2. Run Steam
      • It will likely update itself
   3. Install SteamVR through the Steam interface

   -----------------

2. Build Vrui

   NOTE: presently using Vrui 6.0-001 (though we have begun experimenting with Vrui 8.0-002)

   • Also: for now we often force the Vive features to be compiled by forcibly setting:

   SYSTEM_HAVE_OPENVR = 1

   after the lines that set it based on directory structures.

   NOTE: We really only need VRDeviceDaemon, but the Vrui build system will build everything

   1. Edit to enable a no-HMD mode:
      • Edit: VRDeviceDaemon/VRDevices/OpenVRHost.cpp

      -: maxNumDevices[HMD]=1;

      +: maxNumDevices[HMD]=configFile.retrieveValue<unsigned int>("./maxNumHMDs",0); // default to zero HMDs

   2. Edit makefile to set your installation directory
   3. Build Vrui with

      % make

      • Check the configuration output at the top for the message indicating that the SteamVR requirements are met

      % make install

   -----------------

   NOTE: Some of this assumes you are doing CAVE/Fishtank-style VR (i.e. not using an HMD)

3. Edit the RunViveTracker.sh script to work in no-HMD mode
   1. Copy the existing script to a new RunViveTrackerNoHMD.sh
   2. Edit RunViveTrackerNoHMD.sh
      • Hardcode VIVE_TYPE=Vive
      • Remove (comment out) all lines dealing with ViveOn or ViveOff

      (including all the trap commands)

   -----------------

4. Configure VRDeviceDaemon
   1. Edit VRDevices.cfg
      • NOTE: Change to use the number of tracked objects (shown here is the minimum)
      • NOTE: Vive Pucks are referred to as "Trackers" here

      set maxNumControllers 0

      set maxNumTrackers 1

      optionally set printLogMessages true

   -----------------

5. Ensure there is a "udev" rule for the HTC Vive:
   1. a) Create a new file in the "rules.d" subdirectory:

      % sudo edit /lib/udev/rules.d/60-HTC-Vive-perms.rules

      add: KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="28de", ATTRS{idProduct}=="2101", MODE="0660", TAG+="uaccess"

   OR

   1. b) Copy into place the udev rules provided in the Vrui distribution:

      % sudo cp -p Vrui-<version>/Share/69-3d-inputdevices-acl.rules /etc/udev/rules.d/.

Distilled Running Instructions

1. Ensure the correct driver_lighthouse.so file can be found by RunViveTrackerNoHMD.sh:
   • By default, driver_lighthouse.so will be sought in ~/.steam/steam/steamapps/common/SteamVR/drivers/lighthouse/bin/linux64/
   • By default, libudev.so will be sought in ~/.steam/steam/ubuntu12_32/steam-runtime/amd64/lib/x86_64-linux-gnu/
2. Turn on your Lighthouse base stations

   ASIDE: I spent 2 hours one night at INL not knowing they were off

3. Follow Vive tracker (aka "puck") instructions to sync/pair it
   1. Plug in the dongle
   2. Press the power button to turn it on (LED will probably be blue)
   3. Press and hold the power button until it blinks and the LED turns green
4. Run the RunViveTrackerNoHMD.sh script
   • NOTE: watch the output for messages indicating inability to communicate with a USB device

     If you do get these message look for the Vendor ID and Product ID numbers for the device

     (For Scott the numbers were: vid=28de and pid=2101.)

     • To resolve that issue check back to the "udev" rules setup in the previous section

   % RunViveTrackerNoHMD.sh

   • NOTE: This will result in several messages, some of which are important
     • ignore: ioctl (SFEATURE): Broken pipe (these are not important)
     • informative:
       VRDeviceManager: Managing 2 trackers, 12 buttons, 6 valuators
VRDeviceManager: Managing 2 virtual devices
VRDeviceManager: Initializing 1 device driver modules

5. Confirm the operation using the FreeVR vruiddtest tool

   % vruiddtest -screen

Hardware Limitations

It's not obvious to the general user, but the Vive (and probably also true for the Valve Index) HMDs are what provides access to the two controllers. Pucks can be paired instead of controllers, but only two tracked objects (in addition to the HMD itself) can be connected to the HMD. Additional devices require a Vive Puck Watchman, which is a small form-factor USB dongle, and each Watchman can connect to either one Vive Puck or one Vive Controller.

The company Tundra Labs sells a Tundra Tracker puck and dongles, with dongles that can handle 3, 5 and 7 devices.

Compatible Versions

Determining how to interface with the Lighthouse system is made more difficult because Valve routinely changes the internal API to the driver_lighthouse.so dynamically loadable shared-object file. And the changes to the interface are not made widely available. This problem is exacerbated by the fact that there is no quick way to discern what version of the API an individual file might be accessed through.

Thus I am creating a table listing known (by me) versions of the driver_lighthouse.so file based on their file system. (As most people needing this information will be running on linux64 operating systems, I've limited the table to just those files.)

Mapping driver_lighthouse.so to Vrui versions

Vrui Version	SteamVR version	linux64/driver_lighthouse.so size
??	??	2957781 bytes
4.6-003	1.2.6	3409653 bytes
4.6-005	??	3544108 bytes
??	??	3615672 bytes
??	1.7.6	3809497 bytes
6.0	??	4035190 bytes
8.0	1.15.19	??

See Also (other attempts for Lighthouse on Linux)

Note that some of these are defunct efforts, but they may still have nuggets of valuable information.

• Libsurvive's Github Repo (Libsurvive generally works)
• OSVR's Vive Repo
  • OSVR Vive Configuration doc
• Vive Libre interface to OSVR