VRPN 06.04

Compiling and Running Standard Apps

Once you have downloaded a version of VRPN and unzipped it, you will find the directories quat/, vrpn/ and vrpn_html/. The directory vrpn_html/ contains these web pages. The directory quat/ contains a Quaternion library that is required by some of the Tracker code. The directory vrpn/ contains the source code to the library and the applications. How you make depends on whether you are compiling using Visual C++ or a command-line system (Unix, Linux or Cygwin).

Configuring VRPN

Before compiling on any architecture, you should take a look at the file vrpn_Configuration.h and see if you want to change any of the default configuration options. In particular, DirectInput is configured off by default because it requires the Direct X software development kit to be installed in order to compile VRPN. You can comment out or uncomment any of the definitions in the first section of this file to set VRPN to work the way you want it to.

Compiling on NT

To compile on Visual C++ 5.0/6.0 under windows NT, you enter the vrpn/ folder and double-click on the file vrpn.dsw, which is a workspace file. You click on the "FileView" tab to show the various projects within the workspace. Some of these projects are specific to particular uses (client_and_server is an example of running VRPN client and server objects in the same application, ohm_server runs a particular Ohmmeter at UNC, phan_server runs a Phantom force-feedback device, printcereal tests a B&G CerealBox). Others are germane to standard installations (vrpn_print_devices is a good client-side test program, quat is the quaternion library, test_vrpn is a good stand-alone test program, vrpn is the library itself and vrpn_server is a generic and configurable server that can run many different devices).

To get started, build the quat, vrpn, vrpn_server, printvals and test_vrpn projects (just building test_vrpn will cause the others to build as well). You can do this by right-clicking on the name and selecting Build. VRPN will hopefully build without any warnings (If there are warnings, like in ForceDevice, ignore them unless you run into trouble later). The applications build with perhaps minor errors. The library vrpn.lib ends up in pc_win32/Debug. The executables end up in pc_win32/client_src/[SERVER_NAME]/Debug and pc_win32/server_src/[SERVER_NAME]/Debug.

Important safety tip: All projects that are used to build an application using Visual Studio must use the same code generation method. The VRPN and quat libraries are set by default to use "Debug Multithreaded DLL." This must be the method used by an application, or else the settings in VRPN and quat need be changed (and then the projects cleaned and rebuilt). To set this for a project, use Project/Settings from the menu, select the C/C++ tab, then use the pull-down menu to switch from General to Code Generation. On the pull-down menu on that page, select Debug Multithreaded DLL or the option that matches your build.

Compiling on Other Architectures

On other architectures, you go into the quat directory and type 'gmake'. You then go into the vrpn directory and edit the Makefile, uncommenting out the line that sets HW_OS for the architecture you are on. Then, you compile the VRPN client and server libraries by typing 'gmake.' Then, you go into the client_src subdirectory and edit its Makefile and then compile with 'gmake' (you may need to make a directory for the hw_os you select first). Then you go into the server_src subdirectory and edit its Makefile and then compile with 'gmake'. The applications will build in a subdirectory named for the hw_os you set. For example, on Linux they will build into pc_linux/.

Running the Test Applications

The first test of the build is to run the test_vrpn program. You can do this either by double-clicking it in explorer (in NT) or else by opening a DOS shell and going to that directory. The program should run and print messages about how it is deleting and restarting _Remote objects, and also print tracker positions, dial changes, buttons and perhaps other messages. If it runs without crashing, you're in good shape. Kill it when you're finished watching it.

The vrpn_server.exe program is a generic server that is able to control many kinds of devices. It reads the information about what devices to run from a configuration file, as described on the VRPN servers page. You run the server by copying the example configuration file or making your own new one that lists the devices you want. A good one to start with is to uncomment the line for the vrpn_Tracker_NULL device. You then run 'vrpn_server -f NAME_OF_YOUR_FILE.cfg'. If you require extreme low latency or have a CPU to spare, you can leave use the '-millisleep 0' option.

[within NT] The other applications (vrpn_server and printvals) must be run from within a DOS shell or from a shortcut because they require command-line arguments to work correctly

The vrpn_print_devices.exe program will connect to a server and print out the results from devices at that server. You run it as 'vrpn_print_devices device@hostname', where hostname is the name of the computer that is running the server and devicename is the name of the device there (for example, Tracker0@localhost). It will begin to print reports from the device, whether it is a tracker, button, analog or dial device. You stop the program with ^C.

Example programs:

John Stone from the Beckman Institute provided several examples of using a Phantom (vrpn_Tracker, vrpn_Button, vrpn_ForceDevice), including hooking these to openGL programs under Irix. These can be found in the client_src/haptic directory of the source code tree.