A haptic device is a bidirectional instrumented/actuated human-machine interface, employed by the human operator to actively interact with a computer simulated virtual environment. A haptic device can be in the form of a mouse, steering wheel, fingerpad, robotic handle, gripper, joystick, gloves, magnetically levitated wrist, or even motion platforms that move the entire user's body. It can be used to simulate an environment with mass, damping, friction, and stiffness properties, or it can mimic the mechanical behavior of a virtual tool interacting with its surrounding virtual environment.
CHAI3D provides a base class called cGenericHapticDevice that implements a set of methods to communicate with most common 3D haptic devices. The position of the end-effector or handle of a haptic device can be read by using methods such as getPosition(), getRotation(), getGripperAngleDeg(). Optional user switches or buttons can be read by calling getUserSwitch().
For each model of haptic device (e.g delta.x, omega.x falcon, phantom, etc.) CHAI3D implements a specific class (e.g cDeltaDevice, cPhantomDevice) which inherits from cGenericHapticDevice and implements each command by calling specific commands from the API that supports the device.
All quantities are expressed in IUS (metric) unit. The reference device coordinate system specifies that the x-axis is pointing towards the operator, the y-axis towards his or her right hand side, and the z-axis upward. Finally, the origin is always located at the center of the physical workspace of the device.
If the haptic device carries a wrist or stylus, the orientation of its handle is expressed by using a rotation matrix. The convention is illustrated in the following illustrations for a three, six, and seven degrees-of-freedom device.
02-multi-devices is a simple application that displays a reference frame for each haptic device connected to the computer. Reference frames use colors instead of labels to name the different axis (respectively x, y and z). The color convention is: red for the x-axis, green for the y-axis, and blue for the z-axis.
The haptic device handler (cHapticDeviceHandler) is a class that searches for and lists all haptic devices connected to the computer.
In the following listing we illustrate a simple example that applies a force to a haptic device to bring its end-effector toward the center point of its workspace:
cMyCustomDevice provides a basic template which allows you to very easily interface CHAI3D to your own custom haptic device. Simply follow the 12 commented step in file CMyCustomDevice.cpp and complete the code accordingly. Depending of the numbers of degrees of freedom on your device, not all methods may need to be implemented. For instance, if your device does not provide any rotational degrees of freedom, simply ignore the getRotation() method. Default values will be returned correctly if these are not implemented on your device. In the case of rotations for instance, the identity matrix is returned.
You may also rename this class in which case you will also want to customize the haptics handler to automatically detect your device. Please consult method update() of the cHapticDeviceHandler class which is located in file CHapticDeviceHandler.cpp. Simply see how the haptic device handler already looks for device of type cMyCustomDevice.
If you are encountering any problems with your implementation, check for instance file CDeltaDevices.cpp which implement supports for the Force Dimension and Novint haptic devices. In order to verify the implementation use the
01-mydevice example to get started. Example
11-effects is a great demo to verify how basic haptic effects may behave with you haptic devices. If you do encounter vibrations or instabilities, try reducing the maximum stiffness supported by your device (see STEP1 in file CMyCustomDevice.cpp).
Make sure that your device is also communicating fast enough with your computer. Ideally the communication period should take less than 1ms in order to reach a desired update rate of at least 1000Hz. Problems can typically occur when using a slow serial port (RS232) for instance.