com.kuka.roboticsAPI.motionModel.controlModeModel
Class CartesianImpedanceControlMode

java.lang.Object
  com.kuka.roboticsAPI.motionModel.controlModeModel.AbstractMotionControlMode
      com.kuka.roboticsAPI.motionModel.controlModeModel.AbstractImpedanceControlMode
          com.kuka.roboticsAPI.motionModel.controlModeModel.CartesianImpedanceControlMode

All Implemented Interfaces:

IImpedanceMotionControlMode, IMotionControlMode

Direct Known Subclasses:

CartesianSineImpedanceControlMode

public class CartesianImpedanceControlMode
extends AbstractImpedanceControlMode

This control mode indicates cartesian impedance.

The mode always uses commanded values for the start position of the next motion unless the user sets the 'forceMeasuredValuesForNextMotion'-flag.

Note: The following default settings:
Stiffness [2000 N/m, 2000 N/m, 2000 N/m, 200 Nm/rad, 200 Nm/rad, 200 Nm/rad]
Damping [0.7, 0.7, 0.7, 0.7, 0.7, 0.7]

See Also:

CartesianSineImpedanceControlMode

This element is not in its final state and might change in future versions.

Nested Class Summary

class

CartesianImpedanceControlMode.CartImpBuilder Inner Class to parameterize the CartesianImpedanceControlMode for one or more degrees of freedom.

Constructor Summary

CartesianImpedanceControlMode()
Creates a new cartesian impedance control mode.

CartesianImpedanceControlMode(CartesianImpedanceControlMode other)
Copy constructor.

Method Summary

boolean	equals(Object other) Returns true, if all the impedance parameters are equal.
double[]	getAdditionalControlForce() Gets the additional force to the TCP.
double[]	getDamping() Gets the damping parameter array D_xi with values for Lehr's damping ratio for all degrees of freedom.
double[]	getMaxCartesianVelocity() Gets the maximum cartesian velocity parameter array.
double[]	getMaxControlForce() Gets the maximum control force parameter array.
double[]	getMaxPathDeviation() Gets the maximum cartesian deviation accepted.
Double	getNullSpaceDamping() Gets the damping parameter for null space [Nm*s/rad].
Double	getNullSpaceStiffness() Gets the stiffness parameter for null space [Nm/rad].
AbstractFrame	getReferenceSystem() Gets the reference system for the impedance settings.
AbstractFrame	getSpringPosition() Gets the position of the spring.
double[]	getStiffness() Gets the stiffness parameter array K_x.
int	hashCode()
boolean	hasMaxControlForceStopCondition() Indicates whether a stop condition is fired if the maximum control force is exceeded.
boolean	hasNullSpaceDamping() Boolean value that indicates whether the null space damping parameter is set.
boolean	hasNullSpaceStiffness() Boolean value that indicates whether the null space stiffness parameter is set.
boolean	isRecoverable() States whether the control mode can be used to recover a device or not.
CartesianImpedanceControlMode.CartImpBuilder	parametrize(CartDOF... degreeOfFreedom) Configures parameter for the cartesianImpedance- and cartesianSineImpedanceControlMode.
CartesianImpedanceControlMode	setAdditionalControlForce(double x, double y, double z, double a, double b, double c) Deprecated. Please use method parametrize(CartDOF...).
void	setAdditionalControlForceToDefaultValue() Resets the additional force parameter to its default value.
CartesianImpedanceControlMode	setDamping(double[] values) Deprecated. Please use method parametrize(CartDOF...).
CartesianImpedanceControlMode	setDamping(double x, double y, double z, double a, double b, double c) Deprecated. Please use method parametrize(CartDOF...).
void	setDampingToDefaultValue() Resets the damping parameter to its default value.
CartesianImpedanceControlMode	setMaxCartesianVelocity(double x, double y, double z, double a, double b, double c) Sets the maximum cartesian velocity for this impedance motion.
void	setMaxCartesianVelocityToDefaultValue() Resets the maximum cartesian velocity parameter to its default value.
CartesianImpedanceControlMode	setMaxControlForce(double x, double y, double z, double a, double b, double c, boolean addStopCondition) Sets the maximum control force applied for this mode.
void	setMaxControlForceToDefaultValue() Resets the maximum control force parameter to its default value.
CartesianImpedanceControlMode	setMaxPathDeviation(double x, double y, double z, double a, double b, double c) Sets the maximum cartesian deviation accepted.
void	setMaxPathDeviationToDefaultValue() Resets the maximum path deviation parameter to its default value.
CartesianImpedanceControlMode	setNullSpaceDamping(double nullSpaceDamping) Sets the damping parameter for null space.
void	setNullSpaceDampingToDefaultValue() Resets the null space damping parameter to its default value.
CartesianImpedanceControlMode	setNullSpaceStiffness(double nullSpaceStiffness) Sets the stiffness parameter for null space.
void	setNullSpaceStiffnessToDefaultValue() Resets the null space stiffness parameter to its default value.
CartesianImpedanceControlMode	setReferenceSystem(AbstractFrame referenceSystem) Sets the reference system for the impedance settings.
CartesianImpedanceControlMode	setSpringPosition(AbstractFrame springPosition) Sets the position of the spring.
CartesianImpedanceControlMode	setStiffness(double[] values) Deprecated.
CartesianImpedanceControlMode	setStiffness(double x, double y, double z, double a, double b, double c) Deprecated. Please use method parametrize(CartDOF...).
void	setStiffnessToDefaultValue() Resets the stiffness parameter to its default value.
String	toString()

Methods inherited from class com.kuka.roboticsAPI.motionModel.controlModeModel.AbstractImpedanceControlMode

getMaxJointDeltas, isDeviceSupported, needsMeasuredValues, noCommandedMeasuredDevianceIntended, setMaxJointDeltas, useCommandedValuesForNextMotion, useMeasuredValuesForNextMotion

Methods inherited from class com.kuka.roboticsAPI.motionModel.controlModeModel.AbstractMotionControlMode

getMaxJointSpeed, setMaxJointSpeed

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.kuka.roboticsAPI.motionModel.controlModeModel.IMotionControlMode

getMaxJointSpeed

Constructor Detail

CartesianImpedanceControlMode

public CartesianImpedanceControlMode()

Creates a new cartesian impedance control mode.

This element is not in its final state and might change in future versions.

CartesianImpedanceControlMode

public CartesianImpedanceControlMode(CartesianImpedanceControlMode other)

Copy constructor. Uses the same impedance settings as the given mode.

Parameters:

other - The other mode. null is not allowed.

This element is not in its final state and might change in future versions.

Method Detail

parametrize

public CartesianImpedanceControlMode.CartImpBuilder parametrize(CartDOF... degreeOfFreedom)

Configures parameter for the cartesianImpedance- and cartesianSineImpedanceControlMode. Use this function to set specific parameters for one or more degrees of freedom.

Parameters:

degreeOfFreedom - The degree(s) of freedom for setting parameters. It is possible to set more than one degree at once such as (CartDOF.X, CartDOF.Y)

CartDOF.ALL means [X,Y,Z,A,B,C]
CartDOF.ROT means [A,B,C]
CartDOF.TRANS means [X,Y,Z]

Returns:

CartImpBuilder

getSpringPosition

public final AbstractFrame getSpringPosition()

Gets the position of the spring.

Returns:

The position of the spring.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

This element is not in its final state and might change in future versions.

getReferenceSystem

public final AbstractFrame getReferenceSystem()

Gets the reference system for the impedance settings.

Returns:

The reference system for the impedance settings.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

This element is not in its final state and might change in future versions.

getStiffness

public double[] getStiffness()

Gets the stiffness parameter array K_x.

Returns:

The stiffness parameter array K_x = [valueX, valueY, valueZ, valueA, valueB, valueC] where
valueX is the stiffness value for the X dimension [N/m],

valueY is the stiffness value for the Y dimension [N/m],

valueZ is the stiffness value for the Z dimension [N/m],

valueA is the stiffness value for the A dimension [Nm/rad],

valueB is the stiffness value for the B dimension [Nm/rad],

valueC is the stiffness value for the C dimension [Nm/rad].

Returns the default value if stiffness is not set.

setStiffnessToDefaultValue

public void setStiffnessToDefaultValue()

Resets the stiffness parameter to its default value.
[2000 N/m, 2000 N/m, 2000 N/m, 200 Nm/rad, 200 Nm/rad, 200 Nm/rad]

getDamping

public final double[] getDamping()

Gets the damping parameter array D_xi with values for Lehr's damping ratio for all degrees of freedom.

Returns:

The damping parameter array D_xi = [valueX, valueY, valueZ, valueA, valueB, valueC] where

valueX is the damping value for the X dimension [dimensionless],

valueY is the damping value for the Y dimension [dimensionless],

valueZ is the damping value for the Z dimension [dimensionless],

valueA is the damping value for the A dimension [dimensionless],

valueB is the damping value for the B dimension [dimensionless],

valueC is the damping value for the C dimension [dimensionless].

Returns the default values if array not set.
[0.7, 0.7, 0.7, 0.7, 0.7, 0.7]

setDampingToDefaultValue

public void setDampingToDefaultValue()

Resets the damping parameter to its default value.
[0.7, 0.7, 0.7, 0.7, 0.7, 0.7]

getNullSpaceStiffness

public final Double getNullSpaceStiffness()

Gets the stiffness parameter for null space [Nm/rad].

Returns:

The stiffness parameter for null space [Nm/rad].
Returns null if value not set.

This element is not in its final state and might change in future versions.

setNullSpaceStiffnessToDefaultValue

public void setNullSpaceStiffnessToDefaultValue()

Resets the null space stiffness parameter to its default value.

This element is not in its final state and might change in future versions.

getNullSpaceDamping

public final Double getNullSpaceDamping()

Gets the damping parameter for null space [Nm*s/rad].

Returns:

The damping parameter for null space [Nm*s/rad].
Returns null if value not set.

This element is not in its final state and might change in future versions.

setNullSpaceDampingToDefaultValue

public void setNullSpaceDampingToDefaultValue()

Resets the null space damping parameter to its default value.

This element is not in its final state and might change in future versions.

getMaxCartesianVelocity

public double[] getMaxCartesianVelocity()

Gets the maximum cartesian velocity parameter array.

Returns:

The maximum cartesian velocity parameter array [valueX, valueY, valueZ, valueA, valueB, valueC] where

valueX is the maximum velocity in X direction [mm/s],

valueY is the maximum velocity in Y direction [mm/s],

valueZ is the maximum velocity in Z direction [mm/s],

valueA is the maximum velocity in A direction [rad/s],

valueB is the maximum velocity in B direction [rad/s],

valueC is the maximum velocity in C direction [rad/s].

Returns null if array not set.

This element is not in its final state and might change in future versions.

setMaxCartesianVelocityToDefaultValue

public void setMaxCartesianVelocityToDefaultValue()

Resets the maximum cartesian velocity parameter to its default value.

This element is not in its final state and might change in future versions.

getMaxControlForce

public double[] getMaxControlForce()

Gets the maximum control force parameter array. This can be used to limit the stiffness of the spring to a specified force.

Returns:

The maximum control force parameter array [valueX, valueY, valueZ, valueA, valueB, valueC] where

valueX is the maximum force in X direction [N],

valueY is the maximum force in Y direction [N],

valueZ is the maximum force in Z direction [N],

valueA is the maximum force in A direction [Nm],

valueB is the maximum force in B direction [Nm],

valueC is the maximum force in C direction [Nm].

Returns null if value not set.

This element is not in its final state and might change in future versions.

setMaxControlForceToDefaultValue

public void setMaxControlForceToDefaultValue()

Resets the maximum control force parameter to its default value.

This element is not in its final state and might change in future versions.

getMaxPathDeviation

public double[] getMaxPathDeviation()

Gets the maximum cartesian deviation accepted.

Returns:

The maximum cartesian deviation parameter vector [valueX, valueY, valueZ, valueA, valueB, valueC] where

valueX, is the maximum deviation in X direction [mm],

valueY, is the maximum deviation in Y direction [mm],

valueZ, is the maximum deviation in Z direction [mm],

valueA, is the maximum deviation in A direction [rad],

valueB, is the maximum deviation in B direction [rad].,

valueC, is the maximum deviation in C direction [rad].

Returns null if value not set.

This element is not in its final state and might change in future versions.

setMaxPathDeviationToDefaultValue

public void setMaxPathDeviationToDefaultValue()

Resets the maximum path deviation parameter to its default value.

This element is not in its final state and might change in future versions.

getAdditionalControlForce

public double[] getAdditionalControlForce()

Gets the additional force to the TCP. This force acts in addition to the spring.

Returns:

The additional force to the TCP as parameter array [valueX, valueY, valueZ, valueA, valueB, valueC] where

valueX is the force to apply in X direction [N],

valueY is the force to apply in Y direction [N],

valueZ is the force to apply in Z direction [N],

valueA is the force to apply in A direction [Nm],

valueB is the force to apply in B direction [Nm],

valueC is the force to apply in C direction [Nm].

Returns null if array not set.

This element is not in its final state and might change in future versions.

setAdditionalControlForceToDefaultValue

public void setAdditionalControlForceToDefaultValue()

Resets the additional force parameter to its default value.

This element is not in its final state and might change in future versions.

setDamping

@Deprecated
public CartesianImpedanceControlMode setDamping(double x,
                                                           double y,
                                                           double z,
                                                           double a,
                                                           double b,
                                                           double c)

Deprecated. Please use method parametrize(CartDOF...).

Sets the damping parameters (D_xi.., Lehr's damping ratio) for all degrees of freedom.

Damping values should be between 0 and 1. A good damping value is 0.7.

The mode will use measured values for the next motion, because it's settings have changed. If you do not want such a behavior, call useCommandedValues on the mode.

Parameters:

x - The damping value for the X dimension [dimensionless].
Precondition: value >= 0.1 and value <= 1.0.

y - The damping value for the Y dimension [dimensionless].
Precondition: value >= 0.1 and value <= 1.0.

z - The damping value for the Z dimension [dimensionless].
Precondition: value >= 0.1 and value <= 1.0.

a - The damping value for the A dimension [dimensionless].
Precondition: value >= 0.1 and value <= 1.0.

b - The damping value for the B dimension [dimensionless].
Precondition: value >= 0.1 and value <= 1.0.

c - The damping value for the C dimension [dimensionless].
Precondition: value >= 0.1 and value <= 1.0.

Returns:

This class (fluent interface).

setDamping

@Deprecated
public CartesianImpedanceControlMode setDamping(double[] values)

Deprecated. Please use method parametrize(CartDOF...).

Sets the Cartesian damping parameters (D_xi.., Lehr's damping ratio) for all degrees of freedom.

The mode will use measured values for the next motion, because it's settings have changed. If you do not want such a behavior, call useCommandedValues on the mode.

Parameters:

values - the damping values [x, y, z, a, b, c] for the cartesian impedance [dimensionless for all degrees of freedom].
Precondition: the array must have length 6 and
0.1 <= x, y, z, a, b, c <= 1.0.

Returns:

This class (fluent interface).

setStiffness

@Deprecated
public CartesianImpedanceControlMode setStiffness(double x,
                                                             double y,
                                                             double z,
                                                             double a,
                                                             double b,
                                                             double c)

Deprecated. Please use method parametrize(CartDOF...).

Sets the Cartesian stiffness parameters (K_x..).

The mode will use measured values for the next motion, because it's settings have changed. If you do not want such a behavior, call useCommandedValues on the mode.

Parameters:

x - The stiffness value for the X dimension [N/m].
Precondition: value >= 0.0 and value <= 5000.0.

y - The stiffness value for the Y dimension [N/m].
Precondition: value >= 0.0 and value <= 5000.0.

z - The stiffness value for the Z dimension [N/m].
Precondition: value >= 0.0 and value <= 5000.0.

a - The stiffness value for the A dimension [Nm/rad].
Precondition: value >= 0.0 and value <= 300.0.

b - The stiffness value for the B dimension [Nm/rad].
Precondition: value >= 0.0 and value <= 300.0.

c - The stiffness value for the C dimension [Nm/rad].
Precondition: value >= 0.0 and value <= 300.0.

Returns:

This class (fluent interface).

setStiffness

@Deprecated
public CartesianImpedanceControlMode setStiffness(double[] values)

Deprecated.

Please use method parametrize(CartDOF...).

Sets the Cartesian stiffness parameters (K_x..).

The mode will use measured values for the next motion, because it's settings have changed. If you do not want such a behavior, call useCommandedValues on the mode.

Parameters:

values - the stiffness values [x, y, z, a, b, c] for the cartesian impedance, x, y, z in [N/m], a, b, c in [Nm/rad].
Precondition: the array must have length 6 and 0.0 <= x, y, z <= 5000.0 and 0.0 <= a, b, c <= 300.0.

Returns:

This class (fluent interface).

setSpringPosition

public CartesianImpedanceControlMode setSpringPosition(AbstractFrame springPosition)

Sets the position of the spring.

The spring position defines the position of the spring when the measured and commanded values of the robot start to be different. Normally, the spring is located in the TCP of the robot. But for special cases, this position can be changed by using this method.

The spring position therefore changes the position of the spring in contrast to the TCP, but not it's properties like stiffness or damping. The direction of the applied force on the TCP is therefore affected by the spring position.

The given frame must be connected through one or more static frames with the flange of the robot.

Note that the referenceSystem method also affects how the impedance settings are calculated in the TCP relative to the spring position.

The mode will use measured values for the next motion, because it's settings have changed. If you do not want such a behavior, call useCommandedValues on the mode.

Parameters:

springPosition - The position of the spring.

Returns:

This class (fluent interface).

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

This element is not in its final state and might change in future versions.

setReferenceSystem

public CartesianImpedanceControlMode setReferenceSystem(AbstractFrame referenceSystem)

Sets the reference system for the impedance settings. The system may only be defined through a frame that has a static connection to the robot base.

Set the system to null to indicate that the system is the defined spring position. This is also the default value.

The mode will use measured values for the next motion, because it's settings have changed. If you do not want such a behavior, call useCommandedValues on the mode.

Parameters:

referenceSystem - The reference system.

Returns:

This class (fluent interface).

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

This element is not in its final state and might change in future versions.

setNullSpaceDamping

public CartesianImpedanceControlMode setNullSpaceDamping(double nullSpaceDamping)

Sets the damping parameter for null space.

A good damping value is 0.7.

The mode will use measured values for the next motion, because it's settings have changed. If you do not want such a behavior, call useCommandedValues on the mode.

Parameters:

nullSpaceDamping - The damping parameter for null space [Nm*s/rad].
Precondition: value >= 0.3 and value <= 1.0.

Returns:

This class (fluent interface).

This element is not in its final state and might change in future versions.

setNullSpaceStiffness

public CartesianImpedanceControlMode setNullSpaceStiffness(double nullSpaceStiffness)

Sets the stiffness parameter for null space.

Parameters:

nullSpaceStiffness - The stiffness value for null space [Nm/rad].
Precondition: 0.0 <= value.

Returns:

This class (fluent interface).

This element is not in its final state and might change in future versions.

setMaxPathDeviation

public CartesianImpedanceControlMode setMaxPathDeviation(double x,
                                                         double y,
                                                         double z,
                                                         double a,
                                                         double b,
                                                         double c)

Sets the maximum cartesian deviation accepted. If the deviation is exceeded a stop condition occurs.

Parameters:

x - The maximum deviation in X direction [mm].
Precondition: value >= 0.0.

y - The maximum deviation in Y direction [mm].
Precondition: value >= 0.0.

z - The maximum deviation in Z direction [mm].
Precondition: value >= 0.0.

a - The maximum deviation in A direction [rad].
Precondition: value >= 0.0.

b - The maximum deviation in B direction [rad].
Precondition: value >= 0.0.

c - The maximum deviation in C direction [rad].
Precondition: value >= 0.0.

Returns:

This class (fluent interface).

setMaxControlForce

public CartesianImpedanceControlMode setMaxControlForce(double x,
                                                        double y,
                                                        double z,
                                                        double a,
                                                        double b,
                                                        double c,
                                                        boolean addStopCondition)

Sets the maximum control force applied for this mode. This can be used to limit the stiffness of the spring to a specified force.

Parameters:

x - The maximum force in X direction [N].
Precondition: value >= 0.0.

y - The maximum force in Y direction [N].
Precondition: value >= 0.0.

z - The maximum force in Z direction [N].
Precondition: value >= 0.0.

a - The maximum force in A direction [Nm].
Precondition: value >= 0.0.

b - The maximum force in B direction [Nm].
Precondition: value >= 0.0.

c - The maximum force in C direction [Nm].
Precondition: value >= 0.0.

addStopCondition - Indicates whether the stop condition should be fired if the maximum force is exceeded.

Returns:

This class (fluent interface).

setMaxCartesianVelocity

public CartesianImpedanceControlMode setMaxCartesianVelocity(double x,
                                                             double y,
                                                             double z,
                                                             double a,
                                                             double b,
                                                             double c)

Sets the maximum cartesian velocity for this impedance motion. If the velocity is exceeded a stop condition is fired.

Parameters:

x - The maximum velocity in X direction [mm/s].
Precondition: value >= 0.0.

y - The maximum velocity in Y direction [mm/s].
Precondition: value >= 0.0.

z - The maximum velocity in Z direction [mm/s].
Precondition: value >= 0.0.

a - The maximum velocity in A direction [rad/s].
Precondition: value >= 0.0.

b - The maximum velocity in B direction [rad/s].
Precondition: value >= 0.0.

c - The maximum velocity in C direction [rad/s].
Precondition: value >= 0.0.

Returns:

This class (fluent interface).

setAdditionalControlForce

@Deprecated
public CartesianImpedanceControlMode setAdditionalControlForce(double x,
                                                                          double y,
                                                                          double z,
                                                                          double a,
                                                                          double b,
                                                                          double c)

Deprecated. Please use method parametrize(CartDOF...).

Sets an additional force to the TCP. This force acts in addition to the spring. The additional force is stepwise applied.

Parameters:

x - The force to apply in X direction [N].

y - The force to apply in Y direction [N].

z - The force to apply in Z direction [N].

a - The force to apply in A direction [Nm].

b - The force to apply in B direction [Nm].

c - The force to apply in C direction [Nm].

Returns:

This class (fluent interface).

toString

public String toString()

Overrides:

toString in class Object

This element is not in its final state and might change in future versions.

hasNullSpaceDamping

public boolean hasNullSpaceDamping()

Boolean value that indicates whether the null space damping parameter is set.

Returns:

true, if the null space damping parameter is set, false otherwise.

This element is not in its final state and might change in future versions.

hasNullSpaceStiffness

public boolean hasNullSpaceStiffness()

Boolean value that indicates whether the null space stiffness parameter is set.

Returns:

true, if the null space stiffness parameter is set, false otherwise.

This element is not in its final state and might change in future versions.

hasMaxControlForceStopCondition

public boolean hasMaxControlForceStopCondition()

Indicates whether a stop condition is fired if the maximum control force is exceeded.

Returns:

true if a stop condition is fired if the maximum control force is exceeded.

This element is not in its final state and might change in future versions.

hashCode

public int hashCode()

Specified by:

hashCode in class AbstractImpedanceControlMode

This element is not in its final state and might change in future versions.

equals

public boolean equals(Object other)

Returns true, if all the impedance parameters are equal.

Specified by:

equals in class AbstractImpedanceControlMode

Parameters:

other - other control mode to compare

Returns:

true, if all impedance parameters are equal.

This element is not in its final state and might change in future versions.

isRecoverable

public boolean isRecoverable()

Description copied from interface: IMotionControlMode

States whether the control mode can be used to recover a device or not.

Returns:

True if the control mode can be used to recover a device, otherwise false.