Skip to main content

API Reference

Creating a connection​

# Remote connection: returns XenseTCPGripper
remote_gripper = XenseGripper.create(mac_addr="d672f584b17a")

# Local serial connection: returns XenseSerialGripper
local_gripper = XenseGripper.create(port="COM3")

Providing mac_addr creates a remote XenseTCPGripper. When mac_addr is omitted, port is required for the local serial connection; otherwise, the current implementation raises KeyError because port is missing.

Methods available on both implementations​

MethodPurpose
set_position(position, vmax=80.0, fmax=27.0)Non-blocking position command, 0–85 mm
set_position_sync(...)Command a position and wait for arrival; successful return values vary by implementation, and timeout raises TimeoutError
set_speed(velocity, fmax=27)Positive closes, negative opens, zero stops
get_gripper_status()Return position, velocity, force, and temperature
set_led_color(r, g, b)Set RGB LED channels in the 0–255 range
calibrate()Send a calibration or reset command; the exact behavior depends on the local serial implementation or remote device service
release()Close the serial or DDS client and release resources

Methods available only on remote XenseTCPGripper​

MethodPurpose
open_gripper() / close_gripper()Move to 85 mm / 0 mm
set_control_param(stiffness, kp, ki, kd)Configure the SAFE-mode controller
mode(control_mode, serial_number=...)Temporarily switch mode with a context manager
enable_mode(...) / disable_mode()Manually enable or disable a mode

Local XenseSerialGripper instances do not provide mode(), SAFE mode, open_gripper(), or close_gripper(). When entering SAFE mode on a remote instance, explicitly pass serial_number. Do not rely on serial_number=None to select a sensor automatically; the current selection logic may raise IndexError when only one sensor is discovered.

Position and velocity limits​

gripper.set_position(position=50, vmax=120, fmax=25)
with gripper.mode(XenseGripper.ControlMode.SPEED):
    gripper.set_speed(-40)
    time.sleep(1)
    gripper.set_speed(0)

The position range is 0..85 mm, the vmax range for position commands is 0..350 mm/s, and the fmax range is 0..60 N. Remote velocity-command limits depend on the compute-unit service and device firmware.

Reading status​

status = gripper.get_gripper_status()
if status:
    print(status["position"], "mm")
    print(status["velocity"], "mm/s")
    print(status["force"], "N")
    print(status["temperature"], "°C")