CGenericHapticDevice.h
Go to the documentation of this file.
1 //==============================================================================
2 /*
3  Software License Agreement (BSD License)
4  Copyright (c) 2003-2016, CHAI3D.
5  (www.chai3d.org)
6 
7  All rights reserved.
8 
9  Redistribution and use in source and binary forms, with or without
10  modification, are permitted provided that the following conditions
11  are met:
12 
13  * Redistributions of source code must retain the above copyright
14  notice, this list of conditions and the following disclaimer.
15 
16  * Redistributions in binary form must reproduce the above
17  copyright notice, this list of conditions and the following
18  disclaimer in the documentation and/or other materials provided
19  with the distribution.
20 
21  * Neither the name of CHAI3D nor the names of its contributors may
22  be used to endorse or promote products derived from this software
23  without specific prior written permission.
24 
25  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
28  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
29  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
30  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
31  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
32  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
33  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
35  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36  POSSIBILITY OF SUCH DAMAGE.
37 
38  \author <http://www.chai3d.org>
39  \author Francois Conti
40  \version 3.2.0 $Rev: 2141 $
41 */
42 //==============================================================================
43 
44 //------------------------------------------------------------------------------
45 #ifndef CGenericHapticDeviceH
46 #define CGenericHapticDeviceH
47 //------------------------------------------------------------------------------
48 #include "devices/CGenericDevice.h"
49 #include "math/CMaths.h"
50 #include "system/CGlobals.h"
51 #include "timers/CPrecisionClock.h"
52 //------------------------------------------------------------------------------
53 
54 //------------------------------------------------------------------------------
55 namespace chai3d {
56 //------------------------------------------------------------------------------
57 
58 //==============================================================================
65 //==============================================================================
66 
67 
68 //------------------------------------------------------------------------------
69 // GENERAL CONSTANTS
70 //------------------------------------------------------------------------------
72 const int C_DEVICE_HISTORY_SIZE = 200; // [number of samples]
73 
75 const double C_DEVICE_MIN_ACQUISITION_TIME = 0.0001; // [s]
76 
78 const int C_MAX_DOF = 16;
79 
80 //------------------------------------------------------------------------------
81 
82 
83 //==============================================================================
87 //==============================================================================
89 {
113 };
114 
115 
116 //------------------------------------------------------------------------------
117 #ifndef DOXYGEN_SHOULD_SKIP_THIS
118 //------------------------------------------------------------------------------
119 
120 //==============================================================================
128 //==============================================================================
129 struct cTimestampValue
130 {
132  double m_time;
133 
135  double m_value;
136 };
137 
138 
139 //==============================================================================
147 //==============================================================================
148 struct cTimestampPos
149 {
151  double m_time;
152 
154  cVector3d m_pos;
155 };
156 
157 
158 //==============================================================================
166 //==============================================================================
167 struct cTimestampRot
168 {
170  double m_time;
171 
173  cMatrix3d m_rot;
174 };
175 
176 
177 //------------------------------------------------------------------------------
178 #endif // DOXYGEN_SHOULD_SKIP_THIS
179 //------------------------------------------------------------------------------
180 
181 
182 //==============================================================================
193 //==============================================================================
195 {
198 
200  std::string m_modelName;
201 
203  std::string m_manufacturerName;
204 
207 
210 
213 
216 
219 
222 
225 
228 
231 
234 
237 
240 
243 
246 
249 
252 
255 
258 
261 };
262 
263 //------------------------------------------------------------------------------
265 typedef std::shared_ptr<cGenericHapticDevice> cGenericHapticDevicePtr;
266 //------------------------------------------------------------------------------
267 
268 //==============================================================================
279 //==============================================================================
281 {
282  //--------------------------------------------------------------------------
283  // CONSTRUCTOR & DESTRUCTOR:
284  //--------------------------------------------------------------------------
285 
286 public:
287 
289  cGenericHapticDevice(unsigned int a_deviceNumber = 0);
290 
292  virtual ~cGenericHapticDevice() {};
293 
295  static cGenericHapticDevicePtr create(unsigned int a_deviceNumber = 0) { return (std::make_shared<cGenericHapticDevice>(a_deviceNumber)); }
296 
297 
298  //--------------------------------------------------------------------------
299  // PUBLIC METHODS - GENERAL COMMANDS:
300  //--------------------------------------------------------------------------
301 
302 public:
303 
305  virtual bool open() { return (C_ERROR); }
306 
308  virtual bool close() { return (C_ERROR); }
309 
311  virtual bool calibrate(bool a_forceCalibration = false) { return (m_deviceReady); }
312 
314  virtual bool getPosition(cVector3d& a_position) { a_position.zero(); return (m_deviceReady); }
315 
317  virtual bool getLinearVelocity(cVector3d& a_linearVelocity) { a_linearVelocity = m_linearVelocity; return (m_deviceReady); }
318 
320  virtual bool getRotation(cMatrix3d& a_rotation) { a_rotation.identity(); return (m_deviceReady); }
321 
323  virtual bool getJointAnglesRad(double a_jointAnglesRad[C_MAX_DOF]) { return (C_ERROR); }
324 
326  virtual bool getAngularVelocity(cVector3d& a_angularVelocity) { a_angularVelocity = m_angularVelocity; return (m_deviceReady); }
327 
329  virtual bool getTransform(cTransform& a_transform);
330 
332  virtual bool getGripperAngleRad(double& a_angle);
333 
335  inline bool getGripperAngleDeg(double& a_angle) { double angle; bool result = getGripperAngleRad(angle); a_angle = cRadToDeg(angle); return (result); }
336 
338  virtual bool getGripperAngularVelocity(double& a_gripperAngularVelocity) { a_gripperAngularVelocity = m_gripperAngularVelocity; return (m_deviceReady); }
339 
341  virtual bool getForce(cVector3d& a_force) { a_force = m_prevForce; return (m_deviceReady); }
342 
344  virtual bool getTorque(cVector3d& a_torque) { a_torque = m_prevTorque; return (m_deviceReady); }
345 
347  virtual bool getGripperForce(double& a_gripperForce) { a_gripperForce = m_prevGripperForce; return (m_deviceReady); }
348 
350  virtual bool getUserSwitch(int a_switchIndex, bool& a_status);
351 
353  virtual bool getUserSwitches(unsigned int& a_userSwitches) { a_userSwitches = 0; return (m_deviceReady); }
354 
356  cHapticDeviceInfo getSpecifications() { return (m_specifications); }
357 
359  virtual void setEnableGripperUserSwitch(const bool a_status) { m_gripperUserSwitchEnabled = a_status; }
360 
362  virtual bool getEnableGripperUserSwitch() const { return (m_gripperUserSwitchEnabled); }
363 
365  bool setForce(const cVector3d& a_force) { return (setForceAndTorqueAndGripperForce(a_force, cVector3d(0.0,0.0,0.0), 0.0)); }
366 
368  bool setForceAndTorque(const cVector3d& a_force, const cVector3d& a_torque) { return (setForceAndTorqueAndGripperForce(a_force, a_torque, 0.0)); }
369 
371  virtual bool setForceAndTorqueAndGripperForce(const cVector3d& a_force, const cVector3d& a_torque, double a_gripperForce) { cSleepMs(1); return (m_deviceReady); }
372 
373 
374  //--------------------------------------------------------------------------
375  // PUBLIC STATIC METHODS:
376  //--------------------------------------------------------------------------
377 
378 public:
379 
381  static unsigned int getNumDevices() { return (0); }
382 
383 
384  //--------------------------------------------------------------------------
385  // PUBLIC MEMBERS - GENERAL:
386  //--------------------------------------------------------------------------
387 
388 public:
389 
392 
393 
394  //--------------------------------------------------------------------------
395  // PROTECTED MEMBERS - CURRENT VALUES:
396  //--------------------------------------------------------------------------
397 
398 protected:
399 
402 
405 
408 
411 
414 
417 
418 
419  //--------------------------------------------------------------------------
420  // PROTECTED MEMBERS - VELOCITY ESTIMATION:
421  //--------------------------------------------------------------------------
422 
423 protected:
424 
426  cTimestampPos m_historyPos[C_DEVICE_HISTORY_SIZE];
427 
429  cTimestampRot m_historyRot[C_DEVICE_HISTORY_SIZE];
430 
432  cTimestampValue m_historyGripper[C_DEVICE_HISTORY_SIZE];
433 
436 
439 
442 
445 
448 
451 
454 
457 
460 
463 
464 
465  //--------------------------------------------------------------------------
466  // PROTECTED MEMBERS - GRIPPER USER SWITCH:
467  //--------------------------------------------------------------------------
468 
469 protected:
470 
473 
476 
479 
482 
485 
486 
487  //--------------------------------------------------------------------------
488  // PROTECTED MEMBERS - SIMULATED GRIPPER FOR DEVICES WITH USER SWITCH:
489  //--------------------------------------------------------------------------
490 
491 protected:
492 
495 
498 
501 
504 
507 
508 
509  //--------------------------------------------------------------------------
510  // PROTECTED METHODS - VELOCITY ESTIMATION:
511  //--------------------------------------------------------------------------
512 
513 protected:
514 
516  void estimateLinearVelocity(cVector3d& a_newPosition);
517 
519  void estimateAngularVelocity(cMatrix3d& a_newRotation);
520 
522  void estimateGripperVelocity(double a_newGripperPosition);
523 
524 
525  //--------------------------------------------------------------------------
526  // PROTECTED METHODS - GRIPPER USER SWITCH:
527  //--------------------------------------------------------------------------
528 
529 protected:
530 
532  double computeGripperUserSwitchForce(const double& a_gripperAngle,
533  const double& a_gripperAngularVelocity);
534 
536  bool getGripperUserSwitch();
537 
538 
539  //--------------------------------------------------------------------------
540  // PROTECTED METHODS - DEVICE LIBRARY INITIALIZATION:
541  //--------------------------------------------------------------------------
542 
543 protected:
544 
546  static bool openLibraries() { return (C_SUCCESS); }
547 
549  static bool closeLibraries() { return (C_SUCCESS); }
550 };
551 
552 //------------------------------------------------------------------------------
553 } // namespace chai3d
554 //------------------------------------------------------------------------------
555 
556 //------------------------------------------------------------------------------
557 #endif
558 //------------------------------------------------------------------------------
This class implements a 3D vector.
Definition: CVector3d.h:88
cPrecisionClock m_virtualGripperClock
Clock for computing the position/velocity of the virtual gripper.
Definition: CGenericHapticDevice.h:506
double cRadToDeg(const double &a_angleRad)
This function converts an angle from radians to degrees.
Definition: CMaths.h:653
virtual bool close()
This method closes the connection to the haptic device.
Definition: CGenericHapticDevice.h:308
bool setForceAndTorque(const cVector3d &a_force, const cVector3d &a_torque)
This method sends a force [N] and torque [N*m] command to the haptic device.
Definition: CGenericHapticDevice.h:368
double m_maxGripperAngularDamping
Maximum recommended angular damping factor Kv when using the getGripperAngularVelocity() method from ...
Definition: CGenericHapticDevice.h:230
bool m_sensedRotation
If true then device supports rotation sensing. (i.e stylus, pen), false otherwise.
Definition: CGenericHapticDevice.h:242
double m_maxAngularDamping
Maximum recommended angular damping factor Kv when using the getAngularVelocity() method from the dev...
Definition: CGenericHapticDevice.h:227
bool m_actuatedRotation
If true then device provides actuation capabilities for orientation degrees of freedom (i...
Definition: CGenericHapticDevice.h:251
Implements a high precision clock.
Implements general math utility functions.
virtual ~cGenericHapticDevice()
Destructor of cGenericHapticDevice.
Definition: CGenericHapticDevice.h:292
double m_maxGripperLinearStiffness
Maximum closed loop gripper stiffness [N/m] for a simulation running at 1 KHz.
Definition: CGenericHapticDevice.h:221
This class implements an abstract class for hardware devices.
Definition: CGenericDevice.h:83
std::string m_manufacturerName
Name of the haptic device manufacturer.
Definition: CGenericHapticDevice.h:203
double m_maxLinearDamping
Maximum recommended linear damping factor Kv when using the getVelocity() method from the device clas...
Definition: CGenericHapticDevice.h:224
static cGenericHapticDevicePtr create(unsigned int a_deviceNumber=0)
Shared cGenericHapticDevice allocator.
Definition: CGenericHapticDevice.h:295
bool m_sensedPosition
If true then device supports position sensing (x,y,z axis), false otherwise.
Definition: CGenericHapticDevice.h:239
void zero()
This method clears all vector components with zeros.
Definition: CVector3d.h:256
double m_gripperUserSwitchAngleClick
Position of the gripper when the virtual switch is enabled and the "click" occurs.
Definition: CGenericHapticDevice.h:478
const int C_MAX_DOF
Maximum number of joint of a haptic device.
Definition: CGenericHapticDevice.h:78
cHapticDeviceModel
Definition: CGenericHapticDevice.h:88
int m_indexHistoryPos
Current index position in history data table.
Definition: CGenericHapticDevice.h:435
bool m_rightHand
If true then the device can be used for right hands, false otherwise.
Definition: CGenericHapticDevice.h:260
double m_maxAngularStiffness
Maximum closed loop angular stiffness [N*m/rad] for a simulation running at 1 KHz.
Definition: CGenericHapticDevice.h:218
Definition: CGenericHapticDevice.h:101
This class implements a high precision clock.
Definition: CPrecisionClock.h:85
double m_workspaceRadius
Radius which describes the largest sphere (3D devices) or circle (2D Devices) which can be enclosed i...
Definition: CGenericHapticDevice.h:233
cPrecisionClock m_clockGeneral
General clock used to compute velocity signals.
Definition: CGenericHapticDevice.h:462
Implements a device base class.
Definition: CGenericHapticDevice.h:97
virtual bool getTorque(cVector3d &a_torque)
This method returns the sensed torque [N*m] from the haptic device.
Definition: CGenericHapticDevice.h:344
int m_indexHistoryRotWin
Last index position used to compute velocity.
Definition: CGenericHapticDevice.h:447
const bool C_SUCCESS
Function returns successfully.
Definition: CConstants.h:77
bool m_actuatedPosition
If true then device provides actuation capabilities for translation degrees of freedom (x...
Definition: CGenericHapticDevice.h:248
double m_angularVelocityWindowSize
Window time interval for measuring angular velocity.
Definition: CGenericHapticDevice.h:456
double m_virtualGripperAngle
Virtual gripper current angle in radians [rad].
Definition: CGenericHapticDevice.h:494
bool m_leftHand
If true then the device can be used for left hands, false otherwise.
Definition: CGenericHapticDevice.h:257
Definition: CGenericHapticDevice.h:102
double m_gripperUserSwitchAngleStart
Position of the gripper when the user encounters the virtual switch.
Definition: CGenericHapticDevice.h:475
Definition: CGenericHapticDevice.h:109
double m_gripperMaxAngleRad
Maximum open angle of the gripper [rad].
Definition: CGenericHapticDevice.h:236
Definition: CGenericHapticDevice.h:103
cHapticDeviceModel m_model
Haptic device model.
Definition: CGenericHapticDevice.h:197
virtual bool setForceAndTorqueAndGripperForce(const cVector3d &a_force, const cVector3d &a_torque, double a_gripperForce)
This method sends a force [N], torque [N*m], and gripper force [N] command to the haptic device...
Definition: CGenericHapticDevice.h:371
double m_prevGripperForce
Last gripper force sent to haptic device.
Definition: CGenericHapticDevice.h:407
const double C_DEVICE_MIN_ACQUISITION_TIME
Smallest time interval between two position/status reads from a haptic device.
Definition: CGenericHapticDevice.h:75
cHapticDeviceInfo m_specifications
Technical specifications of haptic device.
Definition: CGenericHapticDevice.h:391
double m_virtualGripperAngleMin
Virtual gripper minimum angle in radians [rad].
Definition: CGenericHapticDevice.h:497
double m_gripperUserSwitchForceEngaged
Force level when the gripper is completely closed after the "click" event has occurred.
Definition: CGenericHapticDevice.h:484
virtual bool getGripperForce(double &a_gripperForce)
This method returns the sensed torque [N*m] from the force gripper.
Definition: CGenericHapticDevice.h:347
double m_linearVelocityWindowSize
Window time interval for measuring linear velocity.
Definition: CGenericHapticDevice.h:453
Implements option settings for CHAI3D.
static bool openLibraries()
This method opens libraries for this class of devices.
Definition: CGenericHapticDevice.h:546
bool m_sensedGripper
If true then device supports a sensed gripper interface, false otherwise.
Definition: CGenericHapticDevice.h:245
Definition: CGenericHapticDevice.h:108
int m_indexHistoryPosWin
Last index position used to compute velocity.
Definition: CGenericHapticDevice.h:444
bool m_actuatedGripper
If true then device provides an actuated gripper, false otherwise.
Definition: CGenericHapticDevice.h:254
This class implements a 3D matrix.
Definition: CMatrix3d.h:97
virtual bool getJointAnglesRad(double a_jointAnglesRad[C_MAX_DOF])
This method returns the joint angles of the haptic device.
Definition: CGenericHapticDevice.h:323
This class implements a 4D transformation matrix encoded as column-major.
Definition: CTransform.h:75
cVector3d m_angularVelocity
Last estimated angular velocity.
Definition: CGenericHapticDevice.h:413
std::shared_ptr< cGenericHapticDevice > cGenericHapticDevicePtr
Definition: CGenericHapticDevice.h:264
const bool C_ERROR
Function returns with an error.
Definition: CConstants.h:74
double m_gripperAngularVelocity
Last estimated gripper angular velocity.
Definition: CGenericHapticDevice.h:416
Definition: CGenericHapticDevice.h:90
This class implements a base class for haptic devices.
Definition: CGenericHapticDevice.h:280
Definition: CGenericHapticDevice.h:104
Definition: CGenericHapticDevice.h:105
static bool closeLibraries()
This method closes libraries for this class of devices.
Definition: CGenericHapticDevice.h:549
cVector3d m_prevTorque
Last torque sent to haptic device.
Definition: CGenericHapticDevice.h:404
virtual bool getLinearVelocity(cVector3d &a_linearVelocity)
This method returns the linear velocity of the haptic device.
Definition: CGenericHapticDevice.h:317
Definition: CGenericHapticDevice.h:92
Definition: CGenericHapticDevice.h:99
int m_indexHistoryGripperWin
Last index position used to compute velocity.
Definition: CGenericHapticDevice.h:450
Definition: CGenericHapticDevice.h:111
bool setForce(const cVector3d &a_force)
This method sends a force [N] command to the haptic device.
Definition: CGenericHapticDevice.h:365
virtual bool getAngularVelocity(cVector3d &a_angularVelocity)
This method returns the angular velocity of haptic device.
Definition: CGenericHapticDevice.h:326
virtual bool getRotation(cMatrix3d &a_rotation)
This method returns the orientation frame of the haptic device end-effector.
Definition: CGenericHapticDevice.h:320
Definition: CGenericHapticDevice.h:91
double m_maxLinearStiffness
Maximum closed loop linear stiffness [N/m] for a simulation running at 1 KHz.
Definition: CGenericHapticDevice.h:215
static unsigned int getNumDevices()
This method returns the number of haptic devices available for this class of devices.
Definition: CGenericHapticDevice.h:381
This structure stores all technical specifications of a haptic device.
Definition: CGenericHapticDevice.h:194
Definition: CGenericHapticDevice.h:93
double m_gripperUserSwitchForceClick
Maximum force level at the force gripper when the "click" occurs.
Definition: CGenericHapticDevice.h:481
Definition: CGenericHapticDevice.h:98
std::string m_modelName
Name of the haptic device model.
Definition: CGenericHapticDevice.h:200
double m_gripperVelocityWindowSize
Window time interval for measuring gripper velocity.
Definition: CGenericHapticDevice.h:459
Definition: CGenericHapticDevice.h:100
virtual bool getGripperAngularVelocity(double &a_gripperAngularVelocity)
This method returns the angular velocity of the gripper. Units are in radians per second [rad/s]...
Definition: CGenericHapticDevice.h:338
bool m_gripperUserSwitchEnabled
If true then virtual gripper user switch is enabled.
Definition: CGenericHapticDevice.h:472
double m_maxLinearForce
Maximum continuous force in [N] that can be generated by the haptic device in translation.
Definition: CGenericHapticDevice.h:206
virtual bool getUserSwitches(unsigned int &a_userSwitches)
This method returns the status of all user switches [true = ON / false = OFF].
Definition: CGenericHapticDevice.h:353
virtual bool getForce(cVector3d &a_force)
This method returns the sensed force [N] from the haptic device.
Definition: CGenericHapticDevice.h:341
const int C_DEVICE_HISTORY_SIZE
Size of buffer.
Definition: CGenericHapticDevice.h:72
cHapticDeviceInfo getSpecifications()
This method returns the technical specifications of this haptic device.
Definition: CGenericHapticDevice.h:356
Definition: CAudioBuffer.cpp:56
double m_virtualGripperAngularVelocity
Virtual speed value used for simulating the opening and closing of the virtual gripper [rad/s]...
Definition: CGenericHapticDevice.h:503
virtual bool calibrate(bool a_forceCalibration=false)
This method calibrates the haptic device.
Definition: CGenericHapticDevice.h:311
int m_indexHistoryRot
Current index position in history data table.
Definition: CGenericHapticDevice.h:438
virtual bool getEnableGripperUserSwitch() const
This method returns the status of the virtual gripper user switch. If true, then gripper is used to e...
Definition: CGenericHapticDevice.h:362
void identity()
This method builds an identity matrix.
Definition: CMatrix3d.h:325
Definition: CGenericHapticDevice.h:94
bool getGripperAngleDeg(double &a_angle)
This method returns the gripper angle in degrees [deg].
Definition: CGenericHapticDevice.h:335
double m_maxGripperForce
Maximum continuous force in [N] that can be produced by the haptic gripper.
Definition: CGenericHapticDevice.h:212
int m_indexHistoryGripper
Current index position in history data table.
Definition: CGenericHapticDevice.h:441
double m_maxAngularTorque
Maximum continuous torque in [N*m] that can be generated by the haptic device in orientation.
Definition: CGenericHapticDevice.h:209
double m_virtualGripperAngleMax
Virtual gripper maximum angle in radians [rad].
Definition: CGenericHapticDevice.h:500
void cSleepMs(const unsigned int a_interval)
This function suspends the execution of the current thread for a specified interval.
Definition: CGlobals.cpp:60
Definition: CGenericHapticDevice.h:96
Definition: CGenericHapticDevice.h:106
virtual void setEnableGripperUserSwitch(const bool a_status)
This method enables or disables the virtual gripper switch.
Definition: CGenericHapticDevice.h:359
Definition: CGenericHapticDevice.h:95
cVector3d m_linearVelocity
Last estimated linear velocity.
Definition: CGenericHapticDevice.h:410
virtual bool getPosition(cVector3d &a_position)
This method returns the position of the haptic device.
Definition: CGenericHapticDevice.h:314
virtual bool open()
This method opens a connection to the haptic device.
Definition: CGenericHapticDevice.h:305
Definition: CGenericHapticDevice.h:107
Definition: CGenericHapticDevice.h:110
cVector3d m_prevForce
Last force sent to haptic device.
Definition: CGenericHapticDevice.h:401
Definition: CGenericHapticDevice.h:112