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.

SUPPORTED GRIPPERS

Available on Piab suction grippers.

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

Example: Read the Configured Vacuum Level

"""
Piab get_vacuum_level example for the Synapse SDK.

Reads the currently configured vacuum level after connecting.

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

import argparse
from loguru import logger

from telekinesis.synapse.tools.suction_grippers import piab


def main(ip: str):
    """Read and log the currently configured vacuum level."""

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

    try:
        level = gripper.get_vacuum_level(unit="percentage")
        logger.success(f"Configured vacuum level: {level}%")
    finally:
        gripper.disconnect()


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

get_vacuum_level returns the last commanded vacuum level - it does not query a live pressure sensor. The value reflects whatever connect (default 50%), set_vacuum_level, or the most recent grasp(vacuum_level=...) call last set.

How to Tune the Parameters

Piab piCOBOT Electric

Parameter	Type	Default	Description
unit	str	"percentage"	Desired output unit. Accepts "percentage" or "kPa".

Return Value

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

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