Skip to main content

🚨 错误码与异常

结论:SDK 不会为每条错误返回统一的数字错误码。普通错误以 Python 异常文本 呈现;电机固件状态码保留在 err 中,错误消息同时给出中文说明和原始码。


👀 用户能看到什么​

场景用户看到的内容
Python API异常类型 + 中文文本,例如 RuntimeError: 未发现任何 U2CANFD 适配器
电机故障MotorFaultError,消息含电机故障中文名和原始码,例如 过载(0xE)
模式错误MotorModeError,说明当前模式和接口要求的模式
diagnose位置、速度、力矩、温度,以及 状态: 过载(0xE);实时数据需要 --enable
teach操作成功/失败提示;p 显示位置、力矩、使能状态和模式
CLI中文提示 + 进程退出码(供脚本判断)

普通 RuntimeError、TimeoutError、ValueError 没有额外数字错误码,直接根据异常文本处理即可。


🧾 常见报错与处理​

报错/现象常见原因处理
未发现任何 U2CANFD 适配器USB 未连接、供电异常、udev 权限不足检查 USB/供电;运行 install_udev --status;重新拔插后 list_devices
配置中不存在 SN=...首次使用,配置中没有该 SN提供 --product-model,或使用 auto_register=True;先运行标定/注册
尚未标定开闭限位未标定或配置丢失运行 calibrate,或手动 teach 记录 o/c
电机未使能或无反馈供电、接线、通道或模式异常检查电源和 CAN 接线;运行 diagnose;teach 中输入 e/r
模式不匹配:...接口模式与当前控制模式不一致使用构造时的 control_mode;固件不支持 POS_FORCE 时改用 pos_vel
故障:过载(0xE)夹持力过大、机构卡住或长时间顶住限位降低 force、移除阻挡;r 或 clear_error() 后重新使能
故障:欠压(0x9) / 超压(0x8)电源电压异常检查电源电压和线缆;稳定后清错、重新使能
故障:通讯丢失(0xD)CAN 线松动、供电中断、波特率不匹配检查 CANH/CANL、终端电阻、供电;运行 configure_motor
移动到 ... 超时目标受阻、速度过低、反馈丢失检查行程和机构;提高速度或超时;确认 state.age 正常
标定未找到边界或未达力阈值机构卡住、软胶夹头、扫描力不足检查机构;用 --dry-run 观察;必要时提高 --force
POS_VEL 下 force 被忽略POS_VEL 协议没有力参数需要力上限时使用 POS_FORCE;否则忽略该警告
同一进程关闭后无法重新打开厂商运行库关闭路径限制重启进程;不要在同一进程反复关闭/打开同一适配器
同时运行 teach 和程序失败同一适配器被两个进程占用只保留一个控制进程;关闭另一个程序后重试

🔢 电机状态码​

电机反馈中的 MotorState.err 是原始固件状态码。0x0 和 0x1 是正常状态,其余为保护/异常状态。

码中文含义与处理
0x0失能正常状态,电机未使能
0x1使能正常状态,电机已使能
0x2输出轴编码器未校准电机编码器需要校准/检修;请联系技术支持
0x8超压供电电压过高;检查电源和线缆
0x9欠压供电电压过低或电源跌落;检查供电
0xA过电流降低夹持力/负载,排除卡阻;清错后重试
0xBMOS 过温降低占空/负载,等待散热;清错后重试
0xC电机线圈过温降低负载,等待冷却;清错后重试
0xD通讯丢失检查 CAN 线、供电、终端电阻和波特率
0xE过载降低 force/负载,排除机构卡阻;清错后重试
其他未知状态(0x..)记录原始码并联系技术支持

💡 查看方式 diagnose 会直接显示 状态: 过载(0xE);代码中可读取 g.state.err、g.state.error,或用 error_text(code) 转中文。


🛠️ 故障恢复​

  1. 停止动作:在 teach 输入 d,或代码中调用 g.stop(disable=True)。

  2. 查看状态:

    python -m VT_TacGripper.tools.diagnose --sn <SN>
  3. 清除故障:

    • teach 中输入 r:清错 + 重新使能 + 保持;
    • 代码中调用 g.clear_error(),成功后再 g.enable()。
  4. 排除原因:降低负载/夹持力,检查供电、CAN 线、散热和机构卡阻。

  5. 重复出现:断电重启后仍出现同一故障码,请联系技术支持,并附上 SN、CAN ID、故障码和复现步骤。

⚠️ 过温/过载后不要立即反复使能 先降低负载并等待温度下降,再清错;连续触发保护可能损坏电机或驱动。


🧰 CLI 退出码​

CLI 工具在终端输出的中文提示是主要信息;退出码用于脚本判断:

退出码含义
0成功
1执行失败、用户取消或未找到设备
2参数/前置条件不满足、通信检查不通过
130用户按 Ctrl-C 中断
3configure_motor 的打开/扫描失败

💡 脚本建议 一般只需判断 0 / 非 0;需要区分具体原因时,根据工具和中文提示处理。


🧾 代码中获取电机错误码​

from VT_TacGripper import MotorFaultError, VTacGripper, error_text

try:
with VTacGripper("<SN>", config_path="./devices.json") as g:
g.enable()
g.move(40, block=True)
except MotorFaultError as exc:
print(f"SN={exc.sn} CAN ID={exc.can_id}")
print(f"错误码=0x{exc.err:X} 文本={error_text(exc.err)}")
print(exc)

普通异常直接读取文本:

try:
...
except Exception as exc:
print(f"失败:{exc}")

状态快照:

print(g.state.err)      # 原始码,例如 14(0xE)
print(g.state.error) # 中文,例如 "过载"
print(g.state.faulted) # 是否保护故障

💡 实时状态需要使能 g.state 中的位置、速度、力矩和温度来自反馈帧;未使能时没有实时数据。诊断温度请使用 diagnose --enable,诊断结束会自动失能。

💡 清错后重新使能 g.clear_error() 只负责清除故障锁存,不会自动使能;清错成功后调用 g.enable(),或直接使用 teach 的 r。