franky.Robot

class franky.Robot

Bases: _RobotInternal

A class representing a Franka robot, and the main entry point of franky.

This class allows executing motions on the robot, querying its state, and setting control parameters.

__init__(self: franky._franky._RobotInternal, fci_hostname: str, relative_dynamics_factor: franky._franky.RelativeDynamicsFactor = 1.0, default_torque_threshold: SupportsFloat | SupportsIndex = 20.0, default_force_threshold: SupportsFloat | SupportsIndex = 30.0, controller_mode: franky._franky.ControllerMode = _franky.ControllerMode.JointImpedance, realtime_config: franky._franky.RealtimeConfig = _franky.RealtimeConfig.Enforce, kalman_q_process_var: SupportsFloat | SupportsIndex = 0.0001, kalman_dq_process_var: SupportsFloat | SupportsIndex = 0.001, kalman_ddq_process_var: SupportsFloat | SupportsIndex = 0.1, kalman_control_process_var: SupportsFloat | SupportsIndex = 1.0, kalman_q_obs_var: SupportsFloat | SupportsIndex = 0.01, kalman_dq_obs_var: SupportsFloat | SupportsIndex = 0.1, kalman_q_d_obs_var: SupportsFloat | SupportsIndex = 0.0001, kalman_dq_d_obs_var: SupportsFloat | SupportsIndex = 0.0001, kalman_ddq_d_obs_var: SupportsFloat | SupportsIndex = 0.0001, kalman_control_adaptation_rate: SupportsFloat | SupportsIndex = 0.1) → None

Connect to a Franka robot.

Parameters:

  • fci_hostname – The hostname or IP address of the robot.

  • relative_dynamics_factor – Global relative dynamics factor. The maximum velocity, acceleration, and jerk of the robot are scaled by this factor.

  • default_torque_threshold – Default torque threshold for the collision behavior [Nm].

  • default_force_threshold – Default force threshold for the collision behavior [N].

  • controller_mode – Default controller mode. See the libfranka documentation for details.

  • realtime_config – Realtime configuration. If set to RealtimeConfig.Enforce, the connection fails if no realtime kernel is available.

  • kalman_q_process_var – Noise variances of the Kalman filter franky uses to estimate the robot state (the *_est fields of RobotState).

  • ... – Noise variances of the Kalman filter franky uses to estimate the robot state (the *_est fields of RobotState).

  • kalman_control_adaptation_rate – Rate of adaptation of the estimated robot state to the desired robot state.

create_web_session(username: str, password: str, token_storage: bool | str | PathLike = False) → DeskWebSession

Create a web session to the Desk interface of this robot.

Note that this method returns a DeskWebSession, which is only compatible with the legacy Franka Desk API (Panda and FR3 on pre-v1 firmware). For FR3 on System 5+ firmware, use franky.Desk directly.

Parameters:

  • username – Username to log into Franka Desk.

  • password – Password to log into Franka Desk.

  • token_storage – Whether and where to persist control tokens.

Returns:

The Desk web session. Note that the session has to be opened before use, e.g. by using it as a context manager.

join_motion(self: franky._franky._RobotInternal, timeout: SupportsFloat | SupportsIndex | None = None) → bool

Wait for the current motion to finish and throw any exception that occurred during the motion.

Parameters:

timeout – Maximum time to wait [s]. If None, waits indefinitely.

Returns:

True if the motion finished before the timeout expired, False otherwise.

move(*args, **kwargs)

Overloaded function.

  1. move(self: franky._franky._RobotInternal, motion: franky._franky.BaseCartesianPoseMotion, asynchronous: bool = False, limit_rate: bool = False, cutoff_frequency: typing.SupportsFloat | typing.SupportsIndex = 100.0) -> None

Execute the given motion.

If a motion is already running, the new motion is queued and takes over seamlessly. The type of control signal (e.g. joint positions, cartesian velocities, torques, …) must not change while the robot is in motion.

Parameters:

  • motion – The motion to execute.

  • asynchronous – Whether to return immediately instead of waiting for the motion to finish. Asynchronous motions can be joined with join_motion.

  • limit_rate – True if Franka’s rate limiting should be activated. False by default. This could distort your motion!

  • cutoff_frequency – Cutoff frequency for a first order low-pass filter applied on the user commanded signal. Set to franka.kMaxCutoffFrequency to disable.

  1. move(self: franky._franky._RobotInternal, motion: franky._franky.BaseCartesianVelocityMotion, asynchronous: bool = False, limit_rate: bool = False, cutoff_frequency: typing.SupportsFloat | typing.SupportsIndex = 100.0) -> None

Execute the given motion.

If a motion is already running, the new motion is queued and takes over seamlessly. The type of control signal (e.g. joint positions, cartesian velocities, torques, …) must not change while the robot is in motion.

Parameters:

  • motion – The motion to execute.

  • asynchronous – Whether to return immediately instead of waiting for the motion to finish. Asynchronous motions can be joined with join_motion.

  • limit_rate – True if Franka’s rate limiting should be activated. False by default. This could distort your motion!

  • cutoff_frequency – Cutoff frequency for a first order low-pass filter applied on the user commanded signal. Set to franka.kMaxCutoffFrequency to disable.

  1. move(self: franky._franky._RobotInternal, motion: franky._franky.BaseJointPositionMotion, asynchronous: bool = False, limit_rate: bool = False, cutoff_frequency: typing.SupportsFloat | typing.SupportsIndex = 100.0) -> None

Execute the given motion.

If a motion is already running, the new motion is queued and takes over seamlessly. The type of control signal (e.g. joint positions, cartesian velocities, torques, …) must not change while the robot is in motion.

Parameters:

  • motion – The motion to execute.

  • asynchronous – Whether to return immediately instead of waiting for the motion to finish. Asynchronous motions can be joined with join_motion.

  • limit_rate – True if Franka’s rate limiting should be activated. False by default. This could distort your motion!

  • cutoff_frequency – Cutoff frequency for a first order low-pass filter applied on the user commanded signal. Set to franka.kMaxCutoffFrequency to disable.

  1. move(self: franky._franky._RobotInternal, motion: franky._franky.BaseJointVelocityMotion, asynchronous: bool = False, limit_rate: bool = False, cutoff_frequency: typing.SupportsFloat | typing.SupportsIndex = 100.0) -> None

Execute the given motion.

If a motion is already running, the new motion is queued and takes over seamlessly. The type of control signal (e.g. joint positions, cartesian velocities, torques, …) must not change while the robot is in motion.

Parameters:

  • motion – The motion to execute.

  • asynchronous – Whether to return immediately instead of waiting for the motion to finish. Asynchronous motions can be joined with join_motion.

  • limit_rate – True if Franka’s rate limiting should be activated. False by default. This could distort your motion!

  • cutoff_frequency – Cutoff frequency for a first order low-pass filter applied on the user commanded signal. Set to franka.kMaxCutoffFrequency to disable.

  1. move(self: franky._franky._RobotInternal, motion: franky._franky.BaseTorqueMotion, asynchronous: bool = False, limit_rate: bool = False, cutoff_frequency: typing.SupportsFloat | typing.SupportsIndex = 100.0) -> None

Execute the given motion.

If a motion is already running, the new motion is queued and takes over seamlessly. The type of control signal (e.g. joint positions, cartesian velocities, torques, …) must not change while the robot is in motion.

Parameters:

  • motion – The motion to execute.

  • asynchronous – Whether to return immediately instead of waiting for the motion to finish. Asynchronous motions can be joined with join_motion.

  • limit_rate – True if Franka’s rate limiting should be activated. False by default. This could distort your motion!

  • cutoff_frequency – Cutoff frequency for a first order low-pass filter applied on the user commanded signal. Set to franka.kMaxCutoffFrequency to disable.

poll_motion(self: franky._franky._RobotInternal) → bool

Check whether the robot is still in motion. This function is non-blocking and returns immediately. Throw any exceptions that occurred during the motion.

Returns:

Whether the robot is still in motion.

recover_from_errors(self: franky._franky._RobotInternal) → bool

Calls the automatic error recovery of the robot and returns whether the recovery was successful.

Returns:

Whether the recovery was successful.

set_cartesian_impedance(self: franky._franky._RobotInternal, K_x: Annotated[collections.abc.Sequence[SupportsFloat | SupportsIndex], 'FixedSize(6)']) → None

Sets the Cartesian stiffness/compliance (for x, y, z, roll, pitch, yaw) in the internal controller.

The values set using Robot::setCartesianImpedance are used in the direction of the stiffness frame, which can be set with Robot::setK.

Inputs received by the torque controller are not affected by this setting.

Parameters:

K_x – Cartesian impedance values \(K_x=(K_{x_{x,y,z}} \in [10,3000] \frac{N}{m}, K_{x_{R,P,Y}} \in [1,300] \frac{Nm}{rad})\)

Raises:
set_collision_behavior(*args, **kwargs)

Overloaded function.

  1. set_collision_behavior(self: franky._franky._RobotInternal, torque_thresholds: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(7)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[7, 1]”], force_thresholds: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(6)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[6, 1]”]) -> None

Set the collision behavior of the robot.

Parameters:

  • torque_threshold – The torque threshold for the collision behavior in Nm.

  • force_threshold – The force threshold for the collision behavior in N.

  1. set_collision_behavior(self: franky._franky._RobotInternal, lower_torque_threshold: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(7)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[7, 1]”], upper_torque_threshold: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(7)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[7, 1]”], lower_force_threshold: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(6)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[6, 1]”], upper_force_threshold: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(6)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[6, 1]”]) -> None

Set the collision behavior of the robot.

Parameters:

  • lower_torque_threshold – The lower torque threshold for the collision behavior in Nm.

  • upper_torque_threshold – The upper torque threshold for the collision behavior in Nm.

  • lower_force_threshold – The lower force threshold for the collision behavior in N.

  • upper_force_threshold – The upper force threshold for the collision behavior in N.

  1. set_collision_behavior(self: franky._franky._RobotInternal, lower_torque_threshold_acceleration: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(7)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[7, 1]”], upper_torque_threshold_acceleration: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(7)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[7, 1]”], lower_torque_threshold_nominal: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(7)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[7, 1]”], upper_torque_threshold_nominal: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(7)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[7, 1]”], lower_force_threshold_acceleration: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(6)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[6, 1]”], upper_force_threshold_acceleration: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(6)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[6, 1]”], lower_force_threshold_nominal: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(6)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[6, 1]”], upper_force_threshold_nominal: typing.SupportsFloat | typing.SupportsIndex | typing.Annotated[collections.abc.Sequence[typing.SupportsFloat | typing.SupportsIndex], “FixedSize(6)”] | typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[6, 1]”]) -> None

Set the collision behavior of the robot.

Parameters:

  • lower_torque_threshold_acceleration – The lower torque threshold for the collision behavior in Nm during acceleration.

  • upper_torque_threshold_acceleration – The upper torque threshold for the collision behavior in Nm during acceleration.

  • lower_torque_threshold_nominal – The lower torque threshold for the collision behavior in Nm during nominal operation.

  • upper_torque_threshold_nominal – The upper torque threshold for the collision behavior in Nm during nominal operation.

  • lower_force_threshold_acceleration – The lower force threshold for the collision behavior in N during acceleration.

  • upper_force_threshold_acceleration – The upper force threshold for the collision behavior in N during acceleration.

  • lower_force_threshold_nominal – The lower force threshold for the collision behavior in N during nominal operation.

  • upper_force_threshold_nominal – The upper force threshold for the collision behavior in N during nominal operation.

set_ee(self: franky._franky._RobotInternal, NE_T_EE: Annotated[collections.abc.Sequence[SupportsFloat | SupportsIndex], 'FixedSize(16)']) → None

Sets the transformation \(^{NE}T_{EE}\) from nominal end effector to end effector frame.

The transformation matrix is represented as a vectorized 4x4 matrix in column-major format.

Parameters:

NE_T_EE – Vectorized NE-to-EE transformation matrix \(^{NE}T_{EE}\), column-major.

Raises:

See also

RobotState::NE_T_EE for end effector pose in ne-frame “nominal end effector frame NE”.

See also

RobotState::O_T_EE for end effector pose in o-frame “world base frame O”.

See also

RobotState::F_T_EE for end effector pose in f-frame “flange frame F”.

set_guiding_mode(self: franky._franky._RobotInternal, guiding_mode: Annotated[collections.abc.Sequence[bool], 'FixedSize(6)'], elbow: bool) → None

Locks or unlocks guiding mode movement in (x, y, z, roll, pitch, yaw).

If a flag is set to true, movement is unlocked.

Parameters:

  • guiding_mode – Unlocked movement in (x, y, z, R, P, Y) in guiding mode.

  • elbow – True if the elbow is free in guiding mode, false otherwise.

Raises:

Note

Guiding mode can be enabled by pressing the two opposing buttons near the robot’s flange.

set_joint_impedance(self: franky._franky._RobotInternal, K_theta: Annotated[collections.abc.Sequence[SupportsFloat | SupportsIndex], 'FixedSize(7)']) → None

Sets the impedance for each joint in the internal controller.

User-provided torques are not affected by this setting.

Parameters:

K_theta – Joint impedance values \(K_{\theta_{1-7}} = \in [0,14250] \frac{Nm}{rad}\)

Raises:
set_k(self: franky._franky._RobotInternal, EE_T_K: Annotated[collections.abc.Sequence[SupportsFloat | SupportsIndex], 'FixedSize(16)']) → None

Sets the transformation \(^{EE}T_K\) from end effector frame to stiffness frame.

The transformation matrix is represented as a vectorized 4x4 matrix in column-major format.

Parameters:

EE_T_K – Vectorized EE-to-K transformation matrix \(^{EE}T_K\), column-major.

Raises:

See also

Robot for an explanation of the stiffness frame.

set_load(self: franky._franky._RobotInternal, load_mass: SupportsFloat | SupportsIndex, F_x_Cload: Annotated[collections.abc.Sequence[SupportsFloat | SupportsIndex], 'FixedSize(3)'], load_inertia: Annotated[collections.abc.Sequence[SupportsFloat | SupportsIndex], 'FixedSize(9)']) → None

Sets dynamic parameters of a payload.

Parameters:

  • load_mass – Mass of the load in \([kg]\).

  • F_x_Cload – Translation from flange to center of mass of load \(^Fx_{C_\text{load}}\) in \([m]\).

  • load_inertia – Inertia matrix \(I_\text{load}\) in \([kg \times m^2]\), column- major.

Raises:

Note

This is not for setting end effector parameters, which have to be set in the administrator’s interface.

stop(self: franky._franky._RobotInternal) → None

Stops all currently running motions.

If a control or motion generator loop is running in another thread, it will be preempted with a franka::ControlException.

Raises:
control_rate = 0.001
property current_cartesian_state

Returns the current cartesian state of the robot.

Returns:

The current cartesian state of the robot.

property current_cartesian_velocity

Returns the current cartesian velocity of the robot.

Returns:

The current cartesian velocity of the robot.

property current_control_signal_type

The type of the current control signal.

property current_joint_positions

Returns the current joint positions of the robot.

Returns:

The current joint positions of the robot.

property current_joint_state

Returns the current joint state of the robot.

Returns:

The current joint state of the robot.

property current_joint_velocities

Returns the current joint velocities of the robot.

Returns:

The current joint velocities of the robot.

property current_pose

Returns the current pose of the robot.

Returns:

The current pose of the robot.

degrees_of_freedom = 7
property elbow_acceleration_limit

Elbow acceleration limit [rad/s²].

property elbow_jerk_limit

Elbow jerk limit [rad/s³].

property elbow_velocity_limit

Elbow velocity limit [rad/s].

property fci_hostname

The hostname of the robot.

property has_errors

Returns whether the robot has errors.

Returns:

Whether the robot has errors.

property is_in_control

Whether the robot is currently in control, i.e. a motion is being executed.

property joint_acceleration_limit

Joint acceleration limit [rad/s²].

property joint_jerk_limit

Joint jerk limit [rad/s³].

property joint_velocity_limit

Joint velocity limit [rad/s].

property model

The model of the robot.

The model is loaded in the constructor, so calling this function does not incur any overhead.

property model_urdf

The URDF of the robot model as string.

property relative_dynamics_factor

Returns the current global relative dynamics factor of the robot.

Returns:

The current relative dynamics factor of the robot.

property rotation_acceleration_limit

Rotational acceleration limit [rad/s²].

property rotation_jerk_limit

Rotational jerk limit [rad/s³].

property rotation_velocity_limit

Rotational velocity limit [rad/s].

property state

Returns the current state of the robot.

Returns:

The current state of the robot.

property translation_acceleration_limit

Translational acceleration limit [m/s²].

property translation_jerk_limit

Translational jerk limit [m/s³].

property translation_velocity_limit

Translational velocity limit [m/s].