ROS 2 Integration for Franka Robotics Research Robots

Note: franka_ros2 is not officially supported on Windows.

Table of Contents

• About
• Caution
• Prerequisites
• Optional .bashrc Settings
• Setup
  • Install From Source
  • Use VSCode DevContainer
  • 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.

Caution

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

Prerequisites

Before installing franka_ros2, ensure you have the following prerequisites:

• ROS 2 Humble Installation: You can install ros-humble-desktop or use VSCode IDE with DevContainer.
• PREEMPT_RT Kernel (optional but recommended): A real-time kernel is necessary for the cartesian_pose, joint_position, and elbow_position command interfaces.
• System-wide libfranka Installation:
  • If you plan to install from source, a libfranka installation is required. Please refer to the libfranka repository for detailed build steps.
  • If you are using the DevContainer, you do not need to install libfranka system-wide, as it will be included in the container.

  Regardless of your setup, it is important to check the compatibility of your Robot OS version with libfranka to avoid potential errors. For detailed compatibility information, please consult the libfranka compatibility matrix.

Optional .bashrc Settings

Enhance your development experience by adding the following line to your .bashrc file:

# Enable colorized warn and error messages
export RCUTILS_COLORIZED_OUTPUT=1

Setup

Install From Source

1. Install Required Packages:

   sudo apt install -y \
   ros-humble-ament-cmake \
   ros-humble-ament-cmake-clang-format \
   ros-humble-angles \
   ros-humble-ros2-controllers \
   ros-humble-ros2-control \
   ros-humble-ros2-control-test-assets \
   ros-humble-controller-manager \
   ros-humble-control-msgs \
   ros-humble-control-toolbox \
   ros-humble-generate-parameter-library \
   ros-humble-joint-state-publisher \
   ros-humble-joint-state-publisher-gui \
   ros-humble-moveit \
   ros-humble-pinocchio \
   ros-humble-realtime-tools \
   ros-humble-xacro \
   ros-humble-hardware-interface \
    ros-humble-ros-gz \
   python3-colcon-common-extensions
   

1. Create a ROS 2 Workspace:

   mkdir -p ~/franka_ros2_ws/src
   

1. Clone the Repositories and Build Packages:

    source /opt/ros/humble/setup.bash
    cd ~/franka_ros2_ws 
    git clone https://github.com/frankaemika/franka_ros2.git src/franka_ros2 
    git clone https://github.com/frankaemika/franka_description.git src/franka_description 
    colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release 
    source install/setup.sh
    

Use VSCode DevContainer

The franka_ros2 package includes a .devcontainer folder, which allows you to use Franka ROS 2 packages without manually installing ROS 2 or libfranka. For detailed instructions, follow the setup guide from VSCode devcontainer_setup.

1. Create a ROS 2 Workspace:

   mkdir franka_ros2_ws
   cd franka_ros2_ws
   

1. Clone the Repositories:

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

1. Copy the .devcontainer Folder:

    cp -r src/franka_ros2/.devcontainer .
    

This step ensures that both the `franka_ros2` and `franka_description` folders are accessible within the DevContainer environment.

1. Open VSCode:

    code . 
    

1. Open the Current Folder in DevContainer:

   Press Ctrl + Shift + P and type: Dev Containers: Rebuild and Reopen in Container.

2. Open the Terminal in VSCode:

   Press Ctrl + (backtick).

3. Source the Environment:

    source /opt/ros/humble/setup.sh  
    

1. Install the Franka ROS 2 Packages:

    colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release 
    source install/setup.sh 
    

Test the Setup

To verify that your setup works correctly without a robot, you can run the following command to use dummy hardware:

ros2 launch franka_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.

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