forcedimension_core.dhd package

Submodules

Module contents

forcedimension_core.dhd.checkControllerMemory(ID: int = -1) → int[source]

This function evaluates the integrity of the device controller firmware and internal configuration on supported device types.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: 0 on success, forcedimension_core.constants.ErrorNum.CONFIGURATION if the firmware or internal configuration health check failed.

forcedimension_core.dhd.close(ID: int = -1) → int[source]

Close the connection to a particular device.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: 0 on success, -1 otherwise.

See also

forcedimension_core.dhd.open()
forcedimension_core.dhd.openID()
forcedimension_core.dhd.openType()
forcedimension_core.dhd.openSerial()

forcedimension_core.dhd.configAngularVelocity(ms: int = 20, mode: VelocityEstimatorMode = VelocityEstimatorMode.WINDOWING, ID: int = -1) → int[source]

Configure the internal angular velocity computation estimator. This only applies to the device wrist. For more information refer to Velocity Estimator.

Parameters:

ms (int) – Time interval used to compute velocity (in [ms]).
mode (VelocityEstimator) – Velocity estimator mode to use.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.
ctypes.ArgumentError – If ms is not implicitly convertible to C int.
ctypes.ArgumentError – If mode is not implicitly convertible to C int.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.getAngularVelocityRad()

forcedimension_core.dhd.configGripperVelocity(ms: int = 20, mode: VelocityEstimatorMode = VelocityEstimatorMode.WINDOWING, ID: int = -1) → int[source]

Configure the internal linear velocity computation estimator. This only applies to the device gripper. For more information refer to Velocity Estimator.

Parameters:

ms (int) – Time interval used to compute velocity (in [ms]).
mode (VelocityEstimator) – Velocity estimator mode to use.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.
ctypes.ArgumentError – If ms is not implicitly convertible to C int.
ctypes.ArgumentError – If mode is not implicitly convertible to C int.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getGripperLinearVelocity()
forcedimension_core.dhd.getGripperAngularVelocityRad()
forcedimension_core.dhd.getGripperAngularVelocityDeg()

forcedimension_core.dhd.configLinearVelocity(ms: int = 20, mode: VelocityEstimatorMode = VelocityEstimatorMode.WINDOWING, ID: int = -1) → int[source]

Configure the internal linear velocity computation estimator. This only applies to the device base. For more information refer to Velocity Estimator.

Parameters:

ms (int) – Time interval used to compute velocity (in [ms]).
mode (VelocityEstimator) – Velocity estimator mode to use.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.
ctypes.ArgumentError – If ms is not implicitly convertible to C int.
ctypes.ArgumentError – If mode is not implicitly convertible to C int.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getLinearVelocity()
forcedimension_core.dhd.configAngularVelocity()
forcedimension_core.dhd.configGripperVelocity()

forcedimension_core.dhd.emulateButton(enable: bool, ID: int = -1) → int[source]

Enable the button behavior emulation in devices that feature a gripper.

Note

For more information on what features devices support, see the Device Types section for more details.

Note

For omega.7 devices with firmware versions 2.x, forces need to be enabled for the button emulation to report the emulated button status.

Parameters:

enable – True to enable, False to disable.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.enableForce(enable: bool, ID: int = -1) → int[source]

Enable the force mode in the device controller.

Parameters:

enable (bool) – True to enable force, False to disable it.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If val is not implicitly convertible to C bool.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.expert.enableGripperForce()
forcedimension_core.dhd.expert.stop()
forcedimension_core.dhd.expert.setBrakes()

forcedimension_core.dhd.enableGripperForce(enable: bool, ID: int = -1) → int[source]

This function enables the gripper force mode in the device controller. This function is only relevant to devices that have a gripper with a default closed or opened state. It does not apply to the sigma.x and omega.x range of devices, whose gripper does not have a default state. For those devices, the gripper force is enabled/disabled by forcedimension_core.dhd.enableForce().

Parameters:

enable (bool) – True to enable force, False to disable it.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If enable is not implicitly convertible to C bool.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.expert.enableForce()
forcedimension_core.dhd.expert.stop()
forcedimension_core.dhd.expert.setBrakes()

forcedimension_core.dhd.enableSimulator(enable: bool) → None[source]

Enable device simulator support. This enables network access on the loopback interface.

Parameters:: enable – True to enable, False to disable

forcedimension_core.dhd.errorGetLast() → ErrorNum[source]

Gets the last error code encountered in the running thread. See Error Management for details.

Returns:: forcedimension_core.dhd.adaptors.ErrorNum enum elements refering to the last error encountered in the current thread.

See also

forcedimension_core.dhd.errorGetStr()

forcedimension_core.dhd.errorGetLastStr()

forcedimension_core.dhd.errorGetLastStr() → str[source]

Get a brief string describing the last error encountered in the running thread. See Error Management for details.

Returns:: A string describing the last error encountered in the running thread.

forcedimension_core.dhd.errorGetStr()

forcedimension_core.dhd.errorGetStr(error: ErrorNum) → str[source]

Get a brief string describing a given error code. See Error Management for details.

Parameters:: error (ErrorNum) – the error code to describe.
Returns:: A string describing error.

forcedimension_core.dhd.errorGetLastStr()

forcedimension_core.dhd.getAngularVelocityDeg(out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the estimated angular velocity (in [deg/s]).

Note

The velocity estimator requires at least 2 position updates during the time interval defined in forcedimension_core.dhd.configAngularVelocity() in order to be able to compute the estimate. Otherwise, if there are no calls to forcedimension_core.dhd.getPosition() or forcedimension_core.dhd.getAngularVelocityDeg(), this function will error with forcedimension_core.constants.ErrorNum.TIMEOUT. For more information refer to Velocity Estimator.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details)
out (MutableArray[int, float]) – An output buffer to store the angular velocity (in [deg/s]).

Raises:

TypeError – If out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.getAngularVelocityRad()

forcedimension_core.dhd.getAngularVelocityRad(out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the estimated angular velocity (in [rad/s]).

Note

The velocity estimator requires at least 2 position updates during the time interval defined in forcedimension_core.dhd.configAngularVelocity() in order to be able to compute the estimate. Otherwise, if there are no calls to forcedimension_core.dhd.getPosition() or forcedimension_core.dhd.getAngularVelocityRad(), this function will return error with forcedimension_core.constants.ErrorNum.TIMEOUT. For more information refer to Velocity Estimator.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
out (MutableArray[int, float]) – An output buffer to store the angular velocity (in [rad/s]).

Raises:

TypeError – If out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.getAngularVelocityDeg()

forcedimension_core.dhd.getAvailableCount() → int[source]

Return the number of available Force Dimension devices connected to the system. This encompasses all devices connected locally, but excludes devices already locked by other applications. Devices are given a unique identifier, as explained in the Support for Multiple Devices section.

Returns:: The number of devices available on success, -1 otherwise.

forcedimension_core.dhd.getBaseAngleXDeg(out: c_double, ID: int = -1) → int[source]

Get the device base plate angle around the X axis (in [deg]).

Parameters:

out (c_double) – Output buffer to store the base plate angle around the X axis (in [deg]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getBaseAngleXRad()
forcedimension_core.dhd.setBaseAngleXRad()
forcedimension_core.dhd.setBaseAngleXDeg()

forcedimension_core.dhd.getBaseAngleXRad(out: c_double, ID: int = -1) → int[source]

Get the device base plate angle around the X axis (in [rad]).

Parameters:

out (c_double) – Output buffer to store the base plate angle around the X axis (in [rad]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getBaseAngleXDeg()
forcedimension_core.dhd.setBaseAngleXRad()
forcedimension_core.dhd.setBaseAngleXDeg()

forcedimension_core.dhd.getBaseAngleZDeg(out: c_double, ID: int = -1) → float[source]

Get the device base plate angle around the Z axis (in [deg]).

Parameters:

out (c_double) – Output buffer to store the base plate angle around the Z axis (in [deg]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getBaseAngleZRad()
forcedimension_core.dhd.setBaseAngleZRad()
forcedimension_core.dhd.setBaseAngleZDeg()

forcedimension_core.dhd.getBaseAngleZRad(out: c_double, ID: int = -1) → int[source]

Get the device base plate angle around the Z axis (in [rad]).

Parameters:

out (c_double) – Output buffer to store the base plate angle around the Z axis (in [rad]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getBaseAngleZDeg()
forcedimension_core.dhd.setBaseAngleZRad()
forcedimension_core.dhd.setBaseAngleZDeg()

forcedimension_core.dhd.getButton(index: int, ID: int = -1) → int[source]

Return the status of the button located on the end-effector

Parameters:

index (int) – button index, 0 for the gripper button up to forcedimension_core.constants.MAX_BUTTONS
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

1 if the button is pressed, 0 if not, and -1 on error.

forcedimension_core.dhd.getButtonMask(ID: int = -1) → int[source]

Return the 32-bit binary mask of the device buttons.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: 32-bit long bitmask. A bit is set to 1 if the associated button is pressed, 0 otherwise. Each indexed button is represented by the corresponding bit LSB to MSB (i.e. button 0 correpnds to the LSB, button 32 the MSB).

See also

forcedimension_core.dhd.getButton()

forcedimension_core.dhd.getComFreq(ID: int = -1) → float[source]

Return the communication refresh rate (in [kHz]) between the computer and the device. Refresh rate computation is based on function calls that apply a force on the device (e.g. forcedimension_core.dhd.setForce()).

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The refresh rate (in [kHz]), 0.0 otherwise.

forcedimension_core.dhd.getComMode(ID: int = -1) → ComMode[source]

Retrive the COM operation mode on compatible devices.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The current COM operation mode on success, -1 otherwise.

forcedimension_core.dhd.getComponentVersionStr(component: int, N: int = 256, ID: int = -1) → str[source]

This function returns a string of length at most N that describes an internal component version (if present).

Parameters:

component (int) – Component ID provided by Force Dimension (device-specific).
N (int) – The maximum number of characters to get from the string that describes an internal component.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ValueError – If N is less than 1.
ctypes.ArgumentError – If component is not implicitly convertible to C uint32_t.
ctypes.ArgumentError – If N is not implicitly convertible to C size_t.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

A string of at most N characters that describes an internal component on success, an empty string otherwise.

forcedimension_core.dhd.getDeviceAngleDeg(out: c_double, ID: int = -1) → int[source]

Get the device base plate angle around the Y axis in degrees.

Parameters:

out (c_double) – Output buffer to store the base plate angle around the Y axis (in [deg]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, and -1 otherwise.

See also

forcedimension_core.dhd.getDeviceAngleRad()
forcedimension_core.dhd.getBaseAngleXRad()
forcedimension_core.dhd.getBaseAngleXDeg()
forcedimension_core.dhd.getBaseAngleZRad()
forcedimension_core.dhd.getBaseAngleZDeg()

forcedimension_core.dhd.getDeviceAngleRad(out: c_double, ID: int = -1) → int[source]

Get the device base plate angle around the Y axis in radians.

Parameters:

out (c_double) – Output buffer to store the base plate angle around the Y axis (in [rad]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, and -1 otherwise.

See also

forcedimension_core.dhd.getDeviceAngleDeg()
forcedimension_core.dhd.getBaseAngleXRad()
forcedimension_core.dhd.getBaseAngleXDeg()
forcedimension_core.dhd.getBaseAngleZRad()
forcedimension_core.dhd.getBaseAngleZDeg()

forcedimension_core.dhd.getDeviceCount() → int[source]

Return the number of compatible Force Dimension devices connected to the system. This encompasses all devices connected locally, including devices already locked by other applications. Devices are given a unique identifier, as explained in the Support for Multiple Devices section.

Returns:: The number of connected devices on success, -1 otherwise.

forcedimension_core.dhd.getDeviceID() → int[source]

Get the ID of the current default device.

Returns:: The ID of the current default device

See also

forcedimension_core.dhd.setDevice()

forcedimension_core.dhd.getEffectorMass(ID: int = -1) → float[source]

Get the mass (in [kg]) of the end-effector currently defined for a device. The gripper mass is used in the gravity compensation feature.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The set mass for the device on success, -1.0 otherwise.

See also

forcedimension_core.dhd.getEffectorMass()
forcedimension_core.dhd.setStandardGravity()
forcedimension_core.dhd.setGravityCompensation()

forcedimension_core.dhd.getForce(out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the force vector applied to the end-effector (in [N]) about the X, Y, and Z axes Please refer to your device user manual for more information on your device coordinate system.

Parameters:

out (MutableArray[int, float]) – An output buffer to store the applied forces on the end-effector (in [N]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

TypeError – If out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setForce()
forcedimension_core.dhd.setForceAndTorque()
forcedimension_core.dhd.setForceAndTorqueAndGripperForce()
forcedimension_core.dhd.getForceAndTorque()
forcedimension_core.dhd.getForceAndTorqueAndGripperForce()

forcedimension_core.dhd.getForceAndTorque(f_out: MutableArray[int, float], t_out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the force and torque vectors applied to the device end-effector.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
f_out (MutableArray[int, float]) – An output buffer to store the applied forces on the end-effector (in [N]).
t_out (MutableArray[int, float]) – An output buffer to store the applied torques on the end-effector (in [Nm]).

Raises:

ValueError – If ID is not implicitly convertible to C char.

Returns:

0, on success, -1 otherwise.

See also

forcedimension_core.dhd.setForce()
forcedimension_core.dhd.setForceAndTorque()
forcedimension_core.dhd.setForceAndTorqueAndGripperForce()
forcedimension_core.dhd.getForce()
forcedimension_core.dhd.getForceAndTorqueAndGripperForce()

forcedimension_core.dhd.getForceAndTorqueAndGripperForce(f_out: MutableArray[int, float], t_out: MutableArray[int, float], fg_out: c_double, ID: int = -1) → int[source]

Retrieve the forces (in [N]) and torques (in [Nm]) applied to the device end-effector. Forces and torques are about the X, Y, and Z axes.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
f_out (MutableArray[int, float]) – An output buffer to store the applied forces on the end-effector (in [N]).
t_out (MutableArray[int, float]) – An output buffer to store the applied torques on the end-effector (in [Nm]).
fg_out (c_double) – An output buffer to store the force applied to the gripper (in [N]).

Raises:

ValueError – If ID is not implicitly convertible to C char.

Returns:

0, on success, -1 otherwise.

See also

forcedimension_core.dhd.setForce()
forcedimension_core.dhd.setForceAndTorque()
forcedimension_core.dhd.getForce()
forcedimension_core.dhd.getForceAndTorque()
forcedimension_core.dhd.getForceAndTorqueAndGripperForce()

forcedimension_core.dhd.getGripperAngleDeg(out: c_double, ID: int = -1) → int[source]

Get the gripper opening angle (in [deg]).

Note

This feature only applies to devices with a gripper. See the Device Types section for more details.

Parameters:

out (c_double) – Output buffer to store the gripper opening angle (in [deg]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

forcedimension_core.dhd.direct.getGripperGap()

forcedimension_core.dhd.getGripperAngleRad(out: c_double, ID: int = -1) → int[source]

Get the gripper opening angle (in [rad]).

Note

This feature only applies to devices with an gripper. See the Device Types section for more details.

Parameters:

out (c_double) – Output buffer to store the gripper opening angle (in [rad]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

See also

forcedimension_core.dhd.direct.getGripperAngleDeg()

forcedimension_core.dhd.direct.getGripperGap()

forcedimension_core.dhd.getGripperAngularVelocityDeg(out: c_double, ID: int = -1) → int[source]

Retrieve the estimated angular velocity of the gripper (in [rad/s]).

Note

The velocity estimator requires at least 2 position updates during the time interval defined in forcedimension_core.dhd.configGripperVelocity() in order to be able to compute the estimate. Otherwise, e.g. if there are no calls to forcedimension_core.dhd.getGripperGap() or forcedimension_core.dhd.getGripperAngularVelocityDeg(), this funtion will error with forcedimension_core.constants.ErrorNum.TIMEOUT. For more information refer to Velocity Estimator

Parameters:

out (c_double) – Output buffer to store the estimated angular velocity of the gripper (in [deg/s]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.getGripperAngularVelocityDeg()

forcedimension_core.dhd.getGripperAngularVelocityRad(out: c_double, ID: int = -1) → int[source]

Retrieve the estimated angular velocity of the gripper (in [rad/s]).

Note

The velocity estimator requires at least 2 position updates during the time interval defined in forcedimension_core.dhd.configGripperVelocity() in order to be able to compute the estimate. Otherwise, e.g. if there are no calls to forcedimension_core.dhd.getGripperGap() or forcedimension_core.dhd.getGripperAngularVelocityRad(), this function will error with forcedimension_core.constants.ErrorNum.TIMEOUT. For more information please refer to Velocity Estimator

Parameters:

out (c_double) – Output buffer to store the estimated angular velocity of the gripper (in [rad/s]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.getGripperAngularVelocityDeg()

forcedimension_core.dhd.getGripperFingerPos(out: MutableArray[int, float], ID: int = -1) → int[source]

Read the position (in [m]) of forefinger rest location about the X, Y, and Z axes of the force gripper structure if present.

Note

This feature only applies to devices with an gripper. See the Device Types section for more details.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
out (MutableArray[int, float]) – An output buffer to store the gripper finger position (in [m]).

Raises:

TypeError – If out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

forcedimension_core.dhd.getGripperGap(out: c_double, ID: int = -1) → int[source]

Get the gripper opening distance (in [m]).

Note

This feature only applies to devices with a gripper. See the Device Types section for more details.

Parameters:

out (c_double) – Output buffer to store the gripper opening distance (in [m]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

forcedimension_core.dhd.getGripperAngleRad()

forcedimension_core.dhd.getGripperLinearVelocity(out: c_double, ID: int = -1) → int[source]

Retrieve the estimated linear velocity of the gripper (in [m/s]).

Note

The velocity estimator requires at least 2 position updates during the time interval defined in forcedimension_core.dhd.configGripperVelocity() in order to be able to compute the estimate. Otherwise, if there are no calls to forcedimension_core.dhd.getGripperGap() or forcedimension_core.dhd.getGripperLinearVelocity(), this function will error with forcedimension_core.constants.ErrorNum.TIMEOUT. For more information please refer to Velocity Estimator

Parameters:

out (c_double) – Output buffer to store the estimated linear velocity of the gripper (in [m/s]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.getGripperThumbPos(out: MutableArray[int, float], ID: int = -1) → int[source]

Read the position (in [m]) of thumb rest location about the X, Y, and Z axes of the force gripper structure if present.

Note

This feature only applies to devices with an gripper. See the Device Types section for more details.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
out (MutableArray[int, float]) – An output buffer to store the grippper thumb position (in [m]).

Raises:

ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

forcedimension_core.dhd.getLinearVelocity(out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the estimated instanteous linear velocity (in [m/s]).

Note

The velocity estimator requires at least 2 position updates during the time interval defined in forcedimension_core.dhd.configLinearVelocity() in order to be able to compute the estimate. Otherwise, if there are no calls to forcedimension_core.dhd.getPosition() or forcedimension_core.dhd.getLinearVelocity(), this function will error with forcedimension_core.constants.ErrorNum.TIMEOUT. For more information refer to Velocity Estimator.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
out (MutableArray[int, float]) – An output buffer to store the linear velocity (in [m/s]).

Raises:

TypeError – If out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.getMaxForce(ID: int = -1) → float[source]

Retrieve the current limit (in [N]) to the force magnitude that can be applied by the haptic device. If the return value if negative, the limit is disabled and the full range of force available can be applied.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The current force limit (in N) if set, and -1.0 if no limit is enforced.

See also

forcedimension_core.dhd.setMaxForce()
forcedimension_core.dhd.getMaxTorque()
forcedimension_core.dhd.getMaxGripperForce()

forcedimension_core.dhd.getMaxGripperForce(ID: int = -1) → float[source]

Retrieve the current limit (in [N]) to the force magnitude that can be applied by the haptic device gripper. If the return value if negative, the limit is disabled and the full range of force available can be applied.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The current force limit (in [N]) if set, and -1.0 if no limit is enforced.

See also

forcedimension_core.dhd.setMaxGripperForce()
forcedimension_core.dhd.getMaxForce()
forcedimension_core.dhd.getMaxTorque()

forcedimension_core.dhd.getMaxTorque(ID: int = -1) → float[source]

Retrieve the current limit (in [Nm]) to the force magnitude that can be appliedby the haptic device. If the return value if negative, the limit is disabled and the full range of force available can be applied.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The current torque limit (in [Nm]) if set, and -1.0 if no limit is enforced.

See also

forcedimension_core.dhd.setMaxTorque()
forcedimension_core.dhd.getMaxForce()
forcedimension_core.dhd.getMaxGripperForce()

forcedimension_core.dhd.getOrientationDeg(out: MutableArray[int, float], ID: int = -1) → int[source]

For devices with a wrist structure, retrieve individual angle of each joint (in [deg]), starting with the one located nearest to the wrist base plate.

Note

This feature only applies to devices with a wrist. See the Device Types section for more details.

Note

forcedimension_core.constants.DeviceType.OMEGA6_RIGHT and forcedimension_core.constants.DeviceType.OMEGA6_LEFT have angles that are instead computed with respect to their internal reference frame, which is rotated π/4 radians around the Y axis. Please refer to your device user manual for more information on your device coordinate system.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details)
out (MutableArray[int, float]) – An output buffer to store the joint angles (in [deg]).

Raises:

TypeError – If out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

See also

forcedimension_core.dhd.getOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationRad()
forcedimension_core.dhd.getPositionAndOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationFrame()

forcedimension_core.dhd.getOrientationFrame(out: Array[int, MutableArray[int, float]], ID: int = -1) → int[source]

Retrieve the rotation matrix of the wrist structure. The identity matrix is returned for devices that do not support orientations.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
out (MutableFloatMatrixLike) – An output buffer to store the orientation frame.

Raises:

ValueError – If ID is not implicitly convertible to C char.
TypeError – If out is specified and does not support item assignment, either because it is not subscriptable or because it is not mutable.
IndexError – If out any dimension of out is less than length 3.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

forcedimension_core.dhd.getOrientationRad(out: MutableArray[int, float], ID: int = -1) → int[source]

For devices with a wrist structure, retrieve individual angle (in [rad]) of each joint, starting with the one located nearest to the wrist base plate.

Note

This feature only applies to devices with a wrist. See the Device Types section for more details.

Note

forcedimension_core.constants.DeviceType.OMEGA6_RIGHT and forcedimension_core.constants.DeviceType.OMEGA6_LEFT have angles that are instead computed with respect to their internal reference frame, which is rotated π/4 radians around the Y axis. Please refer to your device user manual for more information on your device coordinate system.

Parameters:

out (MutableArray[int, float]) – An output buffer to store the joint angles (in [rad]).
ID (int) – Device ID (see Support for Multiple Devices section for details)

Raises:

TypeError – If out is specified and does not support item. assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

See also

forcedimension_core.dhd.getOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationRad()
forcedimension_core.dhd.getPositionAndOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationFrame()

forcedimension_core.dhd.getPosition(out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the position of the end-effector about the X, Y, and Z axes. Please refer to your device user manual for more information on your device coordinate system.

Parameters:

out (MutableArray[int, float]) – An output buffer to store the position of the end-effector.
ID (int) – Device ID (see Support for Multiple Devices section for more details).

Raises:

TypeError – If out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If out is specified and len(out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.dhd.TIMEGUARD on success, -1 otherwise.

See also

forcedimension_core.dhd.getPositionAndOrientationRad()
forcedimension_core.dhd.getPositionAndOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationFrame()

forcedimension_core.dhd.getPositionAndOrientationDeg(p_out: MutableArray[int, float], o_out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the Cartesian position (in [m]), and for devices with a wrist structure, retrieve individual angle of each joint (in [deg]), starting with the one located nearest to the wrist base plate.

Note

This feature only applies to devices with a wrist. See the Device Types section for more details.

Note

forcedimension_core.constants.DeviceType.OMEGA6_RIGHT and forcedimension_core.constants.DeviceType.OMEGA6_LEFT have angles that are instead computed with respect to their internal reference frame, which is rotated π/4 radians around the Y axis. Please refer to your device user manual for more information on your device coordinate system.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
p_out (MutableArray[int, float]) – An output buffer to store the position (in [m]).
o_out (MutableArray[int, float]) – An output buffer to store the joint angles (in [deg]).

Raises:

TypeError – If p_out is specified and does not support item assignment either because its immutable or not subscriptable.
TypeError – If o_out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If p_out is specified and len(p_out) < 3.
IndexError – If o_out is specified and len(p_out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

See also

forcedimension_core.dhd.getOrientationRad()
forcedimension_core.dhd.getOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationRad()
forcedimension_core.dhd.getPositionAndOrientationFrame()

forcedimension_core.dhd.getPositionAndOrientationFrame(p_out: MutableArray[int, float], matrix_out: Array[int, MutableArray[int, float]], ID: int = -1) → int[source]

Retrieve the position (in [m]) and orientation matrix of the end-effector about the X, Y, and Z axes. Please refer to your device user manual for more information on your device coordinate system.

Note

This feature only applies to devices with a wrist. See the Device Types section for more details.

Note

forcedimension_core.constants.DeviceType.OMEGA6_RIGHT and forcedimension_core.constants.DeviceType.OMEGA6_LEFT have angles that are instead computed with respect to their internal reference frame, which is rotated π/4 radians around the Y axis. Please refer to your device user manual for more information on your device coordinate system.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

TypeError – If p_out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If p_out is specified and len(out) < 3.
TypeError – If matrix_out is specified and does not support item assignment, either because it is not subscriptable or because it is not mutable.
IndexError – If matrix_out is specified any dimension is less than length 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

See also

forcedimension_core.dhd.getOrientationRad()
forcedimension_core.dhd.getOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationRad()
forcedimension_core.dhd.getPositionAndOrientationDeg()

forcedimension_core.dhd.getPositionAndOrientationRad(p_out: MutableArray[int, float], o_out: MutableArray[int, float], ID: int = -1) → int[source]

Retrieve the position (in [m]) and for devices with a wrist structure, retrieve individual angle of each joint (in [rad]), starting with the one located nearest to the wrist base plate.

Note

This feature only applies to devices with a wrist. See the Device Types section for more details.

Note

forcedimension_core.constants.DeviceType.OMEGA6_RIGHT and forcedimension_core.constants.DeviceType.OMEGA6_LEFT have angles that are instead computed with respect to their internal reference frame, which is rotated π/4 radians around the Y axis. Please refer to your device user manual for more information on your device coordinate system.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
p_out (MutableArray[int, float]) – An output buffer to store the position (in [m]).
o_out (MutableArray[int, float]) – An output buffer to store the joint angles (in [rad]).

Raises:

TypeError – If p_out is specified and does not support item assignment either because its immutable or not subscriptable.
TypeError – If o_out is specified and does not support item assignment either because its immutable or not subscriptable.
IndexError – If p_out is specified and len(p_out) < 3.
IndexError – If o_out is specified and len(p_out) < 3.
ValueError – If ID is not implicitly convertible to C char.

Returns:

0 or forcedimension_core.constants.TIMEGUARD on success, -1 otherwise.

See also

forcedimension_core.dhd.getOrientationDeg()
forcedimension_core.dhd.getOrientationRad()
forcedimension_core.dhd.getPositionAndOrientationDeg()
forcedimension_core.dhd.getPositionAndOrientationFrame()

forcedimension_core.dhd.getSDKVersion() → VersionTuple[source]

Get the version of the Force Dimension SDK in the form (major, minor, release, revision). Versions of the Force Dimension SDK are reported as major.minor.release-revision by Force Dimension.

Returns:: A VersionTuple that represents the version.

See also

forcedimension_core._runtime.VersionTuple

forcedimension_core.dhd.getSerialNumber(ID: int = -1) → int[source]

Return the device serial number.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The serial number on success, -1 otherwise (serial numbers are non-negative).

forcedimension_core.dhd.getStatus(out: Status, ID: int = -1) → int[source]

Get a tuple representing the status of the haptic device. The status is described in the status section.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: 0 on success, -1 otherwise.

forcedimension_core.dhd.getSystemName(ID: int = -1) → str | None[source]

Return the haptic device type name. As this SDK can be used to control all of Force Dimension haptic products, this can help programmers ensure that their application is running on the appropriate target haptic device.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The device type string on success, None otherwise.

See also

forcedimension_core.dhd.getSystemType()
forcedimension_core.dhd.getSystemRev()
forcedimension_core.dhd.getVersion()

forcedimension_core.dhd.getSystemRev(ID: int = -1) → int[source]

Return the revision associated with this instance of haptic device type. As this SDK can be used to control all of Force Dimension haptic products, this can help programmers ensure that their application is running on the appropriate target haptic device.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The device revision on success, -1 otherwise.

See also

forcedimension_core.dhd.getSystemType()
forcedimension_core.dhd.getSystemName()
forcedimension_core.dhd.getVersion()

forcedimension_core.dhd.getSystemType(ID: int = -1) → DeviceType[source]

Return the Device Types. As this SDK can be used to control all of Force Dimension haptic products, this can help programmers ensure that their application is running on the appropriate target haptic device.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: The device type on success, -1 otherwise.

See also

forcedimension_core.dhd.getSystemRev()
forcedimension_core.dhd.getSystemName()
forcedimension_core.dhd.getVersion()

forcedimension_core.dhd.getVersion(ID: int = -1) → float[source]

Return the Device Controller version. As this SDK can be used to control all of Force Dimension haptic products, this can help programmers ensurethat their application is running on the appropriate version of the haptic controller.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: Returns the version on success, -1.0 otherwise (the version is non-negative).

forcedimension_core.dhd.hasActiveGripper(ID: int = -1) → bool[source]

Checks if the specified device has an active gripper.

Note

This feature only applies to devices with an active gripper. See the Device Types section for more details.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: True if the device has an active gripper, and False otherwise.

See also

forcedimension_core.dhd.isLeftHanded()
forcedimension_core.dhd.hasBase()
forcedimension_core.dhd.hasWrist()
forcedimension_core.dhd.hasActiveWrist()
forcedimension_core.dhd.hasGripper()

forcedimension_core.dhd.hasActiveWrist(ID: int = -1) → bool[source]

True if the device has an active wrist, False otherwise.

Note

This feature only applies to devices with an active wrist. See the Device Types section for more details.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: True if the device has an active wrist, and False otherwise.

See also

forcedimension_core.dhd.isLeftHanded()
forcedimension_core.dhd.hasBase()
forcedimension_core.dhd.hasWrist()
forcedimension_core.dhd.hasGripper()
forcedimension_core.dhd.hasActiveGripper()

forcedimension_core.dhd.hasBase(ID: int = -1) → bool[source]

True if the device has a base, False otherwise.

Note

This feature only applies to devices with a base. See the Device Types section for more details.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: True if the device has a base, and False otherwise.

See also

forcedimension_core.dhd.isLeftHanded()
forcedimension_core.dhd.hasWrist()
forcedimension_core.dhd.hasActiveWrist()
forcedimension_core.dhd.hasGripper()
forcedimension_core.dhd.hasActiveGripper()

forcedimension_core.dhd.hasGripper(ID: int = -1) → bool[source]

Checks if the device has a gripper.

Note

This feature only applies to devices with a gripper. See the Device Types section for more details.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: True if the device has a gripper, and False otherwise.

See also

forcedimension_core.dhd.isLeftHanded()
forcedimension_core.dhd.hasBase()
forcedimension_core.dhd.hasWrist()
forcedimension_core.dhd.hasActiveWrist()
forcedimension_core.dhd.hasActiveGripper()

forcedimension_core.dhd.hasWrist(ID: int = -1) → bool[source]

True if the device has a wrist, False otherwise.

Note

This feature only applies to devices with a wrist. See the Device Types section for more details.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: True if the device has a wrist, and False otherwise.

See also

forcedimension_core.dhd.isLeftHanded()
forcedimension_core.dhd.hasBase()
forcedimension_core.dhd.hasActiveWrist()
forcedimension_core.dhd.hasGripper()
forcedimension_core.dhd.hasActiveGripper()

forcedimension_core.dhd.isLeftHanded(ID: int = -1) → bool[source]

True if the device is configured for left-handed use, False otherwise.

Note

This feature only applies to devices that can be configured for handedness. See the Device Types section for more details.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: True if the device is configured for left-handed use, and False otherwise.

See also

forcedimension_core.dhd.hasBase()
forcedimension_core.dhd.hasWrist()
forcedimension_core.dhd.hasActiveWrist()
forcedimension_core.dhd.hasGripper()
forcedimension_core.dhd.hasActiveGripper()

forcedimension_core.dhd.open() → int[source]

Open a connection to the first available device connected to the system. The order in which devices are opened persists until devices are added or removed.

If this call is successful, the default device ID is set to the newly opened device. See the Support for Multiple Devices section for more information on using multiple devices on the same computer.

Returns:: The device ID on success, -1 otherwise.

See also

forcedimension_core.dhd.openType()
forcedimension_core.dhd.openSerial()
forcedimension_core.dhd.openID()
forcedimension_core.dhd.close()

forcedimension_core.dhd.openID(index: int) → int[source]

Open a connection to one particular device connected to the system. The order in which devices are opened persists until devices are added or removed. If the device at the specified index is already opened, its device ID is returned.

If this call is successful, the default device ID is set to the newly opened device. See the Support for Multiple Devices section for more information on using multiple devices on the same computer.

Parameters:: index (int) – The device enumeration index, as assigned by the underlying operating system (must be between 0 and the number of devices connected to the system).
Raises:: ctypes.ArgumentError – If index is not convertible to C int.
Returns:: The device ID on success, -1 otherwise.

See also

forcedimension_core.dhd.open()
forcedimension_core.dhd.openType()
forcedimension_core.dhd.openSerial()
forcedimension_core.dhd.close()

forcedimension_core.dhd.openSerial(serial: int) → int[source]

Open a connection to the device with a given serial number (available on recent models only).

If this call is successful the default device ID is set to the newly opened device. See the Support for Multiple Devices section for more information on using multiple devices on the same computer.

Parameters:: serial (int) – Requested system serial number.
Returns:: The device ID on success, -1 otherwise.

See also

forcedimension_core.dhd.open()
forcedimension_core.dhd.openID()
forcedimension_core.dhd.openType()
forcedimension_core.dhd.close()

forcedimension_core.dhd.openType(device_type: DeviceType) → int[source]

Open a connection to the first device of a given type connected to the system. The order in which devices are opened persists until devices are added or removed.

If this call is successful, the default device ID is set to the newly opened device. See the Support for Multiple Devices section for more information on using multiple devices on the same computer.

Parameters:: device_type (int) – Requested DeviceType to open.
Returns:: The device ID on success, -1 otherwise.

See also

forcedimension_core.dhd.open()
forcedimension_core.dhd.openSerial()
forcedimension_core.dhd.openID()
forcedimension_core.dhd.close()

forcedimension_core.dhd.reset(ID: int = -1) → int[source]

Puts the device in RESET mode.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: 0 on success, -1 otherwise.

forcedimension_core.dhd.setBaseAngleXDeg(angle: float, ID: int = -1) → int[source]

Set the device base plate angle around the X axis (in [deg]). Please refer to your device user manual for more information on your device coordinate system.

Parameters:

angle (float) – device base plate angle around the X axis (in [deg]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setBaseAngleXRad()
forcedimension_core.dhd.getBaseAngleXRad()
forcedimension_core.dhd.getBaseAngleXDeg()

forcedimension_core.dhd.setBaseAngleXRad(angle: float, ID: int = -1) → int[source]

Set the device base plate angle around the X axis (in [rad]). Please refer to your device user manual for more information on your device coordinate system.

Parameters:

angle (float) – device base plate angle around the X axis (in [rad]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setBaseAngleXDeg()
forcedimension_core.dhd.getBaseAngleXRad()
forcedimension_core.dhd.getBaseAngleXDeg()

forcedimension_core.dhd.setBaseAngleZDeg(angle: float, ID: int = -1) → int[source]

Set the device base plate angle around the Z axis (in [deg]). Please refer to your device user manual for more information on your device coordinate system.

Parameters:

angle (float) – device base plate angle around the Z axis (in [deg])
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If angle is not implicitly convertible to C double
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setBaseAngleZRad()
forcedimension_core.dhd.getBaseAngleZRad()
forcedimension_core.dhd.getBaseAngleZDeg()

forcedimension_core.dhd.setBaseAngleZRad(angle: float, ID: int = -1) → int[source]

Set the device base plate angle around the Z axis (in [rad]). Please refer to your device user manual for more information on your device coordinate system.

Parameters:

angle (float) – device base plate angle around the Z axis (in [rad]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setBaseAngleZDeg()
forcedimension_core.dhd.getBaseAngleZRad()
forcedimension_core.dhd.getBaseAngleZDeg()

forcedimension_core.dhd.setBrakes(enable: bool, ID: int = -1) → int[source]

Enable/disable [device electromagnetic brakes].

Parameters:

enable (bool) – True to turn on the device electromagnetic brakes, False to turn off the device electromagnetic brakes.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If val is not implicitly convertible to C bool.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.enableForce()
forcedimension_core.dhd.enableGripperForce()
forcedimension_core.dhd.stop()

forcedimension_core.dhd.setDevice(ID: int = -1) → int[source]

Select the default device that will receive the SDK commands. The SDK supports multiple devices. This routine allows the programmer to decide which device the SDK single device calls will address. Any subsequent SDK call that does not specifically mention the device ID in its parameter list will be sent to that device.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: 0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getDeviceID()

forcedimension_core.dhd.setDeviceAngleDeg(angle: float, ID: int = -1) → int[source]

Set the device base plate angle around the (inverted) Y axis. Please referto your device user manual for more information on your device coordinate system. An angle value of 0 refers to the device “upright” position, with its base plate perpendicular to axis X. An angle value of 90 refers to the device base plate resting horizontally.

Parameters:

angle (float) – device base plate angle [deg]
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If angle is not implicitly convertible to C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setDeviceAngleRad()
forcedimension_core.dhd.getDeviceAnglDeg()
forcedimension_core.dhd.getDeviceAngleRad()

forcedimension_core.dhd.setDeviceAngleRad(angle: float, ID: int = -1) → int[source]

Set the device base plate angle around the (inverted) Y axis. Please refer to your device user manual for more information on your device coordinate system. An angle value of 0 refers to the device “upright” position, with its base plate perpendicular to X axis. An angle value of π/2 refers to the device base plate resting horizontally.

Parameters:

angle (float) – device base plate angle [rad]
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If angle is not implicitly convertible to C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setDeviceAngleDeg()
forcedimension_core.dhd.getDeviceAnglDeg()
forcedimension_core.dhd.getDeviceAngleRad()

forcedimension_core.dhd.setEffectorMass(mass: float, ID: int = -1) → int[source]

Define the mass of the end-effector (in [kg]). This function is required to provide accurate gravity compensation when custom-made or modified end-effectors are used.

Parameters:

mass (float) – The actual end-effector mass (in [kg]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If angle is not implicitly convertible to C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getEffectorMass()
forcedimension_core.dhd.setStandardGravity()
forcedimension_core.dhd.setGravityCompensation()

forcedimension_core.dhd.setForce(f: Array[int, float], ID: int = -1) → int[source]

Set the desired force (in [N]) about the X, Y, and Z axes to be applied to the end-effector of the device.

Parameters:

f (VectorLike) – Translation force vector (fx, fy, fz) (in [N]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.
ctypes.ArgumentError – If any elements of f are not implicitly convertible to C double.
IndexError – If len(f) < 3).
TypeError – If f is not subscriptable.

Returns:

0 or forcedimension_core.constants.MOTOR_SATURATED on success, -1 otherwise.

See also

forcedimension_core.dhd.direct.setForceAndTorque()
forcedimension_core.dhd.direct.setForceAndGripperForce()
forcedimension_core.dhd.direct.setForceAndTorqueAndGripperForce()
forcedimension_core.dhd.direct.getForce()
forcedimension_core.dhd.direct.getForceAndTorque()
forcedimension_core.dhd.direct.getForceAndTorqueAndGripperForce()

forcedimension_core.dhd.setForceAndGripperForce(f: Array[int, float], fg: float, ID: int = -1) → int[source]

Set the desired force to be applied to the end-effector about the X, Y, and Z axes as well as the force applied by force gripper of the device.

Parameters:

ID (int) – Device ID (see Support for Multiple Devices section for details).
f (VectorLike) – Translational force vector (fx, fy, fz) where fx, fy, and fz are the translation force (in [N]) about the X, Y, and Z axes, respectively.
fg (float) – Grasping force of the gripper (in [N]).

Raises:

ctypes.ArgumentError – If any elements of f is not implicitly convertible to a C double.
IndexError – If len(f) < 3
TypeError – If f is not subscriptable.
ctypes.ArgumentError – If gripper_force is not implicitly convertible to a C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.
IndexError – If len(f) < 3

Returns:

0 or forcedimension_core.constants.MOTOR_SATURATED on success, -1 otherwise.

See also

forcedimension_core.dhd.setForce()
forcedimension_core.dhd.setForceAndTorque()
forcedimension_core.dhd.setForceAndTorqueAndGripperForce()
forcedimension_core.dhd.getForce()
forcedimension_core.dhd.getForceAndTorque()
forcedimension_core.dhd.getForceAndTorqueAndGripperForce()

forcedimension_core.dhd.setForceAndTorque(f: Array[int, float], t: Array[int, float], ID: int = -1) → int[source]

Set the desired force and torque vectors to be applied to the device end-effector.

Parameters:

f (VectorLike) – Translational force vector (fx, fy, fz) where fx, fy, and fz are the translation force (in [N]) on the end-effector about the X, Y, and Z axes, respectively.
t (VectorLike) – Torque vector (tx, ty, tz) where tx, ty, and tz are the torque (in [Nm]) on the end-effector about the X, Y, and Z axes, respectively.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.
ctypes.ArgumentError – If any elements of f is not implicitly convertible to a C double.
IndexError – If len(f) < 3.
TypeError – If f is not subscriptable.
ctypes.ArgumentError – If any elements of t is not implicitly convertible to a C double.
IndexError – If len(t) < 3.
TypeError – If t is not subscriptable.
ctypes.ArgumentError – If gripper_force is not implicitly convertible to a C double.
IndexError – If len(f) < 3.
IndexError – If len(t) < 3.

Returns:

0 or forcedimension_core.constants.MOTOR_SATURATED on success, and -1 otherwise.

See also

forcedimension_core.dhd.setForce()
forcedimension_core.dhd.setForceAndTorqueAndGripperForce()
forcedimension_core.dhd.getForce()
forcedimension_core.dhd.getForceAndTorque()
forcedimension_core.dhd.getForceAndTorqueAndGripperForce()

forcedimension_core.dhd.setForceAndTorqueAndGripperForce(f: Array[int, float], t: Array[int, float], fg: float, ID: int = -1) → int[source]

Set the desired force and torque vectors to be applied to the device end-effector and gripper. Forces and torques are about the X, Y, and Z axes.

Parameters:

f (VectorLike) – Translational force vector (fx, fy, fz) where fx, fy, and fz are the translation force (in [N]) on the end-effector about the X, Y, and Z axes, respectively.
t (VectorLike) – Torque vector (tx, ty, tz) where tx, ty, and tz are the torque (in [Nm]) on the end-effector about the X, Y, and Z axes, respectively.
fg (float) – Grasping force of the gripper (in [N]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.
ctypes.ArgumentError – If any elements of f is not implicitly convertible to a C double.
IndexError – If len(f) < 3.
TypeError – If f is not subscriptable.
ctypes.ArgumentError – If any elements of t is not implicitly convertible to a C double.
IndexError – If len(t) < 3.
TypeError – If t is not subscriptable.
ctypes.ArgumentError – If gripper_force is not implicitly convertible to a C double.
IndexError – If len(f) < 3.
IndexError – If len(t) < 3.

Returns:

0 or forcedimension_core.constants.MOTOR_SATURATED on success, and -1 otherwise.

See also

forcedimension_core.dhd.setForce()
forcedimension_core.dhd.setForceAndTorque()
forcedimension_core.dhd.getForce()
forcedimension_core.dhd.getForceAndTorque()
forcedimension_core.dhd.getForceAndTorqueAndGripperForce()

forcedimension_core.dhd.setGravityCompensation(enable: bool, ID: int = -1) → int[source]

Enable/disable gravity compensation.

Parameters:

enable (bool) – True to turn on gravity compensation, False to turn off gravity compensation.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If val is not implicitly convertible to C bool.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.setStandardGravity()

forcedimension_core.dhd.setMaxForce(limit: float, ID: int = -1) → int[source]

Define a limit (in [N]) to the magnitude of the force that can be applied to the haptic device. The limit applies to all forcedimension_core.dhd.setForce() and related calls, and ensures the force applied to the device end-effector remains below the requested value. If a negative limit is set, there is no max force and the full range of force can be applied.

Note

The force limit enforced only applies to forces set programatically by dhd.libdhd.setForce(). Setting DAC values directly will bypass this limit.

Parameters:

limit (float) – Max magnitude of force that can be applied (in [N]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If limit is not implicitly convertible to C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getMaxForce()
forcedimension_core.dhd.setMaxTorque()
forcedimension_core.dhd.setMaxGripperForce()
forcedimension_core.dhd.expert.setMaxPower()
forcedimension_core.dhd.expert.setMaxUsablePower()

forcedimension_core.dhd.setMaxGripperForce(limit: float, ID: int = -1) → int[source]

Define a limit (in [N]) to the magnitude of the force that can be applied to the haptic device gripper. The limit applies to all forcedimension_core.dhd.setForceAndTorqueAndGripperForce() and related calls, and ensures the force applied to the device gripper remains below the requested value. If a negative limit is set, there is no max force and the full range of force can be applied.

Note

The force limit enforced only applies to forces set programatically by forcedimension_core.dhd.setForceAndTorqueAndGripperForce(). Setting DAC values directly will bypass this limit.

Parameters:

limit (float) – Max magnitude of force that can be applied (in [N]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If limit is not implicitly convertible to C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getMaxGripperForce()
forcedimension_core.dhd.getMaxForce()
forcedimension_core.dhd.setMaxTorque()
forcedimension_core.dhd.expert.setMaxPower()
forcedimension_core.dhd.expert.setMaxUsablePower()

forcedimension_core.dhd.setMaxTorque(limit: float, ID: int = -1) → int[source]

Define a limit (in [Nm]) to the magnitude of the torque that can be applied to the haptic device. The limit applies to all forcedimension_core.dhd.libdhd.setTorque() and related calls, and ensures the torque applied to the device end-effector remains below the requested value. If a negative limit is set, there is no max force and the full range of force can be applied.

Note

The torque limit enforced only applies to torques set programatically by forcedimension_core.dhd.setTorque(). Setting DAC values directly will bypass this limit.

Parameters:

limit (float) – max magnitude of torque that can be applied (in [Nm]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If limit is not implicitly convertible to C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.getMaxTorque()
forcedimension_core.dhd.setMaxForce()
forcedimension_core.dhd.setMaxGripperForce()
forcedimension_core.dhd.expert.setMaxPower()
forcedimension_core.dhd.expert.setMaxUsablePower()

forcedimension_core.dhd.setOutput(output: int, ID: int = -1) → int[source]

Set the user programmable output bits on devices that support it.

Note

For more information on what features devices support, see the Device Types section for more details.

Parameters:

output (int) – A bitwise mask that toggles the programmable output bits.
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If ID is not implicitly convertible to C char.
ctypes.ArgumentError – If output is not implicitly convertible to C uint.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.setStandardGravity(g: float, ID: int = -1) → int[source]

Set the standard gravity constant used in gravity compensation in (in [m/s^2]). By default, the constant is set to 9.81 m/s^2.

Parameters:

g (float) – standard gravity constant (in [m/s^2]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If g is not implicitly convertible to C double.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

forcedimension_core.dhd.setGravityCompensation()

forcedimension_core.dhd.setVibration(f: float, A: float, profile: int = 0, ID: int = -1) → int[source]

Apply a vibration to the end-effector. The vibration is added to the force requested by forcedimension_core.dhd.setForce().

Parameters:

f (float) – Vibration frequency (in [Hz]).
A (float) – Vibration amplitude (in [m]).
type (int) – Vibration profile (unused, reserved for future use).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If f is not implicitly convertible to C double.
ctypes.ArgumentError – If A is not implicitly convertible to C double.
ctypes.ArgumentError – If profile is not implicitly convertible to C int.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.setForce()

forcedimension_core.dhd.stop(ID: int = -1) → int[source]

Stop the device. This routine disables the force on the haptic device and puts it into BRAKE mode.

Parameters:: ID (int) – Device ID (see Support for Multiple Devices section for details).
Raises:: ctypes.ArgumentError – If ID is not implicitly convertible to C char.
Returns:: 0 on success, -1 otherwise.

See also

forcedimension_core.dhd.enableForce()
forcedimension_core.dhd.enableGripperForce()
forcedimension_core.dhd.setBrakes()

forcedimension_core.dhd.waitForReset(timeout: int | None = None, ID: int = -1) → int[source]

Puts the device in RESET mode and waits for the user to calibrate the device. Optionally, a timeout can be defined after which the call returns even if calibration has not occured.

If the timeout is reached, the call returns with error and forcedimension_core.dhd.dhdErrorGetLast() will return forcedimension_core.constants.ErrorNum.TIMEOUT.

Parameters:

timeout (Optional[int]) – Maximum time to wait for calibration (in [ms]).
ID (int) – Device ID (see Support for Multiple Devices section for details).

Raises:

ctypes.ArgumentError – If not implicitly convertible to C int.
ctypes.ArgumentError – If ID is not implicitly convertible to C char.

Returns:

0 on success, -1 otherwise.

See also

forcedimension_core.dhd.reset()