Based on contributions by Ilmar.
This guide covers mounting a Robotiq 2-finger gripper (tested with Hand-E) on a UR robot arm, wiring it to a PLC, and controlling it both from the teach pendant (via URCap) and from an external PC with Python.
What you need
- Robotiq gripper, mounting piece, USB-to-RS485 converter, and a 5-pin wire extension cable.
- The UR robot’s PLC/controller, with a free USB slot and 24V supply available for the gripper.
- Robotiq’s installation manual (referenced throughout this guide).
- The Robotiq Gripper URCap that matches your PolyScope version (see step 5).
- Optional, for bench testing: the Robotiq Installer software (v2.4.9) and a laptop.
- Optional, for scripted control: Python 3.
Steps
1. Mount the gripper
Connect the mounting piece to the robot arm’s end-effector, then screw the gripper into the mounting piece, aligning the pins on the bottom of the gripper with those on top of the mounting piece.
2. Identify the gripper wires
Use the indent in the 5-pin wire as your reference point and follow the wiring diagram below:
If your extension cable’s wire colors don’t match the diagram, disconnect the gripper from the mounting piece and measure the cable through, matching each wire to the labeled pin from the photo in step 1. The VCC wire cannot be measured this way for safety reasons — that’s expected, not a fault.
3. Wire the gripper to the converter and PLC
- Connect RS485+, RS485-, and RS485 GND to the matching pins on the RS485-to-USB converter.
- Connect 24V and GND to the matching supply pins on the PLC.
4. (Optional) Bench-test with the Robotiq Installer software
To verify the gripper works before wiring it into the full setup:
- Plug the RS485-to-USB converter into your laptop and make sure 24V is active.
- Install the Robotiq Installer software (get the latest version from Robotiq Support if this link is outdated).
- Open the software and search for devices — a port entry should appear.
- Click Auto connect.
- Port turns green: connected correctly, you can now control the gripper from the interface.
- Port turns red: either the pins aren’t making contact, or the 24V supply isn’t on yet.
5. Install the URCap and control from the teach pendant
- Connect the RS485-to-USB converter to a USB slot on the PLC, and wire 24V/GND as in step 3.
- Download the Gripper URCap that matches your PolyScope version from Robotiq Support:
- PolyScope 5.19.0 and later: UCG-3.19.1.
- PolyScope 3.15.3 and later: UCG-1.8.13.
- If you’re not sure which PolyScope version you’re on, 3.15.3 is a safe assumption for older controllers.
- Copy the URCap file to a USB stick, insert it into the PLC, and install it.
- A small R icon should now appear next to the local/remote button. Click it to open the gripper initialization window.
- Initialize the gripper. It should turn blue (instead of red) once done, and a control window opens from which you can operate it manually.
- For the command reference (registers, activation sequence, etc.), see Robotiq’s general documentation (PDF).
6. Control the gripper from Python
The gripper also accepts commands over a raw socket connection, so you can drive it from an external PC instead of (or alongside) the pendant. The typical sequence is:
- Create a
RobotiqGripper()instance. - Call
.connect(hostname, port). - Call
.activate()— this must run before any move command. - Call
.move(position, speed, force)(returns immediately) or.move_and_wait_for_pos(position, speed, force)(blocks until the move finishes) to operate the gripper.position,speed, andforceare all in the range 0–255, whereposition = 0is fully open.
Check: the source topic didn’t state the hostname/port used to reach the gripper’s control interface from an external PC — confirm this against your own setup (typically the robot controller’s IP and the port your Robotiq control interface listens on) before reusing the code below.
"""Module to control Robotiq's grippers - tested with HAND-E"""
import socket
import threading
import time
from enum import Enum
from typing import Union, Tuple, OrderedDict
class RobotiqGripper:
"""
Communicates with the gripper directly, via socket with string commands, leveraging string names for variables.
"""
# WRITE VARIABLES (CAN ALSO READ)
ACT = 'ACT' # act : activate (1 while activated, can be reset to clear fault status)
GTO = 'GTO' # gto : go to (will perform go to with the actions set in pos, for, spe)
ATR = 'ATR' # atr : auto-release (emergency slow move)
ADR = 'ADR' # adr : auto-release direction (open(1) or close(0) during auto-release)
FOR = 'FOR' # for : force (0-255)
SPE = 'SPE' # spe : speed (0-255)
POS = 'POS' # pos : position (0-255), 0 = open
# READ VARIABLES
STA = 'STA' # status (0 = is reset, 1 = activating, 3 = active)
PRE = 'PRE' # position request (echo of last commanded position)
OBJ = 'OBJ' # object detection (0 = moving, 1 = outer grip, 2 = inner grip, 3 = no object at rest)
FLT = 'FLT' # fault (0=ok, see manual for errors if not zero)
ENCODING = 'UTF-8' # ASCII and UTF-8 both seem to work
class GripperStatus(Enum):
"""Gripper status reported by the gripper. The integer values have to match what the gripper sends."""
RESET = 0
ACTIVATING = 1
# UNUSED = 2 # This value is currently not used by the gripper firmware
ACTIVE = 3
class ObjectStatus(Enum):
"""Object status reported by the gripper. The integer values have to match what the gripper sends."""
MOVING = 0
STOPPED_OUTER_OBJECT = 1
STOPPED_INNER_OBJECT = 2
AT_DEST = 3
def __init__(self):
"""Constructor."""
self.socket = None
self.command_lock = threading.Lock()
self._min_position = 0
self._max_position = 255
self._min_speed = 0
self._max_speed = 255
self._min_force = 0
self._max_force = 255
def connect(self, hostname: str, port: int, socket_timeout: float = 2.0) -> None:
"""Connects to a gripper at the given address.
:param hostname: Hostname or ip.
:param port: Port.
:param socket_timeout: Timeout for blocking socket operations.
"""
self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
self.socket.connect((hostname, port))
self.socket.settimeout(socket_timeout)
def disconnect(self) -> None:
"""Closes the connection with the gripper."""
self.socket.close()
def log_info(self):
print(f"Pos: {str(self.get_current_position()): >3} "
f"Open: {self.is_open(): <2} "
f"Closed: {self.is_closed(): <2} ")
def _set_vars(self, var_dict: OrderedDict[str, Union[int, float]]):
"""Sends the appropriate command via socket to set the value of n variables, and waits for its 'ack' response.
:param var_dict: Dictionary of variables to set (variable_name, value).
:return: True on successful reception of ack, false if no ack was received, indicating the set may not
have been effective.
"""
# construct unique command
cmd = "SET"
for variable, value in var_dict.items():
cmd += f" {variable} {str(value)}"
cmd += '\n' # new line is required for the command to finish
# atomic commands send/rcv
with self.command_lock:
self.socket.sendall(cmd.encode(self.ENCODING))
data = self.socket.recv(1024)
return self._is_ack(data)
def _set_var(self, variable: str, value: Union[int, float]):
"""Sends the appropriate command via socket to set the value of a variable, and waits for its 'ack' response.
:param variable: Variable to set.
:param value: Value to set for the variable.
:return: True on successful reception of ack, false if no ack was received, indicating the set may not
have been effective.
"""
return self._set_vars(OrderedDict([(variable, value)]))
def _get_var(self, variable: str):
"""Sends the appropriate command to retrieve the value of a variable from the gripper, blocking until the
response is received or the socket times out.
:param variable: Name of the variable to retrieve.
:return: Value of the variable as integer.
"""
# atomic commands send/rcv
with self.command_lock:
cmd = f"GET {variable}\n"
self.socket.sendall(cmd.encode(self.ENCODING))
data = self.socket.recv(1024)
# expect data of the form 'VAR x', where VAR is an echo of the variable name, and X the value
# note some special variables (like FLT) may send 2 bytes, instead of an integer. We assume integer here
var_name, value_str = data.decode(self.ENCODING).split()
if var_name != variable:
raise ValueError(f"Unexpected response {data} ({data.decode(self.ENCODING)}): does not match '{variable}'")
value = int(value_str)
return value
@staticmethod
def _is_ack(data: str):
return data == b'ack'
def _reset(self):
"""
Reset the gripper.
The following code is executed in the corresponding script function
def rq_reset(gripper_socket="1"):
rq_set_var("ACT", 0, gripper_socket)
rq_set_var("ATR", 0, gripper_socket)
while(not rq_get_var("ACT", 1, gripper_socket) == 0 or not rq_get_var("STA", 1, gripper_socket) == 0):
rq_set_var("ACT", 0, gripper_socket)
rq_set_var("ATR", 0, gripper_socket)
sync()
end
sleep(0.5)
end
"""
self._set_var(self.ACT, 0)
self._set_var(self.ATR, 0)
while (not self._get_var(self.ACT) == 0 or not self._get_var(self.STA) == 0):
self._set_var(self.ACT, 0)
self._set_var(self.ATR, 0)
time.sleep(0.5)
def activate(self, auto_calibrate: bool = True):
"""Resets the activation flag in the gripper, and sets it back to one, clearing previous fault flags.
:param auto_calibrate: Whether to calibrate the minimum and maximum positions based on actual motion.
The following code is executed in the corresponding script function
def rq_activate(gripper_socket="1"):
if (not rq_is_gripper_activated(gripper_socket)):
rq_reset(gripper_socket)
while(not rq_get_var("ACT", 1, gripper_socket) == 0 or not rq_get_var("STA", 1, gripper_socket) == 0):
rq_reset(gripper_socket)
sync()
end
rq_set_var("ACT",1, gripper_socket)
end
end
def rq_activate_and_wait(gripper_socket="1"):
if (not rq_is_gripper_activated(gripper_socket)):
rq_activate(gripper_socket)
sleep(1.0)
while(not rq_get_var("ACT", 1, gripper_socket) == 1 or not rq_get_var("STA", 1, gripper_socket) == 3):
sleep(0.1)
end
sleep(0.5)
end
end
"""
if not self.is_active():
self._reset()
while (not self._get_var(self.ACT) == 0 or not self._get_var(self.STA) == 0):
time.sleep(0.01)
self._set_var(self.ACT, 1)
time.sleep(1.0)
while (not self._get_var(self.ACT) == 1 or not self._get_var(self.STA) == 3):
time.sleep(0.01)
# auto-calibrate position range if desired
if auto_calibrate:
self.auto_calibrate()
def is_active(self):
"""Returns whether the gripper is active."""
status = self._get_var(self.STA)
return RobotiqGripper.GripperStatus(status) == RobotiqGripper.GripperStatus.ACTIVE
def get_min_position(self) -> int:
"""Returns the minimum position the gripper can reach (open position)."""
return self._min_position
def get_max_position(self) -> int:
"""Returns the maximum position the gripper can reach (closed position)."""
return self._max_position
def get_open_position(self) -> int:
"""Returns what is considered the open position for gripper (minimum position value)."""
return self.get_min_position()
def get_closed_position(self) -> int:
"""Returns what is considered the closed position for gripper (maximum position value)."""
return self.get_max_position()
def is_open(self):
"""Returns whether the current position is considered as being fully open."""
return self.get_current_position() <= self.get_open_position()
def is_closed(self):
"""Returns whether the current position is considered as being fully closed."""
return self.get_current_position() >= self.get_closed_position()
def get_current_position(self) -> int:
"""Returns the current position as returned by the physical hardware."""
return self._get_var(self.POS)
def auto_calibrate(self, log: bool = True) -> None:
"""Attempts to calibrate the open and closed positions, by slowly closing and opening the gripper.
:param log: Whether to print the results to log.
"""
# first try to open in case we are holding an object
(position, status) = self.move_and_wait_for_pos(self.get_open_position(), 64, 1)
if RobotiqGripper.ObjectStatus(status) != RobotiqGripper.ObjectStatus.AT_DEST:
raise RuntimeError(f"Calibration failed opening to start: {str(status)}")
# try to close as far as possible, and record the number
(position, status) = self.move_and_wait_for_pos(178, 64, 1) # capped below get_closed_position() so the pincers aren't driven fully shut
if RobotiqGripper.ObjectStatus(status) != RobotiqGripper.ObjectStatus.AT_DEST:
raise RuntimeError(f"Calibration failed because of an object: {str(status)}")
assert position <= self._max_position
self._max_position = position
# try to open as far as possible, and record the number
(position, status) = self.move_and_wait_for_pos(self.get_open_position(), 64, 1)
if RobotiqGripper.ObjectStatus(status) != RobotiqGripper.ObjectStatus.AT_DEST:
raise RuntimeError(f"Calibration failed because of an object: {str(status)}")
assert position >= self._min_position
self._min_position = position
if log:
print(f"Gripper auto-calibrated to [{self.get_min_position()}, {self.get_max_position()}]")
def move(self, position: int, speed: int, force: int) -> Tuple[bool, int]:
"""Sends commands to start moving towards the given position, with the specified speed and force.
:param position: Position to move to [min_position, max_position]
:param speed: Speed to move at [min_speed, max_speed]
:param force: Force to use [min_force, max_force]
:return: A tuple with a bool indicating whether the action it was successfully sent, and an integer with
the actual position that was requested, after being adjusted to the min/max calibrated range.
"""
def clip_val(min_val, val, max_val):
return max(min_val, min(val, max_val))
clip_pos = clip_val(self._min_position, position, self._max_position)
clip_spe = clip_val(self._min_speed, speed, self._max_speed)
clip_for = clip_val(self._min_force, force, self._max_force)
# moves to the given position with the given speed and force
var_dict = OrderedDict([(self.POS, clip_pos), (self.SPE, clip_spe), (self.FOR, clip_for), (self.GTO, 1)])
return self._set_vars(var_dict), clip_pos
def move_and_wait_for_pos(self, position: int, speed: int, force: int) -> Tuple[int, ObjectStatus]:
"""Sends commands to start moving towards the given position, with the specified speed and force, and
then waits for the move to complete.
:param position: Position to move to [min_position, max_position]
:param speed: Speed to move at [min_speed, max_speed]
:param force: Force to use [min_force, max_force]
:return: A tuple with an integer representing the last position returned by the gripper after it notified
that the move had completed, a status indicating how the move ended (see ObjectStatus enum for details). Note
that it is possible that the position was not reached, if an object was detected during motion.
"""
set_ok, cmd_pos = self.move(position, speed, force)
if not set_ok:
raise RuntimeError("Failed to set variables for move.")
# wait until the gripper acknowledges that it will try to go to the requested position
while self._get_var(self.PRE) != cmd_pos:
time.sleep(0.001)
# wait until not moving
cur_obj = self._get_var(self.OBJ)
while RobotiqGripper.ObjectStatus(cur_obj) == RobotiqGripper.ObjectStatus.MOVING:
cur_obj = self._get_var(self.OBJ)
# report the actual position and the object status
final_pos = self._get_var(self.POS)
final_obj = cur_obj
return final_pos, RobotiqGripper.ObjectStatus(final_obj)
Example usage:
gripper = RobotiqGripper()
gripper.connect("<controller IP>", "<port>") # ⚠️ Check: hostname/port not given in the source, confirm for your setup
gripper.activate()
gripper.move_and_wait_for_pos(255, 128, 128) # close
gripper.move_and_wait_for_pos(0, 128, 128) # open
gripper.disconnect()
Troubleshooting
- Port turns red in the Robotiq Installer: either the pins aren’t making contact with the converter, or the 24V supply isn’t switched on.
- Can’t measure the VCC wire when tracing cable colors: expected — this wire can’t be read with a multimeter for safety reasons, it doesn’t mean the wire is faulty.
activate()never finishes: check the RS485 wiring and that 24V is present before assuming a software issue.
Related
- How to build a custom URCaps interface for a UR teach pendant — background on how URCaps (like the Robotiq gripper URCap) work.
- How to set the payload and center of gravity on a UR e-Series robot — re-measure payload and center of gravity after mounting the gripper.
Rewritten and consolidated (Sept 2026) from the original student how-to’s: How to install and operate the robot-iq gripper.