API Reference

Core Class

class pyrobotiqgripper.RobotiqGripper(com_port='auto', device_id=9, connection_type='RTU', tcp_host='127.0.0.1', tcp_port=54321, debug=False, **kwargs)[source]

Bases: object

Class use to control Robotiq grippers (2F85, 2F140 or hande).

This class provides methods to initialize, open, close, and monitor the gripper.

Physical connection

The physical connection with the gripper can done in 2 ways: - Connected to the PC via the USB/RS485 adapter. - Connected to the UR robot: In this case the UR RS485 URCAP needs to be installed on the robot controller.

Modbus RTU/TCP communication

Modbus RTU function code supported by robotiq gripper

Description	Modbus function code
Read registers	4
Write registers	16
Master read & write multiple registers	23

For more information for gripper communication please check gripper manual on Robotiq website. https://robotiq.com/support/2f-85-2f-140

Note

This class cannot be use to control epick, 3F or powerpick.

__init__(com_port='auto', device_id=9, connection_type='RTU', tcp_host='127.0.0.1', tcp_port=54321, debug=False, **kwargs)[source]

Create a RobotiqGripper object which can be use to control Robotiq grippers using modbus RTU protocol USB/RS485 connection.

Parameters:

com_portstr: COM port to which the gripper is connected. If “auto” (or equal to the constant AUTO_DETECTION), the library will try to find the COM port to which the gripper is connected. On Windows, COM ports are named COM1, COM2, etc. On Linux, COM ports are named /dev/ttyUSB0, /dev/ttyUSB1, etc. Default is AUTO_DETECTION.
device_idint: Address of the gripper (integer) usually 9.
gripper_typestr: Type of the gripper. Currently only “2F” is supported. Default is “2F”.
connection_typestr: Type of connection to the gripper. “RTU” (or equal to the constant GRIPPER_MODE_RTU) for direct Modbus RTU connection (e.g. via USB/RS485 adapter). “RTU_VIA_TCP” (or equal to the constant GRIPPER_MODE_RTU_VIA_TCP) for Modbus RTU connection via TCP (e.g. when using the UR RS485 URCAP). Default is “RTU”.
tcp_hoststr: Host IP address for TCP connection. Default is “127.0.0.1”
tcp_portint: Port number for TCP connection. Default is 54321.
debugbool: If True, enable debug logging for Modbus communication. Default is False.

Examples

Gripper connected at PC USB port:

>>> import pyrobotiqgripper as rq

>>> gripper = rq.RobotiqGripper(connection_type=rq.GRIPPER_MODE_RTU)
>>> gripper.connect()
>>> gripper.activate()
>>> gripper.start()
>>> gripper.open()
>>> gripper.close()
>>> gripper.move(100) #Move at position 100 in bit
>>> print(gripper.position) #Print gripper position in bit
>>> gripper.calibrate(closemm=0,openmm=85) #Calibrate the gripper with 0mm when closed and 85mm when open
>>> gripper.move_mm(50) #Move at position 50mm
>>> gripper.printStatus() #Print gripper status information in the python terminal
>>> print(gripper.positionmm) #Print gripper position in mm

Gripper connected to UR robot via RS495 URCAP (RTU over TCP):

>>> import pyrobotiqgripper as rq

>>> gripper = rq.RobotiqGripper(connection_type=rq.GRIPPER_MODE_RTU_VIA_TCP,tcp_host="192.168.1.100")
>>> gripper.connect()
>>> gripper.activate()
>>> gripper.start()
>>> gripper.open()

Parameters:

com_port (str)
device_id (int)
connection_type (str)
tcp_host (str)
tcp_port (int)
debug (bool)

connect()[source]: Connect to the gripper. If the connection is already established, do nothing.

disconnect()[source]: Disconnect from the gripper. If the connection is already closed, do nothing.

reset()[source]: Reset the gripper (clear previous activation and calibration if any)

activate(reset=True, start=True, refreshStatus=True)[source]: If not already activated, activate the gripper.

Warning

When you execute this function the gripper is going to fully open and close. During this operation the gripper must be able to freely move. Do not place object inside the gripper.

start(refreshStatus=True)[source]: Gripper start moving. GTO bit is set to 1 but the position command is not changed. The gripper will move to the position command if it is not already there.

stop()[source]: Gripper stop moving. GTO bit is set to 0 but the position command is not changed. The gripper will stop at its current position and hold it.

calibrate_bit(openbit=None, closebit=None)[source]

Calibrate the maximum and minimum position bit value

openbitint: Position value in bits when the gripper is open
closebitint: Position value in bits when the gripper is closed

If no parametesr are provided, the gripper will make a full open followed by a full close to measure the maximum and minium position in bit.

calibrate_speed(minSpeedClosingTime=None, maxSpeedClosingTime=None)[source]

Calibrate gripper speed to be able to estimate gripper position over time

If no parameters are provided, the gripper will do a closing at full speed and a closing at slow speed to evaluate. the bit calibration will also be performed.

Parameters :

minSpeedClosingTimefloat: Time (s) is takes for the gripper to move from a full open position to a full close position at the minimum speed.
maxSpeedClosingTimefloat: Time (s) is takes for the gripper to move from a full open position to a full close position at the maximum speed.

If no parameters are provided, the gripper will do a closing at full speed and a closing at slow speed to evaluate

calibrate_mm(closemm, openmm)[source]

Calibrate the gripper for mm positionning.

Once the calibration is done it is possible to control the gripper in mm.

Parameters:

closemmfloat: Distance between the fingers when the gripper is fully closed.
openmmfloat: Distance between the fingers when the gripper is fully open.

open(speed=255, force=255, wait=False, readStatus=True, refreshStatus=False)[source]

Open the gripper

Parameters:

speedint: Gripper speed between 0 and 255. Default is 255.
forceint: Gripper force between 0 and 255. Default is 255.

close(speed=None, force=None, wait=False, readStatus=True, refreshStatus=False)[source]

Close the gripper.

Parameters:

speedint: Gripper speed between 0 and 255. Default is None.
forceint: Gripper force between 0 and 255. Default is None.

move(position, speed=None, force=None, wait=False, readStatus=True, refreshStatus=False)[source]

Move gripper fingers to the requested position with determined speed and force.

Parameters:

positionint: Position of the gripper. Integer between 0 and 255. 0 being the open position and 255 being the close position.
speedint: Gripper speed between 0 and 255. Default is 255.
forceint: Gripper force between 0 and 255. Default is 255.
waitbool: If True, the function wait until the gripper reach the requested position or detect an object. Default is False.

move_mm(positionmm, speed=None, force=None, wait=False, readStatus=True, refreshStatus=False)[source]

Go to the requested opening expressed in mm

Parameters:

positionmmfloat: Gripper opening in mm.
speedint: Gripper speed between 0 and 255. Default is 255.
forceint: Gripper force between 0 and 255. Default is 255.

Note

Calibration is needed to use this function.

Execute the function calibrate at least 1 time before using this function.

realTimeMove(requestedPosition, minSpeedPosDelta=5, maxSpeedPosDelta=100, continuousGrip=True, autoLock=True, minimalMotion=2, verbose=False)[source]

Move the gripper in real time to the requested position.

Parameters:

requestedPositionint: Requested position for the gripper in bits. Integer between 0 and 255. 0 being the open position and 255 being the close position.
minSpeedPosDeltaint: Minimum position delta to apply the minimum speed. Default is 5.
maxSpeedPosDeltaint: Position delta over which the maximum speed is applied. Default is 100.
continuousGripbool: If True, the gripper continuously try to close on object even after object detection (force>0). Default is True.
autoLockbool: If True, the gripper automatically perform a full speed, full force grip after object detection. Default is True.
minimalMotionint: Minimum motion in bit to perform when a motion is requested. If the position delta between the current position and the requested position is under this value, no motion is performed. Default is 2.
verbosebool: If True, print debug information about the command filtering and execution. Default is False.

waitComplete()[source]

Wait until the gripper has completed its motion or detect an object.

This method blocks until the gripper reaches the target position or detects an object.

isActivated(refreshStatus=True)[source]

Tells if the gripper is activated

Returns:

is_activatedbool: True if the gripper is activated. False otherwise.

isStarted(refreshStatus=True)[source]

Tells if the gripper is started

Returns:

is_startedbool: True if the gripper is started. False otherwise.

is_bit_calibrated()[source]: Tells is the gripper is bit calibrated

is_mm_calibrated()[source]

Tells if the mm calibration is done.

Returns:

is_mm_calibratedbool: True if the gripper mm is calibrated. False otherwise.

is_speed_calibrated()[source]

TElls if the speed calibration is done.

Returns:

is_startedbool: True if the gripper speed is calibrated. False otherwise.

gripper_vmax_bits()[source]

Return the maximum speed in bits per second

Returns: vmax_bits : int

Maximum gripper speed in bits per second.

gripper_vmin_bits()[source]

Return the minimum speed in bits per second

Returns:

vmin_bitsint: Minimum gripper speed in bits per second.

positionCommand()[source]

Return the last commanded position value.

Returns:

int or None: The last position command value (0-255), or None if history is empty.

position(refreshStatus=True)[source]

positionmm(refreshStatus=True)[source]

Return the position of the gripper in mm.

Returns:

positionmmfloat: Current gripper position in mm

Note

Calibration is needed to use this function.

Execute the function calibrate at least 1 time before using this function.

speed()[source]

Return the last set speed value.

Returns:

int or None: The last speed value set (0-255), or None if history is empty.

force()[source]

Return the last set force value.

Returns:

int or None: The last force value set (0-255), or None if history is empty.

objectDetection(mergedHistory=None, duration=0.2, tolerance=3)[source]

Estimate object detection status from history data.

Parameters:

mergedHistorynumpy.ndarray, optional: Pre-merged history array. If None, merges internally.
durationfloat, optional: Stability duration threshold. Default is 0.2.
toleranceint, optional: Position tolerance. Default is 3.

Returns:

int: Object detection status code.

commandHistory()[source]

Return the gripper command history as a pandas DataFrame.

Returns:

pd.DataFrame: A DataFrame containing the command history with columns for time and various command registers (rARD, rATR, etc.).

readStatus()[source]: Retrieve gripper output register information and save it in the parameter dictionary.

status(refreshStatus=True)[source]

Return the current gripper status as a dictionary.

Parameters:

refreshStatusbool, optional: Whether to read fresh status from the gripper. Default is True.

Returns:

dict: A dictionary containing current status values for all registers.

printStatus(refreshStatus=False)[source]

Print gripper status info in the python terminal

Examples

>>> grip.move(100)
>>> grip.printStatus()

Output:

======================================================================
                    GRIPPER STATUS
======================================================================

gOBJ : 3
└─ Fingers are at requested position. No object detected or object has been loss / dropped.

gSTA : 3
└─ Activation is completed.

gGTO : 1
└─ Go to Position Request.

gACT : 1
└─ Gripper activation.

kFLT : 0
└─ 0

gFLT : 9
└─ Minor faults (LED continuous red). No communication during at least 1 second.

gPR  : 100
└─ Echo of the requested position for the Gripper:100/255

gPO  : 100
└─ Actual position of the Gripper obtained via the encoders:100/255

gCU  : 0
└─ The current is read instantaneously from the motor drive, approximate current: 0 mA

======================================================================

statusHistory()[source]

Return the gripper status history as a pandas DataFrame.

Returns:

pd.DataFrame: A DataFrame containing the status history with columns for time and various status registers (gOBJ, gSTA, etc.).

history()[source]

Return the merged command and status history as a pandas DataFrame.

This method combines the command history and status history into a single DataFrame with all timestamps aligned.

Returns:

pd.DataFrame: A DataFrame containing the merged history with columns for time, commands, and status values.

Parameters:

com_port (str)
device_id (int)
connection_type (str)
tcp_host (str)
tcp_port (int)
debug (bool)

Constants

Constants for pyRobotiqGripper package.

This module contains all configuration constants used throughout the package, including communication parameters, gripper limits, and status codes.

Exceptions

Custom exceptions for pyRobotiqGripper package.

exception pyrobotiqgripper.exceptions.RobotiqGripperError[source]

Bases: Exception

Base exception for all pyRobotiqGripper errors.

exception pyrobotiqgripper.exceptions.GripperConnectionError[source]

Bases: RobotiqGripperError

Raised when connection to gripper fails or is lost.

exception pyrobotiqgripper.exceptions.GripperNotActivatedError[source]

Bases: RobotiqGripperError

Raised when an action is requested but gripper is not activated.

__init__()[source]

exception pyrobotiqgripper.exceptions.GripperNotStartedError[source]

Bases: RobotiqGripperError

Raised when an action is requested but gripper is not started.

__init__()[source]

exception pyrobotiqgripper.exceptions.GripperNotCalibratedError[source]

Bases: RobotiqGripperError

Raised when mm-based operations are used without calibration.

__init__()[source]

exception pyrobotiqgripper.exceptions.GripperTimeoutError(operation='Operation', timeout=10)[source]

Bases: RobotiqGripperError

Raised when gripper operation exceeds timeout.

Parameters:

operation (str)
timeout (float)

__init__(operation='Operation', timeout=10)[source]

Parameters:

operation (str)
timeout (float)

exception pyrobotiqgripper.exceptions.GripperPositionError(position, min_val=0, max_val=255)[source]

Bases: RobotiqGripperError

Raised when an invalid position is requested.

Parameters:

position (int)
min_val (int)
max_val (int)

__init__(position, min_val=0, max_val=255)[source]

Parameters:

position (int)
min_val (int)
max_val (int)

exception pyrobotiqgripper.exceptions.GripperCalibrationError[source]

Bases: RobotiqGripperError

Raised when calibration data is invalid.

exception pyrobotiqgripper.exceptions.GripperCommunicationError[source]

Bases: RobotiqGripperError

Raised when Modbus communication fails.

exception pyrobotiqgripper.exceptions.GripperFaultError[source]

Bases: RobotiqGripperError

Raised when the gripper reports a fault.

exception pyrobotiqgripper.exceptions.GripperValidationError[source]

Bases: RobotiqGripperError

Raised when invalid parameters are provided.

exception pyrobotiqgripper.exceptions.UnsupportedGripperTypeError[source]

Bases: RobotiqGripperError

Raised when an unsupported gripper type is specified.

Utilities

Utility functions for pyRobotiqGripper package.

This module provides helper functions for common operations used by the gripper control system, including list manipulation and mathematical utilities.

pyrobotiqgripper.utils.array_merge_on_first_column(arr1, arr2)[source]

Merge two numpy arrays side by side based on a time column.

Parameters:

arr1 – numpy arrays
arr2 – numpy arrays
property – index of the time column (default: TIME)

Returns:

Merged array with all timestamps and NaN where data is missing.

pyrobotiqgripper.utils.array_forward_fill_columns(arr, columns, missing_value=-1)[source]

In-place forward-fill selected columns in a NumPy array.

Parameters:

arr – 2D numpy array (modified in-place)
columns – list of column indices to forward-fill
missing_value – value used to represent missing data (default: -1)

pyrobotiqgripper.utils.floor_to_ms(t)[source]

Floor a time value to millisecond precision.

Parameters:

tfloat: Time value in seconds.

Returns:

float: Time floored to millisecond precision.

pyrobotiqgripper.utils.modbus_probe_with_timeout(port, device_id, timeout=1.0)[source]

Probe a Modbus serial port with a timeout to check for device connectivity.

Parameters:

portstr: The serial port to probe.
device_idint: The Modbus device ID.
timeoutfloat, optional: Timeout in seconds. Default is 1.0.

Returns:

bool: True if device responds, False otherwise.