数据结构参考

本页列出 Wuji SDK 中所有通用数据类型的字段定义。

各设备特定的数据结构详见对应设备文档：Wuji Glove SDK 数据参考。

通用类型

FrameHeader

每帧数据的头部信息。

字段	类型	说明
`seq`	`int`	递增序列号
`timestamp_us`	`int`	设备时间戳（微秒）
`frame_id`	`str`	坐标系 ID（如 `"l_wrist"`），最大 32 字符

Vector3 / Vector3F64

三维向量。Vector3 使用 f32 精度，Vector3F64 使用 f64 精度（用于 IMU 数据，ROS 兼容）。

字段	类型	说明
`x`	`float`	X 分量
`y`	`float`	Y 分量
`z`	`float`	Z 分量

Quaternion

f64 精度的旋转四元数。

字段	类型	说明
`x`	`float`	X 分量
`y`	`float`	Y 分量
`z`	`float`	Z 分量
`w`	`float`	W 分量

Pose

位姿，包含位置和朝向。

字段	类型	说明
`position`	`List[float]`	位置 [x, y, z]（米）
`orientation`	Quaternion	旋转四元数

Handedness

设备手性枚举，用于按手性连接。

值	说明
`Handedness.Left`	左手（序列号第 4 位为 `J`）
`Handedness.Right`	右手（序列号第 4 位为 `K`）

ImuData

IMU 传感器数据，遵循 ROS sensor_msgs/Imu 约定。

字段	类型	说明
`header`	FrameHeader	帧头
`orientation`	Quaternion	朝向四元数
`orientation_covariance`	`list[float]`	朝向协方差（长度 9），首元素为 `-1` 表示朝向不可用
`angular_velocity`	Vector3F64	角速度（rad/s）
`angular_velocity_covariance`	`list[float]`	角速度协方差（长度 9）
`linear_acceleration`	Vector3F64	线加速度（m/s²）
`linear_acceleration_covariance`	`list[float]`	线加速度协方差（长度 9）

Wuji Hand 2 未做板载姿态融合，订阅 hand.imu() 时 orientation_covariance[0] 始终为 -1。

坐标变换

FrameTransform

单个坐标变换。

字段	类型	说明
`timestamp_us`	`int`	时间戳（微秒）
`parent_frame_id`	`str`	父坐标系
`child_frame_id`	`str`	子坐标系
`translation`	`List[float]`	平移 [x, y, z]（米）
`rotation`	Quaternion	旋转四元数

FrameTransforms

坐标变换集合。

字段	类型	说明
`transforms`	`List[FrameTransform]`	变换列表

录制类型

完整用法和代码示例详见数据录制。

TopicRecorder

MCAP 录制会话配置器。注册通道后调用 start() 开始录制。

方法	参数	说明
`__init__()`	`compression: str = "lz4"`, `chunk_size: int = None`	创建录制器，支持 `"lz4"`、`"zstd"`、`"none"`
`record()`	`sub: Subscription`	注册订阅通道到录制器
`start()`	`output_path: str`	开始录制，返回 `RecordingHandle`

RecordingHandle

录制控制句柄，由 TopicRecorder.start() 返回。

方法	返回值	说明
`pause()`	—	暂停录制
`resume()`	—	恢复录制
`stop()`	`RecordingSummary`	停止录制，返回统计摘要
`subscribe_metrics()`	`MetricsStream`	订阅实时质量指标流
`subscribe_status()`	`StatusStream`	订阅录制状态流
`subscribe_alerts()`	`AlertStream`	订阅质量告警流

RecordingSummary

录制统计摘要，由 handle.stop() 返回。

字段	类型	说明
`total_frames`	`int`	总帧数
`file_size`	`int`	MCAP 文件大小（字节）
`duration_s`	`float`	录制时长（秒）
`quality`	`QualitySummary`	质量统计摘要

QualityMetrics

实时质量指标（5 秒滑动窗口）。

字段	类型	说明
`frame_drop_rate`	`float`	丢帧率（0.0~1.0）
`frame_jitter_us`	`float`	帧间抖动（微秒）
`sync_offset_ms`	`float`	跨通道同步偏差（毫秒）
`sync_rate`	`float`	同步成功率（0.0~1.0）
`timestamp_ns`	`int`	纳秒时间戳

QualitySummary

录制质量汇总统计。

字段	类型	说明
`total_frames`	`int`	总帧数
`dropped_frames`	`int`	丢失帧数
`frame_drop_rate`	`float`	丢帧率（0.0~1.0）
`avg_sync_offset_ms`	`float`	平均同步偏差（毫秒）
`max_sync_offset_ms`	`float`	最大同步偏差（毫秒）
`sync_rate`	`float`	同步成功率（0.0~1.0）
`spc_alert_count`	`int`	SPC 告警次数
`duration_s`	`float`	录制时长（秒）

RecordingAlert

质量告警。

字段	类型	说明
`metric`	`str`	触发告警的指标名称
`current_value`	`float`	当前测量值
`threshold`	`float`	告警阈值
`message`	`str`	可读的告警信息

RecordingStatus

录制运行状态。

字段	类型	说明
`state`	`str`	当前状态（`"recording"` 或 `"paused"`）
`frame_count`	`int`	已录制帧数
`duration_s`	`float`	已用时长（秒）

Wuji Hand 2 类型

以下列出 Wuji Hand 2 通过 wuji_sdk.WujiHand2 资源式接口暴露的关键 schema。反馈帧统一携带 FrameHeader，frame_id 为 l_wrist 或 r_wrist（由固件按设备手性填写），timestamp_us 为固件发送时刻。整手反馈帧变长，仅包含在线关节，按 nid 识别。

JointStateFrame

整手关节状态订阅帧（hand.joint_states().subscribe()）。

字段	类型	说明
`header`	FrameHeader	帧头（`seq` + `timestamp_us` + `frame_id`）
`num_joints`	`int`	帧内在线关节数（等于 `len(joints)`）
`joints`	`list[JointStateEntry]`	在线关节状态条目，变长

JointStateEntry

单关节状态。

字段	类型	说明
`nid`	`int`	节点 ID，跨帧定位关节
`position`	`float`	位置（弧度）
`velocity`	`float`	速度（rad/s）
`effort`	`float`	力矩（安培，Kt=1 占位）

JointDiagnosticsFrame

整手关节诊断订阅帧（hand.joint_diagnostics().subscribe()），与 joint_states 同源派生。

字段	类型	说明
`header`	FrameHeader	帧头
`num_joints`	`int`	帧内在线关节数
`joints`	`list[JointDiagnosticsEntry]`	在线关节诊断条目，变长
`comm`	Hand2CommSummary	帧级通信健康摘要，1 Hz 刷新

JointDiagnosticsEntry

单关节诊断快照。

字段	类型	说明
`nid`	`int`	节点 ID
`status_word`	StatusWord	解码后的状态字
`current`	`float`	相电流（A）
`vbus_v_fb`	`float`	母线电压反馈（V）
`mcu_temp_c_fb`	`float`	MCU 温度反馈（°C）
`error_code_current`	`int`	当前错误码（含 stop / warning 位），`WujiHand2.describe_error()` 解码
`comm_response_rate_pct`	`int`	该关节最近 1 秒的 RS485 总线响应率，0–100
`comm_timeout_total`	`int`	该关节累计 RS485 总线超时次数

Hand2CommSummary

帧级通信健康摘要，同时覆盖设备内部（RS485）与 SDK 本地端到端（以太网）两段。设备内部快照由 SDK 常驻任务以 1 Hz 自动刷新，无需手动轮询。

字段	类型	说明
`age_ms`	`int`	设备内部快照距今毫秒数。`65535` = 从未成功采样（设备内部字段均为 0）。`65534` = 已饱和，快照距今 ≥ 65.5 秒
`tactile_online_mask`	`int`	指尖触觉在线位图，bit0 = 拇指 … bit4 = 小指
`e2e_received`	`int`	全部订阅流累计收帧数
`e2e_lost`	`int`	以太网段经序号缺口检测出的累计丢帧数
`e2e_reordered`	`int`	累计乱序/迟到帧数
`e2e_duplicates`	`int`	累计重复帧数
`e2e_window_loss_x100`	`int`	最近 1 秒窗口丢包率，0.01% 单位
`rpc_total`	`int`	累计请求数。`0` 表示当前传输后端不提供 RPC 统计（仅 wuji-proto 后端提供，存活的 wuji-proto 连接必然已发过至少一次请求），因此此处为 0 不等于「没有发生重传」
`rpc_retries`	`int`	累计请求重传次数
`rpc_timeouts`	`int`	累计最终超时的请求数
`comm_get_failures`	`int`	累计内部快照刷新失败次数
`tactile_response_rate_pct`	`list[int]`	每指触觉（node 5）总线响应率，0–100，索引 0 = 拇指 … 4 = 小指
`tactile_timeout_total`	`list[int]`	每指触觉累计总线超时次数，同索引序
`sdk_dropped`	`int`	SDK 内部某一跳落后而丢弃的帧数（累计）——可能是你的订阅消费端，也可能是 SDK 内部的流 handler。与网络丢帧 `e2e_lost` 语义不同

设备内部字段的判读：age_ms、tactile_* 以及每关节的 comm_* 字段同属一份快照，由 SDK 以 1 Hz 刷新。固件升级或触觉标定进行期间会有意跳过这次刷新，因此短暂的陈旧值属预期状态而非故障。用 comm_get_failures 区分两种情况：age_ms 增大而 comm_get_failures 不变 = 正在有意跳过，comm_get_failures 持续增加 = 刷新本身在失败。

计数器饱和，不回绕：本表所有计数达到上限后即停在上限（16 位的 e2e_reordered、e2e_duplicates、rpc_retries、rpc_timeouts、comm_get_failures 停在 65535，32 位的停在 4294967295），不会归零重来。1 kHz 流长跑时确实可能触顶，因此应按两次采样之间的增量判读，而非当作全生命周期的绝对累计值。

StatusWord

解码后的状态字公开视图（低 16 位）。

字段	类型	说明
`ext_state`	`int`	扩展状态值（如 Init / Ready / Enabled / Stopped）
`ext_state_name`	`str`	`ext_state` 的语义名
`position_limit_active`	`bool`	位置限幅触发
`velocity_limit_active`	`bool`	速度限幅触发
`current_limit_active`	`bool`	电流限幅触发

JointCommand

单关节实时指令（publisher.send([JointCommand, ...×20]) 的入参元素）。

字段	类型	说明
`position`	`float`	目标位置（弧度）
`velocity`	`float`	目标速度（rad/s），不需要前馈传 0
`effort`	`float`	目标力矩（A），不需要前馈传 0

构造：JointCommand(position, velocity, effort)。一次 publisher.send(joints) 必须传长度恰好 20 的 list[JointCommand]，离线关节也要占位。

Wuji Hand 类型

以下列出 Wuji Hand 通过 wuji_sdk.WujiHand 暴露的关键 schema，详细字段定义见 Wuji Hand SDK 使用说明。

HandJointStates

20 关节实时状态（hand.joint_states().subscribe() 订阅帧）。手指顺序为 finger-major：{left,right}_finger{1..5}_joint{1..4}。

字段	类型	说明
`header`	FrameHeader	帧头
`position`	`list[float]`	20 关节弧度位置，始终长度 20
`velocity`	`list[float]`	角速度，未提供时长度 0
`effort`	`list[float]`	关节力矩，未提供时长度 0

{
  "header": { "seq": 42, "timestamp_us": 1709876543210, "frame_id": "" },
  "position": [0.001, -0.012, 0.087, 0.045, ...],
  "velocity": [],
  "effort": []
}

HandJointCommand

20 关节指令帧。seq 由客户端单调递增，便于接收方检测丢帧。

字段	类型	说明
`seq`	`int`	客户端自增序号
`position`	`list[float]`	目标位置，长度 20
`velocity`	`list[float]`	目标速度，可选
`effort`	`list[float]`	目标力矩，可选

TactileGloveFrame

配对触觉手套的单帧压力数据，20×31 网格。

字段	类型	说明
`handedness`	`int`	手性（0 = 左、1 = 右，注意与 `WujiHand` SDO 端编码相反）
`sequence`	`int`	帧序号
`timestamp_ms`	`int`	设备时间戳（毫秒）
`pressure`	`list[float]`	620 个 f32 压力值，按 20×31 行主序