Impedance control

Impedance control allows implementation of compliant robot behavior

Joint impedance control

set_joint_stiffness

LibIiwa.set_joint_stiffness(stiffness: Union[List[float], ndarray]) → bool

Define the stiffness for joint impedance control

Parameters:

stiffness (7-element list or numpy.ndarray) – Joint stiffness in Nm/rad [0.0, Inf)

Raises:

  • AssertionError – If the length of the stiffness is not equal to the number of joints

  • AssertionError – If the stiffness is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> stiffness = [400.0, 350.0, 300.0, 250.0, 200.0, 150.0, 100.0]
>>> iiwa.set_joint_stiffness(stiffness)
True

set_joint_damping

LibIiwa.set_joint_damping(damping: Union[List[float], ndarray]) → bool

Define the damping for joint impedance control

Parameters:

damping (7-element list or numpy.ndarray) – Joint damping [0.0, 1.0]

Raises:

  • AssertionError – If the length of the damping is not equal to the number of joints

  • AssertionError – If the damping is not in the range [0.0, 1.0]

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> damping = [0.7, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1]
>>> iiwa.set_joint_damping(damping)
True

Cartesian impedance control

set_cartesian_stiffness

LibIiwa.set_cartesian_stiffness(translational: Union[List[float], ndarray] = [2000.0, 2000.0, 2000.0], rotational: Union[List[float], ndarray] = [200.0, 200.0, 200.0], null_space: float = 100) → bool

Define the stiffness (translational and rotational) for Cartesian impedance control

Note

This method also affects the Cartesian impedance controller with overlaid force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational stiffness in N/m [0.0, 5000.0] (default: [2000.0, 2000.0, 2000.0])

  • rotational (3-element list or numpy.ndarray) – Rotational stiffness in Nm/rad [0.0, 300.0] (default: [200.0, 200.0, 200.0])

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, 5000.0]

  • AssertionError – If the rotational is not in the range [0.0, 300.0]

  • AssertionError – If the null_space is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> translational = [2000.0, 3000.0, 4000.0]
>>> rotational = [50.0, 100.0, 150.0]
>>> iiwa.set_cartesian_stiffness(translational, rotational, null_space=100)
True

set_cartesian_damping

LibIiwa.set_cartesian_damping(translational: Union[List[float], ndarray] = [0.7, 0.7, 0.7], rotational: Union[List[float], ndarray] = [0.7, 0.7, 0.7], null_space: float = 0.7) → bool

Define the damping (translational and rotational) for Cartesian impedance control

Note

This method also affects the Cartesian impedance controller with overlaid force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational damping [0.1, 1.0] (default: [0.7, 0.7, 0.7])

  • rotational (3-element list or numpy.ndarray) – Rotational damping [0.1, 1.0] (default: [0.7, 0.7, 0.7])

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.1, 1.0]

  • AssertionError – If the rotational is not in the range [0.1, 1.0]

  • AssertionError – If the null_space is not in the range [0.3, 1.0]

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> translational = [0.2, 0.3, 0.4]
>>> rotational = [0.5, 0.6, 0.7]
>>> iiwa.set_cartesian_damping(translational, rotational, null_space=0.5)
True

set_cartesian_additional_control_force

LibIiwa.set_cartesian_additional_control_force(translational: Union[List[float], ndarray] = [0.0, 0.0, 0.0], rotational: Union[List[float], ndarray] = [0.0, 0.0, 0.0]) → bool

Define the additional control force (translational and rotational) for Cartesian impedance control

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational additional control force in N (default: [0.0, 0.0, 0.0])

  • rotational (3-element list or numpy.ndarray) – Rotational additional control force in Nm (default: [0.0, 0.0, 0.0])

Raises:

AssertionError – If the length of the translational and rotational is not equal to the number of axes

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> translational = [-10.0, -20.0, -30.0]
>>> rotational = [10.0, 20.0, 30.0]
>>> iiwa.set_cartesian_additional_control_force(translational, rotational)
True

set_cartesian_max_control_force

LibIiwa.set_cartesian_max_control_force(translational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], rotational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], add_stop_condition: bool = False) → bool

Define the limitation of the maximum force (translational) / torque (rotational) on the TCP

Note

This method also affects the Cartesian impedance controller with overlaid force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Maximum force in N (default: [1e6, 1e6, 1e6])

  • rotational (3-element list or numpy.ndarray) – Maximum torque in Nm (default: [1e6, 1e6, 1e6])

  • add_stop_condition (bool) – Whether to cancel the motion if the maximum force at the TCP is exceeded (default: False)

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, Inf)

  • AssertionError – If the rotational is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# set Cartesian maximum control force and cancel the motion if the maximum force is exceeded
>>> translational = [10.0, 20.0, 30.0]
>>> rotational = [10.0, 20.0, 30.0]
>>> iiwa.set_cartesian_max_control_force(translational, rotational, add_stop_condition=True)
True

set_cartesian_max_velocity

LibIiwa.set_cartesian_max_velocity(translational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], rotational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0]) → bool

Define the maximum Cartesian velocity at which motion is aborted if the limit is exceeded

Note

This method also affects the Cartesian impedance controller with overlaid force oscillation

The Cartesian velocity will be automatically converted to mm/s before sending to the robot. Assign high values to the degrees of freedom that are not to be limited

Parameters:

  • translational (3-element list or numpy.ndarray) – Maximum Cartesian velocity in m/s (default: [1e6, 1e6, 1e6])

  • rotational (3-element list or numpy.ndarray) – Maximum Cartesian velocity in rad/s (default: [1e6, 1e6, 1e6])

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, Inf)

  • AssertionError – If the rotational is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# abort the motion for a maximum Cartesian velocity of 10  m/s in the z-axis
>>> translational = [1e6, 1e6, 10.0]
>>> iiwa.set_cartesian_max_velocity(translational)
True

set_cartesian_max_path_deviation

LibIiwa.set_cartesian_max_path_deviation(translational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], rotational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], millimeters: bool = False, degrees: bool = False) → bool

Define the maximum permissible Cartesian path deviation at which motion is aborted if the limit is exceeded

Note

This method also affects the Cartesian impedance controller with overlaid force oscillation

Assign high values to the degrees of freedom that are not to be limited

Parameters:

  • translational (3-element list or numpy.ndarray) – Maximum path deviation (default: [1e6, 1e6, 1e6])

  • rotational (3-element list or numpy.ndarray) – Maximum path deviation (default: [1e6, 1e6, 1e6])

  • millimeters (bool) – Whether the translation is in millimeters or meters (default: meters)

  • degrees (bool) – Whether the rotation is in degrees or radians (default: radians)

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, Inf)

  • AssertionError – If the rotational is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# abort the motion for a maximum Cartesian path deviation of 0.1 m in the y-axis
>>> translational = [1e6, 0.1, 1e6]
>>> iiwa.set_cartesian_max_velocity(translational)
True

Cartesian sine impedance control

class libiiwa.CartesianDOF(value)

Bases: Enum

Cartesian DOF

A = 3
B = 4
C = 5
X = 0
Y = 1
Z = 2
class libiiwa.CartesianPlane(value)

Bases: Enum

Cartesian plane

XY = 0
XZ = 1
YZ = 2

overlay_desired_force

LibIiwa.overlay_desired_force(dof: CartesianDOF, force: float, stiffness: float) → bool

Overlay a constant force, in one Cartesian direction, that does not change over time

Note

Because this method creates a new controller instance, any previous impedance control configuration calls will have no effect. If applicable, configure the impedance controller after calling this method

Parameters:

  • dof (CartesianDOF) – Cartesian DOF

  • force (float) – Overlaid constant force. In N for translational DOFs, in Nm for rotational DOFs

  • stiffness (float) – Stiffness value for the specified DOF. In N/m for translational DOFs, in Nm/rad for rotational DOFs

Raises:

  • AssertionError – If the force is not in the range [0.0, Inf)

  • AssertionError – If the stiffness is not in the range [0.0, 5000] for translational DOFs or [0.0, 300] for rotational DOFs

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# exert an additional pressing constant force of 5 N in the Z direction
>>> iiwa.overlay_desired_force(libiiwa.CartesianDOF.Z, 5.0, 4000.0)
True

overlay_sine_pattern

LibIiwa.overlay_sine_pattern(dof: CartesianDOF, frequency: float, amplitude: float, stiffness: float) → bool

Overlay a simple force oscillation in one Cartesian direction

Note

Because this method creates a new controller instance, any previous impedance control configuration calls will have no effect. If applicable, configure the impedance controller after calling this method

Parameters:

  • dof (CartesianDOF) – Cartesian DOF

  • frequency (float) – Frequency of the oscillation in Hz

  • amplitude (float) – Amplitude of the oscillation which is overlaid in the direction of the specified DOF. In N for translational DOFs, in Nm for rotational DOFs

  • stiffness (float) – Stiffness value for the specified DOF. In N/m for translational DOFs, in Nm/rad for rotational DOFs

Raises:

  • AssertionError – If the frequency is not in the range [0.0, 15.0]

  • AssertionError – If the amplitude is not in the range [0.0, Inf)

  • AssertionError – If the stiffness is not in the range [0.0, 5000] for translational DOFs or [0.0, 300] for rotational DOFs

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# move in a wave path with a deflection of about 0.10 meters (derived from amplitude and stiffness) 
# and a frequency of 2 Hz in the X direction
>>> iiwa.overlay_sine_pattern(libiiwa.CartesianDOF.X, 2.0, 50.0, 500.0)
True

overlay_lissajous_pattern

LibIiwa.overlay_lissajous_pattern(plane: CartesianPlane, frequency: float, amplitude: float, stiffness: float) → bool

Overlay a 2-dimensional oscillation in one plane

Note

Because this method creates a new controller instance, any previous impedance control configuration calls will have no effect. If applicable, configure the impedance controller after calling this method

The parameters of the second DOF of the plane are calculated to generate a Lissajous curve

  • amplitude ratio (1st DOF : 2nd DOF): 1 : 1

  • frequency ratio (1st DOF : 2nd DOF): 1 : 0.4

  • phase offset between 1st and 2nd DOF: pi / 2

Parameters:

  • dof (CartesianPlane) – Cartesian plane

  • frequency (float) – Frequency of the oscillation for the first DOF of the plane in Hz

  • amplitude (float) – Amplitude of the oscillation for both DOFs in N

  • stiffness (float) – Stiffness value for both DOFs in N/m

Raises:
Returns:

True if successful, False otherwise

Return type:

bool

Example:

# generate an oscillation with a frequency ratio X : Y of 1 : 0.4
>>> iiwa.overlay_lissajous_pattern(libiiwa.CartesianPlane.XY, 10.0, 50.0, 500.0)
True

overlay_spiral_pattern

LibIiwa.overlay_spiral_pattern(plane: CartesianPlane, frequency: float, amplitude: float, stiffness: float, total_time: float) → bool

Overlay a spiral-shaped force oscillation in one plane

Note

Because this method creates a new controller instance, any previous impedance control configuration calls will have no effect. If applicable, configure the impedance controller after calling this method

The force characteristic is created by overlaying 2 sinusoidal force oscillations

  • phase offset between 1st and 2nd DOF: pi / 2

Parameters:

  • dof (CartesianPlane) – Cartesian plane

  • frequency (float) – Frequency of the oscillation for both DOFs in Hz

  • amplitude (float) – Amplitude of the oscillation for both DOFs in N

  • stiffness (float) – Stiffness value for both DOFs in N/m

  • total_time (float) – Total time for the spiral-shaped oscillation in seconds

Raises:
Returns:

True if successful, False otherwise

Return type:

bool

Example:

# increase the force in a spiral to a maximum of 100 N.
# The force curve should rotate once per second around the starting point of the spiral.
# The force spiral should rise and fall within 10 seconds
>>> iiwa.overlay_spiral_pattern(libiiwa.CartesianPlane.XY, 1.0, 100.0, 500.0, 10)
True

set_cartesian_amplitude

LibIiwa.set_cartesian_amplitude(translational: Union[List[float], ndarray] = [0.0, 0.0, 0.0], rotational: Union[List[float], ndarray] = [0.0, 0.0, 0.0]) → bool

Define the amplitude of the force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational amplitude in N (default: [0.0, 0.0, 0.0])

  • rotational (3-element list or numpy.ndarray) – Rotational amplitude in Nm (default: [0.0, 0.0, 0.0])

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, Inf)

  • AssertionError – If the rotational is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# TODO
>>> 
>>> iiwa.set_cartesian_amplitude()
True

set_cartesian_frequency

LibIiwa.set_cartesian_frequency(translational: Union[List[float], ndarray] = [0.0, 0.0, 0.0], rotational: Union[List[float], ndarray] = [0.0, 0.0, 0.0]) → bool

Define the frequency of the force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational frequency in Hz (default: [0.0, 0.0, 0.0])

  • rotational (3-element list or numpy.ndarray) – Rotational frequency in Hz (default: [0.0, 0.0, 0.0])

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, 15.0]

  • AssertionError – If the rotational is not in the range [0.0, 15.0]

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# TODO
>>> 
>>> iiwa.set_cartesian_frequency()
True

set_cartesian_phase

LibIiwa.set_cartesian_phase(translational: Union[List[float], ndarray] = [0.0, 0.0, 0.0], rotational: Union[List[float], ndarray] = [0.0, 0.0, 0.0], degrees: bool = False) → bool

Define the phase offset of the force oscillation at the start of the force overlay

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational phase (default: [0.0, 0.0, 0.0])

  • rotational (3-element list or numpy.ndarray) – Rotational phase (default: [0.0, 0.0, 0.0])

  • degrees (bool) – Whether the rotational is in degrees or radians (default: radians)

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, Inf)

  • AssertionError – If the rotational is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# TODO
>>> 
>>> iiwa.set_cartesian_phase()
True

set_cartesian_bias

LibIiwa.set_cartesian_bias(translational: Union[List[float], ndarray] = [0.0, 0.0, 0.0], rotational: Union[List[float], ndarray] = [0.0, 0.0, 0.0]) → bool

Define a constant force overlaid (bias) in addition to the overlaid force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational bias in N (default: [0.0, 0.0, 0.0])

  • rotational (3-element list or numpy.ndarray) – Rotational bias in Nm (default: [0.0, 0.0, 0.0])

Raises:

AssertionError – If the length of the translational and rotational is not equal to the number of axes

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# TODO
>>> 
>>> iiwa.set_cartesian_bias()
True

set_cartesian_force_limit

LibIiwa.set_cartesian_force_limit(translational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], rotational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0]) → bool

Define the force limit of the force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational force limit in N (default: [1e6, 1e6, 1e6])

  • rotational (3-element list or numpy.ndarray) – Rotational force limit in Nm (default: [1e6, 1e6, 1e6])

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, Inf)

  • AssertionError – If the rotational is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# TODO
>>> 
>>> iiwa.set_cartesian_force_limit()
True

set_cartesian_position_limit

LibIiwa.set_cartesian_position_limit(translational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], rotational: Union[List[float], ndarray] = [1000000.0, 1000000.0, 1000000.0], millimeters: bool = False, degrees: bool = False) → bool

Define the maximum deflection due to the force oscillation

Parameters:

  • translational (3-element list or numpy.ndarray) – Translational maximum deflection (default: [1e6, 1e6, 1e6])

  • rotational (3-element list or numpy.ndarray) – Rotational maximum deflection (default: [1e6, 1e6, 1e6])

  • millimeters (bool) – Whether the translation is in millimeters or meters (default: meters)

  • degrees (bool) – Whether the rotation is in degrees or radians (default: radians)

Raises:

  • AssertionError – If the length of the translational and rotational is not equal to the number of axes

  • AssertionError – If the translational is not in the range [0.0, Inf)

  • AssertionError – If the rotational is not in the range [0.0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

# TODO
>>> 
>>> iiwa.set_cartesian_position_limit()
True

set_cartesian_total_time

LibIiwa.set_cartesian_total_time(value: float) → bool

Define the overall duration of the force oscillation

Parameters:

value (float) – Duration of the force oscillation in seconds

Raises:

AssertionError – If the value is not in the range [0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> iiwa.set_cartesian_total_time(60)
True

set_cartesian_rise_time

LibIiwa.set_cartesian_rise_time(value: float) → bool

Define the rise time of the force oscillation

Parameters:

value (float) – Rise time of the force oscillation in seconds

Raises:

AssertionError – If the value is not in the range [0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> iiwa.set_cartesian_rise_time(5)
True

set_cartesian_hold_time

LibIiwa.set_cartesian_hold_time(value: float) → bool

Define the hold time of the force oscillation

Parameters:

value (float) – Hold time of the force oscillation in seconds

Raises:

AssertionError – If the value is not in the range [0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> iiwa.set_cartesian_hold_time(50)
True

set_cartesian_fall_time

LibIiwa.set_cartesian_fall_time(value: float) → bool

Define the fall time of the force oscillation

Parameters:

value (float) – Fall time of the force oscillation in seconds

Raises:

AssertionError – If the value is not in the range [0, Inf)

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> iiwa.set_cartesian_fall_time(5)
True

set_cartesian_stay_active_until_pattern_finished

LibIiwa.set_cartesian_stay_active_until_pattern_finished(active: bool) → bool

Define whether the oscillation is terminated or continued after the end of the motion

Parameters:

active (bool) – Whether the oscillation is continued after the end of the motion

Returns:

True if successful, False otherwise

Return type:

bool

Example:

>>> iiwa.set_cartesian_stay_active_until_pattern_finished(True)
True