Gripper Connection and Disconnection

SUMMARY

Suction Gripper Connection and Disconnection manages the gripper session lifecycle for reliable runtime communication.

This skill ensures robust setup and teardown of the gripper's communication channel before and after task execution.

The Skill

# Connect (Piab, real hardware)
gripper.connect(ip=gripper_ip, protocol="URCAP")
# or
gripper.connect(serial_port=serial_port, protocol="MODBUS_RTU")

# Connect (Piab, simulated in Isaac Sim)
gripper.connect(simulation_prim_path=prim_path)

# Connect (simulation-only custom.SuctionGripper, Isaac Sim)
sim_gripper.connect(simulation_prim_path=prim_path)

# Disconnect
gripper.disconnect()

The Code

Safety first!

A real robot will faithfully do whatever you ask of it - so please take a moment to clear the workspace, keep an E-Stop within reach, and be ready to disconnect.

Operating real hardware is at your own risk.

Real

"""
Demonstrates connecting and disconnecting a suction gripper.

Supports Piab grippers, on real hardware or simulated in Isaac Sim via
`simulation_prim_path`. Also supported for the simulation-only
custom.SuctionGripper, which only accepts `simulation_prim_path` - it has
no hardware transport.

Usage:
    python connection_and_disconnection.py --ip <ROBOT_IP>
    python connection_and_disconnection.py --protocol MODBUS_RTU --serial-port COM3
    python connection_and_disconnection.py --prim_path /World/suction_gripper
"""

import argparse
from loguru import logger

from telekinesis.synapse.tools.suction_grippers import piab


def main(ip: str | None, serial_port: str, protocol: str) -> None:
    """Connects and disconnects a Piab gripper."""

    #===================== Create Gripper ======================================
    gripper = piab.PiabPiCobotElectric()

    # ==================== Run Skill ===========================================
    try:
        gripper.connect(ip=ip, serial_port=serial_port, protocol=protocol)
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        gripper.disconnect()


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Piab gripper connect/disconnect")
    p.add_argument("--protocol",
                   choices=["URCAP", "MODBUS_RTU"],
                   default="URCAP")
    p.add_argument("--ip", default="192.168.2.2", help="IP for Robot Controller")
    p.add_argument("--serial-port", dest="serial_port", default="COM3",
                   help="Serial port for MODBUS_RTU")
    args = p.parse_args()

    main(ip=args.ip,
         serial_port=args.serial_port,
         protocol=args.protocol)

Parameter Configuration

Connect

Piab

Parameter	Type	Default	Description
ip	str	-	IP address of the Universal Robots controller. Required when protocol="URCAP".
serial_port	str	-	Serial port of the RS-485-to-USB converter (e.g. /dev/ttyUSB0, COM3). Required when protocol="MODBUS_RTU".
protocol	str	"URCAP"	"URCAP" (via a UR controller) or "MODBUS_RTU" (direct USB connection). Ignored, and forced to "ISAACSIM", when simulation_prim_path is given.
simulation_prim_path	str | None	None	USD path of the gripper in a running Isaac Sim stage, e.g. /World/piab_gripper. Selects "ISAACSIM" on its own, whatever protocol says.

Isaac Sim (custom.SuctionGripper)

Parameter	Type	Default	Description
simulation_prim_path	str	-	USD path of the gripper in the open Isaac Sim stage, e.g. /World/suction_gripper. Loads the gripper there from its USD asset if nothing exists at that path yet. Required - this class has no ip/serial_port/protocol arguments.
timeout_ms	int	5000	Accepted but ignored; kept so the call signature matches the hardware gripper wrappers.

Disconnect

This skill takes no input parameters.

Returns

Connect

This skill returns nothing (None).

Disconnect

This skill returns nothing (None).

Raises

Connect

Exception	Condition
TypeError	ip, serial_port, protocol, or simulation_prim_path has an invalid type
ValueError	protocol is not "URCAP" or "MODBUS_RTU", or the address required by the selected protocol (ip for URCAP, serial_port for MODBUS_RTU, simulation_prim_path for ISAACSIM) is missing
ConnectionError	The Piab URCap XML-RPC service, or the Modbus RTU serial link, cannot be reached
RuntimeError	The simulated gripper cannot be reached

custom.SuctionGripper.connect only raises TypeError (if simulation_prim_path is not a non-empty string) or RuntimeError (if the simulated gripper cannot be reached).

Disconnect

Exception	Condition
RuntimeError	The gripper is not connected

How to Tune the Parameters

Always call disconnect after task execution to cleanly release the gripper session, and re-connect after a communication fault rather than reusing a stale session. connect raises ConnectionError if the Piab URCap service or Modbus RTU serial link is unreachable, so verify the URCap is installed and running (or the RS-485 converter is wired and powered), and that the address (ip or serial_port) is correct, before calling.

Where to Use the Skill

• Session setup - Call connect once at the start of every script before issuing any gripper commands
• Session teardown - Call disconnect at the end of every script to release the gripper session
• Error recovery - Re-connect after a communication fault to restore the control session

When Not to Use the Skill

Do not call connect or disconnect when:

• The gripper is already connected - connect on an active session overwrites the existing session; disconnect first if reconnecting intentionally
• Inside a tight control loop - establishing a session has latency; connect once at startup and reuse it throughout execution