Note: franka_ros2 is not officially supported on Windows.
The franka_ros2 repository provides a ROS 2 integration of libfranka, allowing efficient control of the Franka Robotics arm within the ROS 2 framework. This project is designed to facilitate robotic research and development by providing a robust interface for controlling the research versions of Franka Robotics robots.
For convenience, we provide Dockerfile and docker-compose.yml files. While it is possible to build franka_ros2 directly on your local machine, this approach requires manual installation of certain dependencies, while many others will be automatically installed by the ROS 2 build system (e.g., via rosdep). This can result in a large number of libraries being installed on your system, potentially causing conflicts. Using Docker encapsulates these dependencies within the container, minimizing such risks. Docker also ensures a consistent and reproducible build environment across systems. For these reasons, we recommend using Docker.
This package is in rapid development. Users should expect breaking changes and are encouraged to report any bugs via GitHub Issues page.
This repository contains a .repos file that helps you clone the required dependencies for Franka ROS 2.
-
Install ROS2 Development environment
franka_ros2 is built upon ROS 2 Humble.
To set up your ROS 2 environment, follow the official humble installation instructions provided here. The guide discusses two main installation options: Desktop and Bare Bones.
-
ROS 2 "Desktop Install" (
ros-humble-desktop)
Includes a full ROS 2 installation with GUI tools and visualization packages (e.g., Rviz and Gazebo).
Recommended for users who need simulation or visualization capabilities. -
"ROS-Base Install (Bare Bones)" (
ros-humble-ros-base)
A minimal installation that includes only the core ROS 2 libraries.
Suitable for resource-constrained environments or headless systems.
# replace <YOUR CHOICE> with either ros-humble-desktop or ros-humble-ros-base sudo apt install <YOUR CHOICE>
Also install the Development Tools package:
sudo apt install ros-dev-tools
Installing the Desktop or Bare Bones should automatically source the ROS2 environment but, under some circumstances you may need to do this again:
source /opt/ros/humble/setup.sh -
-
Create a ROS 2 Workspace:
mkdir -p ~/franka_ros2_ws/src cd ~/franka_ros2_ws # not into src
-
Clone the Repositories:
git clone https://github.com/frankaemika/franka_ros2.git src
-
Install the dependencies
vcs import src < src/franka.repos --recursive --skip-existing -
Detect and install project dependencies
rosdep install --from-paths src --ignore-src --rosdistro humble -y
-
Build
# use the --symlinks option to reduce disk usage, and facilitate development. colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -
Adjust Enviroment
# Adjust environment to recognize packages and dependencies in your newly built ROS 2 workspace. source install/setup.sh
The franka_ros2 package includes a Dockerfile and a docker-compose.yml, which allows you to use franka_ros2 packages without manually installing ROS 2. Also, the support for Dev Containers in Visual Studio Code is provided.
For detailed instructions, on preparing VSCode to use the .devcontainer follow the setup guide from VSCode devcontainer_setup.
-
Clone the Repositories:
git clone https://github.com/frankaemika/franka_ros2.git cd franka_ros2We provide separate instructions for using Docker with Visual Studio Code or the command line. Choose one of the following options:
Option A: Set up and use Docker from the command line (without Visual Studio Code).
Option B: Set up and use Docker with Visual Studio Code's Docker support.
-
Save the current user id into a file:
echo -e "USER_UID=$(id -u $USER)\nUSER_GID=$(id -g $USER)" > .env
It is needed to mount the folder from inside the Docker container.
-
Build the container:
docker compose build
-
Run the container:
docker compose up -d
-
Open a shell inside the container:
docker exec -it franka_ros2 /bin/bash -
Clone the latests dependencies:
vcs import src < src/franka.repos --recursive --skip-existing -
Build the workspace:
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
-
Source the built workspace:
source install/setup.bash -
When you are done, you can exit the shell and delete the container:
docker compose down -t 0
-
Open Visual St A2AA udio Code ...
Then, open folder
franka_ros2 -
Choose
Reopen in containerwhen prompted.The container will be built automatically, as required.
-
Clone the latests dependencies:
vcs import src < src/franka.repos --recursive --skip-existing -
Open a terminal and build the workspace:
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
-
Source the built workspace environment:
source install/setup.bash
colcon testRemember, franka_ros2 is under development.
Warnings can be expected.
To verify that your setup works correctly without a robot, you can run the following command to use dummy hardware:
ros2 launch franka_fr3_moveit_config moveit.launch.py robot_ip:=dont-care use_fake_hardware:=trueIf you encounter a UDP receive timeout error while communicating with the robot, avoid using Docker Desktop. It may not provide the necessary real-time capabilities required for reliable communication with the robot. Instead, using Docker Engine is sufficient for this purpose.
A real-time kernel is essential to ensure proper communication and to prevent timeout issues. For guidance on setting up a real-time kernel, please refer to the Franka installation documentation.
Contributions are welcome! Please see CONTRIBUTING.md for more details on how to contribute to this project.
All packages of franka_ros2 are licensed under the Apache 2.0 license.
For questions or support, please open an issue on the GitHub Issues page.
See the Franka Control Interface (FCI) documentation for more information.