📚 API 文档
本页只覆盖高层控制类 VTacGripper。Bus、OpenDevice、DmMotor 等底层接口属于进阶用法,不在本手册展开。
💡 阅读前提 示例假设夹爪已经完成标定,并且
devices.json中存在对应 SN 的记录。未标定时,position、move()、open()、close()等行程接口会报错。
🧭 导入
from VT_TacGripper import VTacGripper
VTacGripper 是上下文管理器:with 退出时自动调用 release()。
🏗️ 构造
📝 语法
VTacGripper(
sn=None,
*,
bus=None,
store=None,
config_path=None,
product_model=None,
control_hz=None,
travel=None,
control_mode="pos_force",
auto_register=False,
auto_enable=False,
channel=0,
)
🔧 参数
| 参数 | 默认 | 说明 |
|---|---|---|
sn | None | 适配器 SN;None 时自动检测(仅单适配器可用,多适配器会报错) |
bus | None | 复用的总线对象;一般不需要传 |
store | None | 复用的配置存储对象;一般不需 要传 |
config_path | None | 一机一码配置路径;None 使用 ~/.config/vitai-sdk/devices.json |
product_model | None | VT 产品型号;首次注册必需,之后从配置读取 |
control_hz | None | 本次运行的控制频率覆盖值;非默认值会写入 overrides |
travel | None | 本次运行的额定行程覆盖值;非默认值会写入 overrides |
control_mode | "pos_force" | 控制模式:"pos_force"(默认)或 "pos_vel" |
auto_register | False | 配置中无该 SN 时是否自动注册 |
auto_enable | False | 构造完成后是否立即使能并保持当前位置;默认不使能 |
channel | 0 | CAN 通道号 |
⚠️ 构造行为
- 按 SN 读取配置,打开适配器并读取实机量程。
- 按
product_model推导 geometry/电机型号;实机与产品型号不一致时直接报错(S/L 可校验;S/Slim 依靠标定跨度检查)。 - 显式写入并读回校验
control_mode;固件不支持时抛MotorModeError,不会静默回退。 - 默认不使能;构造后需调用
enable(),或传auto_enable=True立即使能并保持。 - 配置中不存在 SN 且未开启
auto_register时,会抛出RuntimeError。
💡 示例
from VT_TacGripper import VTacGripper
with VTacGripper("<SN>", config_path="./devices.json") as g:
g.enable()
try:
print(g.sn, g.unit, g.is_calibrated)
finally:
g.disable()
首次注册:
with VTacGripper(
"<SN>",
product_model="VT-TacGripper-85-S",
config_path="./devices.json",
auto_register=True,
) as g:
g.enable()
...
🎛️ 属性
| 属性 | 类型 | 说明 |
|---|---|---|
g.sn | str | 适配器 SN |
g.unit | str | 行程单位:mm 或 deg |
g.is_calibrated | bool | 是否已有张开/闭合限位 |
g.state | MotorState | 最新反馈快照,字段见下方 |
g.age | float | 最近反馈年龄(秒);从未收到反馈时为 inf |
g.error() | str | 当前固件状态中文文本,如 使能、过载 |
g.mapping() | RangeMap | 当前行程↔弧度映射;未标定时抛 RuntimeError |
g.open_value | float | 张开位行程值(平行 0 mm;圆弧为最大角度) |
g.close_value | float | 闭合位行程值(平行为最大行程;圆弧 0°) |
g.position | float | 当前行程位置(mm 或 deg);未标定时抛 RuntimeError |
g.position_rad | float | 当前电机位置(rad) |
g.velocity | float | 当前电机速度(rad/s) |
g.torque | float | 当前电机力矩(Nm) |
g.control_mode | ControlMode | 构造时确认的控制模式 |
g.enabled | bool | 电机当前是否处于使能状态 |
g.is_online(timeout=0.5) | bool | 最近反馈是否在 timeout 秒内 |
🔌 使能、失能与关闭
enable() / disable()
g.enable(hold=True) # 使能;默认保持当前位置
g.disable() # 显式失能
| 方法 | 说明 |
|---|---|
g.enable(hold=True) | 使能电机;hold=True 时随后保持当前位置。无反馈导致无法保持时会抛异常 |
g.disable() | 失能电机;不会自动重新使能 |
g.enabled | 当前软件记录的使能状态 |
💡 显式生命周期 构造默认不使能。
move/open/close/jog/hold/move_rad在未使能时会抛出RuntimeError;先调用g.enable()。release()不改变使能状态,需要失能时显式调用g.disable()。