Skip to main content

🦾 RAIL UR5 Documentation

These are the docs for the RAIL UR5 with a CB3 controller (PolyScope 3.15) and a Robotiq Hand-E gripper.

The UR5 should be connected to the Wits ethernet, as should the remote PC. For now, the IP addresses are:

DeviceIP address
Robot10.10.187.168
PC10.10.187.131
What you'll set up

Getting the arm moving from a remote PC involves two sides: the robot (URCaps installed and configured on the teach pendant) and the PC (ROS 2 + the UR driver). The gripper needs a little extra plumbing on top — see Controlling the gripper.

🤖 Robot Setup​

All robot-side setup happens on the teach pendant (the touchscreen). The goal here is to get the right URCaps installed and configured so the remote PC can drive both the arm and the gripper.

Installing a URCap​

URCaps are plugins for PolyScope. On the CB3 controller (PolyScope 3.15) you install them from a USB stick:

  1. Copy the .urcap file onto a USB stick (the Robotiq one lives in this directory under urcaps/).
  2. Plug the USB stick into the port on the back of the teach pendant.
  3. On the pendant, go to Setup Robot → URCaps.
  4. Press the + button, browse to the .urcap file on the USB stick, and select it.
  5. Press Restart when prompted. The controller reboots and the URCap becomes available.

You can enable/disable an installed URCap from the same Setup Robot → URCaps screen without uninstalling it — this matters for the gripper (see below).

No USB stick? Use SSH

You don't strictly need a USB stick. Since you have root SSH to the controller, scp the .urcap onto the robot's filesystem first, then browse to it in the + dialog (which can read the controller's own filesystem, not just USB):

scp Robotiq_Grippers-1.8.13.22852.urcap root@10.10.187.168:/root/

Then on the pendant: Setup Robot → URCaps → +, browse to /root/, select the file, and Restart. The menu-and-restart step is still required — that's what registers and starts the plugin.

The URCaps we use​

We have been using three URCaps:

The External Control URCap — Universal_Robots_ExternalControl_URCap

This allows the remote PC to control the arm. After installing it, you also need to point it at your PC:

  • Go to the Installation tab → External Control.
  • Set Host IP to the remote PC's address (currently 10.10.187.131).
  • Leave the Custom port at its default (50002) unless you have a reason to change it.

This is the IP the ROS 2 driver's control program will call back to, so it must match the PC you launch the driver from.

The Robotiq Hand-E Gripper URCap — Robotiq_Grippers-1.8.13.22852 (included in urcaps/)

This allows the pendant to control the gripper.

Disable this to control the gripper from ROS

This URCap must be disabled in order to communicate with the gripper from the remote PC — it holds the tool's RS-485 serial line open. Leave it disabled (via Setup Robot → URCaps) whenever you plan to drive the gripper from ROS.

The RS-485 daemon URCap — Universal_Robots_ToolComm_Forwarder_URCap

This allows a remote PC to access the gripper. It exposes the tool's RS-485 serial port over the network so the PC-side bridge can reach it. Keep this one enabled.

💻 PC Setup​

The remote PC runs ROS 2 Jazzy (on Ubuntu 24.04) and the Universal Robots ROS 2 driver.

Clone the relevant repo:

TODO

Add the workspace repo URL here.

Source the workspace in every new terminal so ROS can find our packages:

source install/setup.bash

Rebuild after any changes are made:

colcon build
tip

colcon build must be run from the root of the workspace, and you should source install/setup.bash again afterwards so the freshly built packages are picked up.

🎮 Controlling the arm​

See the driver's jazzy branch for full details.

To set up the UR driver, run:

ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5 robot_ip:=10.10.187.168 use_mock_hardware:=false description_package:=ur5_test description_file:=src/ur5_test/urdf/ur5_hand_e.urdf.xacro

Here, src/ur5_test/urdf/ur5_hand_e.urdf.xacro is the xacro file that describes the robot and the gripper, in the ur5_test workspace. You may need to change these paths for your setup.

For the simplest tests without the gripper loaded in the URDF, you can just run:

ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5 robot_ip:=10.10.187.168 use_mock_hardware:=false

After executing the driver, run the External Control program on the UR pendant:

  1. Program Robot
  2. Load Program
  3. Select external.urp and press Open
  4. Press Play
Loading external.urp via SSH

PolyScope loads programs from /programs on the controller, so you can scp the program over instead of using a USB stick — it will then appear in the Load Program dialog:

scp external.urp external.installation root@10.10.187.168:/programs/

Copy the matching .installation file too if the program depends on one (e.g. an installation with the External Control Host IP already configured).

The driver can be finicky

The UR driver will sometimes crash before you can press Play. Just Ctrl+C and rerun it once or twice to get it to work. On the pendant, you'll then have to press Stop Program and then Play again.

If you launched RViz and can see the arm in colour (not white), everything is working.

You can then manually control the arm using MoveIt by opening a new terminal and launching:

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

🤏 Controlling the gripper​

This one has been tricky and has cost me a few years of my life, so listen properly!

How it fits together

The gripper is a Robotiq Hand-E on the arm's RS-485 tool port. To reach it from ROS we chain three hops:

  1. A bridge script on the robot (gripper_bridge.py) exposes the serial port over TCP.
  2. A socat bridge on the PC maps that TCP stream to a local virtual serial device (/tmp/ttyUR).
  3. A ROS 2 action server (hand_e_server.py) talks to that virtual serial device and accepts GripperCommand goals.

Make sure the Robotiq gripper URCap is disabled and the RS-485 daemon URCap is enabled (see Robot Setup) before you start.

Step 1 — start the bridge on the robot. In a new terminal, SSH into the robot:

ssh root@10.10.187.168

The password should be easybot. From there, run:

python gripper_bridge.py
note

If this file is missing, you can copy the script from the scripts/ directory alongside this page.

Step 2 — open a socat bridge on the remote PC. Once the robot-side bridge is running:

socat -d -d pty,link=/tmp/ttyUR,raw,echo=0 tcp:10.10.187.168:54322

This creates the /tmp/ttyUR virtual serial device that the action server expects. Leave it running.

Step 3 — launch the Hand-E action server (see scripts/):

ros2 run ur5_test hand_e_server.py

If all is well, you can now send commands to the gripper in ROS.

Close the gripper:

ros2 action send_goal /gripper_action_controller/gripper_cmd control_msgs/action/GripperCommand "{command: {position: 0.0}}"

Open the gripper:

ros2 action send_goal /gripper_action_controller/gripper_cmd control_msgs/action/GripperCommand "{command: {position: 0.025}}"
Position mapping

Following the standard ROS convention, a position near 0.0 closes the fingers and a position near 0.025 opens them.