API Reference

RobotiqGripper

class pyrobotiqgripper.RobotiqGripper(com_port='auto', device_id=9, connection_type='RTU', tcp_host='127.0.0.1', tcp_port=54321, baudrate=115200, 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, baudrate=115200, 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_port (str) – 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_id (int) – Address of the gripper (integer) usually 9.
gripper_type (str) – Type of the gripper. Currently only “2F” is supported. Default is “2F”.
connection_type (str) – 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_host (str) – Host IP address for TCP connection. Default is “127.0.0.1”
tcp_port (int) – Port number for TCP connection. Default is 54321.
baudrate (int) – Gripper communication baudrate.
debug (bool) – 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_mm(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)

Setup

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

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

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

RobotiqGripper.activate(reset=True, start=True, refreshStatus=True)[source]

Activate the gripper if it is not already active.

Parameters:

reset (bool) – Whether to reset the gripper before activation.
start (bool) – Whether to start the gripper motion immediately after activation (gGTO set to 1).
refreshStatus (bool) – Whether to refresh the gripper status before the activation process. The status information is used to determine if the gripper is already activated. Setting this parameter to False can make the activation faster if you are sure the gripper status is up to date.

Warning

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

RobotiqGripper.start(refreshStatus=True, readStatus=True)[source]

Start the gripper motion.

The GTO bit is set to 1. The gripper will move to the position command if it is not already there.

Parameters:

refreshStatus (bool) – Whether to refresh the gripper status before the start process. The status information is used to determine if the gripper is already started. Setting this parameter to False can make the start process faster if you are sure the gripper status is up to date.
readStatus (bool) – Whether to read the gripper status while sending the start command.

RobotiqGripper.stop(refreshStatus=True, readStatus=True)[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.

Parameters:

refreshStatus (bool, optional) – Whether to refresh the gripper status before deciding whether to preserve the activation bit. Defaults to True.
readStatus (bool, optional) – If True, read fresh gripper status in the same Modbus transaction as the stop write (function code 23). If False, only the stop is written (function code 16). Defaults to True.

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

Calibrate the maximum and minimum position bit values of the gripper.

This function sets the reference positions for the gripper in bits. If no parameters are provided, the gripper will perform a full open followed by a full close to measure the maximum and minimum positions.

Parameters:

openbit (int, optional) – Position value in bits when the gripper is open.
closebit (int, optional) – Position value in bits when the gripper is closed.

Warning

If no parameters are provided, the gripper will make a full open followed by a full close to measure the maximum and minimum positions in bits. Ensure the gripper can move freely during this operation.

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

Calibrate gripper speed to estimate gripper position over time.

If no parameters are provided, the gripper will perform a full-speed closing and a slow-speed closing to evaluate its motion. Bit calibration will also be performed.

Parameters:

minSpeedClosingTime (float, optional) – Time in seconds for the gripper to move from fully open to fully closed at minimum speed.
maxSpeedClosingTime (float, optional) – Time in seconds for the gripper to move from fully open to fully closed at maximum speed.

Warning

If no parameters are provided, the gripper will perform a full-speed closing and a slow-speed closing to evaluate its motion. Ensure the gripper can move freely during this operation.

RobotiqGripper.calibrate_mm(closemm, openmm)[source]

Calibrate the gripper for millimeter positioning.

Once this calibration is done, it is possible to control the gripper using millimeters.

Parameters:

closemm (float) – Distance between the fingers when the gripper is fully closed.
openmm (float) – Distance between the fingers when the gripper is fully open.

Warning

Bit calibration is required before executing this function. If the bit calibration is not done, the function calibrate_bit() will be executed automatically before calibrating in millimeters.

Control

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

Open the gripper.

Parameters:

speed (int, optional) – Gripper speed between 0 and 255. Defaults to 255.
force (int, optional) – Gripper force between 0 and 255. Defaults to 255.
wait (bool, optional) – If True, the function waits until the gripper reaches the requested position or detects an object. Defaults to True.
readStatus (bool, optional) – If True, the gripper status is read after sending the command. Defaults to True.
refreshStatus (bool, optional) – If True, the gripper status is refreshed before sending the command. The status information is used to determine if the gripper is already activated. Setting this parameter to False can make the command process faster if the gripper status is up to date. Defaults to False.

RobotiqGripper.close(speed=255, force=255, wait=True, readStatus=True, refreshStatus=False, start=False)[source]

Close the gripper.

Parameters:

speed (int, optional) – Gripper speed between 0 and 255. Defaults to 255.
force (int, optional) – Gripper force between 0 and 255. Defaults to 255.
wait (bool, optional) – If True, the function waits until the gripper reaches the requested position or detects an object. Defaults to True.
readStatus (bool, optional) – If True, the gripper status is read after sending the command. Defaults to True.
refreshStatus (bool, optional) – If True, the gripper status is refreshed before sending the command. The status information is used to determine if the gripper is already activated. Setting this parameter to False can make the command process faster if the gripper status is up to date. Defaults to False.
start (bool, optional) – If True, the activation and go-to bits are combined with this move in a single Modbus transaction instead of requiring a separate start() call first. The gripper must already be activated (activate() called at least once). Defaults to False.

RobotiqGripper.open_mm()[source]: Return distance between fingers in open position

RobotiqGripper.close_mm()[source]: Return distance between fingers in open position

RobotiqGripper.move(position, speed=255, force=255, wait=True, readStatus=True, refreshStatus=False, start=False)[source]

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

Parameters:

position (int) – Target position of the gripper. Must be between 0 and 255, where 0 represents fully open and 255 represents fully closed.
speed (int, optional) – Gripper speed between 0 and 255. Defaults to 255.
force (int, optional) – Gripper force between 0 and 255. Defaults to 255.
wait (bool, optional) – If True, the function waits until the gripper reaches the requested position or detects an object. Defaults to True.
readStatus (bool, optional) – If True, the gripper status is read after sending the command. Defaults to True.
refreshStatus (bool, optional) – If True, the gripper status is refreshed before sending the command. The status information is used to determine if the gripper is already activated. Setting this parameter to False can make the command process faster if the gripper status is up to date. Defaults to False.
start (bool, optional) – If True, the activation and go-to bits are combined with this move in a single Modbus transaction instead of requiring a separate start() call first. The gripper must already be activated (activate() called at least once). Defaults to False.

Examples

Combine start() and move() in a single Modbus transaction:

>>> gripper.activate()
>>> gripper.move(200, speed=150, force=100, start=True)

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

Move the gripper to the requested opening in millimeters.

Parameters:

positionmm (float) – Target gripper opening in millimeters.
speed (int, optional) – Gripper speed between 0 and 255. Defaults to 255.
force (int, optional) – Gripper force between 0 and 255. Defaults to 255.
wait (bool, optional) – If True, the function waits until the gripper reaches the requested position or detects an object. Defaults to True.
readStatus (bool, optional) – If True, the gripper status is read after sending the command. Defaults to True.
refreshStatus (bool, optional) – If True, the gripper status is refreshed before sending the command. The status information is used to determine if the gripper is already activated. Setting this parameter to False can make the command process faster if the gripper status is up to date. Defaults to False.

Note

Millimeter calibration is required to use this function. Execute the function calibrate_mm() before using this function.

RobotiqGripper.moveToCurrentPosition(speed=None, force=None)[source]

Move the gripper to its current position. This has the effect to stop the gripper while keeping it started. It is more flexible than jsut stopping the gripper.

Parameters:

speed (int) – Gripper speed parameter value to move to current position
force (int) – Gripper force parameter value to move to current position

Realtime Control

RobotiqGripper.realTimePositionMove(controlSignal, controlBuffer=0.05, speedLowerControlThreshold=10, speedUpperControlThreshold=30, gripSpeed=None, gripForce=None, verbose=0)[source]

Move the gripper in real time to the requested position.

Meant to be called at high frequency (e.g. 100 Hz) in a non-blocking control loop for remote operation application.

Parameters:

controlSignal – Analogic position control signal in range [0,1]
controlBuffer – Dimension of the signal deadzones express in percentage of the the control signal. Deadzones are positionned at the bottom and the top of the control range.
speedLowerControlThreshold – The speed is function of the difference between current position and target position. The function is ramp that start at speedLowerControlThreshold and finish at speedUpperControlThreshold.
speedUpperControlThreshold – The speed is function of the difference between current position and target position. The function is ramp that start at speedLowerControlThreshold and finish at speedUpperControlThreshold.
gripSpeed – Speed parameter use to secure a grip when an object is detected. If used, gripForce and gripSpeed have to be both set.
gripForce – Force parameter use to secure a grip when an object is detected. If used, gripForce and gripSpeed have to be both set.
verbose (int, optional) – Verbose level for debug.

Examples

Make a loop to control the gripper using a joystick with pygame

>>> import pygame
>>> import time
>>> import pyrobotiqgripper as rq
>>> grip = rq.RobotiqGripper()
>>> pygame.init()
>>> pygame.joystick.init()
>>> js = pygame.joystick.Joystick(0)
>>> js.init()
>>> while True:
>>>     positionSignal = js.get_axis(0)
>>>     pygame.event.pump()
>>>     grip.realTimePositionMove(positionSignal)

RobotiqGripper.realTimePositionMove_Mode()[source]: Return the mode of the realTimePositionMove function

RobotiqGripper.realTimeSpeedMove(controlSignal, controlBuffer=0.05, gripSpeed=None, gripForce=None, verbose=0)[source]

Move the gripper with a speed signal.

Meant to be called at high frequency (e.g. 100 Hz) in a non-blocking control loop for remote operation application.

Parameters:

controlSignal (float) – Analogic signal in the range [-1, 1] use to control gripper speed. Positive closes the gripper, negative opens it, 0 holds the current position. Magnitude controls the commanded speed.
controlBuffer (float) – controlSignal deadzone express in percentage of the control range. The deadzone is positionned at the center of the control range.
gripSpeed – Speed parameter use to secure a grip when an object is detected. If used, gripForce and gripSpeed have to be both set.
gripForce – Force parameter use to secure a grip when an object is detected. If used, gripForce and gripSpeed have to be both set.
verbose (int, optional) – Verbose level for debug.

Examples

Make a loop to control the gripper using a joystick with pygame

>>> import pygame
>>> import time
>>> import pyrobotiqgripper as rq
>>> grip = rq.RobotiqGripper()
>>> pygame.init()
>>> pygame.joystick.init()
>>> js = pygame.joystick.Joystick(0)
>>> js.init()
>>> while True:
>>>     speedSignal = js.get_axis(0)
>>>     pygame.event.pump()
>>>     grip.realTimeSpeedMove(speedSignal)

RobotiqGripper.realTimeSpeedMove_Mode()[source]: Return the mode of the realTimeSpeedMove function

Status

RobotiqGripper.isActivated(refreshStatus=True)[source]

Check whether the gripper is activated.

Parameters:: refreshStatus (bool, optional) – Whether to refresh the gripper status before checking the activation state. The status information is used to determine if the gripper is already activated. Setting this parameter to False can make the check faster if the gripper status is up to date. Defaults to True.
Returns:: True if the gripper is activated, False if not activated, None if there is no available information to confirm gripper activation status
Return type:: bool

RobotiqGripper.isStarted(refreshStatus=True)[source]

Check whether the gripper is started.

Returns:: True if the gripper is started, False if not started, None is there is not enough information to confirm if the gripper is started.
Return type:: bool

RobotiqGripper.is_bit_calibrated()[source]

Check whether the gripper is bit calibrated (ie. the gripper know its position in bit when fully open and fully closed).

Returns:: True if the gripper is bit calibrated, False otherwise.
Return type:: bool

RobotiqGripper.is_mm_calibrated()[source]

Check whether the gripper millimeter (mm) calibration is done.

Returns:: True if the gripper is mm calibrated, False otherwise.
Return type:: bool

RobotiqGripper.positioningResolution()[source]: Return the gripper positionning resolution in mm/bit. The number of mm the gripper will move if its position parameter vary of 1 bit.

RobotiqGripper.is_speed_calibrated()[source]

Check whether the gripper speed calibration is done.

Returns:: True if the gripper speed is calibrated, False otherwise.
Return type:: bool

RobotiqGripper.gripper_vmax_bits()[source]

Return the maximum gripper speed in bits per second.

Returns:: Maximum gripper speed in bits per second.
Return type:: int

RobotiqGripper.gripper_vmin_bits()[source]

Return the minimum gripper speed in bits per second.

Returns:: Minimum gripper speed in bits per second.
Return type:: int

RobotiqGripper.minSpeedMmSecond()[source]: Return the minimum gripper speed in mm/s

RobotiqGripper.maxSpeedMmSecond()[source]: Return the maximum gripper speed in mm/s

RobotiqGripper.speedResolutionBit()[source]: Return the speed resultion in gripper position bit/s per gripper speed bit. Correspond to the speed increase if speed parameter vary of 1 bit.

RobotiqGripper.speedResolutionMm()[source]: Return the speed resultion in mm/s per bit. This correspond the speed increase in mm/s if the speed parameter vary of 1 bit

RobotiqGripper.positionCommand()[source]

Return the last commanded position value.

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

RobotiqGripper.position(refreshStatus=True)[source]

Return the current position of the gripper in bits.

Parameters:: refreshStatus (bool, optional) – Whether to refresh the gripper status before getting the position. The status information is used to determine the current position. Setting this parameter to False can make the retrieval faster if the gripper status is already up to date. Defaults to True.
Returns:: Current gripper position in bits (0-255), or None if history is empty.
Return type:: int | None

RobotiqGripper.position_mm(refreshStatus=True)[source]

Return the current position of the gripper in millimeters.

Parameters:: refreshStatus (bool, optional) – Whether to refresh the gripper status before getting the position. The status information is used to determine the current position. Setting this parameter to False can make the retrieval faster if the gripper status is already up to date. Defaults to True.
Returns:: Current gripper position in millimeters.
Return type:: float

Note

Calibration is required to use this function. Execute the calibration function at least once before using this function.

RobotiqGripper.lastMoveTime()[source]: Return the time of gripper last move

RobotiqGripper.lastMoveDirection()[source]

Return the last direction of movement of the gripper based gripper position history

Returns:: Last direction of movement. 1 for closing, -1 for opening, 0 if unknown.
Return type:: int

RobotiqGripper.speed()[source]

Return the last set speed parameter value.

Returns:

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

RobotiqGripper.force()[source]

Return the last set force paramater value.

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

RobotiqGripper.objectDetection(refreshStatus=True)[source]

Return object detection code gOBJ

Even if the refreshStatus is not requested, it will be done if the status have never been retrieved.

Parameters:

refreshSatus (boolean) – Indicate if the object detection status is directly retrieved from the gripper or if it is taken from the last previously read status.

Returns:

Object detection status code.

0: Fingers in motion, no object detected
1: Fingers stopped while opening, object detected
2: Fingers stopped while closing, object detected
3: Fingers at requested position, no object detected or lost/dropped

Return type:

int

RobotiqGripper.printObjectDetection(refreshStatus=True)[source]: Print object detection status in a human readable way

RobotiqGripper.evaluateGrip(refreshStatus=True)[source]

Evaluate from gripper past state the status of the grip Grip evaluation is only possible of gripper status has been retrieved at high frequency until then (>10hz). The gripper needs to be speed calibrated evaluate the grip.

Parameters:

refreshSatus (boolean) – Indicate if the object detection status is directly retrieved from the gripper or if it is taken from the last previously read status.

Returns:

Quality of grip code

0: No object detected
1: Stable grip
2: Object compressing or slipping from the hand
3: Object lost

Return type:

int

RobotiqGripper.readStatus()[source]: Retrieve gripper output register information and save it in the status history.

RobotiqGripper.lastStatusReadTime()[source]

RobotiqGripper.status(refreshStatus=True)[source]

Return the current gripper status as a dictionary.

Parameters:: refreshStatus (bool, optional) – Whether to read fresh status from the gripper. Defaults to True.
Returns:: A dictionary containing current status values for all registers.
Return type:: dict

RobotiqGripper.printStatus(refreshStatus=True)[source]

Print gripper status info in the Python terminal.

Parameters:: refreshStatus (bool, optional) – Whether to read fresh status from the gripper before printing. Defaults to False. If you are sure that the status information is up to date, setting this parameter to False can make the printing faster.

Examples

>>> grip.move(100)
>>> grip.print_status()

Output:

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

gOBJ : 3
└─ Fingers are at requested position. No object detected or object has been lost / 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

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

RobotiqGripper.commandHistoryPanda()[source]

Return the gripper command history as a pandas DataFrame.

Returns:

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

Return type:

pd.DataFrame

RobotiqGripper.statusHistoryPanda()[source]

Return the gripper status history as a pandas DataFrame.

Returns:

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

Return type:

pd.DataFrame

RobotiqGripper.historyPanda()[source]

Return the merged command and status history as a pandas DataFrame. The first line of the DataFrame corresponds to the odlest command or status entry, the last line corresponds to the most recent command or status entry.

Returns:

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

Return type:

pd.DataFrame

RobotiqGripper.commandHistory()[source]

Return the gripper command history as a numpy array.

Warning

This function keep reference of the commandHistory source array. If you want to edit the value of the return numpy array make a copy of it. commandHistory().copy()

Returns:

A numpy array containing the status history.

Columns are

0 -> “time” 1 -> “rARD” 2 -> “rATR” 3 -> “rGTO” 4 -> “rACT” 5 -> “rPR” 6 -> “rSP” 7 -> “rFR”

The constant dictionnaries can be use to converter column id into parameter name or column name into column id.

COMMAND_HISTORY_COLUMNS_ID_2_NAME COMMAND_HISTORY_COLUMNS_NAME_2_ID

Return type:

numpy array

RobotiqGripper.statusHistoryNumpy()[source]

Return the gripper status history as a numpy array.

Warning

This function keep reference of the statusHistory source array. If you want to edit the value of the return numpy array make a copy of it. statusHistoryNumpy().copy()

Returns:

A numpy array containing the status history.

Columns are

0 -> “time” 1 -> “gOBJ” 2 -> “gSTA” 3 -> “gGTO” 4 -> “gACT” 5 -> “kFLT” 6 -> “gFLT” 7 -> “gPR” 8 -> “gPO” 9 -> “gCU”

The constant dictionnaries can be use to converter column id into parameter name or column name into column id.

STATUS_HISTORY_COLUMNS_ID_2_NAME STATUS_HISTORY_COLUMNS_NAME_2_ID

Return type:

numpy array

RobotiqGripper.historyNumpy()[source]

Return the merged command and status history as a numpy array. The first line of the array corresponds to the odlest command or status entry, the last line corresponds to the most recent command or status entry.

Returns:

A numpy array containing the merged history.

Columns are

0 -> “time” 1 -> “rARD” 2 -> “rATR” 3 -> “rGTO” 4 -> “rACT” 5 -> “rPR” 6 -> “rSP” 7 -> “rFR” 8 -> “gOBJ” 9 -> “gSTA” 10 -> “gGTO” 11 -> “gACT” 12 -> “kFLT” 13 -> “gFLT” 14 -> “gPR” 15 -> “gPO” 16 -> “gCU”

The constant dictionnaries can be use to converter column id into parameter name or column name into column id.

HISTORY_COLUMNS_ID_2_NAME HISTORY_COLUMNS_NAME_2_ID

Return type:

numpy array

Additional Tools

These tools are not required to control a gripper: they support experimenting with and debugging the realtime control features (see Realtime usage).

Mouse Joystick

class pyrobotiqgripper.mouse_joystick.MouseJoystick(deadzone=0)[source]

Bases: object

Reports mouse position as two axes, each with a dead zone centered on the screen, sized as a fraction of the corresponding screen dimension.

Axis 0 (AXIS_X): horizontal position, -1 (left) to 1 (right). Axis 1 (AXIS_Y): vertical position, 1 (top) to -1 (bottom).

Parameters:: deadzone (float)

__init__(deadzone=0)[source]

Parameters:: deadzone (float, optional) – Fraction (0-1) of the screen dimension, centered on the middle of the screen, that reports 0 for that axis. Defaults to 0.10 (10%).

get_axis(axis)[source]

Return the requested axis value in [-1, 1].

Parameters:: axis (int) – AXIS_X (0) for horizontal position, AXIS_Y (1) for vertical position.

pyrobotiqgripper.mouse_joystick.AXIS_X: Axis index for the horizontal mouse position, for use with get_axis().

pyrobotiqgripper.mouse_joystick.AXIS_Y: Axis index for the vertical mouse position, for use with get_axis().

Gripper Visualizer

Requires the optional PySide6 package, included in the all extra (uv add "pyrobotiqgripper[all]").

class pyrobotiqgripper.visualizer.GripperVisualizer(gripper, bounded_signals=None, state_signals=None, refresh_interval_ms=100, window_title='Gripper Live State')[source]

Bases: object

Background window plotting a gripper’s live history.

The window is created and driven entirely on a dedicated background thread, started and stopped explicitly with start() and stop(). Closing the window from the UI also stops the thread.

Parameters:

gripper – The RobotiqGripper instance to read history from. Only its commandHistory() and statusHistoryNumpy() methods are called; the gripper is never written to or read live from Modbus by this class.
bounded_signals (Sequence[str], optional) – History column names initially checked on the 0-255 chart. Must be a subset of BOUNDED_SIGNALS. Defaults to DEFAULT_BOUNDED_SIGNALS (actual position, commanded speed, commanded force).
state_signals (Sequence[str], optional) – History column names initially checked on the state chart. Must be a subset of STATE_SIGNALS. Defaults to DEFAULT_STATE_SIGNALS (object detection).
refresh_interval_ms (int, optional) – Redraw period, in milliseconds. Defaults to 100.
window_title (str, optional) – Title of the visualization window. Defaults to "Gripper Live State".

Note

The timeline window shown on both charts is fixed at TIMELINE_DURATION_S (5 seconds), matching the gripper’s own history buffer (MAX_HISTORY samples at the typical 100 Hz control loop rate) and is not adjustable from the window.

Warning

Reading the gripper’s history buffers concurrently with whichever thread is filling them (e.g. a joystick control loop) is not lock protected. For a live debugging display this is an acceptable trade-off: at worst a single redraw reads a partially updated row.

Warning

An instance only supports a single start()/stop() cycle: Qt does not support re-creating a QApplication after a previous one has been destroyed in the same process. Calling start() again after stop() raises RuntimeError; create a new GripperVisualizer instance instead.

Examples

>>> import pyrobotiqgripper as rq
>>> from pyrobotiqgripper.visualizer import GripperVisualizer
>>> gripper = rq.RobotiqGripper()
>>> visualizer = GripperVisualizer(gripper)
>>> visualizer.start()
>>> # ... drive the gripper from the main thread ...
>>> visualizer.stop()

__init__(gripper, bounded_signals=None, state_signals=None, refresh_interval_ms=100, window_title='Gripper Live State')[source]

Parameters:

bounded_signals (Sequence[str] | None)
state_signals (Sequence[str] | None)
refresh_interval_ms (int)
window_title (str)

start()[source]

Start the visualization window on a background thread.

Does nothing if the window is already running.

Raises:: RuntimeError – If this instance was already started and stopped once before. Qt does not support re-creating a QApplication after a previous one has been destroyed in the same process, so a given GripperVisualizer instance only supports a single start/stop cycle. Create a new instance for a second run.
Return type:: None

stop()[source]

Request the window to close and wait for its thread to exit.

Does nothing if the window is not running.

Return type:: None

is_running()[source]

Return whether the visualization thread is currently running.

Returns:: True if the background thread is alive.
Return type:: bool

pyrobotiqgripper.visualizer.BOUNDED_SIGNALS: History column names selectable on the 0-255 bounded chart (gPO, rPR, rSP, rFR, gPR, gCU).

pyrobotiqgripper.visualizer.DEFAULT_BOUNDED_SIGNALS: Signals checked by default on the bounded chart when none are given: actual position, commanded speed and commanded force.

pyrobotiqgripper.visualizer.STATE_SIGNALS: History column names selectable on the state chart, carrying small enumerated / flag register values (gOBJ, gSTA, gGTO, gACT, kFLT, gFLT, rARD, rATR, rGTO, rACT).

pyrobotiqgripper.visualizer.DEFAULT_STATE_SIGNALS: Signals checked by default on the state chart when none are given: object detection.

Bipper

Requires the optional sounddevice package, included in the all extra (uv add "pyrobotiqgripper[all]").

Plays a continuous tone whose beep rate speeds up as input_signal increases towards 1.0. Used by the Joystick CLI’s --bipper option to give an audio cue of grip force during realtime control.

class pyrobotiqgripper.bipper.Bipper(sample_rate=44100, volume=0.3, audio_pitch=600.0, min_beep_rate=1.5, max_beep_rate=12.0)[source]

Bases: object

__init__(sample_rate=44100, volume=0.3, audio_pitch=600.0, min_beep_rate=1.5, max_beep_rate=12.0)[source]

property input_signal

property audio_pitch

property min_beep_rate

property max_beep_rate

property volume

start()[source]: Starts background audio playback thread.

stop()[source]: Stops background audio playback thread.

Joystick CLI

Console script (pyrobotiqgripper-joystick) used to drive a gripper with a joystick or mouse from the command line. See the Joystick CLI usage guide for installation and examples; run pyrobotiqgripper-joystick --help for the full list of options.

pyrobotiqgripper.joystick_cli.main(argv=None)[source]

Entry point for the joystick CLI.

Parameters:: argv (List[str] | None)
Return type:: int

Constants

pyrobotiqgripper.BAUDRATE: Default baudrate of the gripper use by Robotiq gripper.

pyrobotiqgripper.BYTESIZE: Byte size use by Robotiq gripper

pyrobotiqgripper.PARITY: Parity use by Robotiq gripper

pyrobotiqgripper.STOPBITS: Stop bits used by Robotiq gripper

pyrobotiqgripper.TIMEOUT: Default timeout use for communication with Robotiq gripper

pyrobotiqgripper.AUTO_DETECTION: Automatically detect the USB port on which the gripper connected.

pyrobotiqgripper.GRIPPER_MODE_RTU_VIA_TCP: Set communication to be RTU via TCP

pyrobotiqgripper.GRIPPER_MODE_RTU: Set communication to be RTU

pyrobotiqgripper.REGISTER_DIC

Dictionary containing all input and output registers for the Robotiq gripper.

Each top-level key represents a register group:

Input registers (g / k prefix): - gOBJ : Object detection status

0: Fingers in motion, no object detected

1: Fingers stopped while opening, object detected

2: Fingers stopped while closing, object detected

3: Fingers at requested position, no object detected or lost/dropped

gSTAGripper status
- 0: Reset / automatic release
- 1: Activation in progress
- 3: Activation completed
gGTOGo-to status
- 0: Stopped / performing activation or release
- 1: Go to position requested
gACTActivation status
- 0: Gripper reset
- 1: Gripper activation
kFLT : Controller fault codes (0–255)
gFLT : Gripper fault codes (0–255, specific faults for indices 0, 5, 7–15)
gPR : Echo of requested positions (0–255)
gPO : Actual positions read from encoders (0–255)
gCU : Instantaneous current from motor drive (0–255, in mA)

Output registers (r prefix): - rARD : Automatic release status

0: Closing auto-release

1: Opening auto-release

rATRAutomatic release type
- 0: Normal
- 1: Emergency auto-release
rGTOGo-to command status
- 0: Stop
- 1: Go to requested position
rACTActivation command
- 0: Deactivate gripper
- 1: Activate gripper (must stay on until routine completes)
rPR : Target positions for gripper fingers (0–255)
rSP : Speed of gripper movement (0–255)
rFR : Final gripping force (0–255)

This dictionary is mapping integer codes to human-readable descriptions for every register.