Gripper Grasp

SUMMARY

Grasp starts vacuum generation on a suction gripper to pick up an object.

This skill is used to pick an object once the gripper's cup(s) are in contact with the surface.

UNITS

vacuum_level in the configured vacuum unit - "percentage" (default, 0-100%) or "kPa" (0-100 kPa max). The scales are numerically identical: 75% is the same as 75 kPa.

The Skill

gripper.grasp(vacuum_level=75, unit="percentage")

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 grasping an object with a suction gripper.

Supports Piab grippers, on real hardware or simulated in Isaac Sim. Also
supported for the simulation-only custom.SuctionGripper, whose grasp() takes
no parameters - vacuum_level and unit do not apply to it.

Usage:
    python grasp.py --ip <ROBOT_IP>
    python grasp.py --protocol MODBUS_RTU --serial-port COM3
"""

import argparse
import time
from loguru import logger

from telekinesis.synapse.tools.suction_grippers import piab


def main(ip: str | None, serial_port: str, protocol: str) -> None:
    """Grasps an object with a Piab gripper at a 60% vacuum level."""

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

    # ==================== Run Skill ===========================================
    try:
        gripper.connect(ip=ip, serial_port=serial_port, protocol=protocol)
        gripper.grasp(vacuum_level=60, unit="percentage")
        logger.success("Grasp command issued.")

        # Give the pump time to build up vacuum before reading the status.
        time.sleep(2.0)
        logger.success(f"Part present: {gripper.get_part_present()}")
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        gripper.disconnect()


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Piab gripper grasp")
    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

Piab

Parameter	Type	Default	Description
vacuum_level	int | None	None	Desired vacuum level, 0-100 (max 100 kPa). When omitted, the last configured level is used.
unit	str	"percentage"	Unit of vacuum_level. Accepts "percentage" or "kPa".

Isaac Sim (custom.SuctionGripper)

This class's grasp() takes no parameters - the simulation does not model vacuum level, so there is nothing to pass. Use Set Vacuum Level beforehand only if you want the value to be readable afterward; it has no effect on the grip.

Returns

This skill returns nothing (None). The call returns as soon as the vacuum command is issued - it does not wait for the vacuum level to stabilize or for a part to be detected. Use get_part_present afterward to confirm the grasp succeeded.

Raises

Exception	Condition
TypeError	vacuum_level or unit has an invalid type
ValueError	vacuum_level or unit is unsupported
ConnectionError	The backend is not connected
RuntimeError	The command fails

How to Tune the Parameters

Higher vacuum_level grips heavier or non-porous parts more securely but increases cycle time and cup wear; lower it for lightweight or porous parts, where excess vacuum can deform the surface or draw air straight through the material without ever reaching a stable seal. When vacuum_level is omitted, grasp reuses whatever was last configured via connect (50% default) or set_vacuum_level - pass it explicitly per call when different parts in the same run need different grip strength. unit only changes how the value is interpreted ("percentage" and "kPa" are numerically identical up to 100), so pick whichever matches how thresholds are documented elsewhere in your pipeline.

Where to Use the Skill

• Pick operations - Start vacuum after positioning the cup(s) against the part surface
• Variable grip strength - Raise vacuum_level for heavier or non-porous parts, lower it for delicate or porous ones

When Not to Use the Skill

Do not use Grasp when:

• The gripper is not connected - always call connect before issuing commands
• The cup is not yet in contact with the part - grasping into open air wastes cycle time and may trigger a low-vacuum fault; position the gripper first