 |
|
This document provides an on-line description of the DHD 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 is transparently multi-platform. Currently, implementations exist on
The DHD is also available for the following Real-Time Operating Systems (RTOS):
The only requirement imposed by the multi-platform architecture of the DHD is the use of a preprocessor directive that matches your target system, as indicated in dhdc.h :
The DHD is designed with two purposes in mind:
The following sections describe the basic device features from a software perspective.
This version of the DHD can be used with the following devices:
Unknown devices that comply with the same protocol are referenced by DHD_DEVICE_CUSTOM.
Unless otherwise specified (e.g. for a specific device), the following convention is used when passing Cartesian data to a function in an array of the form:
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 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 supports as many haptic devices connected to the same computer as the underlying operating system can accommodate. Once a device is opened, it receives an ID that uniquely identifies it within the SDK. The device that receives the commands from the SDK can be identified and selected at any time by calling dhdGetDeviceID() and dhdSetDevice(). Also, every device specific function of the SDK 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 SDK provides internal mechanisms that estimate the velocity of the device in the joint and cartesian coordinate systems. The default velocity estimator configuration should be suitable for most use cases, but can be reconfigured by calling:
The estimated velocity can be retrieved by calling:
Note that in this release, velocity is computed using DHD_VELOCITY_WINDOWING mode.
The DHD features a throttling mechanism to provide a controllable communication refresh rate while preserving resources 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. In order to do so, TimeGuard prevents the application from requesting new position data if recent data from an earlier communication event is still recent enough. This mechanism can remove communication overhead without affecting performance if set properly, but can also significantly affect performance if set to the wrong value. It is recommended to leave the TimeGuard feature to its default setting unless a specific software architecture requires it. SDK 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 adjust this feature.
Every module of the SDK is thread-safe. Programmers need not add their own synchronizing mechanism to control access to the device or its geometric model.
Multi-threading operation is fully supported by the SDK (see Thread-Safe Operation above). The SDK provides a simple convenience function (dhdStartThread()) to start threads with a portable, operating system independent syntax. For more complex thread management, Force Dimension recommends using the native thread libraries of each operating system.
The dhdStartThread() function allows to start any C-like function in a separate thread, with an optional argument and a given priority level. The priority level is defined in a portable, operating system independent way as:
The DHD uses a thread-safe global accessible via dhdErrorGetLast(), 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 dhdErrorGetLast() 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.
The following functions can be used to retrieve error codes and their descriptions:
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 SDK, it is recommended to keep this threshold as low as the application requires.
Here is an overview of the units used in the SDK, unless otherwise specified:
The following functions can be called at any time.
This SDK 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 SDK 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 SDK and require a deep understanding of control theory, as well as of the device design itself.
USE AT YOUR OWN RISK !
The following functions only apply to the DHD_DEVICE_CONTROLLER and DHD_DEVICE_CONTROLLER_HR devices.
Please contact your distributor for any technical support inquiry.