文档阅读指引

版本发布记录

Wuji SDK 各版本更新内容与变更说明

产品介绍

Wuji SDK 简介、核心功能、系统要求与安装

• 概述
  产品定位、支持设备与核心功能
• 使用前准备
  系统要求、Python 与 C SDK 安装

快速开始

3 个完整示例快速上手

• 回调订阅（0.subscribe_callback.py）
  使用回调函数接收触觉数据
• 异步订阅（1.subscribe_async.py）
  使用 async/await 接收触觉数据
• 数据录制（2.recording.py）
  录制多通道传感器数据到 MCAP 文件
• Wuji Hand 上手
  通过 wuji-sdk 连接 Wuji Hand 并做一次握拳动作

设备发现与连接

发现、连接与管理 Wuji 设备

• 设备发现
  扫描局域网内的 Wuji 设备
• 连接设备
  自动 / SN / 地址 / USB / 手性五种连接方式与 ConnectOptions
• 多设备管理
  同时操作多个设备
• 断开连接
  断开单个设备或全部设备

数据订阅

订阅设备数据流

• 订阅模式
  异步接收、同步非阻塞、回调接收三种模式
• 关闭订阅
  取消订阅与资源释放
• 跨设备合并订阅
  订阅来自所有设备合并的全局资源
• 可用数据流
  各设备支持的数据流，链接到设备文档
• Wuji Hand 数据订阅
  订阅 20 关节状态、实时控制、电机力矩上限、触觉手套数据

数据录制

录制多通道传感器数据到 MCAP 文件

• 压缩选项
  LZ4、Zstd 或不压缩
• 录制全局资源
  同时录制跨设备合并资源与设备数据
• 暂停与恢复
  暂停和恢复录制，不丢失会话状态
• 分集切换
  将连续采集拆分为多个文件
• 质量监控
  实时监控丢帧率、帧间抖动与同步偏移
• 录制摘要
  录制结束时返回汇总统计
• 示例
  基础和完整录制示例

数据结构参考

通用数据类型字段定义

• 通用类型
  FrameHeader、Vector3、Quaternion、Pose
• 坐标变换
  FrameTransform、FrameTransforms
• 录制类型
  TopicRecorder、RecordingHandle、RecordingSummary、QualityMetrics
• Wuji Hand 类型
  HandJointState、HandJointCommand、TactileGloveFrame

设备参数与标定

读写设备参数、用户隔离、标定流程入口

• 参数读取
  序列号、固件版本、IP 地址等
• 参数写入
  修改 IP、端口等可写参数
• 设备操作
  参数持久化、重启等设备操作因产品而异，详见对应设备文档
• SDK 用户管理
  按操作者隔离 SDK 本地参数与标定文件
• 标定
  标定结果按 SDK 用户 × 设备序列号双重隔离，流程见各产品文档
• 可用参数
  各设备支持的参数，链接到设备文档
• 查看所有资源
  列出设备上的资源、参数和 Topic

时间同步与时间戳

设备时间戳含义、PTP-like 同步机制与手动同步 API

• 数据帧时间戳
  FrameHeader.timestamp_us 同步前后语义
• 同步机制
  NTP 四时间点客户端授时流程
• 自动同步
  ConnectOptions.auto_time_sync_interval_ms 配置
• 手动同步
  sync_time() API 与 TimeSyncResult 返回字段
• 时间戳单调性
  跨同步保证严格单调递增，可直接用于时序排序
• 同步精度
  round_trip_us 反映同步质量

最佳实践

错误处理、重连、多设备与日志

• 错误处理
  WujiException 8 种错误类型
• 重连策略
  指数退避自动重连
• 多设备协调
  并行操作多台设备的模式与注意事项
• 日志控制
  6 个日志级别配置
• 设备日志
  读取设备端 defmt 日志
• 录制最佳实践
  分集管理、质量监控与存储建议
• 性能优化
  减少订阅数量、及时关闭不需要的订阅

故障排查

按问题类型分类的排查指南

• 安装
  SDK 安装失败处理
• 运行异常
  异常消息对照表与数据延迟/丢帧排查
• 兼容性
  SDK 与固件版本兼容性
• 技术支持
  联系技术支持解决未解问题

C 接口参考

C 接口参考与 Python 等价对照

• 初始化与约定
  wuji_init/shutdown + 返回值分类 + 资源释放函数
• 设备发现与连接
  wuji_scan / wuji_connect / 连接目标与参数
• 订阅设备数据流
  typed wuji_<device>_subscribe_* 回调
• 订阅全局资源
  wuji_subscribe_tf / wuji_subscribe_tf_static
• 使用约束
  回调指针生命周期、不在回调内 close、wuji_last_error 同线程语义、END/ERROR 终止帧
• Python 接口对照
  Python 与 C 函数并排映射
• CMake 工程示例
  最小 cc 链接命令与 CMake 工程参考