🚨 错误码与异常
结论: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 | 过电流 | 降低夹持力/负载,排除卡阻;清错后重试 |
0xB | MOS 过温 | 降低占空/负载,等待散热;清错后重试 |
0xC | 电机线圈过温 | 降低负载,等待冷却;清错后重试 |
0xD | 通讯丢失 | 检查 CAN 线、供电、终端电阻和波特率 |
0xE | 过载 | 降低 force/负载,排除机构卡阻;清错后重试 |
| 其他 | 未知状态(0x..) | 记录原始码并联系技术支持 |
💡 查看方式
diagnose会直接显示状态: 过载(0xE);代码中可读取g.state.err、g.state.error,或用error_text(code)转中文。
🛠️ 故障恢复
-
停止动作:在
teach输入d,或代码中调用g.stop(disable=True)。 -
查看状态:
python -m VT_TacGripper.tools.diagnose --sn <SN> -
清除故障:
teach中输入r:清错 + 重新使能 + 保持;- 代码中调用
g.clear_error(),成功后再g.enable()。
-
排除原因:降低负载/夹持力,检查供电、CAN 线、散热和机构卡阻。
-
重复出现:断电重启后仍出现同一故障码,请联系技术支持,并附上 SN、CAN ID、故障码和复现步骤。
⚠️ 过温/过载后不要立即反复使能 先降低负载并等待温度下降,再清错;连续触发保护可能损坏电机或驱动。
🧰 CLI 退出码
CLI 工具在终端输出的中文提示是主要信息;退出码用于脚本判断:
| 退出码 | 含义 |
|---|---|
0 | 成功 |
1 | 执行失败、用户取消或未找到设备 |
2 | 参数/前置条件不满足、通信检查不通过 |
130 | 用户按 Ctrl-C 中断 |
3 | configure_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。