故障排查

SDK 安装失败

确认 Python 版本 ≥ 3.10
使用 pip install --upgrade pip 更新 pip
遇到编译错误时，尝试安装预编译的 wheel 包

脚本运行中抛出异常

异常消息	原因	处理
`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` 确认当前生效值
`ValueError`	向 Wuji Hand 2 的 `hand.joint(index)` 传入超出 `0..=19` 范围的索引	传入 0 到 19 的整数。SDK 会在创建关节句柄前抛出 `ValueError`

订阅数据延迟或丢帧

检查网络带宽和延迟（有线连接优于 WiFi）
减少同时订阅的数据流数量
确认回调函数中没有耗时操作阻塞接收
Wuji Hand 2 可订阅 hand.joint_diagnostics()，其帧级 comm 摘要能定位丢帧发生在哪一段：e2e_lost 是网络丢帧，sdk_dropped 是消费端处理不及时。字段定义见 Wuji Hand 2 SDK 接口参考 — Hand2CommSummary

SDK 版本与固件版本不兼容

查看 SDK 版本发布记录了解版本对应关系
建议 SDK 和固件保持同一主次版本（如均为 0.6.x）

升级 SDK 后 `tactile_binary` 或 `tactile_residual` 不发数据

Wuji Glove 触觉数据布局调整为 24×31（原 24×32）。SDK 按新布局校验入帧尺寸与接触标定模型，二者任一仍为 24×32 即停发对应数据流，避免错位输出。恢复路径：将 Wuji Glove 固件升级至支持 24×31 的版本，并按新布局重做触觉接触标定。详见 Wuji Glove 触觉数据 reference。

设备日志导出

Flash 日志导出

Wuji SDK v2026.8.31 提供 Wuji Hand 2 Flash 历史日志导出接口。调用 export_flash_logs() 后，当前线程会一直等待，直到设备日志读取完成并写入文件，函数才会返回包含 path 和 frames 的字典。导出文件采用 JSONL 格式，每行是一条 JSON 记录。Wuji Hand 2 固件 v2.6.0 及以上支持同一设备的并发导出，较早固件请依次导出。对于不支持 Flash 日志的固件或协议版本，导出会提示不支持：

result = hand.export_flash_logs()
print(result["path"], result["frames"])

path 是导出文件路径，frames 是成功解码的日志帧数。向 out_dir 传入目录路径可指定保存位置。未传入时，文件保存到 ~/.wuji/logs/flash_<serial>_<date>_<time>.jsonl。同一秒内生成的文件会增加编号后缀，不会覆盖已有文件。

设备日志环为空时，frames 为 0。此时生成的空文件仍表示导出成功。

Python 导出异常如下：

WujiException 表示设备正由其他导出任务占用、设备或固件不支持当前协议、出现连接或 flash-log 协议错误，或多次重试仍无法完成。
NodeOfflineError 表示目标节点离线。
OSError 表示 SDK 无法创建或写入结果文件。

导出失败时不会生成结果文件。C SDK 的调用方式、状态码和结果释放方式详见 Wuji Hand 2 Flash 日志导出。

获取技术支持

联系 support@wuji.tech 时，请附上设备日志（若可获取）、设备序列号、固件版本、SDK/Studio 版本、操作系统和版本，以及问题复现步骤。不同设备的日志导出方式不同，请先查看设备日志。