Gripper Set Vacuum Level

SUMMARY

Set Vacuum Level configures the vacuum level a suction gripper uses on subsequent grasp calls.

This skill is used to tune grip strength for a specific part without passing vacuum_level on every grasp call.

UNITS

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

The Skill

gripper.set_vacuum_level(vacuum_level=60, 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 setting the vacuum level of a suction gripper.

Supports Piab grippers, on real hardware or simulated in Isaac Sim. Also
supported for the simulation-only custom.SuctionGripper, which takes the same
vacuum_level/unit arguments but only stores the value for later readback -
the simulation does not model vacuum level, so the grip is unaffected.

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

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:
    """Sets the vacuum level of a Piab gripper to 60%."""

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

    # ==================== Run Skill ===========================================
    try:
        gripper.connect(ip=ip, serial_port=serial_port, protocol=protocol)
        gripper.set_vacuum_level(vacuum_level=60, unit="percentage")
        logger.success(f"Vacuum level set; effective: "
                       f"{gripper.get_vacuum_level(unit='percentage')}%")
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        gripper.disconnect()


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

Parameter	Type	Default	Description
vacuum_level	int	-	Desired vacuum level, 0-100 (max 100 kPa).
unit	str	"percentage"	Unit of vacuum_level. Accepts "percentage" or "kPa".

Returns

This skill returns nothing (None). On Piab, the value is applied to the backend immediately - it is not just cached for the next grasp call - and the default level after connect is 50%. On custom.SuctionGripper, the value is only stored for Get Vacuum Level to read back; the simulation has no default until this is called at least once.

Raises

Exception	Condition
TypeError	vacuum_level is not an integer, or unit is not a string
ValueError	vacuum_level is outside 0 to 100, or unit is unsupported
ConnectionError	The backend is not connected
RuntimeError	The command fails

How to Tune the Parameters

Set vacuum_level lower for delicate or porous parts (cardboard, foam, unsealed containers), where too much vacuum can crush the surface or never reach a stable seal because air leaks through the material; set it higher for heavy, rigid, non-porous parts that need a stronger hold to survive acceleration during a move. Because set_vacuum_level applies immediately rather than being cached, changing it mid-sequence takes effect on the very next grasp call.

Where to Use the Skill

• Part-specific tuning - Set a lower vacuum level for delicate or porous parts, higher for heavier or non-porous ones
• Session setup - Configure the level once after connect if every grasp in the script uses the same part

When Not to Use the Skill

Do not use Set Vacuum Level when:

• The gripper is not connected - always call connect before issuing commands
• Vacuum level varies per pick - pass vacuum_level directly to Grasp instead of reconfiguring the session default each time