DHD-API 3.2.2 documentationThis document provides an on-line description of the DHD-3.2 calls and the related functionalities of the Force Dimension haptic devices. It presents a detailed syntax of each function and its arguments, and explains the programming concepts and features that will help the programmer get the best performance out of Force Dimension haptic devices.
The DHD-3.2 is transparently multi-platform. Currently, implementations exist on
The only requirement imposed by the multi-platform architecture of the DHD-3.2 is the use of a preprocessor directive that matches your target system, as indicated in dhdc.h :
The DHD-3.2 is designed with two purposes in mind:
The following sections describe the basic device features from a software perspective.
This version of the DHD-3.2 can be used with the following devices from Force Dimension:
Unknown devices that comply with the same protocol are referenced by DHD_DEVICE_CUSTOM.
When a device is active (powered ON), it is in one of the four states or 'modes' described below. For additional information, please refer to the programming and user manuals.
Force Dimension haptic devices status can be retrieved via the dhdGetStatus() function. The function returns a status vector containing the following fields:
The DHD-3.2 supports up to 8 haptic devices connected to the same computer. The devices can use the PCI or the USB connection mode indifferently. Once a device is opened, it receives an ID that uniquely identifies it within the API. The device that receives the commands from the API can be identified and selected at any time by calling dhdGetDeviceID() and dhdSetDevice(). Also, every device specific function of the API can take as a last argument the device ID. If no last argument is given, or if that last argument is -1 (the default), the default device is used.
The API provides internal mechanisms that estimate the velocity of the device in the cartesian coordinate system. The velocity estimator can be configured by calling dhdConfigLinearVelocity. The actual velocity estimator is calculated during calls to dhdGetPosition(), which will be triggered automatically in the background if required. Estimated velocity can be retrieved by calling dhdGetLinearVelocity(). There are two modes used to estimate velocity: DHD_VELOCITY_WINDOWING and DHD_VELOCITY_AVERAGING.
The DHD-3.2 features a throttling mechanism to provide a controllable communication refresh rate while preserving CPU time on non real-time OS. This mechanism prevents the OS from querying the device for its position at a rate higher than an adjustable threshold. TimeGuard prevents the application from requesting new position data if recent data from an earlier communication event is still recent enough. This mechanism removes significant communication overhead without affecting performance if set properly. API calls that trigger the TimeGuard feature will return DHD_TIMEGUARD if communication with the device was not necessary, 0 otherwise (or see error management for possible return values). See dhdSetTimeGuard() to enable this feature.
Every module of the DHD-3.2 is thread-safe. Programmers need not add their own synchronizing mechanism to control access to the device or its geometric model.
The DHD-3.2 uses a thread-safe global, dhdErrno, to store the last error that occurred in each running thread. Most functions and methods will return either 0 or a valid, positive value on success, and -1 (or NULL) in case of failure. On failure, programmers can check the value of dhdErrno against the error values.
To help identify the error, the dhdErrorGetStr() functions return a short descriptive string. Similarly, dhdErrorGetLastStr() returns a string describing the last error that occurred within the calling thread.
As Force Dimension haptic devices can generate a significant amount of force, it could accelerate to a point that may damage the system, or surprise unaware users. To prevent such situations, the controller factory settings offer a safety feature that forces the device into BRAKE mode if the velocity becomes greater than a given threshold. While it is possible to modify this value using advanced features from this API, it is recommended to keep this threshold as low as the application requires.
Here is an overview of the units used in the API, unless otherwise specified:
The following functions can be called at any time.
This API offers high-level functions and methods that make it very easy to interface a Force Dimension haptic Device with any application. However, in some cases, users might want to get direct access to lower-level functionalities of the device (such as encoder readings and direct motor command) The API allows advanced users to access these routines by enabling the expert mode. Please note that the expert mode is for experienced programmers who have a thorough understanding of their haptic interface. Force Dimension cannot be held responsible for any damage resulting from use of the expert mode. The following functions are part of the expert API and require a deep understanding of control theory, as well as of the device design itself.
USE AT YOUR OWN RISK !
Please contact your distributor for any technical support inquiry.