View this PageEdit this PageUploads to this PageVersions of this PageHomeRecent ChangesSearchHelp Guide

VRPN Xtra Documentation

Last Update 05/12/04.

This is an attempt to bring CVS and the Docu into Sync. Probably it would be a good idea anyway to change this to doxygen.

Doxygen Documentation has been written and just needs to be uploaded and added to the Swiki. Don't rely on the contents stated below !!!



The commands that deal with the external devices and shared memory objects, provided by the VRPN system.



There are a few commands that wrap up the basic part of the system:

"vrpnGetCurrentTimestamp"

Return the current time using the same timestamps that the vrpn trackers and the marker trackers use.

"vrpnClientInit"

Initialize the vrpn subsystem. You should call this before using any other part of the VRPN subsystem.

"vrpnServerInit string"

Reads the configuration file with the given name and create the appropriate tracker server objects. NOTE: if you have invalid trackers in the file, VRPN may try to continutally reinitialize them, which can be a huge performance hit since it happens synchronously. Make sure your configuration file is correct.

"vrpnShutdown"

Shutdown the vrpn subsystem.

"vrpnCheckMessages"

Check the vrpn system for messages. Send and receive all queued messages. Most likely this is when the vrpn callbacks will happen (although they can happen elsewhere). Call this frequently.



Commands for accessing devices as a "client" (ie. for being notified when the device value changes). All access, even for devices attached to the local machine, use these commands. See the VRPN documentation if you are curious why.

"vrpnOpenRemoteTracker string, symbol, int"

Opens a connection to a tracker.

Parameters:
  • The first parameter is of the form "name@host" where the name is the tracker name, and the host is the machine it's running on.
  • The second parameter is the callback to receive updates.
    • The callback takes 2 parameters (int trkId, data)
    • The data is of the form [ report, report, ...]
      • position report: [sensorNum, 1, timestamp, [x,y,z],[q0,q1,q2,q3]]
      • vel or accel report : [sensorNum, 2 or 3, timestamp, [x,y,z],[q0,q1,q2,q3,q4],delta]

UNSURE !!


  • The third parameter specifies if the tracker reports should be collected into a list before calling the callback (if 0, do not collect, if 1 collect). For fast remote trackers, you MUST set this to 1, as the vrpn subsystem could lock up the xtra reading reports from the tracker if the Lingo callback takes any non-trivial amount of time to return.

Result: An integer tracker id is returned.

"vrpnCloseRemoteTracker int"

Close the tracker with the id passed in the first parameter.

"vrpnSetRemoteTrackerReportTypes int, int, int, int"

Set which report types we care about for a remote tracker.

Parameters:
  • The first parameter is the tracker id.
  • The second parameter represents position reports (0 or 1)
  • The third parameter represents velocity reports (0 or 1)
  • The fourth parameter represents acceleration reports (0 or 1)

Note: Very few trackers actually generate more than position reports. The default is to accept all 3.

"vrpnAddManualTrackerReport int, list"

Add a report to the manual tracker.

Parameters: int trackerId, int sensorID, list data
  • trackerID: The tracker for which to generate a report.
  • sensorID: %%% UNSURE %%% The sensor ???
  • data: list of list of reports formatted as below:
    • [ [report], [report], ... ]
    • formatting of each report:
    • 1: position report
      • [1, timestamp, [pos,pos,pos],[quat,quat,quat,quat]],
    • 2: velocity report
      • [2, timestamp, [vel,vel,vel],[quat,quat,quat,quat], delta]
    • 3: acceleration report
      • [3, timestamp, [acc,acc,acc],[quat,quat,quat,quat], delta]
The timestamp is an integer, and is appoximately the milliseconds since Director was opened. This is the scale of time that is used by the callbacks with other tracker reports, and by the callbacks for the marker tracking pose estimates. If timestamp is 0, the current time is used.

  • " vrpnOpenRemoteButton string, symbol, int"
    • Open a connection to a device with buttons on it.
    • The first parameter is of the form "name@host" where the name is the button device name, and the host is the machine it's running on.
    • The second parameter is the callback to receive updates.
      • The callback takes 2 parameters (int buttonId, [[int timestamp, int buttonNum, int buttonVal],...])
      • The buttonId is the id of the button object, returned when the remote button connection is opened.
      • The second parameter is a list of reports, each of which contains 3 values.
        • The timestamp is the time the button state changed.
        • The buttonNum is the button number that changed on that device, and buttonVal is the new state (typically 0 for off and 1 for on).
    • The third parameter specifies if the button reports should be collected into a list before calling the callback (if 0, do not collect, if 1 collect). For rapidly, continuously changing button devices, you should set this to 1, as the vrpn subsystem could lock up the xtra reading reports from the tracker if the Lingo callback takes any non-trivial amount of time to return.
    • An integer button id is returned.
  • " vrpnCloseRemoteButton int"
    • Close the button with the id passed in the first parameter.
  • " vrpnOpenRemoteAnalog string, symbol, int"
    • Open a connection to a device with analog sensors on it.
    • The first parameter is of the form "name@host" where the name is the analog device name, and the host is the machine it's running on.
    • The second parameter is the callback to receive updates.
      • The callback takes 2 parameters (int analogId, [[int timestamp, [float sensorVal, float sensorVal, ...],...])
      • The analogId is the id of the analog object, returned when the remote analog connection is opened.
      • The second parameter is a list of reports, each of which contains 2 values.
        • The timestamp is the time the analog state changed.
        • The second element is a list of floating point values, between -1.0 and 1.0, one for each analog sensor the device has. A new report is generated when any sensor changes.
    • The third parameter specifies if the analog reports should be collected into a list before calling the callback (if 0, do not collect, if 1 collect). For rapidly, continuously changing analog devices, you should set this to 1, as the vrpn subsystem could lock up the xtra reading reports from the device if the Lingo callback takes any non-trivial amount of time to return.
    • An integer analog id is returned.
  • " vrpnCloseRemoteAnalog int"
    • Close the analog with the id passed in the first parameter.


  • " vrpnCreateManualTracker int, string"
    • Create a tracker server that we will manually feed reports to.
    • The first parameter is the the number of sensors.
    • The second parameter is the name of the tracker.
    • An integer tracker id is returned.
  • " vrpnCloseManualTracker int"
    • Close a manual tracker, with the id specified in the parameter.

  • " vrpnCreateSharedInteger string, int, symbol"
    • Create a shared integer object server.
    • parameter 1 is the name of the object
    • parameter 2 is the initial value
    • parameter 3 is the callback function for updates
      • the function takes 2 parameters (int objectId, int newValue)
    • returns the integer id for the object
  • " vrpnCreateSharedFloat string, float, symbol"
    • Create a shared float object server.
    • parameter 1 is the name of the object
    • parameter 2 is the initial value
    • parameter 3 is the callback function for updates
      • the function takes 2 parameters (int objectId, float newValue)
    • returns the integer id for the object
  • " vrpnCreateSharedString string, string, symbol"
    • Create a shared string object server. Strings can have at most 1000 characters.
    • parameter 1 is the name of the object
    • parameter 2 is the initial value
    • parameter 3 is the callback function for updates
      • the function takes 2 parameters (int objectId, string newValue)
    • returns the integer id for the object
  • " vrpnOpenRemoteSharedInteger string, symbol"
    • Create a connection to a remote shared integer object.
    • parameter 1 is the name of the object and the host, "name@host"
    • parameter 2 is the callback function for updates
      • the function takes 2 parameters (int objectId, int newValue)
    • returns the integer id for the object
  • " vrpnOpenRemoteSharedFloat string, symbol"
    • Create a connection to a remote shared float object.
    • parameter 1 is the name of the object and the host, "name@host"
    • parameter 2 is the callback function for updates
      • the function takes 2 parameters (int objectId, float newValue)
    • returns the integer id for the object
  • " vrpnOpenRemoteSharedString string, symbol"
    • Create a connection to a remote shared string object. Strings can have at most 1000 characters.
    • parameter 1 is the name of the object and the host, "name@host"
    • parameter 2 is the callback function for updates
      • the function takes 2 parameters (int objectId, string newValue)
    • returns the integer id for the object
  • " vrpnCloseSharedObject int"
    • close the object with the id in the parameter
  • " vrpnSetSharedObjectValue int, any"
    • Set the value of a shared object (server or remote).
    • parameter 1 is the object id
    • parameter 2 is the new object value
  • " vrpn_asin float"
    • convenience function. return the arc sin of the parameter.
  • " vrpn_acos float"
    • convenience function. return the arc cos of the parameter.
  • " vrpn_atan float"
    • convenience function. return the arc tan of the parameter.
  • " vrpn_atan2 float,float"
    • convenience function. return the arc tan of the 2 parameters.
  • " vrpn_quat_to_euler list"
    • convenience function. return the 3 euler angles corresponding to the quaternion passed in.

Link to this Page