SDK 安装失败
- 确认 Python 版本 ≥ 3.10
- 使用
pip install --upgrade pip更新 pip - 遇到编译错误时，尝试安装预编译的 wheel 包
脚本运行中抛出异常
订阅数据延迟或丢帧
- 检查网络带宽和延迟（有线连接优于 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 日志的固件或协议版本，导出会提示不支持：
path 是导出文件路径，frames 是成功解码的日志帧数。向 out_dir 传入目录路径可指定保存位置。未传入时，文件保存到 ~/.wuji/logs/flash_<serial>_<date>_<time>.jsonl。同一秒内生成的文件会增加编号后缀，不会覆盖已有文件。
设备日志环为空时，frames 为 0。此时生成的空文件仍表示导出成功。
Python 导出异常如下：
WujiException表示设备正由其他导出任务占用、设备或固件不支持当前协议、出现连接或 flash-log 协议错误、多次重试仍无法完成，或 SDK 无法创建或写入结果文件。NodeOfflineError表示目标节点离线。