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.

• 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

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

Operating System:

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Ubuntu 24.04 LTS (Noble Numbat)
• Linux with PREEMPT_RT patched kernel recommended for real-time control

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)

The easiest way to install libfranka is by using the pre-built Debian packages published on GitHub.

substitute <libfranka_version> with the desired version number (e.g., 0.19.0). And substitute <ubuntu_codename> with your Ubuntu codename (e.g., focal, jammy, noble). you can find it by running lsb_release -cs.

# Download package
wget https://github.com/frankarobotics/libfranka/releases/download/<libfranka_version>/libfranka_<libfranka_version>_<ubuntu_codename>_amd64.deb
# Download checksum
wget https://github.com/frankarobotics/libfranka/releases/download/<libfranka_version>/libfranka_<libfranka_version>_<ubuntu_codename>_amd64.deb.sha256
# Verify package integrity
sha256sum -c libfranka_<libfranka_version>_<ubuntu_codename>_amd64.deb.sha256
# Install package
sudo dpkg -i libfranka_<libfranka_version>_<ubuntu_codename>_amd64.deb

The following example installs libfranka 0.19.0 on Ubuntu 22.04 (Jammy):

wget https://github.com/frankarobotics/libfranka/releases/download/0.19.0/libfranka_0.19.0_jammy_amd64.deb
wget https://github.com/frankarobotics/libfranka/releases/download/0.19.0/libfranka_0.19.0_jammy_amd64.deb.sha256
sha256sum -c libfranka_0.19.0_jammy_amd64.deb.sha256
sudo dpkg -i libfranka_0.19.0_jammy_amd64.deb

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

• Docker installed on your system
• Visual Studio Code with Dev Containers extension (optional, for VS Code users)

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

1. Install Visual Studio Code

   Download from https://code.visualstudio.com/

2. Install the Dev Containers extension

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X)
   • Search for "Dev Containers" and install it

3. Configure Ubuntu version (optional, defaults to 20.04)

   Edit devcontainer_distro file in the project root and specify the desired Ubuntu version:

   22.04 # Ubuntu 22.04 (default)

4. Open in container

   • Open the project in VS Code: code .
   • Press Ctrl+Shift+P
   • Select "Dev Containers: Reopen in Container"
   • Wait for the container to build

5. Build libfranka

   Open a terminal in VS Code and run:

   mkdir build && cd build
   cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF ..
   cmake --build . -- -j$(nproc)

6. Create Debian package (optional)

   cd build
   cpack -G DEB

   The package will be in the build/ directory. To install on your host system:

   # On host system (outside container)
   cd libfranka/build
   sudo dpkg -i libfranka*.deb

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

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

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

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

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)

Inside the build folder, run:

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

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

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

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

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.

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

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 .

• API Documentation

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

Customize your build with CMake options:

Example:

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

Network connection issues

See the Troubleshooting Network guide.

libfranka is licensed under the Apache 2.0 license.

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

• Installation
• Examples
• Troubleshooting

The easiest way to install pylibfranka is via pip. Pre-built wheels include all necessary dependencies.

pip install pylibfranka

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

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

• 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.

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

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

pip install .

This will install pylibfranka in your current Python environment.

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

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

This example shows how to read and display the complete state of the robot.

To run the example:

cd examples
python3 print_robot_state.py --ip <robot_ip> [--rate <rate>] [--count <count>]

Where: - --ip is the robot's IP address (defaults to "localhost") - --rate is the frequency at which to print the state in Hz (defaults to 0.5) - --count is the number of state readings to print (defaults to 1, use 0 for continuous)

The print robot state example:

• Connects to the robot
• Reads the complete robot state
• Prints detailed information about:
  • Joint positions, velocities, and torques
  • End effector pose and velocities
  • External forces and torques
  • Robot mode and error states
  • Mass and inertia properties

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

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>

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