com.kuka.roboticsAPI.motionModel.controlModeModel
Class CartesianSineImpedanceControlMode

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

All Implemented Interfaces:

IImpedanceMotionControlMode, IMotionControlMode

public class CartesianSineImpedanceControlMode
extends CartesianImpedanceControlMode

This control mode indicates cartesian impedance with a sine function on top of it to apply several sine patterns. Actually supported patterns are sine, lissajous and spiral. Additionally to this, the control mode can also be used to realize the desiredForce feature.

The sine function is calculated through the formula:
f(x) = amplitude * sin(frequency * x + phase) + bias

The components can be changed through the control mode which leads to an oscillation of the robot.

Note: The robot will perform the pattern or create the desired force only as long as the robot is inside it's specified position limit (see positionLimit(double, double, double, double, double, double)).

Default values:

• Stiffness cartDOF X,Y,Z,A,B,C [2000, 2000, 2000, 200, 200, 200]
  
• Damping cartDOF X,Y,Z,A,B,C [0.7, 0.7, 0.7, 0.7, 0.7, 0.7]
  
• Amplitude cartDOF X,Y,Z,A,B,C [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
  
• Bias cartDof X,Y,Z,A,B,C [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
  
• Frequency cartDof X,Y,Z,A,B,C [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
  
• Phase cartDof X,Y,Z,A,B,C [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
  
• PositionLimit [infinite]
  
• ForceLimit [infinite]
  
• HoldTime [infinite]
  

Valid ranges:

• Stiffness cartDOF X,Y,Z [0.0, 5000.0]; cartDOF A,B,C [0.0, 300.0]
  
• Damping cartDOF X,Y,Z,A,B,C [0.0, 1.0]
  
• Frequency cartDOF X,Y,Z,A,B,C [0.0, 15.0]
  

Nested Class Summary

class

CartesianSineImpedanceControlMode.CartSineImpBuilder Class to parameterize the CartesianSineImpedanceControlMode for one or more degrees of freedom.

Nested classes/interfaces inherited from class com.kuka.roboticsAPI.motionModel.controlModeModel.CartesianImpedanceControlMode

CartesianImpedanceControlMode.CartImpBuilder

Constructor Summary

CartesianSineImpedanceControlMode()
Creates a new cartesian sine impedance control mode.

CartesianSineImpedanceControlMode(CartesianSineImpedanceControlMode other)
Copy constructor.

Method Summary

CartesianSineImpedanceControlMode	amplitude(double x, double y, double z, double a, double b, double c) Deprecated.
CartesianSineImpedanceControlMode	bias(double x, double y, double z, double a, double b, double c) Deprecated.
static CartesianSineImpedanceControlMode	createDesiredForce(CartDOF degreeOfFreedom, double force, double stiffness) Creates a new CartesianSineImpedanceControlMode with a desired force.
static CartesianSineImpedanceControlMode	createLissajousPattern(CartPlane cartPlane, double frequency, double amplitude, double stiffness) Creates a new CartesianSineImpedanceControlMode for a Lissajous pattern.
static CartesianSineImpedanceControlMode	createSinePattern(CartDOF degreeOfFreedom, double frequency, double amplitude, double stiffness) Creates a new CartesianSineImpedanceControlMode for a sine pattern.
static CartesianSineImpedanceControlMode	createSpiralPattern(CartPlane cartPlane, double frequency, double amplitude, double stiffness, double totalTimeSecs) Creates a new CartesianSineImpedanceControlMode for a spiral pattern.
boolean	equals(Object other) Returns true, if all the impedance parameters are equal.
CartesianSineImpedanceControlMode	forceLimit(double x, double y, double z, double a, double b, double c) Deprecated.
CartesianSineImpedanceControlMode	frequency(double x, double y, double z, double a, double b, double c) Deprecated.
double[]	getAmplitude() Gets the amplitude of the selected CartesianSineControlMode pattern.
double[]	getBias() Gets the bias of the control mode.
double	getFallTime() Gets the fall time of the control mode.
double[]	getForceLimit() Gets the feed forward force limit in [N,N,N,Nm,Nm,Nm].
double[]	getFrequency() Gets the frequency of the control mode.
double	getHoldTime() Gets the hold time of the control mode.
double[]	getPhase() Gets the phase of the control mode.
double[]	getPositionLimit() Gets the feed forward position limit.
double	getRiseTime() Gets the rise time of the control mode.
boolean	getStaysActiveUntilPatternFinished() Gets the flag which indicates whether the command will stay active until the sine pattern specified through the control mode is finished, even if the corresponding motion is finished.
int	hashCode()
CartesianSineImpedanceControlMode.CartSineImpBuilder	parametrize(CartDOF... cartesianDegreeOfFreedom) Configures parameter for the cartesianImpedance- and cartesianSineImpedanceControlMode.
CartesianSineImpedanceControlMode	phase(double x, double y, double z, double a, double b, double c) Deprecated.
CartesianSineImpedanceControlMode	positionLimit(double x, double y, double z, double a, double b, double c) Deprecated.
CartesianImpedanceControlMode	setAdditionalControlForce(double x, double y, double z, double a, double b, double c) Deprecated.
CartesianSineImpedanceControlMode	setFallTime(double fallTimeSecs) Sets the fall time of the control mode.
CartesianSineImpedanceControlMode	setHoldTime(double holdTimeSecs) Sets the hold time of the control mode.
CartesianSineImpedanceControlMode	setRiseTime(double riseTimeSecs) Sets the rise time of the control mode.
CartesianSineImpedanceControlMode	setStayActiveUntilPatternFinished(boolean stayActiveUntilPatternFinished) Sets the flag which indicates whether the command will stay active until the sine pattern specified through the control mode is finished, even if the corresponding motion is finished.
CartesianSineImpedanceControlMode	setTotalTime(double totalTimeSecs) Sets the total duration time for the selected pattern of the cartesianSineImpedanceControlMode.
String	toString()

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

getAdditionalControlForce, getDamping, getMaxCartesianVelocity, getMaxControlForce, getMaxPathDeviation, getNullSpaceDamping, getNullSpaceStiffness, getReferenceSystem, getSpringPosition, getStiffness, hasMaxControlForceStopCondition, hasNullSpaceDamping, hasNullSpaceStiffness, isRecoverable, setAdditionalControlForceToDefaultValue, setDamping, setDamping, setDampingToDefaultValue, setMaxCartesianVelocity, setMaxCartesianVelocityToDefaultValue, setMaxControlForce, setMaxControlForceToDefaultValue, setMaxPathDeviation, setMaxPathDeviationToDefaultValue, setNullSpaceDamping, setNullSpaceDampingToDefaultValue, setNullSpaceStiffness, setNullSpaceStiffnessToDefaultValue, setReferenceSystem, setSpringPosition, setStiffness, setStiffness, setStiffnessToDefaultValue

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

CartesianSineImpedanceControlMode

public CartesianSineImpedanceControlMode()

Creates a new cartesian sine impedance control mode.

CartesianSineImpedanceControlMode

public CartesianSineImpedanceControlMode(CartesianSineImpedanceControlMode other)

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

Parameters:

other - The other mode. null is not allowed.

Method Detail

parametrize

public CartesianSineImpedanceControlMode.CartSineImpBuilder parametrize(CartDOF... cartesianDegreeOfFreedom)

Description copied from class: CartesianImpedanceControlMode

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

Overrides:

parametrize in class CartesianImpedanceControlMode

Parameters:

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

createSinePattern

public static CartesianSineImpedanceControlMode createSinePattern(CartDOF degreeOfFreedom,
                                                                  double frequency,
                                                                  double amplitude,
                                                                  double stiffness)

Creates a new CartesianSineImpedanceControlMode for a sine pattern. This function creates a default sine oscillation.

Default Values:

• RiseTime/ FallTime are calculated as follows: (1/frequency)*0.5
  
• For all other default values see CartesianSineImpedanceControlMode

Note: For changing the default sine-pattern settings or configure additional parameters use the parametrize(CartDOF...)-function.

Parameters:

degreeOfFreedom - The degree of freedom for performing the sine oscillation.

frequency - The value of the frequency. [Hz]

amplitude - The value of the amplitude. CartDOF X,Y,Z [N] / A,B,C [Nm]

stiffness - The value of the stiffness. CartDOF X,Y,Z [N/m] / A,B,C [Nm/rad]

Returns:

CartesianSineImpedanceControlMode

hashCode

public int hashCode()

Overrides:

hashCode in class CartesianImpedanceControlMode

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.

Overrides:

equals in class CartesianImpedanceControlMode

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.

createLissajousPattern

public static CartesianSineImpedanceControlMode createLissajousPattern(CartPlane cartPlane,
                                                                       double frequency,
                                                                       double amplitude,
                                                                       double stiffness)

Creates a new CartesianSineImpedanceControlMode for a Lissajous pattern. This function creates a default setting of two combined sine oscillations with two different frequencies (f1 = frequency, f2 = frequency*0.4) and a phase shift of Pi/2.

Default Values:

• RiseTime/ FallTime are calculated as follows: (1/(frequency*0.4))*0.5
  
• For all other default values see CartesianSineImpedanceControlMode

Note: For changing the default lissajous-pattern settings or configure additional parameters use the parametrize(CartDOF...)-function.

Parameters:

cartPlane - The plane in the Cartesian space for performing the lissajous-pattern. e.g. (XY, XZ, YZ)

frequency - The value of the frequency for the sine oscillation f1 [Hz]

amplitude - The value of the amplitude. CartDOF X,Y,Z [N] / A,B,C [Nm]

stiffness - The value of the stiffness. CartDOF X,Y,Z [N/m] / A,B,C [Nm/rad]

Returns:

CartesianSineImpedanceControlMode

Throws:

IllegalArgumentException - if the cartPlane parameter is null

createSpiralPattern

public static CartesianSineImpedanceControlMode createSpiralPattern(CartPlane cartPlane,
                                                                    double frequency,
                                                                    double amplitude,
                                                                    double stiffness,
                                                                    double totalTimeSecs)

Creates a new CartesianSineImpedanceControlMode for a spiral pattern. This function creates a default setting of two combined sine oscillations with a phase shift of Pi/2.

Default Values:

• RiseTime/ FallTime are calculated as follows: totalTimeSecs/2
  
• For all other default values see CartesianSineImpedanceControlMode

Note: For changing the default spiral-pattern settings or configure additional parameters use the parametrize(CartDOF...)-function.

Parameters:

cartPlane - The plane in the Cartesian space for performing the spiral-pattern. e.g. (XY, XZ, YZ)

frequency - The value of the frequency for the two sine oscillations [Hz]

amplitude - The value of the amplitude. CartDOF X,Y,Z [N] / A,B,C [Nm]

stiffness - The value of the stiffness for the degree of freedoms of the given plane [N/m]

totalTimeSecs - The value of the totalTime [s]. The time duration for expanding the spiral pattern.

Returns:

CartesianSineImpedanceControlMode

createDesiredForce

public static CartesianSineImpedanceControlMode createDesiredForce(CartDOF degreeOfFreedom,
                                                                   double force,
                                                                   double stiffness)

Creates a new CartesianSineImpedanceControlMode with a desired force. The desired force can be set for each dimension (X,Y,Z in N, A,B,C Nm).

To achieve a constant force, the amplitude, frequency and phase are set to zero, the bias is set to the given values.

Parameters:

degreeOfFreedom - The degree(s) of freedom for performing the desired force.

force - The value of the desired force. For X,Y,Z in [N] and A,B,C in [Nm]

stiffness - The value of the stiffness. CartDOF X,Y,Z [N/m] / A,B,C [Nm/rad]

Returns:

CartesianSineImpedanceConotrolMode

setTotalTime

public CartesianSineImpedanceControlMode setTotalTime(double totalTimeSecs)

Sets the total duration time for the selected pattern of the cartesianSineImpedanceControlMode. The total time is specified as: totalTime = riseTime + holdTime + fallTime

Note: riseTime and fallTime specified as max(1/frequency)*0.5. If the time limit is reached, only the sineImpedanceControlmode stopped but not the motion command. If, instead, the motion stops before the time limit is reached, is sineImpedanceControlMode also stops.

Parameters:

totalTimeSecs - The value of the duration time for a pattern [s]

Returns:

CartesianSineImpedanceControlMode

setHoldTime

public CartesianSineImpedanceControlMode setHoldTime(double holdTimeSecs)

Sets the hold time of the control mode.

Parameters:

holdTimeSecs - The hold time of the control mode [s].

Returns:

CartesianSineImpedanceControlMode

setFallTime

public CartesianSineImpedanceControlMode setFallTime(double fallTimeSecs)

Sets the fall time of the control mode.

Parameters:

fallTimeSecs - The fall time of the control mode [s]

Returns:

CartesianSineImpedanceControlMode

setRiseTime

public CartesianSineImpedanceControlMode setRiseTime(double riseTimeSecs)

Sets the rise time of the control mode.

Parameters:

riseTimeSecs - The rise time of the control mode [s]

Returns:

CartesianSineImpedanceControlMode

getForceLimit

public double[] getForceLimit()

Gets the feed forward force limit in [N,N,N,Nm,Nm,Nm].

The limit clips the user defined forces. The default values are infinity, so that no clipping occurs.

Returns:

The force limit in [N,N,N,Nm,Nm,Nm].

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

getStaysActiveUntilPatternFinished

public boolean getStaysActiveUntilPatternFinished()

Gets the flag which indicates whether the command will stay active until the sine pattern specified through the control mode is finished, even if the corresponding motion is finished.

If the flag is false and the corresponding motion is finished, the command will be finished and the force specified through this pattern will be set to 0.

If the flag is true the command stays active until the sine pattern has finished (according to the value set by setTotalTime()) and the motion has reached the target.

Returns:

True if the command will stay active until the sine pattern specified through the control mode is finished, even if the corresponding motion is finished.

getPositionLimit

public double[] getPositionLimit()

Gets the feed forward position limit.

The limit describes the maximum allowed distance between the measured and commanded position created by the additional desired force. If the position limit is reached, the applied force is set to 0.

The default values of the position limit are infinity.

Returns:

The position limit.

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

getAmplitude

public double[] getAmplitude()

Gets the amplitude of the selected CartesianSineControlMode pattern.

Amplitude in [N N N Nm Nm Nm] of sinusoidal output pattern.

Returns:

The amplitude of the control mode.

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

getBias

public double[] getBias()

Gets the bias of the control mode.

Offset in [N N N Nm Nm Nm] of Amplitude.

Returns:

The bias of the control mode.

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

getFrequency

public double[] getFrequency()

Gets the frequency of the control mode.

Frequency in Hertz of sinusoidal motion.

Returns:

The frequency of the control mode.

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

getPhase

public double[] getPhase()

Gets the phase of the control mode.

Difference in degree.

Returns:

The phase of the control mode.

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

getFallTime

public double getFallTime()

Gets the fall time of the control mode.

Returns:

The fall time of the control mode [s]

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

getHoldTime

public double getHoldTime()

Gets the hold time of the control mode.

The default value of the holdTime is infinity.

Returns:

The hold time of the control mode [s]

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

getRiseTime

public double getRiseTime()

Gets the rise time of the control mode.

Returns:

The rise time of the control mode [s]

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

setStayActiveUntilPatternFinished

public CartesianSineImpedanceControlMode setStayActiveUntilPatternFinished(boolean stayActiveUntilPatternFinished)

Sets the flag which indicates whether the command will stay active until the sine pattern specified through the control mode is finished, even if the corresponding motion is finished.

If the flag is false and the corresponding motion is finished, the command will be finished and the force specified through this pattern will be set to 0.

If the flag is true the command stays active until the sine pattern has finished (according to the value set by setTotalTime()) and the motion has reached the target.

Parameters:

stayActiveUntilPatternFinished - The flag which indicates whether the command will stay active until the sine pattern specified through the control mode is finished, even if the corresponding motion is finished.

Returns:

This class (fluent interface).

toString

public String toString()

Overrides:

toString in class CartesianImpedanceControlMode

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

phase

@Deprecated
public CartesianSineImpedanceControlMode phase(double x,
                                                          double y,
                                                          double z,
                                                          double a,
                                                          double b,
                                                          double c)

Deprecated.

Please use method parametrize(CartDOF...).

Sets the phase of the control mode.
Difference in degree, esp. for support of "lissajou patterns".

Parameters:

x - The phase value for the X dimension.

y - The phase value for the Y dimension.

z - The phase value for the Z dimension.

a - The phase value for the A dimension.

b - The phase value for the B dimension.

c - The phase value for the C dimension.

Returns:

This class (fluent interface).

frequency

@Deprecated
public CartesianSineImpedanceControlMode frequency(double x,
                                                              double y,
                                                              double z,
                                                              double a,
                                                              double b,
                                                              double c)

Deprecated.

Please use method parametrize(CartDOF...).

Sets the frequency of the control mode.
Frequency in Hertz of sinusoidal motion.

Parameters:

x - The frequency value for the X dimension.

y - The frequency value for the Y dimension.

z - The frequency value for the Z dimension.

a - The frequency value for the A dimension.

b - The frequency value for the B dimension.

c - The frequency value for the C dimension.

Returns:

This class (fluent interface).

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

bias

@Deprecated
public CartesianSineImpedanceControlMode bias(double x,
                                                         double y,
                                                         double z,
                                                         double a,
                                                         double b,
                                                         double c)

Deprecated.

Please use method parametrize(CartDOF...).

Sets the bias of the control mode.

Offset in [N N N Nm Nm Nm] of Amplitude.

Parameters:

x - The bias value for the X dimension (N).

y - The bias value for the Y dimension (N).

z - The bias value for the Z dimension (N).

a - The bias value for the A dimension (Nm).

b - The bias value for the B dimension (Nm).

c - The bias value for the C dimension (Nm).

Returns:

This class (fluent interface).

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

setAdditionalControlForce

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

Deprecated.

Please use method parametrize(CartDOF...).

Sets the bias of the control mode.

Offset in [N N N Nm Nm Nm] of Amplitude.

Overrides:

setAdditionalControlForce in class CartesianImpedanceControlMode

Parameters:

x - The bias value for the X dimension (N).

y - The bias value for the Y dimension (N).

z - The bias value for the Z dimension (N).

a - The bias value for the A dimension (Nm).

b - The bias value for the B dimension (Nm).

c - The bias value for the C dimension (Nm).

Returns:

This class (fluent interface).

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

amplitude

@Deprecated
public CartesianSineImpedanceControlMode amplitude(double x,
                                                              double y,
                                                              double z,
                                                              double a,
                                                              double b,
                                                              double c)

Deprecated.

Please use method parametrize(CartDOF...).

Sets the amplitude of the control mode.

Amplitude in [N N N Nm Nm Nm] of sinusoidal output pattern.

Parameters:

x - The amplitude value for the X dimension.

y - The amplitude value for the Y dimension.

z - The amplitude value for the Z dimension.

a - The amplitude value for the A dimension.

b - The amplitude value for the B dimension.

c - The amplitude value for the C dimension.

Returns:

This class (fluent interface).

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

positionLimit

@Deprecated
public CartesianSineImpedanceControlMode positionLimit(double x,
                                                                  double y,
                                                                  double z,
                                                                  double a,
                                                                  double b,
                                                                  double c)

Deprecated.

Please use method parametrize(CartDOF...).

Sets the feed forward position limit. Position values are in mm. Rotation values in rad.

The limit describes the maximum allowed distance between the measured and commanded position.

Parameters:

x - The positionLimit value for the X dimension (mm).

y - The positionLimit value for the Y dimension (mm).

z - The positionLimit value for the Z dimension (mm).

a - The positionLimit value for the A dimension (rad).

b - The positionLimit value for the B dimension (rad).

c - The positionLimit value for the C dimension (rad).

Returns:

This class (fluent interface).

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

forceLimit

@Deprecated
public CartesianSineImpedanceControlMode forceLimit(double x,
                                                               double y,
                                                               double z,
                                                               double a,
                                                               double b,
                                                               double c)

Deprecated.

Please use method parametrize(CartDOF...).

Sets the feed forward force limit in [N,N,N,Nm,Nm,Nm].

The limit clips the user defined forces. The default values should be sufficient for most applications.

Parameters:

x - The forceLimit value for the X dimension (N).

y - The forceLimit value for the Y dimension (N).

z - The forceLimit value for the Z dimension (N).

a - The forceLimit value for the A dimension (Nm).

b - The forceLimit value for the B dimension (Nm).

c - The forceLimit value for the C dimension (Nm).

Returns:

This class (fluent interface).

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