franky

(opens in a new tab)

(opens in a new tab)

(opens in a new tab)

(opens in a new tab)

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 (opens in a new tab) 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 (opens in a new tab), such as Gripper control is made directly available in Python.

Check out the documentation (opens in a new tab) and the examples (opens in a new tab) for an introduction.

If you do not have a robot at hand, you can also try the simulation (opens in a new tab) 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 (opens in a new tab): Cartesian position (opens in a new tab), Cartesian velocity (opens in a new tab), Joint position (opens in a new tab), and Joint velocity (opens in a new tab) control. franky's trajectory controllers use Ruckig (opens in a new tab) to generate smooth, time-optimal trajectories while respecting velocity, acceleration, and jerk limits.

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

• Real-time control from Python and C++ (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) provides simulator support (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) for how to install matching wheels.

📚 Documentation

The full documentation is available at timschneider42.github.iohttps://timschneider42.github.io/franky/ (opens in a new tab).

📜 License

Starting with version 2.0.0, franky is licensed under the MIT License (opens in a new tab). 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 (opens in a new tab)) are extracted from the headers of libfranka (opens in a new tab), Copyright (c) Franka Robotics GmbH, which is licensed under the Apache License 2.0 (opens in a new tab).

Contributing

If you wish to contribute to this project, you are welcome to create a pull request. Please check out the contributing guidelines (opens in a new tab) first.