Gripper Get Vacuum Level

SUMMARY

Get Vacuum Level returns the last commanded vacuum level of a suction gripper.

This skill is used to confirm the currently configured grip strength, for example before logging or before a conditional grasp decision.

UNITS

Returns the vacuum level (0-100) in the requested vacuum unit - "percentage" (default) or "kPa" (max 100 kPa). The scales are numerically identical.

The Skill

level = gripper.get_vacuum_level(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 reading the last commanded 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 reports back
whatever was last passed to set_vacuum_level() - the simulation does not
model an actual vacuum level, and returns None until set_vacuum_level() has
been called at least once.

Usage:
    python get_vacuum_level.py --ip <ROBOT_IP>
    python get_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:
    """Reads the last commanded vacuum level of a Piab gripper in both units."""

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

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


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Piab gripper get 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
unit	str	"percentage"	Desired output unit. Accepts "percentage" or "kPa".

Returns

Type	Description
int | None	The last commanded vacuum level in the requested unit, or None if no vacuum level has ever been set.

Raises

Exception	Condition
TypeError	unit is not a string
ValueError	unit is unsupported

Where to Use the Skill

• Pre-grasp verification - Confirm the configured level matches expectations before a critical pick
• Logging - Record the vacuum level used for each pick in a data pipeline

When Not to Use the Skill

Do not use Get Vacuum Level when:

• You need to detect whether a part is held - use Get Part Present instead; this skill only reports the configured setpoint, not live grasp status