DRD-API 3.2.2 documentationTHIS IS BETA SOFTWARE
This release of the DRD-3.2 is beta software and is provided "as is", with no warranty of any kind. Force Dimension will accept no responsibility for any damage that result from using this software, including damage to any hardware involved.
Please note that the performance and safety of the robotic regulation provided by the DRD-3.2 depends on the operating system, execution context and physical hardware used. A background in control theory and real-time programming is strongly recommended prior to writing applications using the DRD-3.2.
USE AT YOUR OWN RISK
This document describes the DRD-3.2 robotics software library. The DRD-3.2 has been designed specifically to enable robotic control of Force Dimension haptic devices, as well as to make it possible to write applications that combine interactive (haptic) and automatic (robotic) capabilities. As a consequence, the DRD-3.2 is built alongside the DHD-API and shares some fundamental resources with it. It is therefore possible to use the DHD-API calls (dhd*) and the DRD-3.2 calls (drd*) in the same application. For the same reason, this documentation manual sometimes refers to the DHD API 3.2 documentation.
This section describes how the DRD-3.2 is structured. In a nutshell, the library manages axis regulation in its own thread, while API calls asynchronously control the regulation loop parameters. Unsurprisingly, the library is targeted at real-time platforms to guarantee the performance and safety of the regulation (as well as the users and hardware involved). However, the DRD-3.2 has been implemented so that it can run with reasonable performance and acceptable safety on non-real time platforms, thanks in part to a control instability detection algorithm.
At the heart of the library is the regulation thread, which constraints the position of each joint. The thread can be started with drdStart() (after the device has been initialized), and stopped with drdStop(). The refresh rate of the control thread can be retrieved by calling drdGetCtrlFreq(). Once the the thread is running (which can be assessed with drdIsRunning()), the device can only be moved by changing the regulation target of each joint. This can be achieved by calling one of the drdMove* or drdTrack* functions. The drdMove* functions are designed to send the device end-effector on a direct, smooth trajectory to any point in the workspace, while the drdTrack* calls should be used to smoothly constrain the device motion on a continuous trajectory along a set of points sent asynchronously to the control thread (see drdTrackPos() for more details). The key difference between the two sets of functions is that drdMove* calls do not guarantee continuity if a new call is made before an earlier call finishes. On the other hand, drdTrack* calls do guarantee continuity regardless of when they are invoked. However, drdTrack* trajectory generation is performed on each axis individually, while drdMove* functions generate trajectories in 3D space. Outside of these different behaviors, both drdMove* and drdTrack* calls use a trajectory generation algorithm that guarantees continuous acceleration changes. For more details on the trajectory generation, see the section on trajectory generation parameters.
The trajectory generation algorithm implemented in the DRD-3.2 uses triangular acceleration constraints to guarantee smooth movements in both joint and cartesian spaces. The following parameters can be used to change the behavior of the generated trajectories:
On non real-time platforms, the periodicity of the regulation thread cannot be guaranteed. This has direct consequences on control stability and performance. In order to limit the performance degradation, the DRD-3.2 implements a regulator that does not assume periodicity and can tolerate some jitter in the control loop. In order to optimize the performance of the control thread, drdSetPriorities() can be used to change the priority of both the calling and the regulation thread. It must however be emphasized that, by definition, no performance guarantee can be offered on non real-time operating systems, and unpredictable behaviors (including disastrous instability) may occur. In order to prevent hardware damage, the regulation thread uses an internal measure of its own stability. See Control Instability Detection for more details.
During its execution, the regulation thread measures the jitter and delays of each iteration. Short of the thread being fully suspended by the system, these metrics allow the library to detect instability and exit gracefully, while applying the electro-magnetic brakes on the controlled device, in case of dangerous control performance degradation.
This version of the DRD-3.2 can be used with the second generation omega.x haptic devices and the delta.x (USB version). As of this release, robotic regulation is limited to the 3 translational degrees-of-freedom.
Unless specified explicitly, the following units are used throughout the API:
The DRD-3.2 uses the same thread-safe global as the DHD-API, dhdErrno, to store the last error that occurred in each running thread. Please refer to the DHD-API documentation (in the Error Management section) for more information.
The DRD-3.2 supports up to 4 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 drdGetDeviceID() and drdSetDevice(). 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.
Please contact your distributor for any technical support inquiry.