Robotic SDK: DRD - Robotic SDK Documentation

DRD - Robotic SDK Documentation

DRD - Robotic SDK Documentation

# Disclaimer

This release of the DRD 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 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.

USE AT YOUR OWN RISK

# Introduction

This document describes the DRD robotics software library. The DRD 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 is built alongside the DHD haptic library and shares some fundamental resources with it. It is therefore possible to use DHD calls (`dhd*`) and DRD calls (`drd*`) in the same application. For the same reason, this documentation makes direct references to the DHD Haptic SDK documentation.

This section describes how the DRD is structured. Conceptually, the library manages axis regulation in its own high-priority thread, while all DRD function calls asynchronously control the regulation loop parameters. The DRD 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 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.

## Regulation

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.

## Trajectory Generation Parameters

The trajectory generation algorithm implemented in the DRD 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:

- Amax - the maximal allowed acceleration [m/s^2]
- Vmax - the maximal allowed velocity [m/s]
- Jerk - the variation of acceleration over time [m/s^3]

## Non Real-Time Considerations

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 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.

## Control Instability Detection

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.

# SDK Function References

- drdOpen()
- drdOpenID()
- drdSetDevice()
- drdGetDeviceID()
- drdClose()
- drdIsSupported()
- drdIsRunning()
- drdIsMoving()
- drdIsFiltering()
- drdGetTime()
- drdSleep()
- drdWaitForTick()
- drdIsInitialized()
- drdAutoInit()
- drdCheckInit()
- drdPrecisionInit()
- drdGetPositionAndOrientation()
- drdGetVelocity()
- drdGetCtrlFreq()
- drdStart()
- drdRegulatePos()
- drdRegulateRot()
- drdRegulateGrip()
- drdSetForceAndTorqueAndGripperForce()
- drdSetForceAndWristJointTorquesAndGripperForce()
- drdEnableFilter()
- drdMoveToPos()
- drdMoveToRot()
- drdMoveToGrip()
- drdMoveTo()
- drdMoveToEnc()
- drdMoveToAllEnc()
- drdTrackPos()
- drdTrackRot()
- drdTrackGrip()
- drdTrack()
- drdTrackEnc()
- drdTrackAllEnc()
- drdHold()
- drdLock()
- drdStop()
- drdGetPriorities()
- drdSetPriorities()
- drdSetEncPGain()
- drdGetEncPGain()
- drdSetEncIGain()
- drdGetEncIGain()
- drdSetEncDGain()
- drdGetEncDGain()
- drdSetMotRatioMax()
- drdGetMotRatioMax()
- drdSetEncMoveParam()
- drdSetEncTrackParam()
- drdSetPosMoveParam()
- drdSetPosTrackParam()
- drdSetRotMoveParam()
- drdSetRotTrackParam()
- drdSetGripMoveParam()
- drdSetGripTrackParam()
- drdGetEncMoveParam()
- drdGetEncTrackParam()
- drdGetPosMoveParam()
- drdGetPosTrackParam()
- drdGetRotMoveParam()
- drdGetRotTrackParam()
- drdGetGripMoveParam()
- drdGetGripTrackParam()

# Technical Support

Please contact your distributor for any technical support inquiry.