franky Control Library

franky is a high-level control library for Franka robots that supports both Python and C++. It uses the Ruckig library to plan time-optimal trajectories, allowing for smooth motion without requiring the user to manage 1 kHz real-time programming.

Key capabilities include:

• Trajectory Control: Cartesian (position/velocity) and Joint (position/velocity) control.
• Torque Control: Direct joint torque control and built-in Cartesian/Joint impedance control.
• Real-time Preemption: Ability to change targets or preempt motions on the fly.
• Reactive Behavior: Define reactions to unexpected events like environmental contact.
• Callbacks: Non-blocking motion and reaction callbacks for logging or debugging.
• Full libfranka Access: Direct Python access to most libfranka functionality (e.g., gripper control, reading robot state, setting force thresholds).

Franky supports four primary trajectory control modes. Each mode has specific motion classes for point-to-point, waypoint, or stop commands:

Joint Position Control

Used for moving specific joints to target positions. Classes: Motion, JointMotion, JointWaypointMotion, JointWaypoint, JointStopMotion, BaseJointPositionMotion.

Joint Velocity Control

Used for controlling the speed of individual joints. Classes: JointVelocityMotion, JointVelocityWaypointMotion, JointVelocityWaypoint, JointVelocityStopMotion, BaseJointVelocityMotion.

Cartesian Position Control

Used for moving the end-effector to specific poses in 3D space. Classes: CartesianMotion, CartesianWaypointMotion, CartesianWaypoint, CartesianStopMotion, BaseCartesianPoseMotion.

Cartesian Velocity Control

Used for controlling the end-effector's linear and angular velocity. Classes: CartesianVelocityMotion, CartesianVelocityWaypointMotion, CartesianVelocityWaypoint, CartesianVelocityStopMotion, BaseCartesianVelocityMotion.

To prevent blocking your main execution thread, use the asynchronous versions of gripper commands (moveAsync in C++, move_async in Python).

In C++, these return a std::future<bool>. You can use wait_for to implement timeouts. If a timeout occurs, you should call gripper.stop() to cancel the motion.

In Python, move_async returns an object where .wait(timeout_seconds) returns a boolean indicating if the operation completed within the window. If it returns False, call gripper.stop().

// C++ Timeout Example
std::future<bool> success_future = gripper.moveAsync(0.05, speed);

if (success_future.wait_for(std::chrono::seconds(1)) != std::future_status::ready) {
  gripper.stop();
  success_future.wait();
  std::cout << "Gripper motion timed out." << std::endl;
} else {
  std::cout << "Success: " << success_future.get() << std::endl;
}

# Python Timeout Example
success_future = gripper.move_async(0.05, speed)

if success_future.wait(1):
    print(f"Success: {success_future.get()}")
else:
    gripper.stop()
    success_future.wait()
    print("Gripper motion timed out.")

Impedance control in franky provides client-side spring-damper laws in torque mode. It allows the robot to behave like a mass-spring-damper system rather than following a rigid trajectory.

There are two primary variants for both joint-space and Cartesian impedance:

1. Fixed-target motions (JointImpedanceMotion, CartesianImpedanceMotion): These interpret a target once at the start of the motion and regulate toward it.
2. Tracking motions (JointImpedanceTrackingMotion, CartesianImpedanceTrackingMotion): These keep the controller alive and allow for online updates to references and gains. In Python, the recommended interface for continuous updates (e.g., for manual guidance or teleoperation) is using the JointImpedanceTracker or CartesianImpedanceTracker classes.

When updating gains via set_gains(), changes are smoothed in the real-time loop using exponential interpolation to avoid abrupt stiffness steps.

Relative dynamics factors allow you to scale the velocity, acceleration, and jerk limits of a motion. These factors can be set at three different layers:

1. Robot level: Set via robot.relative_dynamics_factor.
2. Move command level: Set via the relative_dynamics_factor argument in robot.move().
3. Motion level: Set as a parameter on the motion object itself.

Multiplication Rule: Factors from different layers are multiplied together, not overridden. For example, a factor on a motion will scale down the existing robot-level factor. A motion-level factor can only reduce dynamics, never increase them.

Exception - MAX_DYNAMICS: If any layer sets the factor to RelativeDynamicsFactor.MAX_DYNAMICS, the motion will execute with maximum velocity, acceleration, and jerk limits, ignoring all other layers.

⚠️ Warning: MAX_DYNAMICS should only be used for emergency stops (e.g., unexpected contact). Using it for standard motions is dangerous and likely to cause discontinuity errors.

# Setting a global scalar factor for the robot
robot.relative_dynamics_factor = 0.05

# Setting separate scaling factors for velocity, acceleration, and jerk
robot.relative_dynamics_factor = RelativeDynamicsFactor(0.05, 0.1, 0.15)

# Setting a factor during a specific move command (multiplied by robot factor)
robot.move(m_jp2, relative_dynamics_factor=0.8)