Grasp (Suction Gripper)

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.

SUPPORTED GRIPPERS

Available on Piab suction grippers.

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

Example: Grasp at a Specific Vacuum Level

"""
Piab grasp example for the Synapse SDK.

Connects to a Piab piCOBOT Electric gripper and grasps at 75% vacuum.

Usage:
    python grasp.py --ip <ROBOT_IP>
"""

import argparse
from loguru import logger

from telekinesis.synapse.tools.suction_grippers import piab


def main(ip: str):
    """Grasp an object at 75% vacuum."""

    # Create and connect to the gripper
    gripper = piab.PiabPiCobotElectric()
    gripper.connect(ip=ip, protocol="URCAP")

    try:
        gripper.grasp(vacuum_level=75, unit="percentage")
        logger.success(f"Grasped at {gripper.get_vacuum_level()}% vacuum.")
    finally:
        gripper.disconnect()


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Piab gripper grasp example")
    parser.add_argument("--ip", type=str, required=True, help="UR controller IP address")
    args = parser.parse_args()

    main(ip=args.ip)

The Explanation of the Code

grasp starts vacuum generation. When vacuum_level is omitted, the currently configured level is used (the default is 50%, or whatever was last set with set_vacuum_level). Passing vacuum_level explicitly also updates the configured level for subsequent calls.

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.

How to Tune the Parameters

Piab piCOBOT Electric

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".

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