libfranka: C++ Library for Franka Robotics Research Robots

[![codecov][codecov-status]][codecov]

libfranka is a C++ library that provides low-level control of Franka Robotics research robots. The [generated API documentation][api-docs] offers an overview of its capabilities, while the [Franka Control Interface (FCI) documentation][fci-docs] provides more information on setting up the robot and utilizing its features and functionalities.

To find the appropriate version to use, please refer to the [Compatibility Matrix][compatibility-matrix].

Key Features

• Low-level control: Access precise motion control for research robots.
• Real-time communication: Interact with the robot in real-time.

Getting Started

1. System Requirements

Before using libfranka, ensure your system meets the following requirements:

• Operating System: [Linux with PREEMPT_RT patched kernel][real-time-kernel] (Ubuntu 16.04 or later, Ubuntu 22.04 recommended)
• Compiler: GCC 7 or later
• CMake: Version 3.10 or later
• Robot: Franka Robotics robot with FCI feature installed

2. Installing dependencies

sudo apt-get update
sudo apt-get install -y build-essential cmake git libpoco-dev libeigen3-dev libfmt-dev

To use libfranka version 0.14.0 or later, you will need to install [pinocchio][stack-of-tasks] and some more dependencies:

sudo apt-get install -y lsb-release curl
sudo mkdir -p /etc/apt/keyrings
curl -fsSL http://robotpkg.openrobots.org/packages/debian/robotpkg.asc | sudo tee /etc/apt/keyrings/robotpkg.asc

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/robotpkg.asc] http://robotpkg.openrobots.org/packages/debian/pub $(lsb_release -cs) robotpkg" | sudo tee /etc/apt/sources.list.d/robotpkg.list

sudo apt-get update
sudo apt-get install -y robotpkg-pinocchio

3. Building and Installation from Source

Before building and installing from source, please uninstall existing installations of libfranka to avoid conflicts:

sudo apt-get remove "*libfranka*"

Clone the Repository

You can clone the repository and choose the version you need by selecting a specific tag:

git clone --recurse-submodules https://github.com/frankaemika/libfranka.git
cd libfranka

List available tags

git tag -l

Checkout a specific tag (e.g., 0.15.0)

git checkout 0.15.0

Update submodules

git submodule update

Create a build directory and navigate to it

mkdir build
cd build

Configure the project and build

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/opt/openrobots/lib/cmake -DBUILD_TESTS=OFF ..
make

Installing libfranka as a Debian Package (Optional but recommended)

Building a Debian package is optional but recommended for easier installation and management. In the build folder, execute:

File truncated at 100 lines see the full file

CHANGELOG

0.15.0 - 2025-01-16

Requires Franka Research 3 System Version >= 5.7.2

• Improved error minimization for joint/cartesian pose velocities and accelerations.
• Updated joint position and cartesian pose examples to start from the initial q or O_T_EE.
• Fixed joint position and cartesian pose low-pass filters to use the same command in the first package.
• Added a general logger, allowing users to implement custom loggers for receiving log messages.
• Fixed the bug that prevented exit in case of network connection interruption.

Important

• The flags fci_joint_motion_generator_position_limits_violation_flag and fci_cartesian_motion_generator_joint_position_limits_violation_flag are now always set to false and will be deprecated in future releases. They will be replaced by joint_position_limits_violation.

BREAKING

• The previous CSV robot state logger has been renamed to robot_state_logger and relocated.

0.14.1 - 2024-09-06

• Added doxygen generation

0.14.0 - 2024-03-26

Requires Franka Research 3 system version >= 5.7.0

• Compute dynamic robot parameters with Pinocchio library.

0.13.5 - 2024-09-06

• Updated doxygen generation

0.13.4 - 2024-09-05

Requires Franka Research 3 system version >= 5.5.0

• Added package.xml for ros humble release

0.13.3 - 2024-01-18

Requires Franka Research 3 system version >= 5.5.0

• Bump libfranka-common version compatible with 5.5.0
• Delete the temporary-workaround max-path-pose deviation. Fixed in the system image.

0.13.2 - 2023-12-04

• Hotfix: (temporary-workaround) for max-path-pose-deviation in ExternalMode for active control.

0.13.1 - 2023-11-30

• Hotfix: (temporary-workaround) for max-path-pose-deviation in ExternalMode for callback based control.

0.13.0 - 2023-11-16

• Add abstract ActiveControlBase class for the ActiveControllers to implement.
• BREAKING Fix function naming errors in robot class.
• BREAKING ActiveController initializer functions return ActiveControlBase

0.12.1 - 2023-09-20

• Fix install common/include typo

0.12.0 - 2023-09-14

Requires Franka Research 3 system version >= 5.2.0

• BREAKING ActiveControl serves now as base class for ActiveTorqueControl, that implements the torque control functionality
• ActiveMotionGenerator class introduced to support external control loops for JointPositions, JointVelocities, CartesianPose and CartesianVelocities

0.11.0 - 2023-08-16

Requires Franka Research 3 system version >= 5.2.0

• BREAKING Instead of using constants, velocity limits in rate-limiter are computed based on the current desired joint position.
• Allow external control loops by the introduction of the ActiveControl read-write-interface for torque-control

0.10.0 - 2022-09-02

Requires Franka Research 3 system version >= 5.2.0

• BREAKING Remove getVirtualWall and setFilters commands
• BREAKING Disable rate-limiter by default
• BREAKING Adapt rate limiting values in rate_limiting.h for FR3 robot

0.9.2 - 2022-08-31

Requires Panda system version >= 4.2.1

• Revert usage of set_version_from_git in CMakeLists.txt, using hardcoded values instead

0.9.1 - 2022-08-26

Requires Panda system version >= 4.2.1

• Use orthonormalized rotations in cartesianLowpassFilter, limitRate and cartesian_impedance_control example
• Support building libfranka from outside the library, so the debian package name can be set externally.
• Check if GitHub remote is always in sync
• Bug fixes in rate_limiting_tests.cpp

File truncated at 100 lines see the full file