ROS 2 Integration for Franka Robotics Research Robots

Note: franka_ros2 is not officially supported on Windows.

Table of Contents

• About
• Caution
• Setup
  • Local Machine Installation
  • Docker Container Installation
• Test the Setup
• Troubleshooting
  • libfranka: UDP receive: Timeout error
• Contributing
• License
• Contact

About

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.

Caution

This package is in rapid development. Users should expect breaking changes and are encouraged to report any bugs via GitHub Issues page.

Franka ROS 2 Dependencies Setup

This repository contains a .repos file that helps you clone the required dependencies for Franka ROS 2.

Prerequisites

Local Machine Installation

1. Install ROS 2 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.

   #### Choose one of the following:

   • 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 **ROS 2** environment but, under some circumstances you may need to do this again:

    source /opt/ros/humble/setup.sh
    

1. Create a ROS 2 Workspace:

   mkdir -p ~/franka_ros2_ws/src
   cd ~/franka_ros2_ws  # not into src
   

1. Clone the Repositories:

    git clone https://github.com/frankaemika/franka_ros2.git src
    

1. Install the dependencies

    vcs import src < src/franka.repos --recursive --skip-existing
    

1. Detect and install project dependencies

   rosdep install --from-paths src --ignore-src --rosdistro humble -y
   

1. Build

   # use the --symlinks option to reduce disk usage, and facilitate development.
   colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
   

1. Adjust Enviroment

   # Adjust environment to recognize packages and dependencies in your newly built ROS 2 workspace.
   source install/setup.sh
   

Docker Container Installation

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.

1. Clone the Repositories:

    git clone https://github.com/frankaemika/franka_ros2.git
    cd franka_ros2
    

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

Option A: using Docker Compose

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

1. Build the container:

      docker compose build
      

1. Run the container:

      docker compose up -d
      

1. Open a shell inside the container:

      docker exec -it franka_ros2 /bin/bash
      

1. Clone the latests dependencies:

      vcs import src < src/franka.repos --recursive --skip-existing
      

1. Build the workspace:

      colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
      

1. Source the built workspace:

      source install/setup.bash
      

1. When you are done, you can exit the shell and delete the container:

      docker compose down -t 0
      

Option B: using Dev Containers in Visual Studio Code

1. Open Visual Studio Code …

   Then, open folder franka_ros2

2. Choose Reopen in container when prompted.

   The container will be built automatically, as required.

3. Clone the latests dependencies:

      vcs import src < src/franka.repos --recursive --skip-existing
      

1. Open a terminal and build the workspace:

      colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
      

1. Source the built workspace environment:

      source install/setup.bash
      

Test the build

   colcon test
   

Remember, franka_ros2 is under development. Warnings can be expected.

Run a sample ROS 2 application

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:=true

Run Gazebo examples with ROS 2

If you want to use Gazebo to run your code, you can find some examples here: franka_gazebo

Troubleshooting

libfranka: UDP receive: Timeout error

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

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for more details on how to contribute to this project.

License

All packages of franka_ros2 are licensed under the Apache 2.0 license.

Contact

For questions or support, please open an issue on the GitHub Issues page.

See the Franka Control Interface (FCI) documentation for more information.

Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.

Contributors must sign-off each commit by adding a Signed-off-by: ... line to commit messages to certify that they have the right to submit the code they are contributing to the project according to the Developer Certificate of Origin (DCO).