libfranka

libfranka is a C++ library for Franka Robotics research robots

README

libfranka: C++ Library for Franka Robotics Research Robots

codecov

libfranka is a C++ library that provides low-level control of Franka Robotics research robots. The API References offers an overview of its capabilities, while the Franka Control Interface (FCI) documentation 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 Robot System Version Compatibility.

Key Features

  • Low-level control: Access precise motion control for research robots.

  • Real-time communication: Interact with the robot in real-time.

  • Multi-platform support: Ubuntu 20.04, 22.04, and 24.04 LTS

1. System Requirements

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

Operating System:
Build Tools (for building from source):

  • GCC 9 or later

  • CMake 3.22 or later

  • Git

Hardware:

  • Franka Robotics robot with FCI feature installed

  • Network connection to robot (1000BASE-T Ethernet recommended)

3. Building with Docker (Development Environment)

Docker provides a consistent, isolated build environment. This method is ideal for:

  • Development and testing

  • Building for multiple Ubuntu versions

  • Avoiding dependency conflicts on your host system

Prerequisites

  • Docker installed on your system

  • Visual Studio Code with Dev Containers extension (optional, for VS Code users)

Clone the Repository

git clone --recurse-submodules https://github.com/frankarobotics/libfranka.git
cd libfranka
git checkout 0.19.0  # or your desired version

Method B: Using Docker Command Line

  1. Build the Docker image

    # For Ubuntu 20.04
docker build --build-arg UBUNTU_VERSION=20.04 -t libfranka-build:20.04 .ci/

# For Ubuntu 22.04
docker build --build-arg UBUNTU_VERSION=22.04 -t libfranka-build:22.04 .ci/

# For Ubuntu 24.04
docker build --build-arg UBUNTU_VERSION=24.04 -t libfranka-build:24.04 .ci/

  2. Run the container and build

    docker run --rm -it -v $(pwd):/workspaces -w /workspaces libfranka-build:20.04

# Inside container:
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF ..
cmake --build . -- -j$(nproc)
cpack -G DEB
exit

  3. Install on host system

    cd build
sudo dpkg -i libfranka*.deb

4. Building from Source (Advanced)

Prerequisites

System packages:

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

Ubuntu 20.04: ensure CMake >= 3.22:

wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc | gpg --dearmor -o /usr/share/keyrings/kitware-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ focal main" | sudo tee /etc/apt/sources.list.d/kitware.list
sudo apt-get update
sudo apt-get install -y cmake

Remove Existing Installations

sudo apt-get remove -y "*libfranka*"

Build Dependencies from Source

Follow these steps in order. All dependencies are built with static linking.

1. Boost 1.77.0

git clone --depth 1 --recurse-submodules --shallow-submodules \
    --branch boost-1.77.0 https://github.com/boostorg/boost.git
cd boost
./bootstrap.sh --prefix=/usr/local
sudo ./b2 install -j$(nproc)
cd .. && rm -rf boost

2. TinyXML2

git clone --depth 1 --branch 10.0.0 https://github.com/leethomason/tinyxml2.git
cd tinyxml2
mkdir build && cd build

cmake .. \
  -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local

make -j$(nproc)
sudo make install

cd ../.. && rm -rf tinyxml2

3. console_bridge

git clone --depth 1 --branch 1.0.2 https://github.com/ros/console_bridge.git
cd console_bridge
mkdir build && cd build

cmake .. \
  -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local

make -j$(nproc)
sudo make install

cd ../..
rm -rf console_bridge

4. urdfdom_headers

git clone --depth 1 --branch 1.0.5 https://github.com/ros/urdfdom_headers.git
cd urdfdom_headers
mkdir build && cd build

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local

make -j$(nproc)
sudo make install

cd ../..
rm -rf urdfdom_headers

5. urdfdom (with patch)

wget https://raw.githubusercontent.com/frankarobotics/libfranka/main/.ci/urdfdom.patch

git clone --depth 1 --branch 4.0.0 https://github.com/ros/urdfdom.git
cd urdfdom

git apply ../urdfdom.patch

mkdir build && cd build
cmake .. \
  -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local

make -j$(nproc)
sudo make install
cd ../..
rm -rf urdfdom

6. Assimp

git clone --depth 1 --recurse-submodules --shallow-submodules \
    --branch v5.4.3 https://github.com/assimp/assimp.git
cd assimp && mkdir build && cd build
cmake .. -DBoost_USE_STATIC_LIBS=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
    -DBUILD_SHARED_LIBS=OFF -DASSIMP_BUILD_TESTS=OFF \
    -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
make -j$(nproc) && sudo make install
cd ../.. && rm -rf assimp

7. Pinocchio (with patch)

wget https://raw.githubusercontent.com/frankarobotics/libfranka/main/.ci/pinocchio.patch
git clone --depth 1 --recurse-submodules --shallow-submodules \
    --branch v3.4.0 https://github.com/stack-of-tasks/pinocchio.git
cd pinocchio && git apply ../pinocchio.patch
mkdir build && cd build
cmake .. -DBoost_USE_STATIC_LIBS=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
    -DBUILD_SHARED_LIBS=OFF -DBUILD_PYTHON_INTERFACE=OFF \
    -DBUILD_DOCUMENTATION=OFF -DBUILD_TESTING=OFF \
    -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
make -j$(nproc) && sudo make install
cd ../.. && rm -rf pinocchio

Build libfranka

git clone --recurse-submodules https://github.com/frankarobotics/libfranka.git
cd libfranka
git checkout 0.19.0
git submodule update --init --recursive

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release \
      -DBUILD_TESTS=OFF \
      -DCMAKE_INSTALL_PREFIX=/usr/local ..
cmake --build . -- -j$(nproc)

Create Debian Package (Optional)

Inside the build folder, run:

cpack -G DEB
sudo dpkg -i libfranka*.deb

5. Verifying Installation

After installation (any method), verify that libfranka is properly installed:

Check library file:

ls -l /usr/lib/libfranka.so

Expected output:

/usr/lib/libfranka.so -> libfranka.so.0.19.0

Check header files:

ls /usr/include/franka/

Expected output:

active_control_base.h      active_torque_control.h  control_tools.h
gripper_state.h            lowpass_filter.h         robot.h
...

Check installed package version:

dpkg -l | grep libfranka

Expected output:

ii  libfranka  0.19.0  amd64  libfranka - Franka Robotics C++ library

6. Usage

After installation, configure your system for real-time control and run example programs:

System Setup

  1. Network configuration: Follow Minimum System and Network Requirements

  2. Real-time kernel: See Setting up the Real-Time Kernel

  3. Getting started: Read the Getting Started Manual

Running Examples

If you built from source, example programs are in the build/examples/ directory:

cd build/examples
./communication_test <robot-ip>

Replace <robot-ip> with your robot’s IP address (e.g., 192.168.1.1).

For more examples, see the Usage Examples documentation.

7. Pylibfranka (Python Bindings)

Pylibfranka provides Python bindings for libfranka, allowing robot control with Python.

Installation

Pylibfranka is included in the libfranka Debian packages. For manual installation:

# Build with Python bindings enabled
cd libfranka/build
cmake -DGENERATE_PYLIBFRANKA=ON ..
cmake --build . -- -j$(nproc)
sudo cmake --install .

Documentation

8. Development Information

Contributing to libfranka

If you’re contributing to libfranka development:

Install pre-commit hooks:

pip install pre-commit
pre-commit install

This automatically runs code formatting and linting checks before each commit.

Run checks manually:

pre-commit run --all-files

Build Options

Customize your build with CMake options:

Option

Description

Default

CMAKE_BUILD_TYPE

Build type (Release/Debug)

Release

BUILD_TESTS

Build unit tests

ON

BUILD_EXAMPLES

Build example programs

ON

GENERATE_PYLIBFRANKA

Build Python bindings

OFF

CMAKE_INSTALL_PREFIX

Installation directory

/usr/local

Example:

cmake -DCMAKE_BUILD_TYPE=Debug \
      -DBUILD_TESTS=ON \
      -DGENERATE_PYLIBFRANKA=ON \
      ..

Troubleshooting

Network connection issues

See the Troubleshooting Network guide.

License

libfranka is licensed under the Apache 2.0 license.

pylibfranka Installation and Usage Guide

This document provides comprehensive instructions for installing and using pylibfranka, a Python binding for libfranka that enables control of Franka Robotics robots.

Table of Contents

Installation

Platform Compatibility

Ubuntu Version

Supported Python Versions

20.04 (Focal)

Python 3.9 only

22.04 (Jammy)

Python 3.9, 3.10, 3.11, 3.12

24.04 (Noble)

Python 3.9, 3.10, 3.11, 3.12

Note: Ubuntu 20.04 users must use Python 3.9 due to glibc compatibility requirements.

From Source

If you need to build from source (e.g., for development or unsupported platforms):

Prerequisites

  • Python 3.9 or newer

  • CMake 3.16 or newer

  • C++ compiler with C++17 support

  • Eigen3 development headers

  • Poco development headers

Disclaimer: If you are using the provided devcontainer, you can skip the prerequisites installation as they are already included in the container.

Installing Prerequisites on Ubuntu/Debian

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

Build and Install

From the root folder, you can install pylibfranka using pip:

pip install .

This will install pylibfranka in your current Python environment.

Examples

pylibfranka comes with three example scripts that demonstrate how to use the library to control a Franka robot.

Joint Position Example

This example demonstrates how to use an external control loop with pylibfranka to move the robot joints.

To run the example:

cd examples
python3 joint_position_example.py --ip <robot_ip>

Where <robot_ip> is the IP address of your Franka robot. If not specified, it defaults to “localhost”.

The active control example: - Sets collision behavior parameters - Starts joint position control with CartesianImpedance controller mode - Moves the robot using an external control loop - Performs a simple motion of selected joints

Joint Impedance Control Example

This example demonstrates how to implement a joint impedance controller that renders a spring-damper system to move the robot through a sequence of target joint configurations.

To run the example:

cd examples
python3 joint_impedance_example.py --ip <robot_ip>

Where –ip is the robot’s IP address (defaults to “localhost”).

The joint impedance example:

  • Implements a minimum jerk trajectory generator for smooth joint motion

  • Uses a spring-damper system for compliant control

  • Moves through a sequence of predefined joint configurations:

    • Home position (slightly bent arm)

    • Extended arm pointing forward

    • Arm pointing to the right

    • Arm pointing to the left

    • Return to home position

  • Includes position holding with dwell time between movements

  • Compensates for Coriolis effects

And more control examples

There are more control examples to discover. All of them can be executed in a similar way:

cd examples
python3 other_example.py --ip <robot_ip>

Gripper Control Example

This example demonstrates how to control the Franka gripper, including homing, grasping, and reading gripper state.

To run the example:

cd examples
python3 move_gripper.py --robot_ip <robot_ip> [--width <width>] [--homing <0|1>] [--speed <speed>] [--force <force>]

Where: - –robot_ip is the robot’s IP address (required) - –width is the object width to grasp in meters (defaults to 0.005) - –homing enables/disables gripper homing (0 or 1, defaults to 1) - –speed is the gripper speed (defaults to 0.1) - –force is the gripper force in N (defaults to 60)

The gripper example:

  • Connects to the gripper

  • Performs homing to estimate maximum grasping width

  • Reads and displays gripper state including:

    • Current width

    • Maximum width

    • Grasp status

    • Temperature

    • Timestamp

  • Attempts to grasp an object with specified parameters

  • Verifies successful grasping

  • Releases the object