FOVE on Linux

Installation

*Please note that Ubuntu 20.04 is required (specs are listed below)

TLDR;

wget https://repos.fove-inc.com/fove_repos.pub && sudo apt-key add fove_repos.pub && sudo apt-key add fove_repos.pub && echo "deb [arch=amd64] https://repos.fove-inc.com/ fove-focal main" | sudo tee /etc/apt/sources.list.d/fove-focal.list && sudo apt update && sudo apt install fove-runtime fove-client-dev

 

Detailed Instructions

We distribute our Linux builds via Apt. First, you need to add FOVE's GPG public key. We self sign our Linux packages.

wget https://repos.fove-inc.com/fove_repos.pub
sudo apt-key add fove_repos.pub

Rumor has it that apt-key is deprecated. But luckily, it still works! Also, if you don't have wget, well, you should apt get it.

Next step would be to add our repo to your sources list, and then, update apt's cache.

echo "deb [arch=amd64] https://repos.fove-inc.com/ fove-focal main" | sudo tee /etc/apt/sources.list.d/fove-focal.list
sudo apt update

From there, you can now see that there are some fove packages available to you:

$ apt search fove

fove-client-dev/fove-focal 1.0-1 amd64
FOVE Development Package

fove-runtime/fove-focal,now 1.0-1 amd64
FOVE Runtime Package

fove-runtime is the package that contains the VR platform, including the compositor, drivers, etc.

fove-client-dev contains the C/C++ SDK, with headers and a dynamic library.

 

The final step would be to install the desired packages

sudo apt install fove-runtime fove-client-dev

 

Usage

TLDR;

As a daemon:

systemctl --user start fove-service.service

Run directly:

fove-service

Once your headset is plugged in, you should see a starry sky in the headset and you're ready to start building or using FOVE content.

 

Detailed Instructions

Make sure to plug in your FOVE correctly.

 

 

ProTip: If you only need 3-DOF tracking, you can forgo the position tracking camera and the USB 2.0 headset cable.

ProTip #2: The headset's USB2 cable is power only so it can be plugged into another computer or a wall charger.

 

The fove-service is the main daemon that handles the FOVE hardware and dealing with clients. It also will automatically launch and unlaunch fove-compositor (the application that renders to the HMD screen), and fove-companion (the application that draws the calibration sequence) on demand. It shuts things down as needed to be as minimal as possible.

 

When running fove-service directly, it will launch the compositor and companion via fork() and exec() and their output will all go to the same console. When fove-service is launched via our systemd service units, will will launch the other apps indirectly via systemd. This is useful as you can use systemctl and journalctl to monitor the status and check the logs of each executable separately. For example:

$ systemctl --user status fove-compositor
● fove-compositor.service - Fove Compositor
Loaded: loaded (/usr/lib/systemd/user/fove-compositor.service; static; vendor preset: enabled)
Active: active (running) since Wed 2021-01-20 07:18:34 UTC; 6h ago
Main PID: 509 (fove-compositor)
CGroup: /user.slice/user-1001.slice/user@1001.service/fove-compositor.service
└─509 /usr/bin/fove-compositor

Jan 20 13:48:39 FOVE2050013 fove-compositor[509]: Compositor: 351 frames in 5.014108 seconds: 70 fps
... [more logs] ...

 

More info

Your system has some shiny new fove executables, but what do they do? We present to you, in alphabetical order, the following useful information:

fove-cli -> This is a command line tool to interact with the FOVE system. For example: fove et calibration start to start eye tracking calibration. There's some help menus within.

fove-companion -> This handles drawing calibration and some auxiliary tasks. It's handled automatically so you don't need to call it directly.

fove-compositor -> This is the fove compositor. It connects to the screen, takes buffers from client applications, handles distortion, time warp, and well, compositing, and then draws to the screen. This is also handled automatically, so you don't need to call it directly.

fove-debug-tool -> This is our main gui tool, you can use this to start and stop things, etc.

fove-mirror-client -> This application displays what's in the headset to the monitor.

fove-service -> This is the main service that talks to clients, talks to hardware, runs the eye tracker, and generally, handles things.

fove-systemd-helper -> For systemd interoperation, don't need to worry about this much.

 

The Debug Tool

Most of the important things are displayed in the debug tool, which you can launch by invoking the executable fove-debug-tool. You can see the headset position/orientation, state of eye tracking, calibration buttons, and many other things here. You can also expand the image panes to see the eye and position tracking cameras.

 

Developing Content

C/C++ & OpenGL/Vulkan

You can build apps directly in C/C++. Please see our OpenGL example here:

https://github.com/FoveHMD/FoveCppSample

A Vulkan example is planned but does not exist yet.

 

Unreal

Our Unreal plugin supports Linux. Please get it on GitHub here:

https://github.com/jbfove/UnrealEngine

Important: You will see a 404 unless logged into a GitHub account connected to an Unreal account. This is for license reasons.

 

Unity

Unity support is coming soon!

 

Supported Platforms

OS: Ubuntu Desktop 20.04

This is the only platform we support. There's nothing specific to Ubuntu 20.04 in the code, but simply that we build the binaries from a 20.04 dockerfile, and thus all the dependencies are specific to Ubuntu 20.04.

If you can install all the dependencies listed by ldd `which fove-service` and edit the ELF executable to point to the paths as they are on your system, it will probably work fine on any distro, but that's on you.

 

GPU: NVIDIA GPU with binary driver

Again, this is the only one we are currently testing. Realistically, it may be the only one that can meet the demands of VR currently. However, we hope to test more drivers in the future.

 

CPU Architecture: AMD64

We support arm64/aarch64 for NVIDIA Jetson Xavier TX2 in the enterprise edition. However, the desktop version only supports AMD64 for the time being.

We do not provide any 32 bit support on any platform. Anything old enough to still be 32 bit is probably not going to work well with VR.

 

Software Ecosystem: X11 + Vulkan (Compositor) + Vulkan or OpenGL (Clients)

We hope to add Wayland support soon, but currently we are using xcb/xlib and some X11 specific things in Vulkan such as vkAcquireXlibDisplayEXT.

 

Our compositor can also run using DRM + EGLstreams (NVIDIA specific, but we listed that already!). This avoids the need for X11 but is generally not recommended except for very custom setups like Kiosks.

 

ProTip: If you do need support for another platform, we might be able to make that happen. Please contact us. We can't promise support for anything, but we will do our best to accommodate.

 

Backwards Compatibility

Currently, we are not committing to backwards compatibility on Linux yet. This means a Linux Client using SDK 1.0 may not work against v1.1 of the Service.

 

Having maintained backcompat on Windows for years, we've learned that there's some pain in handling this if not set up properly. So once we clean up a few problem areas, we'll then declare backwards compatibility support for Linux from that point on.

 

Logging

All FOVE executables share the same logging system which has 3 levels: Debug, Warning, and Error. Third party clients can also write to it with the fove_logText function call.

 

IPC logging via fove-service

All logs go via IPC mechanisms to the fove-service which writes them to the log file and can resend them out to other programs like fove-debug-tool's log viewer and fove-cli log listen's cli log viewer. If the service is not running, then the IPC based logs will not go anywhere, but when running the service will listen for logs from various clients. Thus log file thus contains interspersed logs from various executables.

~/.config/fove/Logs/FoveLog.log

This log file is replaced each time the fove-service starts. Please be careful.

 

stdout/stderr

The LOG_WRITE_TO_STDOUT configuration var controls whether we also write logs to stdout/stderr. This is enabled by default for most applications, but disabled by default for some like fove-cli (since we don't want to pollute the stdout of a CLI interface), and the fove client library (since we don't want to pollute the stdout of thirdparty programs). You can set this variable via config, please read below.

 

When LOG_WRITE_TO_STDOUT  is enabled, Debug logs go to stdout, and Warning/Error logs go to stderr. We would like to make this more configurable in the future.

 

Writing to stdout/stderr ensures that, even when the IPC logging via the service is not running or otherwise working, you can still receive logs from FOVE. It also means that you can integrate FOVE with standard Unix tools like journald logging system without any custom setup.

 

[Since v1.0.2] Colorization of stdout via escape sequences is enabled automatically when stdout is a tty, checked via the standard isatty function. You can force it on by setting LOG_STDOUT_COLOR_MODE to 1, or set it to 2 to force disable it. The escape sequences (and thus colors) can be changed by setting any sequence to LOG_STDOUT_COLOR_X (where X is either D W or E for the different log levels) and LOG_STDOUT_COLOR_RESTORE is written after each line.

Configuration

Each FOVE executable has various parameters that are configurable. You can use the fove-cli program to manipulate the config.

fove-cli help config   -> Displays all config related options
fove-cli config cat    -> Prints all config values that are not equal to the default
fove-cli config clear  -> Clears all config values in the config file (does not affect env vars)
fove-cli config edit   -> Opens the config file in an editor (using xdg-open on Linux)
fove-cli config get    -> Fetches a single config value
fove-cli config keys   -> Lists every configuration key for this platform & version
fove-cli config path   -> Prints the path to the config file
fove-cli config set    -> Sets a single config value in the config file (does not affect env vars)

We do not document all configuration values. This list is platform and version dependent. Most of them are internal implementation details and thus not really of concern.

FOVE executables log the configuration upon launch, and upon detected change to the config file, so you can debug things that way.

 

Config File

The config file is a simple ini-style KEY=VALUE format. Lines starting with # are comment but sometimes the get overwritten upon save, so we don't recommend using comments.

~/.config/fove/FoveVR.config

Because this config is in the home folder, it will be in a different location for different users. So if you run the FOVE service as root, but the compositor under a user, they will read different configs. Please beware of this.

The config file is monitored periodically for changes, so some configuration keys can take effect while the program is running. The config contents, upon first read and upon change, are always logged by each executable to the log, so you can debug issues.

 

Config via Environment Variables

For non-windows platforms, environment variables can be used to override values from the config file. The environment vars are prefixed with FOVE_. The following example sets a localization override for Japanese, then launches the Debug Tool in Japanese without affecting any other programs.

FOVE_LOC_LANGUAGE_OVERRIDE=ja fove-debug-tool

This enables the following things:

• You can set different values for the same config option for different programs. This is done by setting their environment before launching them. Otherwise, they would read from the same config file (assuming they're running under the same user), and thus have the same value.
• You can do one-time-only config sets easily using bash, without having to reset afterwards like the above example
• You can effectively shift responsibility for configuration to any other tools that can set environment variables, including systemd service units and shell scripts.

fove-cli config get/cat will list the values as seen from the environment if they exist or the config file, but the setters like set and clear only set the config file, and thus may not make a noticeable change if overridden by environment. Please be careful about this.

 

Users & Permissions

The Windows version runs the FOVE service as a privileged service, and everything else under the current graphical user session. Regardless of which user they run under, they all share the same C:/ProgramData/FOVE folder for things like the config file.

 

On Linux, we've designed it so everything runs under and within a normal user. So our general data folder is at $HOME/.config/fove. This includes not just the config file but also the unix sockets that we use for IPC. This means that, while no special permissions are needed, you need to make sure all fove executables, including third party application using the client library, run under the same user. In particular, you don't need to and shouldn't use things like sudo with FOVE.

If you have a good reason to run different binaries under different users, please let us know, support for this could be added.

 

The one thing that requires permissions by default is access to the USB HID device to talk to the headset. We ship a udev rules file at /etc/udev/rules.d/90-fove.rules that allows any user to open the FOVE device. If this file is not present, then fove-service will not be able to access the headset, unless running under root, which like we said, you shouldn't do.

 

Troubleshooting

Issue	Explanation / Solution / Workaround
Cannot calibrate. Running fove-companion gives: fove-companion: error while loading shared libraries: libopenvr_api.so: cannot open shared object file: No such file or directory	fove-companion is the calibration app. Currently it has a dependency on the OpenVR libraries to support calibration when SteamVR is running instead of the FOVE Compositor. This dependency is not currently (as of v1.0) made explicit in our package. You can manually install openvr-api from apt to get it working. In a future version we will either load that dependency dynamically or at least make the dependency explicit in our package so that apt installs it automatically.
Data is coming in from the headset, but nothing is showing on the HMD screen.   FOVE Log gives something like: VulkanBackend: failed to create Xlib HMD backendVulkanBackend: no displays have been found	This happens when the screen cannot be found. Make sure:   1. The headset's HDMI cable is plugged in to the NVIDIA graphics card, without adapters. (Active type HDMI->DisplayPort adapters usually work, but it's safer without, esp. for troubleshooting). In particular, if you motherboard has a HDMI port, that is not the place to plug in the FOVE.   2. That you are not using an Optimus (dual-GPU) laptop. While these do usually work on Windows with FOVE (assuming the HDMI port is hardwired to the NVIDIA card on the mainboard, and apps are set to open on the right card), we've had additional trouble with this on Linux and are not supporting it right now.   3. That you are running the official NVIDIA binary drivers and not the open source drivers (nouveau). We have not tested the open source drivers.   4. That you are running X11, not wayland (XWayland is not yet tested), or have booted to multi-user mode directly before running FOVE (in which case the compositor will use libdrm to draw to the headset).   If all of these are valid, please post to our developer forum or email us, including with your log.
FOVE HMD shows up as a monitor (eg. in gnome).	This indicates that you are not using the NVIDIA binary driver. Please see above item.   While not recommended, you can run in extended mode with: fove-cli config set COMPOSITOR_DISPLAY_MODE 1   You may have to change the rotation/orientation of the FOVE HMD relative to your monitor a bit before it correctly launches the compositor window on the right screen (you can also use hotkeys to move the window between screens). X exposes all screens as a virtual shared screen, so it's hard for our software to locate which part is the portion representing the FOVE HMD screen.

 

We are considering Linux support as beta. There are some rough edges. Please get in touch with any problems you have as we are looking to actively resolve things in the priority that our customers need.