Repository Summary

Checkout URI https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
VCS Type git
VCS Version humble
Last Updated 2024-02-26
Dev Status DEVELOPED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

Name Version
ur 2.2.10
ur_bringup 2.2.10
ur_calibration 2.2.10
ur_controllers 2.2.10
ur_dashboard_msgs 2.2.10
ur_moveit_config 2.2.10
ur_robot_driver 2.2.10

README

Universal Robots ROS2 Driver

Universal Robots has become a dominant supplier of lightweight, robotic manipulators for industry, as well as for scientific research and education.

Universal Robot e-Series family

This is one of the very first ROS2 manipulator drivers. Some of the new features are enabled by ROS2 and include decreased latency, improved security, and more flexibility regarding middleware configuration. The package contains launch files to quickly get started using the driver as a standalone version or in combination with MoveIt2

This driver is developed on top of Universal_Robots_Client_Library and support some key cobot functionalities like; pause at emergency stop, safeguard stop, automatic speed scaling to avoid violate the safety setting and manually speed scaling from the teach pendant. In addition the externalControl URCap makes it possible to include ROS2 behaviors in the robot program.

The driver is compatible across the entire line of UR robots -- from 3 kg payload to 16 kg payload and includes both the CB3 and the E-series.

Check also presentations and videos about this driver.

Build Status

ROS2 Distro Foxy Galactic Humble Rolling
Branch foxy galactic humble main
Build Status Foxy Binary Build
Foxy Semi-Binary Build
Galactic Binary Build
Galactic Semi-Binary Build
Humble Binary Build
Humble Semi-Binary Build
Rolling Binary Build
Rolling Semi-Binary Build

NOTE: There are two build stages checking current and future compatibility of the driver.

  1. Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.

Uses repos file: src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.<ros-distro>.repos

  1. Semi-binary builds - against released core ROS packages (main and testing), but the immediate dependencies are pulled from source. Shows that local build with dependencies is possible and if fails there we can expect that after the next package sync we will not be able to build.

Uses repos file: src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver.repos

Each of these stages also performs integration tests using ursim. In order to execute these tests locally, they have to be enabled:

  colcon build --packages-select ur_robot_driver --cmake-args -DUR_ROBOT_DRIVER_BUILD_INTEGRATION_TESTS=On

Packages in the Repository:

  • ur - Meta-package that provides a single point of installation for the released packages.
  • ur_bringup - launch file and run-time configurations, e.g. controllers (DEPRECATED).
  • ur_calibration - tool for extracting calibration information from a real robot.
  • ur_controllers - implementations of controllers specific for UR robots.
  • ur_dashboard_msgs - package defining messages used by dashboard node.
  • ur_moveit_config - example MoveIt configuration for UR robots.
  • ur_robot_driver - driver / hardware interface for communication with UR robots.

Deprecation: The ur_bringup package is deprecated and will be removed from Iron Irwini on.

Getting Started

For getting started, you'll basically need three steps:

  1. Install the driver (see below). You can either install this driver from binary packages or build it from source. We recommend a binary package installation unless you want to join development and submit changes.

  2. Start & Setup the robot. Once you've installed the driver, setup the robot

Please do this step carefully and extract the calibration as explained here. Otherwise the TCP's pose will not be correct inside the ROS ecosystem.

If no real robot is required, you can use a simulated robot that will behave almost exactly like the real robot.

  1. Start the driver. See the usage documentation for details.

Install from binary packages

  1. Install ROS2. This branch supports only ROS2 Humble. For other ROS2 versions, please see the respective branches.
  2. Install the driver using
   sudo apt-get install ros-${ROS_DISTRO}-ur

Build from source

Before building from source please make sure that you actually need to do that. Building from source might require some special treatment, especially when it comes to dependency management. Dependencies might change from time to time. Upstream packages (such as the library) might change their features / API which require changes in this repo. Therefore, this repo's source builds might require upstream repositories to be present in a certain version as otherwise builds might fail. Starting from scratch following exactly the steps below should always work, but simply pulling and building might fail occasionally.

  1. Install ROS2. branch supports only ROS2 Humble. For other ROS2 versions, please see the respective branches.

Once installed, please make sure to actually source ROS2 before proceeding.

  1. Make sure that colcon, its extensions and vcs are installed:
   sudo apt install python3-colcon-common-extensions python3-vcstool

  1. Create a new ROS2 workspace:
   export COLCON_WS=~/workspace/ros_ur_driver
   mkdir -p $COLCON_WS/src

  1. Clone relevant packages, install dependencies, compile, and source the workspace by using:
   cd $COLCON_WS
   git clone -b humble https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git src/Universal_Robots_ROS2_Driver
   vcs import src --skip-existing --input src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.${ROS_DISTRO}.repos
   rosdep update
   rosdep install --ignore-src --from-paths src -y
   colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
   source install/setup.bash

  1. When consecutive pulls leads to build errors, please make sure to update the upstream packages before filing an issue:
   cd $COLCON_WS
   vcs import src --skip-existing --input src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.${ROS_DISTRO}.repos
   rosdep update
   rosdep install --ignore-src --from-paths src -y

MoveIt! support

MoveIt! support is built-in into this driver already. Watch MoveIt in action with the Universal Robots ROS2 driver:

Video: MoveIt2 Demo

The video shows free-space trajectory planning around a modeled collision scene object using the MoveIt2 MotionPlanning widget for Rviz2.

See the MoveIt! section of the Usage guide for details.

Expected Changes in the Near Future

  • Trajectory control currently only supports position commands. In the future, velocity control will be added.

Contributor Guidelines

Code is auto-formatted with clang-format 14 whenever a git commit is made. Please ensure these dependencies are installed:

  pip3 install pre-commit
  sudo apt install clang-format-14

Prepare the pre-commit formatting to run like this:

  pre-commit install

CONTRIBUTING

Contributing Guidelines

Thank you for your interest in contributing to Universal_Robots_ROS2_Driver. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check [existing open][issues], or [recently closed][closed-issues], issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the master branch.
  2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
  3. Ensure local tests pass.
  4. Commit to your fork using clear commit messages.
  5. Send a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional documentation on forking a repository and creating a pull request.

Licensing

Any contribution that you make to this repository will be under the 3-Clause BSD License, as dictated by that license.


Repository Summary

Checkout URI https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
VCS Type git
VCS Version iron
Last Updated 2024-02-26
Dev Status DEVELOPED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

Name Version
ur 2.3.5
ur_calibration 2.3.5
ur_controllers 2.3.5
ur_dashboard_msgs 2.3.5
ur_moveit_config 2.3.5
ur_robot_driver 2.3.5

README

Universal Robots ROS2 Driver

Universal Robots has become a dominant supplier of lightweight, robotic manipulators for industry, as well as for scientific research and education.

Universal Robot e-Series family

This is one of the very first ROS2 manipulator drivers. Some of the new features are enabled by ROS2 and include decreased latency, improved security, and more flexibility regarding middleware configuration. The package contains launch files to quickly get started using the driver as a standalone version or in combination with MoveIt2

This driver is developed on top of Universal_Robots_Client_Library and support some key cobot functionalities like; pause at emergency stop, safeguard stop, automatic speed scaling to avoid violate the safety setting and manually speed scaling from the teach pendant. In addition the externalControl URCap makes it possible to include ROS2 behaviors in the robot program.

The driver is compatible across the entire line of UR robots -- from 3 kg payload to 16 kg payload and includes both the CB3 and the E-series.

Check also presentations and videos about this driver.

Release Status

ROS2 Distro Foxy (EOL) Galactic (EOL) Humble Iron Rolling
Branch foxy galactic humble iron main
Release status Foxy Binary Build
Galactic Binary Build



The table above shows the build status for each package of this repo from the ROS buildfarm. For end-of-life (EOL) distributions the nightly binary builds from our CI are shown. EOL distributions will receive no more updates and may be lacking features.

A more detailed build status shows the state of all CI workflows inside this repo. Please note that the detailed view is intended for developers, while the one here should give end users an overview of the current released state.

Packages in the Repository:

  • ur - Meta-package that provides a single point of installation for the released packages.
  • ur_calibration - tool for extracting calibration information from a real robot.
  • ur_controllers - implementations of controllers specific for UR robots.
  • ur_dashboard_msgs - package defining messages used by dashboard node.
  • ur_moveit_config - example MoveIt configuration for UR robots.
  • ur_robot_driver - driver / hardware interface for communication with UR robots.

Getting Started

For getting started, you'll basically need three steps:

  1. Install the driver
   sudo apt-get install ros-rolling-ur

See the installation instructions for more details and source-build instructions.

  1. Start & Setup the robot. Once you've installed the driver, setup the robot and create a program for external control.

Please do this step carefully and extract the calibration as explained here. Otherwise the TCP's pose will not be correct inside the ROS ecosystem.

If no real robot is required, you can use a simulated robot that will behave almost exactly like the real robot.

  1. Start the driver. See the usage documentation for details.
   # Replace ur5e with one of ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e, ur20
   # Replace the IP address with the IP address of your actual robot / URSim
   ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=192.168.56.101

  1. Unless started in headless mode: Run the external_control program by pressing play on the teach pendant.

MoveIt! support

MoveIt! support is built-in into this driver already. Watch MoveIt in action with the Universal Robots ROS2 driver:

Video: MoveIt2 Demo

The video shows free-space trajectory planning around a modeled collision scene object using the MoveIt2 MotionPlanning widget for Rviz2.

See the MoveIt! section of the Usage guide for details.

Expected Changes in the Near Future

  • Trajectory control currently only supports position commands. In the future, velocity control will be added.

Contributor Guidelines

Code is auto-formatted with clang-format 14 whenever a git commit is made. Please ensure these dependencies are installed:

  pip3 install pre-commit
  sudo apt install clang-format-14

Prepare the pre-commit formatting to run like this:

  pre-commit install

CONTRIBUTING

Contributing Guidelines

Thank you for your interest in contributing to Universal_Robots_ROS2_Driver. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check [existing open][issues], or [recently closed][closed-issues], issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the master branch.
  2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
  3. Ensure local tests pass.
  4. Commit to your fork using clear commit messages.
  5. Send a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional documentation on forking a repository and creating a pull request.

Licensing

Any contribution that you make to this repository will be under the 3-Clause BSD License, as dictated by that license.


Repository Summary

Checkout URI https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
VCS Type git
VCS Version main
Last Updated 2024-03-18
Dev Status DEVELOPED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

Name Version
ur 2.4.3
ur_calibration 2.4.3
ur_controllers 2.4.3
ur_dashboard_msgs 2.4.3
ur_moveit_config 2.4.3
ur_robot_driver 2.4.3

README

Universal Robots ROS2 Driver

Universal Robots has become a dominant supplier of lightweight, robotic manipulators for industry, as well as for scientific research and education.

Universal Robot e-Series family

This is one of the very first ROS2 manipulator drivers. Some of the new features are enabled by ROS2 and include decreased latency, improved security, and more flexibility regarding middleware configuration. The package contains launch files to quickly get started using the driver as a standalone version or in combination with MoveIt2

This driver is developed on top of Universal_Robots_Client_Library and support some key cobot functionalities like; pause at emergency stop, safeguard stop, automatic speed scaling to avoid violate the safety setting and manually speed scaling from the teach pendant. In addition the externalControl URCap makes it possible to include ROS2 behaviors in the robot program.

The driver is compatible across the entire line of UR robots -- from 3 kg payload to 16 kg payload and includes both the CB3 and the E-series.

Check also presentations and videos about this driver.

Release Status

ROS2 Distro Foxy (EOL) Galactic (EOL) Humble Iron Rolling
Branch foxy galactic humble iron main
Release status Foxy Binary Build
Galactic Binary Build



The table above shows the build status for each package of this repo from the ROS buildfarm. For end-of-life (EOL) distributions the nightly binary builds from our CI are shown. EOL distributions will receive no more updates and may be lacking features.

A more detailed build status shows the state of all CI workflows inside this repo. Please note that the detailed view is intended for developers, while the one here should give end users an overview of the current released state.

Packages in the Repository:

  • ur - Meta-package that provides a single point of installation for the released packages.
  • ur_calibration - tool for extracting calibration information from a real robot.
  • ur_controllers - implementations of controllers specific for UR robots.
  • ur_dashboard_msgs - package defining messages used by dashboard node.
  • ur_moveit_config - example MoveIt configuration for UR robots.
  • ur_robot_driver - driver / hardware interface for communication with UR robots.

System Requirements

Please see the requirements for the Universal_Robots_Client_Library, as this driver is build on top of Universal_Robots_Client_Library.

Getting Started

For getting started, you'll basically need three steps:

  1. Install the driver
   sudo apt-get install ros-rolling-ur

See the installation instructions for more details and source-build instructions.

  1. Start & Setup the robot. Once you've installed the driver, setup the robot and create a program for external control.

Please do this step carefully and extract the calibration as explained here. Otherwise the TCP's pose will not be correct inside the ROS ecosystem.

If no real robot is required, you can use a simulated robot that will behave almost exactly like the real robot.

  1. Start the driver. See the usage documentation for details.
   # Replace ur5e with one of ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e, ur20, ur30
   # Replace the IP address with the IP address of your actual robot / URSim
   ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=192.168.56.101

  1. Unless started in headless mode: Run the external_control program by pressing play on the teach pendant.

MoveIt! support

MoveIt! support is built-in into this driver already. Watch MoveIt in action with the Universal Robots ROS2 driver:

Video: MoveIt2 Demo

The video shows free-space trajectory planning around a modeled collision scene object using the MoveIt2 MotionPlanning widget for Rviz2.

See the MoveIt! section of the Usage guide for details.

Expected Changes in the Near Future

  • Trajectory control currently only supports position commands. In the future, velocity control will be added.

Contributor Guidelines

Code is auto-formatted with clang-format 14 whenever a git commit is made. Please ensure these dependencies are installed:

  pip3 install pre-commit
  sudo apt install clang-format-14

Prepare the pre-commit formatting to run like this:

  pre-commit install

CONTRIBUTING

Contributing Guidelines

Thank you for your interest in contributing to Universal_Robots_ROS2_Driver. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check [existing open][issues], or [recently closed][closed-issues], issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the master branch.
  2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
  3. Ensure local tests pass.
  4. Commit to your fork using clear commit messages.
  5. Send a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional documentation on forking a repository and creating a pull request.

Licensing

Any contribution that you make to this repository will be under the 3-Clause BSD License, as dictated by that license.


Repository Summary

Checkout URI https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
VCS Type git
VCS Version galactic
Last Updated 2022-10-11
Dev Status DEVELOPED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

README

Universal Robots ROS2 Driver

Universal Robots has become a dominant supplier of lightweight, robotic manipulators for industry, as well as for scientific research and education.

Universal Robot e-Series family

This is one of the very first ROS2 manipulator drivers. Some of the new features are enabled by ROS2 and include decreased latency, improved security, and more flexibility regarding middleware configuration. The package contains launch files to quickly get started using the driver as a standalone version or in combination with MoveIt2

This driver is developed on top of Universal_Robots_Client_Library and support some key cobot functionalities like; pause at emergency stop, safeguard stop, automatic speed scaling to avoid violate the safety setting and manually speed scaling from the teach pendant. In addition the externalControl URCap makes it possible to include ROS2 behaviors in the robot program.

The driver is compatible across the entire line of UR robots -- from 3 kg payload to 16 kg payload and includes both the CB3 and the E-series.

Check also presentations and videos about this driver.

Build Status

ROS2 Distro Foxy Galactic Humble Rolling
Branch foxy galactic main main
Build Status Foxy Binary Build
Foxy Semi-Binary Build
Foxy Source Build
Galactic Binary Build
Galactic Semi-Binary Build
Galactic Source Build
Humble Binary Build
Humble Semi-Binary Build
Humble Source Build
Rolling Binary Build
Rolling Semi-Binary Build
Rolling Source Build
Execution Test   Execution Testing Execution Testing Execution Testing

NOTE: There are three build stages checking current and future compatibility of the driver.

  1. Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.

Uses repos file: src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.<ros-distro>.repos

  1. Semi-binary builds - against released core ROS packages (main and testing), but the immediate dependencies are pulled from source. Shows that local build with dependencies is possible and if fails there we can expect that after the next package sync we will not be able to build.

Uses repos file: src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver.repos

  1. Source build - also core ROS packages are build from source. It shows potential issues in the mid future.

Packages in the Repository:

  • ur_bringup - launch file and run-time configurations, e.g. controllers.
  • ur_controllers - implementations of controllers specific for UR robots.
  • ur_dashboard_msgs - package defining messages used by dashboard node.
  • ur_description - description files for the UR robots: meshes, URDF/XACRO files, etc.
  • ur_moveit_config - example MoveIt configuration for UR robots.
  • ur_robot_driver - driver / hardware interface for communication with UR robots.

Getting Started

You can either install this driver from binary packages or build it from source. We recommend a binary package installation unless you want to join development and submit changes.

Install from binary packages

  1. Install ROS2 Galactic. This branch supports only ROS2 galactic. For other ROS2 versions, please see the respective branches.
  2. Install the driver using
   sudo apt-get install ros-galactic-ur-robot-driver

Build from source

  1. Install ROS2 Galactic. This branch supports only ROS2 galactic. For other ROS2 versions, please see the respective branches. The main branch will stay valid for all new ROS2 versions as long as they are compatible with the main branch. Therefore you might not find a dedicated branch for a recent ROS2 version. In that case, please use the main branch.

  2. Make sure that colcon and its extensions are installed:

   sudo apt install python3-colcon-common-extensions

  1. Create a new ROS2 workspace:
   export COLCON_WS=~/workspace/ros_ur_driver
   mkdir -p $COLCON_WS/src

  1. Pull relevant packages, install dependencies, compile, and source the workspace by using:
   cd $COLCON_WS
   git clone -b galactic https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git src/Universal_Robots_ROS2_Driver
   rosdep update
   rosdep install --ignore-src --from-paths src -y
   colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
   source install/setup.bash

Using MoveIt

MoveIt! support is built-in into this driver already. Watch MoveIt in action with the Universal Robots ROS2 driver:

Video: MoveIt2 Demo

The video shows free-space trajectory planning around a modeled collision scene object using the MoveIt2 MotionPlanning widget for Rviz2.

Real robot / URSim

To test the driver with the example MoveIt-setup, first start the driver as described below.

ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true

Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the robot as explained here.

Fake hardware on ROS2 Galactic

Currently, the scaled_joint_trajectory_controller does not work on ROS2 Galactic. There is an upstream Merge-Request pending to fix that. Until this is merged and released, please change the default controller in the controllers.yaml file. Make sure that the default field is assigned true for the joint_trajectory_controller and false for the scaled_joint_trajectory_controller.

controller_names:
  - scaled_joint_trajectory_controller
  - joint_trajectory_controller
scaled_joint_trajectory_controller:
  action_ns: follow_joint_trajectory
  type: FollowJointTrajectory
  default: false
  joints:
    - shoulder_pan_joint
    - shoulder_lift_joint
    - elbow_joint
    - wrist_1_joint
    - wrist_2_joint
    - wrist_3_joint
joint_trajectory_controller:
  action_ns: follow_joint_trajectory
  type: FollowJointTrajectory
  default: true
  joints:
    - shoulder_pan_joint
    - shoulder_lift_joint
    - elbow_joint
    - wrist_1_joint
    - wrist_2_joint
    - wrist_3_joint

Then start

ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=false initial_joint_controller:=joint_trajectory_controller
# and in another shell
ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true

Network Setup

There are many possible ways to connect a UR robot. This section describes a good example using static IP addresses and a direct connection from the PC to the Robot to minimize latency introduced by network hardware. Though a good network switch usually works fine, as well.

  1. Connect the UR control box directly to the remote PC with an ethernet cable.

  2. Open the network settings from the UR teach pendant (Setup Robot -> Network) and enter these settings:

IP address: 192.168.1.102
Subnet mask: 255.255.255.0
Default gateway: 192.168.1.1
Preferred DNS server: 192.168.1.1
Alternative DNS server: 0.0.0.0

  1. On the remote PC, turn off all network devices except the "wired connection", e.g. turn off wifi.

  2. Open Network Settings and create a new Wired connection with these settings. You may want to name this new connection UR or something similar:

IPv4
Manual
Address: 192.168.1.101
Netmask: 255.255.255.0
Gateway: 192.168.1.1

  1. Verify the connection from the PC with e.g. ping.
ping 192.168.1.102

Connect to External Control via URCap

This section describes installation and launching of the URCap program from the pendant. It allows ROS to control the robot externally. Generally, you will launch the driver via ROS then start URCap from the pendant.

  1. To enable external control of the UR robot from a remote PC you need to install the externalcontrol-1.0.5.urcap which can be downloaded from Universal_Robots_ExternalControl_URCap.

Note: For installing this URCap a minimal PolyScope version of 3.7 or 5.1 (in case of e-Series) is necessary.

  1. For installing the necessary URCap and creating a program, please see the individual tutorial on how to setup a CB3 robot or how to setup an e-Series robot

  2. On the remote PC, launch the suitable launch file which starts the robot driver and controllers (see details in Usage section).

  3. From the Program Robot tab of the teach pendant, load external_control.urp. Click on the "Control by..." section of the program to check the Host IP of the external PC. If it needs to be modified, make the modification under the Installation tab (as prompted on screen). You do not need to modify the Custom Port.

  4. When the Host IP is correct, click the play button to connect with the external PC.

Usage

For starting the driver there are two main launch files in the ur_bringup package.

  • ur_control.launch.py - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts dashboard_client if real robot is used.
  • ur_dashboard_client.launch.py - start the dashboard client for UR robots.

Also, there are predefined launch files for all supported types of UR robots.

The arguments for launch files can be listed using ros2 launch ur_bringup <launch_file_name>.launch.py --show-args. The most relevant arguments are the following:

  • ur_type (mandatory) - a type of used UR robot (ur3, ur3e, ur5, ur5e, ur10, ur10e, or ur16e).
  • robot_ip (mandatory) - IP address by which the root can be reached.
  • use_fake_hardware (default: false) - use simple hardware emulator from ros2_control. Useful for testing launch files, descriptions, etc. See explanation below.
  • initial_positions (default: dictionary with all joint values set to 0) - Allows passing a dictionary to set the initial joint values for the fake hardware from ros2_control. It can also be set from a yaml file with the load_yaml commands as follows:
      <xacro:property name="initial_positions" value="${load_yaml(initial_positions_file)}"/>

  In this example, the **initial_positions_file** is a xacro argument that contains the absolute path to a yaml file. An example of the initial positions yaml file is as follows:
      elbow_joint: 1.158
      shoulder_lift_joint: -0.953
      shoulder_pan_joint: 1.906
      wrist_1_joint: -1.912
      wrist_2_joint: -1.765
      wrist_3_joint: 0.0

  • fake_sensor_commands (default: false) - enables setting sensor values for the hardware emulators. Useful for offline testing of controllers.
  • robot_controller (default: joint_trajectory_controller) - controller for robot joints to be started. Available controllers: joint_trajectory_controller, scaled_joint_trajectory_controller. Note: joint_state_broadcaster, speed_scaling_state_broadcaster, force_torque_sensor_broadcaster, and io_and_status_controller will always start.

    HINT: list all loaded controllers using ros2 control list_controllers command.

NOTE: The package can simulate hardware with the ros2_control FakeSystem. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see ros2_control documentation for more details.

Example Commands for Testing the Driver

Allowed UR-Type strings: ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e.

1. Start hardware, simulator or mockup
  • To do test with hardware, use:
  ros2 launch ur_bringup ur_control.launch.py ur_type:=<UR_TYPE> robot_ip:=<IP_OF_THE_ROBOT> launch_rviz:=true

For more details check the argument documentation with ros2 launch ur_bringup ur_control.launch.py --show-arguments

After starting the launch file start the external_control URCap program from the pendant, as described above.

  • To do an offline test with URSim check details about it in this section

  • To use mocked hardware (capability of ros2_control), use use_fake_hardware argument, like:

  ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=true

NOTE: Instead of using the global launch file for control stack, there are also prepeared launch files for each type of UR robots named. They accept the same arguments are the global one and are used by:

  ros2 launch ur_bringup <ur_type>.launch.py

2. Sending commands to controllers

Before running any commands, first check the controllers' state using ros2 control list_controllers.

  • Send some goal to the Joint Trajectory Controller by using a demo node from ros2_control_demos package by starting the following command in another terminal:
   ros2 launch ur_bringup test_joint_trajectory_controller.launch.py

After a few seconds the robot should move.

  • To test another controller, simply define it using initial_joint_controller argument, for example when using fake hardware:
   ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy initial_joint_controller:=joint_trajectory_controller use_fake_hardware:=true launch_rviz:=true

And send the command using demo node:

   ros2 launch ur_bringup test_scaled_joint_trajectory_controller.launch.py

After a few seconds the robot should move (or jump when using emulation).

3. Using only robot description

If you just want to test description of the UR robots, e.g., after changes you can use the following command:

   ros2 launch ur_description view_ur.launch.py ur_type:=ur5e

Usage with official UR simulator

The docker-compose setup is prepared for usage of driver with the official UR simulator. Follow instructions here.

Expected Changes in the Near Future

  • Trajectory control currently only supports position commands. In the future, velocity control will be added.

Contributor Guidelines

Code is auto-formatted with clang-format 10 whenever a git commit is made. Please ensure these dependencies are installed:

  pip3 install pre-commit
  sudo apt install clang-format-10

Prepare the pre-commit formatting to run like this:

  pre-commit install`

CI setup

There are three build stages checking current and future compatibility of the driver.

  1. Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.

  2. Semi-binary builds - against released core ROS packages (main and testing), but the immediate dependencies are pulled from source. Shows that local build with dependencies is possible and if fails there we can expect that after the next package sync we will not be able to build.

  3. Source build - also core ROS packages are build from source. It shows potential issues in the mid future.

CONTRIBUTING

Contributing Guidelines

Thank you for your interest in contributing to Universal_Robots_ROS2_Driver. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check [existing open][issues], or [recently closed][closed-issues], issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the master branch.
  2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
  3. Ensure local tests pass.
  4. Commit to your fork using clear commit messages.
  5. Send a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional documentation on forking a repository and creating a pull request.

Licensing

Any contribution that you make to this repository will be under the 3-Clause BSD License, as dictated by that license.


Repository Summary

Checkout URI https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git
VCS Type git
VCS Version foxy
Last Updated 2023-04-17
Dev Status DEVELOPED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

README

Universal Robots ROS2 Driver

Universal Robots has become a dominant supplier of lightweight, robotic manipulators for industry, as well as for scientific research and education.

Universal Robot e-Series family

This is one of the very first ROS2 manipulator drivers. Some of the new features are enabled by ROS2 and include decreased latency, improved security, and more flexibility regarding middleware configuration. The package contains launch files to quickly get started using the driver as a standalone version or in combination with MoveIt2

This driver is developed on top of Universal_Robots_Client_Library and support some key cobot functionalities like; pause at emergency stop, safeguard stop, automatic speed scaling to avoid violate the safety setting and manually speed scaling from the teach pendant. In addition the externalControl URCap makes it possible to include ROS2 behaviors in the robot program.

The driver is compatible across the entire line of UR robots -- from 3 kg payload to 16 kg payload and includes both the CB3 and the E-series.

Build Status

ROS2 Distro Foxy Galactic Humble Rolling
Branch foxy galactic main main
Build Status Foxy Binary Build
Foxy Semi-Binary Build
Galactic Binary Build
Galactic Semi-Binary Build
Humble Binary Build
Humble Semi-Binary Build
Rolling Binary Build
Rolling Semi-Binary Build
Execution Test   Execution Testing Execution Testing Execution Testing

NOTE: There are two build stages checking current and future compatibility of the driver.

  1. Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.

Uses repos file: src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.<ros-distro>.repos

  1. Semi-binary builds - against released core ROS packages (main and testing), but the immediate dependencies are pulled from source. Shows that local build with dependencies is possible and if fails there we can expect that after the next package sync we will not be able to build.

Uses repos file: src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver.repos

Known Issues

-

Packages in the Repository:

  • ur_bringup - launch file and run-time configurations, e.g. controllers.
  • ur_calibration - tool for extracting calibration information from a real robot.
  • ur_controllers - implementations of controllers specific for UR robots.
  • ur_dashboard_msgs - package defining messages used by dashboard node.
  • ur_description - description files for the UR robots: meshes, URDF/XACRO files, etc.
  • ur_moveit - example MoveIt configuration for UR robots.
  • ur_robot_driver - driver / hardware interface for communication with UR robots.

Getting Started

  1. Install ROS2 Rolling or Install ROS2 Galactic. This branch will support both distributions until API breaking changes are made, at which point a galactic branch will be forked. For using this driver with ROS2 foxy checkout foxy branch.

  2. Make sure that colcon and its extensions are installed:

   sudo apt install python3-colcon-common-extensions

  1. Create a new ROS2 workspace:
   export COLCON_WS=~/workspace/ros_ur_driver
   mkdir -p $COLCON_WS/src

  1. Pull relevant packages, install dependencies, compile, and source the workspace by using:
   cd $COLCON_WS
   git clone -b foxy https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git src/Universal_Robots_ROS2_Driver
   rosdep install --ignore-src --from-paths src -y -r
   colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
   source install/setup.bash

Hardware Setup

  1. To enable external control of the UR robot from a remote PC you need to install the externalcontrol-1.0.5.urcap which can be found inside the resources folder of this driver or download the latest from Universal_Robots_ExternalControl_URCap.

Note: For installing this URCap a minimal PolyScope version of 3.7 or 5.1 (in case of e-Series) is necessary.

  1. For installing the necessary URCap and creating a program, please see the individual tutorial on how to setup a CB3 robot or how to setup an e-Series robot

  2. On the remote PC, launch the suitable launch file which starts the robot driver and controllers (see details in Usage section).

  3. In the Program tab of the teach pendant, navigate to the URCaps section on the left and add the external control to the robot program by clicking on it. The program can then be executed by pressing the play button. Make sure the robot is turned on. The robot power status will be displayed on the bottom left.

Extract calibration information

Each UR robot is calibrated inside the factory giving exact forward and inverse kinematics. To also make use of this in ROS, you first have to extract the calibration information from the robot.

Though this step is not necessary to control the robot using this driver, it is highly recommended to do so, as otherwise endeffector positions might be off in the magnitude of centimeters.

See the ur_calibration package's documentation for details on calibration extraction and handling.

Usage

For starting the driver there are three main launch files in the ur_bringup package.

  • ur_control.launch.py - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts dashboard_client if real robot is used.
  • ur_moveit.launch.py - start everything from ur_control.launch.py plus an example scenario with MoveIt2.
  • ur_dashboard_client.launch.py - start the dashboard client for UR robots.

Also, there are predefined launch files for all supported types of UR robots.

The arguments for launch files can be listed using ros2 launch ur_bringup <launch_file_name>.launch.py --show-args. The most relevant arguments are the following:

  • ur_type (mandatory) - a type of used UR robot (ur3, ur3e, ur5, ur5e, ur10, ur10e, or ur16e).
  • robot_ip (mandatory) - IP address by which the root can be reached.
  • use_fake_hardware (default: false) - use simple hardware emulator from ros2_control. Useful for testing launch files, descriptions, etc. See explanation below.
  • initial_positions (default: dictionary with all joint values set to 0) - Allows passing a dictionary to set the initial joint values for the fake hardware from ros2_control. It can also be set from a yaml file with the load_yaml commands as follows:
      <xacro:property name="initial_positions" value="${load_yaml(initial_positions_file)}"/>

  In this example, the **initial_positions_file** is a xacro argument that contains the absolute path to a yaml file. An example of the initial positions yaml file is as follows:
      elbow_joint: 1.158
      shoulder_lift_joint: -0.953
      shoulder_pan_joint: 1.906
      wrist_1_joint: -1.912
      wrist_2_joint: -1.765
      wrist_3_joint: 0.0

  • fake_sensor_commands (default: false) - enables setting sensor values for the hardware emulators. Useful for offline testing of controllers.
  • robot_controller (default: joint_trajectory_controller) - controller for robot joints to be started. Available controllers: joint_trajectory_controller, scaled_joint_trajectory_controller. Note: joint_state_broadcaster, speed_scaling_state_broadcaster, force_torque_sensor_broadcaster, and io_and_status_controller will always start.

    HINT: list all loaded controllers using ros2 control list_controllers command.

NOTE: The package can simulate hardware with the ros2_control FakeSystem. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see ros2_control documentation for more details.

Example Commands for Testing the Driver

  • To start the robot driver and controllers, use:
   ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=true

For an offline test with the emulated hardware you can just copy-paste this line. To run on the hardware, write the IP address of your robot and omit the use_fake_hardware argument.

NOTE: If controllers are not starting automatically, i.e., the robot state is not shown in rviz, you can start them manually:

   ros2 control load_controller --set-state start joint_state_broadcaster
   ros2 control load_controller --set-state start joint_trajectory_controller

To check the controllers' state use ros2 control list_controllers command.

  • Send some goal to the Joint Trajectory Controller by using a demo node from ros2_control_demos package by starting the following command in another terminal.

NOTE: As the ros2_control_demos package is currently not released for ROS2 Foxy, you'll have to build it in your workspace in order to use this launchfile. We are aware that this is not ideal, but we thought it would be better to not drop the testing launchfile at all and provide this info to users.

   ros2 launch ur_bringup test_joint_trajectory_controller.launch.py

After a few seconds the robot should move.

  • To test another controller, simply define it using robot_controller argument:
   ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy robot_controller:=scaled_joint_trajectory_controller use_fake_hardware:=true launch_rviz:=true

And send the command using demo node:

   ros2 launch ur_bringup test_scaled_joint_trajectory_controller.launch.py

After a few seconds the robot should move (or jump when using emulation).

  • To test the driver with the example MoveIt-setup, first start the controllers then start MoveIt.
   ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=false

   ros2 launch ur_bringup ur_moveit.launch.py ur_type:=ur5e robot_ip:="xxx.xxx" use_fake_hardware:=true launch_rviz:=true

Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the robot.

  1. If you just want to test description of the UR robots, e.g., after changes you can use the following command:
   ros2 launch ur_description view_ur.launch.py ur_type:=ur5e

Usage with official UR simulator

The docker-compose setup is prepared for usage of driver with the official UR simulator. Follow instructions here.

Expected Changes in the Near Future

  • Using upstream force_torque_sensor_broadcaster (ros-controls/ros2_controllers#152)
  • Trajectory control currently only supports position commands. In the future, velocity control will be added.

Contributor Guidelines

Code is auto-formatted with clang-format 10 whenever a git commit is made. Please ensure these dependencies are installed:

  pip3 install pre-commit
  sudo apt install clang-format-10

Prepare the pre-commit formatting to run like this:

  pre-commit install`

CONTRIBUTING

Contributing Guidelines

Thank you for your interest in contributing to Universal_Robots_ROS2_Driver. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check [existing open][issues], or [recently closed][closed-issues], issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the master branch.
  2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
  3. Ensure local tests pass.
  4. Commit to your fork using clear commit messages.
  5. Send a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional documentation on forking a repository and creating a pull request.

Licensing

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.