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 of 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 attribute 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

In modern VRPN distributions, the file "Format_Of_Protocol.txt" contains the basic description of the VRPN protocol. (In the past the file was named simply "format" which made it near-impossible to find if you didn't already know the name of the file!) The contents of that file are primarily about the general header format and the opening handshake sequence, but really say nothing about the messages containing actual input/tracking data between the client and the server, so the rest of the protocol was left as "an exercise for the reader."

The information in this Wiki page is a combination of information from that protocol description file and empirical exploration (which might have included exploring the source code as well).

The VRPN handshake connection sequence

Server starts and opens a TCP socket for listening on port 3883 (by default)
VRPN client connects to TCP port 3883
Introductory messages ("cookies") are exchanged (basically simultaneously):
- Server sends a "cookie" with it's version number and logging status
- Client sends a "cookie" with it's version number and logging status
VRPN version numbers are compared for compatibility
If either peer indicates logging should be done, a message is sent
Server and client both open UDP sockets
(I think this is not done when "tcp:" is specified.)
Server and client both send udp_description messages
(I think this is not done when "tcp:" is specified.)
Server and client both send sender_description messages for all senders registered locally
(This provides a mapping between ASCII device description names to integer numbers)

(It isn't clear what benefit there is in having the client send what it wants to the server — the server only cares if it was compiled with the "vrpn_FILTER_MESSAGES" flag, which it never is!)
Server and client both send type_description messages for all types registered locally
(This provides a mapping between ASCII information type names to integer numbers)

(It isn't clear what benefit there is in having the client send what it wants to the server — the server doesn't care!)

The VRPN "Cookie" Format

The "cookie" string is 24 characters long and contains the ASCII string:

vrpn: ver. XX.YY  L\0\0\0\0\0

where:

XX = major version number ("07" as of this writing)
YY = minor version number ("34" as of this writing)
L = remote log mode requested ("0", "1", "2", or "3")

Known Bugs and Oddities

This list of things to watch out for are not necessarily bugs, but also things that just seem odd (and maybe it will be mostly the latter):

When unknown devices are requested by a client, the vrpn_server will remember these as though they are known devices and will report them in the future when sending all the known device names.
The protocol for SENDER_DESCRIPTION and TYPE_DESCRIPTION messages includes sending the length of the string as a separate value, but this is redundant with the "Total Length" value in the header, so wasn't necessary. (Too late now though.)

VRPN

Contents