API 参考

创建连接

# 远程连接：返回 XenseTCPGripper
remote_gripper = XenseGripper.create(mac_addr="d672f584b17a")

# 本地串口连接：返回 XenseSerialGripper
local_gripper = XenseGripper.create(port="COM3")

提供 mac_addr 时创建远程 XenseTCPGripper；不提供 mac_addr 时必须通过 port 指定串口，否则当前实现会因缺少 port 而抛出 KeyError。

两种实现均提供的方法

方法	说明
set_position(position, vmax=80.0, fmax=27.0)	非阻塞位置控制，position 范围 0–85 mm
set_position_sync(...)	位置控制并等待到位；成功返回值因实现不同可能不同，超时抛出 TimeoutError
set_speed(velocity, fmax=27)	速度控制；正值闭合、负值打开
get_gripper_status()	返回 position、velocity、force、temperature
set_led_color(r, g, b)	设置 RGB LED，通道范围 0–255
calibrate()	发送校准或复位命令；具体行为取决于本地串口实现或远程设备服务
release()	关闭串口或 DDS 客户端并释放资源

仅远程 XenseTCPGripper 提供的方法

方法	说明
open_gripper() / close_gripper()	移动到 85 mm / 0 mm
set_control_param(stiffness, kp, ki, kd)	SAFE 模式下设置控制器参数
mode(control_mode, serial_number=...)	以上下文管理器临时切换模式
enable_mode(...) / disable_mode()	手动启用/关闭模式

本地 XenseSerialGripper 没有 mode()、SAFE、open_gripper() 或 close_gripper()。远程实例进入 SAFE 模式时应显式传入 serial_number；不要依赖 serial_number=None 自动选择传感器，当前自动选择逻辑在仅发现一个传感器时可能抛出 IndexError。

位置与速度边界

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)    # 停止

位置范围为 0..85 mm，位置指令的 vmax 范围为 0..350 mm/s，fmax 范围为 0..60 N。远程速度指令的限制取决于算力板服务和设备固件。

读取状态

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