VRPN

VRPN library & protocol

VRPN is a library (API) and communications protocol developed at the University of North Carolina's Virtual Reality research group. It provides a cross-platform/cross-device mechanism to link peripherals over various types (mostly related to VR) with applications. It works across the network, so there can be a host that interfaces with the peripheral and another computer (or computers) that read that data to provide the interaction with the virtual reality rendering software. (NOTE: the link at the beginning of this paragraph has some worthwhile details, but is somewhat out of date -- see the GitHub repo version below for the up-to-date version.)

Repositories

• VRPN on Github: VRPN has transitioned to the GitHub repository.
• VRPN at UNC: This is the old UNC ftp repository.

Usage

VRPN operates in a client/server model. The server resides on the host computer with the direct connections to the peripheral devices. The server is configured to read one or more devices, in some cases transmogrify the data, and then listen for client connections, serving the data to connected clients.

The Server

The configuration file contains an ASCII list of devices for the server to gather data from, including information of serial ports, or device files, etc, along with possible configuration options. By default, VRPN will listen on port 3883.

The general procedure for running the VRPN server is to edit the "vrpn.conf" file to uncomment the options needed for the particular input devices handled by that server and then either run the server with no arguments if the configuration file can be found in the default location, or to use the "-f" option to specify a particular configuration. For example:

% vrpn_server -f vrpn_dtrack.conf

The Client

In most cases, the client will be a particular VR application that has been compiled with the VRPN client library. This can include anything from individual VR applications to modules that are included within another system, such as the Unity game engine.

Test Clients

Typically, as a system is being configured, the administrator will want to confirm correct operation of the server, including correct reading of the data from the inputs themselves. For this, there are test clients, which read data from the server, and then display that data in a way that allows the VR system administrator to confirm that the values are as expected. The VRPN package of course includes such a test program, but there are third party solutions as well, including FreeVR.

VRPN's test clients

VRPN provides a handful of programs that serve as test clients, providing different aspects of information from the VRPN server. The most interesting of these are:

• vrpn_print_messages
• vrpn_print_devices
• vrpn_orientation
• vrpn_print_performance

VRPN's vrpn_print_messages

When the user is not aware of what messages are being provided by a VRPN server, then the vrpn_print_messages tool is useful for seeing what messages are being sent, and thus what input devices are active on the server.

% vrpn_print_messages <vrpnhost>

VRPN's vrpn_print_devices

The most commonly used test client program that is provided with the VRPN package for observing the data from a VRPN server is: vrpn_print_devices. One thing to note is that the user must already know the name of the device to read from a server in order to request the data. Also, while the UDP protocol is typically used for it's quality of lower-latency, TCP is sometimes preferred, for example to ensure that none of the data values are skipped.

Here's an example of reading data from a DTrack device on the machine vrpnhost:

% vrpn_print_devices DTrack@tcp://vrpnhost

The data will then stream to the terminal window.

VRPN's vrpn_orientation

For analyzing the quality of the orientation component of a position tracker input, the vrpn_orientation tool is very handy in that it shows a colored cube rotate based on the quaternion component of a position tracker input.

The rendering of the cube is done with OpenGL in a Glut window.

% vrpn_orientation SpinAE@tcp:127.0.0.1

VRPN's vrpn_print_performance

To analyze the update rate of an input device, the vrpn_print_performance tool outputs the number of data packets received in 1 second intervals for the given input device. This test client can handle multiple input requests:

% vrpn_print_performance SpinAE@tcp:127.0.0.1 SpinAz@tcp:127.0.0.1

Different input types can be disabled by preceding the input-specifier with the options: -notracker[sic], --nobutton, and --noanalog.

The reporting interval can be changed with the --reportinterval <seconds>.

FreeVR's vrpntest

The FreeVR VR integration library also provides a sample client program that is useful for confirming the working operation of a VRPN server — vrpntest. The vrpntest program combines many of the features available individually in the VRPN test client examples. For instance, unlike the VRPN vrpn_print_devices, vrpntest does not require foreknowledge of what devices are provided by a server, but will request a full list of all known devices, and report the inputs from all of them.

By default vrpntest will read from a VRPN server on the local system (localhost), but an alternate hostname can be provided. Also, vrpntest can output in a curses-style full-terminal layout with an enhanced represenation of position trackers and valuator inputs with the -screen option:

% vrpntest vrpnhost

% vrpntest -screen vrpnhost

The VRPN Protocol

...

See Also

• VRPN's Wikipedia entry