故障排查
安装
Q: SDK 安装失败？
- 确认 Python 版本 ≥ 3.10
- 使用
pip install --upgrade pip更新 pip - 遇到编译错误时，尝试安装预编译的 wheel 包
运行异常
Q: SDK 脚本运行中抛出异常？
| 异常消息 | 原因 | 处理 |
|---|---|---|
DeviceNotFound | 设备未发现 | 检查物理连接和网络 |
Disconnected | 连接中断 | 检查线缆，重新连接 |
ConnectionTimeout | 连接超时 | 检查网络连接或增加 timeout_ms 参数 |
OperationTimeout | 操作超时 | 增加 timeout_ms 参数或检查设备状态 |
StreamClosed | 订阅流关闭 | 设备可能断开，重新连接 |
SessionAlreadyExists | 同一设备已建立会话 | 沿用既有句柄，或先 disconnect() 后重连 |
| 连接 Wuji Hand 报错并列出未响应的关节 | 手未就绪，部分关节没有应答 | 检查供电与线缆，确认关节上电后重连。Python SDK 与 C SDK 表现一致 |
ValueError | Wuji Hand 2 写入 hand.mit_params()（kp / kd 均要求非负）、hand.effort_limit()（非负）或 joint_command 实时指令时传入 NaN / Inf / 负值 | 在写入前过滤非法值 |
ValueError | Wuji Hand 2 写入 hand.effort_limit() 的值超出设备当前允许上限，设备拒绝该次写入 | 调低写入值。上限由固件设定，读回 effort_limit 确认当前生效值 |
Q: SDK 订阅数据延迟或丢帧？
- 检查网络带宽和延迟（有线连接优于 WiFi）
- 减少同时订阅的数据流数量
- 确认回调函数中没有耗时操作阻塞接收
- Wuji Hand 2 可订阅
hand.joint_diagnostics()，其帧级comm摘要能定位丢帧发生在哪一段：e2e_lost是网络丢帧，sdk_dropped是消费端处理不及时。字段定义见 Wuji Hand 2 类型 — Hand2CommSummary
兼容性
Q: SDK 版本与固件版本不兼容？
- 查看 SDK 版本发布记录 了解版本对应关系
- 建议 SDK 和固件保持同一主次版本（如均为 0.6.x）
Q: 升级 SDK 后 tactile_binary 或 tactile_residual 突然不发数据？
Wuji Glove 触觉数据布局调整为 24×31（原 24×32）。SDK 按新布局校验入帧尺寸与接触标定模型，二者任一仍为 24×32 即停发对应数据流，避免错位输出。恢复路径：将 Wuji Glove 固件升级至支持 24×31 的版本，并按新布局重做触觉接触标定。详见 Wuji Glove 触觉数据 reference。
技术支持
Q: 如何获取技术支持？
请联系 support@wuji.tech，并附上以下信息：
- 设备序列号（SN）
- 固件版本
- SDK/Studio 版本
- 操作系统和版本
- 问题复现步骤