franky.CartesianImpedanceTrackingMotion

class franky.CartesianImpedanceTrackingMotion

Bases: CartesianImpedanceBase

Cartesian impedance tracking motion.

This motion keeps the same Cartesian impedance controller alive while reading the latest reference from a handle or callback every control cycle.

__init__(self: franky._franky.CartesianImpedanceTrackingMotion, translational_stiffness: SupportsFloat | SupportsIndex = 500, rotational_stiffness: SupportsFloat | SupportsIndex = 50, force_constraints: Annotated[collections.abc.Sequence[SupportsFloat | SupportsIndex | None], 'FixedSize(6)'] | None = None, posture_task: franky._franky.PostureTask | None = None, manipulability_task: franky._franky.ManipulabilityTask | None = None, max_delta_tau: SupportsFloat | SupportsIndex = 1.0, lower_joint_limits: Annotated[numpy.typing.ArrayLike, numpy.float64, '[7, 1]'] | None = None, upper_joint_limits: Annotated[numpy.typing.ArrayLike, numpy.float64, '[7, 1]'] | None = None, joint_limit_activation_distance: SupportsFloat | SupportsIndex = 0.1, joint_limit_stiffness: SupportsFloat | SupportsIndex = 4.0, joint_limit_damping: SupportsFloat | SupportsIndex = 1.0, joint_limit_max_torque: SupportsFloat | SupportsIndex = 5.0, translational_error_clip: Annotated[numpy.typing.ArrayLike, numpy.float64, '[3, 1]'] = array([0.1, 0.1, 0.1]), rotational_error_clip: Annotated[numpy.typing.ArrayLike, numpy.float64, '[3, 1]'] = array([0.25, 0.25, 0.25]), gains_time_constant: SupportsFloat | SupportsIndex = 0.1, friction: franky._franky.FrictionCompensationParams | None = None) → None

Construct a dynamic Cartesian impedance tracking controller.

Cartesian damping is chosen internally as critically damped with respect to the requested stiffness. The optional posture_task adds a secondary joint-posture objective (a PostureTask) that is projected into the Jacobian nullspace, biasing the redundant arm posture without changing the Cartesian task to first order. Its per-joint stiffness leaves zero-stiffness joints unpushed. manipulability_task adds a manipulability-maximization objective in the same nullspace. Their gains can be retuned at runtime via set_nullspace_gains.

The controller reads target gains each cycle and exponentially interpolates toward them with the given time constant, allowing smooth runtime stiffness changes.

add_reaction(self: franky._franky.BaseTorqueMotion, reaction: franky._franky.TorqueReaction) → None

Add a reaction to the motion.

Reactions are evaluated in every step of the motion and can replace the current motion with a new motion.

Parameters:

reaction – The reaction to add.

Warning

Do not call this function synchronously from a condition, motion function, or reaction callback while this motion’s reactions are being evaluated. Reaction evaluation holds the reaction-list mutex, so doing so would deadlock.

get_gains(self: franky._franky.CartesianImpedanceBase) → franky._franky.CartesianImpedanceGains

Get a copy of the current target impedance gains.

Mutating the returned object has no effect on the motion; pass it to setGains to apply changes.

get_nullspace_gains(self: franky._franky.CartesianImpedanceBase) → franky._franky.NullspaceGains

Get a copy of the current target nullspace gains.

Mutating the returned object has no effect on the motion; pass it to setNullspaceGains to apply changes.

get_reference(self: franky._franky.CartesianImpedanceTrackingMotion) → franky._franky.CartesianReference | None

Get a copy of the last published Cartesian reference, or None if no reference has been set yet. Mutating the returned object has no effect on the motion; pass it to set_reference to apply changes.

register_callback(self: franky._franky.BaseTorqueMotion, callback: collections.abc.Callable[[franky._franky.RobotState, franky._franky.Duration, franky._franky.Duration, franky._franky.Duration, franky._franky.Torques], None]) → None

Register a callback that is called in every step of the motion.

Parameters:

callback – The callback to register. Callbacks are called with the robot state, the time step [s], the relative time [s], the absolute time [s] and the control signal computed in this step.

set_gains(self: franky._franky.CartesianImpedanceBase, gains: franky._franky.CartesianImpedanceGains) → None

Set the target impedance gains.

The gains are validated and then smoothed in the control loop via exponential interpolation.

Parameters:

gains – The new target gains.

set_nullspace_gains(self: franky._franky.CartesianImpedanceBase, gains: franky._franky.NullspaceGains) → None

Set the target nullspace gains.

The gains are smoothed in the control loop via exponential interpolation.

Parameters:

gains – The new target nullspace gains.

set_reference(self: franky._franky.CartesianImpedanceTrackingMotion, reference: franky._franky.CartesianReference) → None

Set the Cartesian reference tracked by the controller. The reference is validated and picked up by the control loop in the next cycle.

property params

The parameters of the motion.

property reactions

Currently registered reactions of the motion.