#include <visp3/robot/vpVirtuose.h>

Public Member Functions
	vpVirtuose ()

	~vpVirtuose ()

void	addForce (vpColVector &force)

void	enableForceFeedback (int enable)

vpColVector	getArticularPosition () const

vpColVector	getArticularVelocity () const

vpPoseVector	getAvatarPosition () const

vpPoseVector	getBaseFrame () const

VirtCommandType	getCommandType () const

bool	getDeadMan () const

bool	getEmergencyStop () const

vpColVector	getForce () const

VirtContext	getHandler ()

vpPoseVector	getObservationFrame () const

vpPoseVector	getPhysicalPosition () const

vpColVector	getPhysicalVelocity () const

vpPoseVector	getPosition () const

bool	getPower () const

vpColVector	getVelocity () const

void	init ()

void	setArticularForce (const vpColVector &articularForce)

void	setArticularPosition (const vpColVector &articularPosition)

void	setArticularVelocity (const vpColVector &articularVelocity)

void	setBaseFrame (const vpPoseVector &position)

void	setCommandType (const VirtCommandType &type)

void	setForce (const vpColVector &force)

void	setForceFactor (const float &forceFactor)

void	setIndexingMode (const VirtIndexingType &type)

void	setIpAddress (const std::string &ip)

void	setObservationFrame (const vpPoseVector &position)

void	setPeriodicFunction (VirtPeriodicFunction CallBackVirt)

void	setPosition (vpPoseVector &position)

void	setPowerOff ()

void	setPowerOn ()

void	setSaturation (const float &forceLimit, const float &torqueLimit)

void	setTimeStep (const float &timeStep)

void	setVelocity (vpColVector &velocity)

void	setVelocityFactor (const float &velocityFactor)

void	setVerbose (bool mode)

void	startPeriodicFunction ()

void	stopPeriodicFunction ()

Protected Attributes
VirtContext	m_virtContext

std::string	m_ip

bool	m_verbose

int	m_apiMajorVersion

int	m_apiMinorVersion

int	m_ctrlMajorVersion

int	m_ctrlMinorVersion

VirtCommandType	m_typeCommand

VirtIndexingType	m_indexType

bool	m_is_init

float	m_period

Detailed Description

This class was tested with Haption (http://www.haption.com) Virtuose 6D haptic device.

The class vpVirtuose allows to work with the original Virtuose API inside ViSP. The Virtuose API supports the following devices:

Virtuose 6D35-45
Virtuose 3D35-40
Virtuose 3D10-20
Virtuose Desktop
Virtuose Inca

Not all Virtuose API function are implemented in the class. Original Virtuose API functions need to be called with a VirtContext object, provided by the function getHandler().

The Virtuose library implements different control modes that could be set using setCommandType(). The choice of the control mode depends on the application. The following is the description of the main control modes as described in the Virtuose API documentation.

Force/position control (impedance mode): the application sends forces and torques to the device and reads the position and speed of the end-effector frame.
Position/force control (admittance mode): this advanced control mode allows direct coupling with virtual objects; in that case, the application sends the position and speed of the center of the object to the device, and reads the forces and torques to be applied to the object for dynamic integration. Stiffness and damping are calculated by the embedded software, knowing the mass and inertia of the object, in order to ensure control stability.
Position/force with virtual guides: this is the same as above, with addition of virtual guides (e.g. fixed translation, fixed rotation, etc.).

The Virtuose library defines the following reference frames:

The environment frame, corresponding to the origin of the virtual scene; it is specified by the software application independently of the Virtuose API.
The observation frame, corresponding generally to the position of the camera; it is defined with respect to environment frame. This frame location could be set using setObservationFrame().
The base frame, representing the center of the haptic device; it is defined with respect to the observation frame. This frame location could be set using setBaseFrame().
The tool frame corresponds to the base of the tool fixed at the end of the haptic device, and is defined with respect to the environment frame.
The end-effector (avatar) frame corresponds to the position of the user hand on the device, taking into account the geometry of the tool, and is defined with respect to tool frame.

The position of the following frames can be defined only once using the API: base frame (with respect to the observation frame) thanks to setBaseFrame() and end-effector frame (with respect to the tool frame).

The position of the observation frame (with respect to the environment frame) can be modified dynamically using setObservationFrame().

The position of the tool frame (with respect to the environment frame) cannot be modified.

All values used in the Virtuose API are expressed in physical units using metric conventions:

Durations in seconds (s)
Dimensions in meters (m)
Angles in radians (rad)
Linear velocities in meters per second (m.s -1 )
Angular velocities in radians per second (rad.s -1 )
Forces in Newtons (N)
Torques in Newton-meters (N.m)
Masses in kilogrammes (kg)
Inertia components in kg.m2

The following sample code shows how to connect to the haptic device to get its current joint position:

#include <visp3/robot/vpVirtuose.h>
int main()
{
  vpVirtuose virtuose;
  virtuose.init();
  vpColVector q = virtuose.getArticularPosition();
  std::cout << "Joint position: " << q.t() << std::endl;
}

Examples:: testVirtuose.cpp, testVirtuoseAfma6.cpp, testVirtuoseHapticBox.cpp, testVirtuoseJointLimits.cpp, and testVirtuosePeriodicFunction.cpp.

Definition at line 133 of file vpVirtuose.h.

Constructor & Destructor Documentation

vpVirtuose::vpVirtuose ( )

Default constructor. Set command type to virtual mechanism by default (impedance mode). Authorize indexing on all movements by default.

Definition at line 53 of file vpVirtuose.cpp.

References m_apiMajorVersion, and m_apiMinorVersion.

vpVirtuose::~vpVirtuose ( )

Default destructor that delete the VirtContext object.

Definition at line 67 of file vpVirtuose.cpp.

References m_virtContext.

Member Function Documentation

void vpVirtuose::addForce ( vpColVector & force )

Add a force to be applied to the virtuose (impedance effort). This function works in every mode.

Parameters

force : Is 6 component dynamic tensor (three forces and three torques) wrt virtuose end-effector and is expressed in the coordinates of the base frame.

Definition at line 81 of file vpVirtuose.cpp.

References vpException::dimensionError, vpException::fatalError, init(), m_virtContext, and vpArray2D< Type >::size().

void vpVirtuose::enableForceFeedback ( int enable )

Activate or desactivate force feedback.

Parameters

enable : 1 to activate (system's default value), 0 to desactivate.

Definition at line 106 of file vpVirtuose.cpp.

References vpException::fatalError, init(), and m_virtContext.

vpColVector vpVirtuose::getArticularPosition ( ) const

Return the 6 joint values of the virtuose.

Examples:: testVirtuose.cpp, and testVirtuoseJointLimits.cpp.

Definition at line 120 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

vpColVector vpVirtuose::getArticularVelocity ( ) const

Return the 6 joint velocities of the virtuose.

Definition at line 145 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

vpPoseVector vpVirtuose::getAvatarPosition ( ) const

Return the indexed position of the end-effector, expressed in the coordinates of the environment reference frame. With respect to the function getPosition(), getAvatarPosition() takes into account current offsets (indexing) and motor scale factors.

See Also: getPosition(), getPhysicalPosition()

Definition at line 172 of file vpVirtuose.cpp.

References vpPoseVector::buildFrom(), vpException::fatalError, m_is_init, and m_virtContext.

vpPoseVector vpVirtuose::getBaseFrame ( ) const

Return the current position of the base frame with respect to the observation reference frame.

See Also: setBaseFrame(), getObservationFrame()

Definition at line 209 of file vpVirtuose.cpp.

References vpPoseVector::buildFrom(), vpException::fatalError, m_is_init, and m_virtContext.

VirtCommandType vpVirtuose::getCommandType ( ) const

Return the current command type.

Definition at line 243 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

bool vpVirtuose::getDeadMan ( ) const

Return the status of DeadMan sensor : true if the sensor is ON (a user is holding the handle) and false if the sensor is OFF (no user detected).

Definition at line 263 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

bool vpVirtuose::getEmergencyStop ( ) const

Return the status of the emergency stop button : true if the system is operational (button correctly plugged and not triggered) and false if the system is not operational (button not plugged or triggered).

Examples:: testVirtuose.cpp.

Definition at line 282 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

vpColVector vpVirtuose::getForce ( ) const

Return the 6-dimension force tensor to be applied to the object attached to the Virtuose, allowing the dynamic simulation of the scene.

Definition at line 301 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

VirtContext vpVirtuose::getHandler ( )

Return the handler used to communicate with the device. This function could be used to access to a functionality that is not implemented in vpVirtuose class.

The following sample code shows how to use this function to get the device joint positions. This functionality is already implemented in getArticularPosition().

#include <visp3/robot/vpVirtuose.h>
int main()
{
  vpVirtuose virtuose;
  virtuose.init();
  VirtContext handler = virtuose.getHandler();
  float q[6];
  if (virtGetArticularPosition(handler, q)) { // Use the handler to access to Haption API directly
    std::cout << "Cannot get articular position" << std::endl;
  }
  std::cout << "Joint position: ";
  for (unsigned int i=0; i<6; i++)
    std::cout << q[i] << " ";
  std::cout << std::endl;
}

See Also: getArticularPosition()

Definition at line 352 of file vpVirtuose.cpp.

References m_virtContext.

vpPoseVector vpVirtuose::getObservationFrame ( ) const

Return the cartesian current position of the observation reference frame with respect to the environment reference frame.

See Also: setObservationFrame(), getBaseFrame()

Definition at line 362 of file vpVirtuose.cpp.

References vpPoseVector::buildFrom(), vpException::fatalError, m_is_init, and m_virtContext.

vpPoseVector vpVirtuose::getPhysicalPosition ( ) const

Return the cartesian physical position of the Virtuose expressed in the coordinates of the base reference frame.

See Also: getAvatarPosition(), getPosition()

Examples:: testVirtuoseHapticBox.cpp, and testVirtuosePeriodicFunction.cpp.

Definition at line 396 of file vpVirtuose.cpp.

References vpPoseVector::buildFrom(), vpException::fatalError, m_is_init, and m_virtContext.

vpColVector vpVirtuose::getPhysicalVelocity ( ) const

Return the physical cartesian velocity twist of the Virtuose expressed in the coordinates of the base reference frame.

Returns: A 6-dimension velocity twist with 3 translation velocities and 3 rotation velocities.

See Also: getVelocity()

Examples:: testVirtuoseHapticBox.cpp, and testVirtuosePeriodicFunction.cpp.

Definition at line 432 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

vpPoseVector vpVirtuose::getPosition ( ) const

Return the cartesian position of the virtuose (or the object attached to it, if any) expressed in the coordinates of the environment reference frame.

See Also: getAvatarPosition(), getPhysicalPosition()

Definition at line 455 of file vpVirtuose.cpp.

References vpPoseVector::buildFrom(), vpException::fatalError, m_is_init, and m_virtContext.

bool vpVirtuose::getPower ( ) const

Return status of the motors : true if motors are ON, false otherwise.

Definition at line 488 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

vpColVector vpVirtuose::getVelocity ( ) const

Return the cartesian velocity twist of the virtuose (or the object attached to it, if any) expressed in the coordinates of the environment reference frame.

Returns: A 6-dimension velocity twist with 3 translation velocities and 3 rotation velocities.

See Also: getPhysicalVelocity()

Examples:: testVirtuoseAfma6.cpp.

Definition at line 505 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

void vpVirtuose::init ( void )

Initialize virtuose device opening the connection to the device and setting the default command type. If the device is already initialized, a call to init() does nothing.

Examples:: testVirtuose.cpp.

Definition at line 527 of file vpVirtuose.cpp.

References vpException::fatalError, m_ctrlMajorVersion, m_ctrlMinorVersion, m_ip, m_is_init, m_period, m_typeCommand, m_verbose, and m_virtContext.

Referenced by addForce(), enableForceFeedback(), setArticularForce(), setArticularPosition(), setArticularVelocity(), setBaseFrame(), setCommandType(), setForce(), setForceFactor(), setIndexingMode(), setObservationFrame(), setPeriodicFunction(), setPosition(), setPowerOff(), setPowerOn(), setSaturation(), setTimeStep(), setVelocity(), setVelocityFactor(), startPeriodicFunction(), and stopPeriodicFunction().

void vpVirtuose::setArticularForce ( const vpColVector & articularForce )

Send a command of articular force to the Virtuose. setArticularForce() only works in mode COMMAND_TYPE_ARTICULAR_IMPEDANCE, to be set with setCommandType().

Parameters

articularForce : Six dimension torque vector.

Examples:: testVirtuoseJointLimits.cpp.

Definition at line 569 of file vpVirtuose.cpp.

References vpException::dimensionError, vpException::fatalError, init(), m_virtContext, and vpArray2D< Type >::size().

void vpVirtuose::setArticularPosition ( const vpColVector & articularPosition )

Send a command of articular (joint) position to the virtuose. This function works only in COMMAND_TYPE_ARTICULAR mode, to be set with setCommandType().

Parameters

articularPosition : Six dimension joint position vector.

Definition at line 595 of file vpVirtuose.cpp.

References vpException::dimensionError, vpException::fatalError, init(), m_virtContext, and vpArray2D< Type >::size().

void vpVirtuose::setArticularVelocity ( const vpColVector & articularVelocity )

Send a command of articular (joint) velocity to the virtuose. This function works only in COMMAND_TYPE_ARTICULAR mode, to be set with setCommandType().

Parameters

articularVelocity : Six dimension joint velocity vector.

Definition at line 621 of file vpVirtuose.cpp.

References vpException::dimensionError, vpException::fatalError, init(), m_virtContext, and vpArray2D< Type >::size().

void vpVirtuose::setBaseFrame ( const vpPoseVector & position )

Move the base frame with respect to the observation reference frame. It can be called at any time.

Parameters

position : Position of the base frame.

See Also: getBaseFrame(), setObservationFrame()

Definition at line 649 of file vpVirtuose.cpp.

References vpPoseVector::extract(), vpException::fatalError, init(), and m_virtContext.

void vpVirtuose::setCommandType ( const VirtCommandType & type )

Set the command type.

Parameters

type

: Possible values:

COMMAND_TYPE_NONE : No possible movement.
COMMAND_TYPE_IMPEDANCE : Force/position control.
COMMAND_TYPE_VIRTMECH : Position/force control with virtual mechanism.
COMMAND_TYPE_ARTICULAR : Joint control.
COMMAND_TYPE_ARTICULAR_IMPEDANCE : Force/Position control in the joint space.

Examples:: testVirtuoseAfma6.cpp, and testVirtuoseJointLimits.cpp.

Definition at line 681 of file vpVirtuose.cpp.

References vpException::fatalError, init(), m_typeCommand, and m_virtContext.

void vpVirtuose::setForce ( const vpColVector & force )

Set the force to be applied by the Virtuose. setForce() only works in COMMAND_TYPE_IMPEDANCE mode, to be set with setCommandType().

Parameters

force : Force vector that represents a dynamic tensor with 6 components.

Examples:: testVirtuoseAfma6.cpp, and testVirtuoseHapticBox.cpp.

Definition at line 701 of file vpVirtuose.cpp.

References vpException::dimensionError, vpException::fatalError, init(), m_virtContext, and vpArray2D< Type >::size().

void vpVirtuose::setForceFactor ( const float & forceFactor )

Set the force scale factor.

Parameters

forceFactor : Force scale factor applied to the force torque tensor set by setForce().

Definition at line 726 of file vpVirtuose.cpp.

References vpException::fatalError, init(), and m_virtContext.

void vpVirtuose::setIndexingMode ( const VirtIndexingType & type )

Set indexing (offset) mode.

Parameters

type

: Possible choices are:

INDEXING_ALL : authorize indexing on all movements.
INDEXING_TRANS : authorize indexing on translation, i.e., the orientation of the object is always identical to the orientation of the device end-effector.
INDEXING_NONE : forbids indexing on all movements.
The following values are also implemented: INDEXING_ALL_FORCE_FEEDBACK_INHIBITION, INDEXING_TRANS_FORCE_FEEDBACK_INHIBITION. These values correspond to the same modes listed before, but the force feedback is inhibited during indexing.

Definition at line 746 of file vpVirtuose.cpp.

References vpException::fatalError, init(), m_indexType, and m_virtContext.

void vpVirtuose::setIpAddress ( const std::string & ip )

inline

Set haptic device ip address and port. Default value is "localhost#5000".

Examples:: testVirtuoseHapticBox.cpp, and testVirtuoseJointLimits.cpp.

Definition at line 169 of file vpVirtuose.h.

void vpVirtuose::setObservationFrame ( const vpPoseVector & position )

Move the observation frame with respect to the environment reference frame. It can be called at any time.

Parameters

position : Position of the observation frame.

See Also: getObservationFrame(), setBaseFrame()

Definition at line 768 of file vpVirtuose.cpp.

References vpPoseVector::extract(), vpException::fatalError, init(), and m_virtContext.

void vpVirtuose::setPeriodicFunction ( VirtPeriodicFunction CallBackVirt )

Register the periodic function. setPeriodicFunction() defines a callback function to be called at a fixed period of time, as timing for the simulation. The callback function is synchronized with the Virtuose controller (messages arrive at very constant time intervals from it) and generates hardware interrupts to be taken into account by the operating system. In practice, this function is much more efficient for timing the simulation than common software timers. This function is started using startPeriodicFunction() and stopped using stopPeriodicFunction().

Parameters

CallBackVirt : Callback function.

Example of the use of the periodic function:

#include <visp3/robot/vpVirtuose.h>
void CallBackVirtuose(VirtContext VC, void* ptr)
{
  (void) VC;
  vpVirtuose* p_virtuose=(vpVirtuose*)ptr;
  vpPoseVector position = p_virtuose->getPosition();
  return;
}
int main()
{
  vpVirtuose virtuose;
  float period = 0.001;
  virtuose.setTimeStep(period);
  virtuose.setPeriodicFunction(CallBackVirtuose, period, virtuose);
  virtuose.startPeriodicFunction();
  virtuose.stopPeriodicFunction();
}