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.

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
Execution Test

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

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
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
Source build - also core ROS packages are build from source. It shows potential issues in the mid future.

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

Install ROS2 Rolling. For using this driver with ROS2 foxy. Checkout foxy branch, for using it with ROS2 galactic, use the galactic branch.

Make sure that colcon, its extensions and vcs are installed:

sudo apt install python3-colcon-common-extensions python3-vcstool

Create a new ROS2 workspace:

export COLCON_WS=~/workspace/ros_ur_driver
mkdir -p $COLCON_WS/src

Pull relevant packages, install dependencies, compile, and source the workspace by using:

cd $COLCON_WS
git clone 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 -r
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:

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.

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.

Connect the UR control box directly to the remote PC with an ethernet cable.
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

On the remote PC, turn off all network devices except the "wired connection", e.g. turn off wifi.
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

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.

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.

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
On the remote PC, launch the suitable launch file which starts the robot driver and controllers (see details in Usage section).
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.
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_robot_driver 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_robot_driver <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_robot_driver 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_robot_driver 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_robot_driver 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_robot_driver <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_robot_driver 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_robot_driver 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_robot_driver 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

For using the driver with the URSim docker image please 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.

Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.
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.
Source build - also core ROS packages are build from source. It shows potential issues in the mid future.

ozangungor12/Universal_Robots_ROS2_Driver