Installing and testing
Clone this wiki locally
Compiling and Running Standard Apps
Once you have downloaded a version of VRPN and unzipped it, you will find the vrpn/ directory , which contains the source code to the library and the applications. How you make depends on whether you are compiling using Visual C++, a command-line system (Unix, Linux or Cygwin), or CMake.
If you use CMake to build the code, then you do not need to follow the rest of the instructions listed below; all of the configuration and build options are included within the CMake build itself. Once you have run CMake, just build the resulting project in the build system you selected.
If you do not use CMake, then follow the instructions below.
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 Windows
To compile on Visual C++ 6.0 under Windows, you enter the vrpn/ folder and double-click on the file vrpn.dsw, which is a workspace file. To compile under Visual Studio 2005+, you use the vrpn.sln 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, 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 "Multithreaded DLL" (debug or not). 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 edit makefile, uncommenting out the line that sets HW_OS for the architecture you are on. Then type gmake inside that directory. You then go into the main vrpn directory and do the same, that is, editing Makefile and typing gmake. This will compile the VRPN client and server libraries. Then, you go into the client_src subdirectory and edit 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 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.
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.