Monado

Monado OpenXR Runtime

Monado is an open-source tool that provides an OpenXR runtime environment for Linux (and Android) systems. These are the steps I took to get it compiled on an RHEL-based (and later a Ubuntu-based) Linux distributions.

Package Dependencies

Monado uses Vulkan for rendering, so the primary Vulkan packages must be installed. There are several others as well, many of which will already be installed in a typical Linux development system.

Note that in no case is it necessary to have the OpenXR-SDK installed when building or running Monado, though it does include the handy HelloXR (hello_xr) test program.

RHEL-based distro additional packages

These are the additional packages that I had to install (for RHEL-based distro):

• mesa-vulkan-devel.x86_64
• vulkan-loader-devel.x86_64
• vulkan-tools.x86_64 (Optional)
• hidapi-devel.x86_64
• systemd-devel.x86_64 (for the Debian/Ubuntu equivalent of libudev-dev)

• glslang (I had to compile this by hand)

As noted, there was no package for glslang, so I cloned it from:

• https://github.com/KhronosGroup/glslang

and used CMake to build and install it; and made a "module" file to load it.

Also note that for slightly older versions (before 2.30) of the shared object loader tool ("ldd") require a small code change, explained below in the build process.

Plus, there is a CMake configuration issue that I only encounter on my Rocky Linux system that needs to be worked around.

Finally, you probably will need to update some udev-rules to enable non-root access to VR devices. Ubuntu-based distributions have the xr-hardware package, but I have not found an equivalent for RHEL-based distros. (For my Rocky system, I add the file "69-Vrui-devices.rules" in /etc/udev/rules.d as available in the Vrui VR system.)

Debian/Ubuntu-based distro additional packages

For Debian, Ubuntu and related distros, the packages will have these names:

• mesa-vulkan-drivers
• libvulkan-dev
• vulkan-tools
• libhidapi-dev
• libudev-dev
• glslang-tools
• glslang-dev
• xr-hardware — this package adds new udev-rules that give users permission to access VR hardware

The full list of dependencies from a Debian/Ubuntu perspective are available at the Monado gitlab page:

• Monado Dependencies

Building Monado

Monado is available via git clone as:

% git clone https://gitlab.freedesktop.org/monado/monado.git

I set the CMAKE_BUILD_TYPE to Release, and also set CMAKE_INSTALL_PREFIX to a separate directory where I will have Monado installed. (I use the "Module" system, so I do not put installations in a mixed system directory, which makes it easier to work with multiple versions.)

Monado should then build cleanly with the standard make and make install operations (with the three exceptions explained below — look at those before building):

% mkdir monado/Build
% cd monado/Build
% cmake -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_INSTALL_PREFIX:PATH=<install-dir> <source-dir> 
% # In my case, I also have to add a pointer to the GLSLangValidator binary:
[...]
% make
[...]
% make install
[...]

Minor tweak to ensure SteamVR-Lighthouse build

If you plan to use the steamvr_lh driver for 6-DOF tracking based on the Lighthouse tracking system then there is one other step to take before running cmake. (NOTE that the steamvr_lh driver is based on using a closed-source shared-object file, but it currently does a far superior job of managing lighthouse position tracking.)

The CMake build configuration is set to look for the directory $HOME/.steam/root, and if found, will automatically build the SteamVR-Lighthouse driver code. Thus, if you want this enabled, make sure that directory exists. And since, when running with steamvr_lh there will be an expectation of a lighthouse configuration sub-directory, we might as well create that too:

% mkdir -p $HOME/.steam/root/config/lighthouse

Minor modification for systems with ldd version < 2.30

When compiling on a system that has a version of the ldd shared-object printer earlier than version 2.30 (which actually means your dynamic loader is older), then the following code change is required:

% cd monado; # Or whatever you named your cloned directory &mdash I append the date
% cp -p src/xrt/auxiliary/util/u_linux.c{,_orig}
% vi src/xrt/auxiliary/util/u_linux.c
[near the top, add:
  #if __GLIBC_MINOR__ < 30   // This assumes the Major version is "2"
  #include <sys/syscall.h>
  int gettid(void) { return (int)syscall(SYS_gettid); }
  #endif
]

Minor modification to the build files on Rocky/RHEL Linux

There is an issue with the build files produced by the CMake step. For a reason I do not yet understand, the link.txt files generated by CMake for each of the Monado executables are missing the inclusion of the C++ Filesystem library! This can be fixed by manually editing each link.txt file (after optionally saving the original file with _orig as a precaution):

% cp -p src/xrt/targets/service/CMakeFiles/monado-service.dir/link.txt{,_orig}
% cp -p src/xrt/targets/cli/CMakeFiles/cli.dir/link.txt{,_orig}
% cp -p src/xrt/targets/gui/CMakeFiles/gui.dir/link.txt{,_orig}
% cp -p src/xrt/targets/steamvr_drv/CMakeFiles/driver_monado.dir/link.txt{,_orig}
% vi src/xrt/targets/service/CMakeFiles/monado-service.dir/link.txt src/xrt/targets/cli/CMakeFiles/cli.dir/link.txt src/xrt/targets/gui/CMakeFiles/gui.dir/link.txt src/xrt/targets/steamvr_drv/CMakeFiles/driver_monado.dir/link.txt
[And for each of these files, add "-lstdc++fs" to the end of the line]

The build should now work.

Running the Monado OpenXR Runtime

Once Monado is built and installed, there are a handful of tools available in the bin directory. The tool that is the OpenXR runtime is:

% monado-service

The monado-service tool will then search for VR input devices, GPUs, and VR display devices. Messages will generally be reported regarding each of these searches.

In the general test case (i.e. prior to connecting an HMD), Monado will create a Dummy HMD as the default.

To quit monado, simply hit Enter in the shell in which it is run. (It is possible to setup Monado as a service, but running in a shell is the simple method.)

There are several environment variables that can be set which influence the operation of Monado. The list of those settings can be found on the Monado Getting Started page (envvars).

Before running monado-service, "permanent" configuration settings can be added to the file: $HOME/.config/monado/config_v0.json.

As mentioned above, I use the Environment Modules system to control which particular versions of various tools are currently enabled via the PATH and other system environment variables. So before running monado-service I first load the Monado module:

% module load monado
Monado version 20220223 loaded.
% monado-service
[...]

Running Monado with SteamVR-Lighthouse driver

When running monado-service with the expectation of making use of the SteamVR-Lighthouse library, two environment variables need to be set:

% export STEAMVR_LH_ENABLE=1
% export STEAMVR_PATH=<path to "drivers/lighthouse/bin/linux64/driver_lighthouse.so>

And as of this writing, the version of the driver_lighthouse.so file comes from the Steam package "SteamVR beta 2.8.2"Italic text, which has a file length of 6794512 bytes.

% chsum $STEAMVR_PATH/drivers/lighthouse/bin/linux64/driver_lighthouse.so
1955656289 6794512

To obtain the driver_lighthouse.so file, you will need a Steam account, and it might be possible to use the steamcmd command line tool to download the needed package — though I'm not entirely sure this is the correct syntax. (FYI, for the current version of Monado — February 2025 — you probably need the driver for "SteamVR beta 2.8.4".)

Steam>app_update 250820 -beta beta

OpenXR Applications

You can now run Applications compiled with the OpenXR SDK. To inform such applications of the presence of the Monado runtime, the XR_RUNTIME_JSON environment variable should be set to point to a JSON configurattion file (e.g. active_runtime.json). That file sets particular parameters of the runtime, such as where to find the libopenxr_monado.so shared-object file.

Running an OpenXR application will now appear in the Monado runtime rendering window:

% export XR_RUNTIME_JSON=/home/myhome/MonadoInstallDir/etc/xdg/openxr/1/active_runtime.json
% hello_xr -g OpenGL -ff hmd

Building OpenXR

I have a separate Wiki entry for OpenXR.

Obtaining OpenXR Applications

To my knowledge, there are not (yet) many widely available OpenXR applications available for Linux. Here are some applications I'm aware of:

• HelloXR — a test program provided by the OpenXR-SDK
• Khronos OpenXR Tutorial
• VTK
• ParaView
• Blender — I have not yet tried this
• Godot game engine — I have not yet tried this
• I also am in the process of porting my FreeVR Tutorial suite to OpenXR
• Plus I am in the process of porting my ANARI-FreeVR examples (not yet published) to work directly with OpenXR

Caveats

• As mentioned in the "Build" section, the open-source LibSurvive driver for Monado is of limited functionality — the tracking jumps around too much to be usable (at least with my Lighthouse configuration). So now that the new steamvr_lh direct-Lighthouse driver is now available, I highly recommend building and running with this option.
• I have attempted to run Monado with the Wayland Linux compositor on my Linux Mint system, however I have yet to actually get it to work. So presently I always run monado-service with X11-windows — which to-date is still my preferred Linux environment.
• In some cases, the first Vulkan driver may not work. There are presently two solutions to this: 1) use the "Vulkan2" driver; or 2) Use the Vulkan-Layers layer from Collabora.

See Also

• Monado Freedesktop Gitlab — Monado itself
  • Monado Freedesktop Gitlab top level
• Monado Getting Started
• Introducing Monado Blog post
  • Blog: Monado SLAM datasets now available
  • Blog: Welcoming the libsurvive project
• Writing a new Monado driver

Alternative variants of Monado (for Streaming)

• WiVRn — stream-to-Quest Monado-based OpenXR runtime
• Electric Maple — stream-to-Quest Monado-based OpenXR runtime (partially works)
• ALVR — Stream VR applications from your PC to your headset via Wi-Fi