Visual Servoing Platform  version 3.2.0 under development (2018-12-09)
vpVirtuose Class Reference

#include <visp3/robot/vpVirtuose.h>

Public Member Functions

 vpVirtuose ()
 
 ~vpVirtuose ()
 
void addForce (vpColVector &force)
 
void close ()
 
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
 
unsigned int getJointsNumber () 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
 
unsigned int m_njoints
 

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.

  1. 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.
  2. 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.
  3. 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:

  1. The environment frame, corresponding to the origin of the virtual scene; it is specified by the software application independently of the Virtuose API.
  2. 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().
  3. 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().
  4. 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.
  5. 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();
std::cout << "Joint position: " << q.t() << std::endl;
}
Examples:
testVirtuose.cpp, testVirtuoseAfma6.cpp, testVirtuoseHapticBox.cpp, testVirtuoseJointLimits.cpp, and testVirtuosePeriodicFunction.cpp.

Definition at line 143 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 54 of file vpVirtuose.cpp.

References m_apiMajorVersion, and m_apiMinorVersion.

vpVirtuose::~vpVirtuose ( )

Default destructor that delete the VirtContext object.

Definition at line 77 of file vpVirtuose.cpp.

References close().

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 89 of file vpVirtuose.cpp.

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

void vpVirtuose::close ( )

Default destructor that delete the VirtContext object.

Definition at line 66 of file vpVirtuose.cpp.

References m_virtContext.

Referenced by ~vpVirtuose().

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 114 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 127 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, m_njoints, and m_virtContext.

vpColVector vpVirtuose::getArticularVelocity ( ) const

Return the 6 joint velocities of the virtuose.

Definition at line 151 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, m_njoints, 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 179 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 213 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 244 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 300 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 350 of file vpVirtuose.cpp.

References m_virtContext.

unsigned int vpVirtuose::getJointsNumber ( ) const

Get device number of joints.

Returns
The number of joints of the device. Sould be 6 for Virtuose, 9 for the glove fingers.

Definition at line 357 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_njoints.

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 373 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 406 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 439 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 462 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 492 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 509 of file vpVirtuose.cpp.

References vpException::fatalError, m_is_init, and m_virtContext.

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 589 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 617 of file vpVirtuose.cpp.

References vpException::dimensionError, vpException::fatalError, init(), m_njoints, 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 647 of file vpVirtuose.cpp.

References vpException::dimensionError, vpException::fatalError, init(), m_njoints, 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 677 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 709 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 729 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 755 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 779 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 182 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 800 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);
}
See also
startPeriodicFunction(), stopPeriodicFunction()
Examples:
testVirtuoseHapticBox.cpp, testVirtuoseJointLimits.cpp, and testVirtuosePeriodicFunction.cpp.

Definition at line 861 of file vpVirtuose.cpp.

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

void vpVirtuose::setPosition ( vpPoseVector position)

Modify the current value of the control position and send it to the Virtuose.

Parameters
position: Position of the end-effector (or the attached object, if any).

Definition at line 876 of file vpVirtuose.cpp.

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

void vpVirtuose::setPowerOff ( )

Turn the motor power OFF.

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

Definition at line 901 of file vpVirtuose.cpp.

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

void vpVirtuose::setPowerOn ( )

Turn the motor power ON.

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

Definition at line 914 of file vpVirtuose.cpp.

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

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

Set saturation values of the force feedback

Parameters
forceLimit: Value expressed in N.
torqueLimit: Value expressed in Nm.

Definition at line 929 of file vpVirtuose.cpp.

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

void vpVirtuose::setTimeStep ( const float &  timeStep)

Set the the simulation time step. The function must be called before the selection of the type of control mode.

Parameters
timeStep: Simulation time step (seconds).
Examples:
testVirtuoseJointLimits.cpp.

Definition at line 944 of file vpVirtuose.cpp.

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

void vpVirtuose::setVelocity ( vpColVector velocity)

Modify the current value of the control velocity and send it to the Virtuose.

Parameters
velocity: Velocity twist vector, where translations velocities are expressed in m/s and rotation velocities in rad/s.

Definition at line 963 of file vpVirtuose.cpp.

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

void vpVirtuose::setVelocityFactor ( const float &  velocityFactor)

Set the speed factor.

Parameters
velocityFactor: Scale factor applied to the velocities set using setVelocity().

Definition at line 987 of file vpVirtuose.cpp.

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

void vpVirtuose::setVerbose ( bool  mode)
inline

Enable/disable verbose mode.

Parameters
mode: true to enable, false to disable verbose.
Examples:
testVirtuoseAfma6.cpp, testVirtuoseHapticBox.cpp, testVirtuoseJointLimits.cpp, and testVirtuosePeriodicFunction.cpp.

Definition at line 196 of file vpVirtuose.h.

void vpVirtuose::startPeriodicFunction ( )
void vpVirtuose::stopPeriodicFunction ( )

Member Data Documentation

int vpVirtuose::m_apiMajorVersion
protected

Definition at line 205 of file vpVirtuose.h.

Referenced by vpVirtuose().

int vpVirtuose::m_apiMinorVersion
protected

Definition at line 206 of file vpVirtuose.h.

Referenced by vpVirtuose().

int vpVirtuose::m_ctrlMajorVersion
protected

Definition at line 207 of file vpVirtuose.h.

Referenced by init().

int vpVirtuose::m_ctrlMinorVersion
protected

Definition at line 208 of file vpVirtuose.h.

Referenced by init().

VirtIndexingType vpVirtuose::m_indexType
protected

Definition at line 210 of file vpVirtuose.h.

Referenced by setIndexingMode().

std::string vpVirtuose::m_ip
protected

Definition at line 203 of file vpVirtuose.h.

Referenced by init().

unsigned int vpVirtuose::m_njoints
protected
float vpVirtuose::m_period
protected

Definition at line 212 of file vpVirtuose.h.

Referenced by init(), setPeriodicFunction(), and setTimeStep().

VirtCommandType vpVirtuose::m_typeCommand
protected

Definition at line 209 of file vpVirtuose.h.

Referenced by init(), and setCommandType().

bool vpVirtuose::m_verbose
protected

Definition at line 204 of file vpVirtuose.h.

Referenced by init().