ROS 2 Integration for Franka Robotics Research Robots

Note: franka_ros2 is not officially supported on Windows.

Table of Contents

• About
• Caution
• Optional .bashrc Settings
• 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.

Setup

Local Machine Installation

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

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

   source /opt/ros/humble/setup.bash

2. Create a ROS 2 Workspace:

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

3. Clone the Repositories:

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

4. Detect and install project dependencies

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

5. Build

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

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

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

3. Build the container:

   docker compose build

4. Run the container:

   docker compose up -d

5. Open a shell inside the container:

   docker exec -it franka_ros2 /bin/bash

6. Build the workspace:

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

7. Source the built workspace:

   source install/setup.bash

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

2. Open Visual Studio Code ...

   Then, open folder franka_ros2

3. Choose Reopen in container when prompted.

   The container will be built automatically, as required.

4. Open a terminal and build the workspace:

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

5. Source the built workspace environment:

   source install/setup.bash

Test the build

colcon test

Remember, franka_ros2 is under development.
Warnings can be expected.
Errors? Well, they’re just undocumented features !".

Run a sample ROS2 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

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.