franka_ros

ROS Franka robot interfaces.

This module defines ROS-backed interfaces for Franka Panda and FR3 robots. It provides state handling, controller integration, compliance management, load configuration, collision-behavior services, and tool-center-point updates.

class robotblockset.ros.franka_ros.JointCompliance[source]

Bases: _struct

Container for Franka joint-compliance parameters.

Attributes:

  • K (np.ndarray | None) – Joint stiffness vector.

  • D (np.ndarray | None) – Joint damping vector.

Initialize joint stiffness and damping storage.

Notes

Values are initialized to None and are populated later from the Franka defaults or explicit user settings.

__init__() → None[source]

Initialize joint stiffness and damping storage.

Notes

Values are initialized to None and are populated later from the Franka defaults or explicit user settings.

class robotblockset.ros.franka_ros.CartesianCompliance[source]

Bases: _struct

Container for Franka Cartesian-compliance parameters.

Attributes:

  • Kp (np.ndarray | None) – Translational stiffness vector.

  • Kr (np.ndarray | None) – Rotational stiffness vector.

  • R (np.ndarray | None) – Rotation matrix of the translational stiffness frame.

  • D (float | None) – Damping scaling factor.

Initialize Cartesian stiffness, orientation, and damping storage.

Notes

Values are initialized to None and are populated later from the Franka defaults or explicit user settings.

__init__() → None[source]

Initialize Cartesian stiffness, orientation, and damping storage.

Notes

Values are initialized to None and are populated later from the Franka defaults or explicit user settings.

class robotblockset.ros.franka_ros.FrankaCollisionBehaviour[source]

Bases: _struct

Container for Franka collision-threshold parameters.

Attributes:

  • lower_torque_thresholds_acceleration (np.ndarray | None) – Lower joint-torque thresholds in acceleration mode.

  • upper_torque_thresholds_acceleration (np.ndarray | None) – Upper joint-torque thresholds in acceleration mode.

  • lower_torque_thresholds_nominal (np.ndarray | None) – Lower joint-torque thresholds in nominal mode.

  • upper_torque_thresholds_nominal (np.ndarray | None) – Upper joint-torque thresholds in nominal mode.

  • lower_force_thresholds_acceleration (np.ndarray | None) – Lower Cartesian force thresholds in acceleration mode.

  • upper_force_thresholds_acceleration (np.ndarray | None) – Upper Cartesian force thresholds in acceleration mode.

  • lower_force_thresholds_nominal (np.ndarray | None) – Lower Cartesian force thresholds in nominal mode.

  • upper_force_thresholds_nominal (np.ndarray | None) – Upper Cartesian force thresholds in nominal mode.

Initialize storage for Franka collision-threshold parameters.

__init__() → None[source]

Initialize storage for Franka collision-threshold parameters.

class robotblockset.ros.franka_ros.FrankaDefaults[source]

Bases: _struct

Container for default Franka controller and safety parameters.

Attributes:

  • InternalController (str) – Default internal Franka controller mode.

  • JointCompliance (JointCompliance) – Default joint-compliance parameters.

  • CartesianCompliance (CartesianCompliance) – Default Cartesian-compliance parameters.

  • CollisionBehavior (FrankaCollisionBehaviour) – Default collision-threshold parameters.

Initialize default Franka compliance and collision parameters.

__init__() → None[source]

Initialize default Franka compliance and collision parameters.

class robotblockset.ros.franka_ros.panda_ros(ns: str = '', model: str = 'panda', init_node: bool = True, multi_node: bool = False, control_strategy: str = 'JointImpedance')[source]

Bases: panda_spec, fr3_spec, robot_ros

ROS interface for Franka Panda and FR3 robots.

Attributes:

  • collision_behavior (FrankaCollisionBehaviour) – Active collision-threshold configuration.

  • joint_compliance (JointCompliance) – Active joint-compliance configuration.

  • cartesian_compliance (CartesianCompliance) – Active Cartesian-compliance configuration.

Initialize a ROS-backed Franka Panda or FR3 wrapper.

Parameters:

  • ns (str, optional) – ROS namespace of the robot.

  • model (str, optional) – Robot model, typically "panda" or "fr3".

  • init_node (bool, optional) – If True, initialize a ROS node for the wrapper.

  • multi_node (bool, optional) – If True, initialize the ROS node in anonymous mode.

  • control_strategy (str, optional) – Initial RobotBlockSet control strategy.

__init__(ns: str = '', model: str = 'panda', init_node: bool = True, multi_node: bool = False, control_strategy: str = 'JointImpedance') → None[source]

Initialize a ROS-backed Franka Panda or FR3 wrapper.

Parameters:

  • ns (str, optional) – ROS namespace of the robot.

  • model (str, optional) – Robot model, typically "panda" or "fr3".

  • init_node (bool, optional) – If True, initialize a ROS node for the wrapper.

  • multi_node (bool, optional) – If True, initialize the ROS node in anonymous mode.

  • control_strategy (str, optional) – Initial RobotBlockSet control strategy.

ResetCurrentTarget(do_move: bool = False, **kwargs: Any) → None[source]

Reset the current target and optionally synchronize the active controller target.

Parameters:

  • do_move (bool, optional) – If True, propagate the current measured state to the active controller target before resetting the RobotBlockSet state.

  • **kwargs (Any) – Additional keyword arguments forwarded to the base implementation.

GetStateCallback(data: franka_msgs.msg.FrankaState) → None[source]

Store the latest Franka state message.

Parameters:

data (FrankaState) – Franka state message received from ROS.

GetState() → franka_msgs.msg.FrankaState | None[source]

Update the RobotBlockSet state from the latest Franka state message.

Returns:

Latest Franka state message, if available.

Return type:

FrankaState | None

GetCollisions() → Tuple[Any, Any][source]

Return the latest joint and Cartesian collision indicators.

GetContacts() → Tuple[Any, Any][source]

Return the latest joint and Cartesian contact indicators.

GetCollisionBehaviour() → Dict[str, Any][source]

Return the configured Franka collision-threshold parameters.

SetCollisionBehavior(F: ndarray, tq: ndarray, F_low: ndarray | None = None, tq_low: ndarray | None = None, restart: bool = False) → int | None[source]

Set nominal Franka collision thresholds.

Parameters:

  • F (WrenchType) – Nominal Cartesian force and torque thresholds.

  • tq (JointTorqueType) – Nominal joint-torque thresholds.

  • F_low (WrenchType, optional) – Lower Cartesian thresholds. If None, half of F is used.

  • tq_low (JointTorqueType, optional) – Lower joint-torque thresholds. If None, half of tq is used.

  • restart (bool, optional) – If True, restart the active controller around the update.

Returns:

1 on exception, otherwise None.

Return type:

int | None

SetFullCollisionBehavior(F: ndarray, tq: ndarray, F_acc: ndarray | None = None, tq_acc: ndarray | None = None, F_low: ndarray | None = None, tq_low: ndarray | None = None, F_acc_low: ndarray | None = None, tq_acc_low: ndarray | None = None, restart: bool = False) → int | None[source]

Set nominal and acceleration Franka collision thresholds.

Parameters:

  • F (WrenchType) – Nominal Cartesian force and torque thresholds.

  • tq (JointTorqueType) – Nominal joint-torque thresholds.

  • F_acc (WrenchType, optional) – Acceleration-mode Cartesian thresholds.

  • tq_acc (JointTorqueType, optional) – Acceleration-mode joint-torque thresholds.

  • F_low (WrenchType, optional) – Lower nominal Cartesian thresholds.

  • tq_low (JointTorqueType, optional) – Lower nominal joint-torque thresholds.

  • F_acc_low (WrenchType, optional) – Lower acceleration Cartesian thresholds.

  • tq_acc_low (JointTorqueType, optional) – Lower acceleration joint-torque thresholds.

  • restart (bool, optional) – If True, restart the active controller around the update.

Returns:

1 on exception, otherwise None.

Return type:

int | None

GetCartesianCompliance() → Tuple[Any, Any, Any, Any][source]

Return the active Cartesian compliance parameters.

SetCartesianCompliance(Kp: ndarray | None = None, Kr: ndarray | None = None, R: ndarray | None = None, D: float | None = None, hold_pose: bool = True) → int[source]

Update Cartesian compliance parameters through the active controller.

Parameters:

  • Kp (Vector3DType, optional) – Translational stiffness values.

  • Kr (Vector3DType, optional) – Rotational stiffness values.

  • R (RotationMatrixType, optional) – Rotation matrix of the translational stiffness frame.

  • D (float, optional) – Damping scaling factor.

  • hold_pose (bool, optional) – If True, hold the current target pose while updating compliance.

Returns:

Result code returned by the active controller.

Return type:

int

GetCartesianStiffness() → Tuple[Any, Any][source]

Return the active Cartesian stiffness parameters.

SetCartesianStiffness(Kp: ndarray | None = None, Kr: ndarray | None = None, hold_pose: bool = True) → int[source]

Update Cartesian stiffness while preserving the remaining compliance settings.

Parameters:

  • Kp (Vector3DType, optional) – Translational stiffness values.

  • Kr (Vector3DType, optional) – Rotational stiffness values.

  • hold_pose (bool, optional) – If True, hold the current target pose while updating stiffness.

Returns:

Result code returned by SetCartesianCompliance().

Return type:

int

GetCartesianDamping() → Any[source]

Return the active Cartesian damping parameter.

SetCartesianDamping(D: float | None = None, hold_pose: bool = True) → int[source]

Update Cartesian damping while preserving the remaining compliance settings.

Parameters:

  • D (float, optional) – Damping scaling factor.

  • hold_pose (bool, optional) – If True, hold the current target pose while updating damping.

Returns:

Result code returned by SetCartesianCompliance().

Return type:

int

SetCartesianSoft(stiffness: Any, hold_pose: bool = True) → int[source]

Scale Cartesian compliance relative to the Franka default values.

Parameters:

  • stiffness (Any) – Scalar or vector compliance scaling factor.

  • hold_pose (bool, optional) – If True, hold the current target pose while updating compliance.

Returns:

0 when the scaling request is applied.

Return type:

int

GetJointCompliance() → Tuple[Any, Any][source]

Return the active joint compliance parameters.

SetJointCompliance(K: ndarray | None = None, D: ndarray | None = None, hold_pose: bool = True) → None[source]

Update joint compliance parameters through the active controller.

Parameters:

  • K (JointTorqueType, optional) – Joint stiffness values.

  • D (JointTorqueType, optional) – Joint damping values.

  • hold_pose (bool, optional) – If True, hold the current target pose while updating compliance.

GetJointStiffness() → Any[source]

Return the active joint stiffness values.

SetJointStiffness(K: ndarray | None = None, hold_pose: bool = True) → None[source]

Update joint stiffness while preserving the remaining compliance settings.

Parameters:

  • K (JointTorqueType, optional) – Joint stiffness values.

  • hold_pose (bool, optional) – If True, hold the current target pose while updating stiffness.

GetJointDamping() → Any[source]

Return the active joint damping values.

SetJointDamping(D: ndarray | None = None, hold_pose: bool = True) → None[source]

Update joint damping while preserving the remaining compliance settings.

Parameters:

  • D (JointTorqueType, optional) – Joint damping values.

  • hold_pose (bool, optional) – If True, hold the current target pose while updating damping.

SetJointSoft(stiffness: Any, hold_pose: bool = True) → None[source]

Scale joint compliance relative to the Franka default values.

SetCartesianImpedanceFranka(stiffness: Any) → int[source]

Set Franka Cartesian impedance.

Sets the cartesian impedance of the internal franka controller.

These values only have effect when franka’s internal motion generators are used.

SetJointImpedanceFranka(stiffness: Any, restart: bool = False) → int[source]

Sets the joint impedance of the internal franka controller :param ——————: :param restart: if True, then controller will first be stopped, impedance changed, then the controller will be started. :type restart: bool, optional

SetTCP(*tcp: Any, frame: str = 'Gripper', send_to_robot: bool = False, EE_frame: str = 'Flage') → None[source]

Set the TCP locally and optionally propagate it to the robot.

SetKFrame(EE_T_K: Any) → int[source]

Set the EE-to-stiffness-frame transform.

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 as follow – EE_T_K float[16] Vectorized EE-to-K transformation matrix , column-major.

GetStiffnessFrame() → ndarray[source]

Return the current EE-to-stiffness-frame transform.

SetStiffnessFrame(T: Any | None = None) → None[source]

Set the stiffness frame.

SetStiffnessFrame Sets the stiffness frame (EETK) relative to EE frame

(controller is temporary stopped!)

SetLoad(mass: float, COM: tuple | None = None, inertia: tuple | None = None) → Any[source]

Update the configured end-effector load on the robot.

SetEEFrame(NE_T_EE: Any) → int[source]

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 as follow – NE_T_EE float[16] 4x4 matrix -> Vectorized NE-to-EE transformation matrix , column-major.

isConnected() → bool[source]

Return whether the ROS Franka interface has been connected.

isReady() → bool[source]

Return whether the ROS Franka interface is ready for commands.

isActive() → bool[source]

Return whether the robot is in an active motion-capable state.

Check(silent: bool = False) → list[source]

Check the current Franka error state.

Parameters:

silent (bool, optional) – If True, suppress status messages while checking the robot.

Returns:

List of active Franka error flags.

Return type:

list[str]

SetNewEEConfig(tool_name: str, restart: bool = True) → int[source]

Load a new end-effector configuration from ROS parameters.

Parameters:

  • tool_name (str) – Name of the tool configuration on the ROS parameter server.

  • restart (bool, optional) – If True, restart the active controller after reconfiguration.

Returns:

0 on success, otherwise a nonzero error code.

Return type:

int

ErrorRecovery(enforce: bool = False, reset_target: bool = True) → int[source]

Recover the robot from an error state.

Parameters:

  • enforce (bool, optional) – If True, skip state checks and send the recovery request immediately.

  • reset_target (bool, optional) – If True, reset the current RobotBlockSet target before recovery.

Returns:

0 when recovery handling completes.

Return type:

int

Start() → Any[source]

Activate the current control mode and prepare for motion.

Returns:

Result returned by the base robot.Start() implementation.

Return type:

Any

Stop() → None[source]

Stop the active motion mode through the base robot API.

CheckContacts() → int[source]

Return whether any Cartesian contact is currently detected.

Returns:

1 if contact is detected, otherwise 0.

Return type:

int

GoTo_qtraj(qt: ndarray, qdott: ndarray, qddott: ndarray, time: Any, wait: float) → int[source]

Execute a joint trajectory through the ROS trajectory interface.

Parameters:

  • qt (JointPathType) – Joint-position trajectory.

  • qdott (JointPathType) – Joint-velocity trajectory.

  • qddott (JointPathType) – Joint-acceleration trajectory.

  • time (Any) – Time vector for the trajectory points.

  • wait (float) – Additional wait time after the trajectory finishes.

Returns:

Motion result code.

Return type:

int

class robotblockset.ros.franka_ros.panda_ros_reconcycle[source]

Bases: panda_ros

ReconCycle-specific Franka Panda ROS wrapper.

Attributes:

Base_link_name (str) – Name of the robot base link used by the ReconCycle setup.

Initialize the ReconCycle-specific Panda wrapper.

__init__() → None[source]

Initialize the ReconCycle-specific Panda wrapper.

shutdown_hook() → None[source]

Handle ROS shutdown for the ReconCycle wrapper.

ResetCurrentTarget(send_msg: bool = True) → Any[source]

Legacy alias for resetting the current target.

Parameters:

send_msg (bool, optional) – Legacy flag mapped to do_move of panda_ros.ResetCurrentTarget().

Returns:

Result returned by panda_ros.ResetCurrentTarget().

Return type:

Any

check_contact() → int[source]

Legacy alias for contact detection.

Returns:

Result returned by CheckContacts().

Return type:

int

on_shutdown() → None[source]

Register the ReconCycle shutdown hook with ROS.

SetNewEEConfig(tool_name: str, mass: float | None = None, COM: list | None = None, trans_mat: list | None = None, inertia: list | None = None, restart: bool = True) → None[source]

Apply a new ReconCycle end-effector configuration.

Parameters:

  • tool_name (str) – Name of the JSON configuration file.

  • mass (float, optional) – Tool mass.

  • COM (list, optional) – Center of mass relative to the robot flange.

  • trans_mat (list, optional) – Flattened transformation matrix from flange to end effector.

  • inertia (list, optional) – Flattened inertia matrix.

  • restart (bool, optional) – If True, restart the active controller around the update.

Classes

CartesianCompliance()

Container for Franka Cartesian-compliance parameters.

FrankaCollisionBehaviour()

Container for Franka collision-threshold parameters.

FrankaDefaults()

Container for default Franka controller and safety parameters.

JointCompliance()

Container for Franka joint-compliance parameters.

panda_ros([ns, model, init_node, ...])

ROS interface for Franka Panda and FR3 robots.

panda_ros_reconcycle()

ReconCycle-specific Franka Panda ROS wrapper.