franky-control 2.0.0

High-Level Control Library for Franka Robots with Python and C++ Support

franky is a high-level control library for Franka robots, offering Python and C++ support. By providing a high-level control interface, franky eliminates the need for strict real-time programming at 1 kHz, making control from non-real-time environments, such as Python programs, feasible. Instead of relying on low-level control commands, franky expects high-level position or velocity targets and uses Ruckig to plan time-optimal trajectories in real-time.

Although Python does not provide real-time guarantees, franky strives to maintain as much real-time control as possible. Motions can be preempted at any moment, prompting franky to re-plan trajectories on the fly. To handle unforeseen situations—such as unexpected contact with the environment — franky includes a reaction system that allows for updating motion commands dynamically. Furthermore, most non-real-time functionality of libfranka, such as Gripper control is made directly available in Python.

Check out the documentation and the examples for an introduction.

If you do not have a robot at hand, you can also try the simulation first.

🚀 Features

• Control your Franka robot directly from Python in just a few lines! No more endless hours setting up ROS, juggling packages, or untangling dependencies. Just pip install — no ROS at all.

• Trajectory control: Cartesian position, Cartesian velocity, Joint position, and Joint velocity control. franky's trajectory controllers use Ruckig to generate smooth, time-optimal trajectories while respecting velocity, acceleration, and jerk limits.

• Torque control: Direct torque control and Impedance control. Command joint torques directly, or use franky's built-in Cartesian and joint impedance controllers.

• Real-time control from Python and C++ Need to change the target while the robot’s moving? No problem. franky replans trajectories on the fly so that you can preempt motions anytime.

• Reactive behavior Robots don’t always go according to plan. franky lets you define reactions to unexpected events—like contact with the environment — so you can change course in real-time.

• Motion and reaction callbacks Want to monitor what’s happening under the hood? Add callbacks to your motions and reactions. They won’t block the control thread and are super handy for debugging or logging.

• Things are moving too fast? Tune the robot's dynamics to your needs Adjust max velocity, acceleration, and jerk to match your setup or task. Fine control for smooth, safe operation.

• Full Python access to the libfranka API Want to tweak impedance, read the robot state, set force thresholds, or mess with the Jacobian? Go for it. If libfranka supports it, chances are franky does, too.

• Scared to test code on the real system?: franky-sim provides simulator support for franky! It is easy to install and use and serves as a drop-in replacement for the real robot.

📖 Python Quickstart Guide

Real-time kernel already installed and real-time permissions granted? Just install franky via

pip install franky-control

Otherwise, follow the installation instructions first.

We also provide development builds of the latest master (stable) and dev (unstable) branches:

# Replace 10 with your robot server version
# Development (stable): latest master branch
pip install --pre franky-control --extra-index-url "https://timschneider42.github.io/franky/whl/by-robot-server-version/10/"
# Development (unstable): latest dev branch
pip install --pre franky-control --extra-index-url "https://timschneider42.github.io/franky/branches/dev/whl/by-robot-server-version/10/"

Now we are already ready to go! Unlock the brakes in the web interface, activate FCI, and start coding:

from franky import *

robot = Robot("10.90.90.1")  # Replace this with your robot's IP

# Let's start slow (this lets the robot use a maximum of 5% of its velocity, acceleration, and jerk limits)
robot.relative_dynamics_factor = 0.05

# Move the robot 20cm along the relative X-axis of its end-effector
motion = CartesianMotion(Affine([0.2, 0.0, 0.0]), ReferenceType.Relative)
robot.move(motion)

If you are seeing server version mismatch errors, your robot is likely running an older firmware or is an older Franka Panda model — see the FAQ for how to install matching wheels.

📚 Documentation

The full documentation is available at https://timschneider42.github.io/franky/.

📜 License

Starting with version 2.0.0, franky is licensed under the MIT License. Versions prior to 2.0.0 were released under the LGPL v3.0 and remain available under that license.

The Python docstrings of the franka.* entities (python/docstrings.hpp) are extracted from the headers of libfranka, Copyright (c) Franka Robotics GmbH, which is licensed under the Apache License 2.0.

Contributing

If you wish to contribute to this project, you are welcome to create a pull request. Please check out the contributing guidelines first.