读取原始数据 | Qnbot Docs Center

这一章的数据由设备固件直接产出，不需要算法包：start() 之后，姿态随有效设备帧发布；设备帧包含 IMU 数据时，也会发布 IMU。三种运行方式不会生成这些数据或改变发布频率。数据来源的完整说明见数据来源与读取方式。

手套姿态

device.pose() 应在 SDK 创建并选择设备后取得。持续处理姿态时，把解析逻辑放入 callback，并在启动前注册：

from threading import Event

from qnbot_sdk import Sdk
from qnbot_sdk.glove import GloveConfig

def on_pose(sample):
    pose = sample.value
    print(pose.meta.source)
    print(pose.payload.root_pose.position)
    print(pose.payload.root_pose.quaternion_xyzw)
    print(pose.payload.fingertip_world)
    print(pose.payload.fingertip_local)
    print(pose.payload.raw_valid_mask)
    print(pose.payload.held_mask)
    print(pose.payload.quality_flags)

sdk = Sdk(devices=(GloveConfig(),))
glove = sdk.glove()
try:
    glove.device().pose().subscribe(on_pose)
    glove.start()
    Event().wait()
finally:
    glove.close()

按用途选择读取路径：

想做什么	读取路径
按帧来源分流（多只手套或多路输入）	`meta.source`
放置手腕或掌心	`payload.root_pose`
把虚拟手放到世界坐标、驱动外部骨架	`payload.fingertip_world`
相对手腕做重定向或手内计算	`payload.fingertip_local`
跳过原始数据无效的手指	`payload.raw_valid_mask`
识别沿用上一条有效值的手指	`payload.held_mask`
判断整帧质量	`payload.quality_flags`

完整字段、类型和可空行为见 GlovePose 和 GloveFeaturePayload。

IMU（实验性功能）

device.imu() 用于读取 USB 串口设备在数据 JSON 中提供的 GloveImu 原始计数：

from threading import Event

from qnbot_sdk import Sdk
from qnbot_sdk.glove import GloveConfig

def on_imu(sample):
    imu = sample.value
    print(imu.payload.valid)
    print(imu.payload.gyroscope_raw)
    print(imu.payload.accelerometer_raw)

sdk = Sdk(devices=(GloveConfig(),))
glove = sdk.glove()
try:
    glove.device().imu().subscribe(on_imu)
    glove.start()
    Event().wait()
finally:
    glove.close()

gyroscope_raw 与 accelerometer_raw 都是三个有符号 16 位整数，依次对应设备协议中的三个轴。SDK 不对这些数据进行单位换算、标定或姿态融合。valid 为 False 时仍会保留并发布原始计数，可根据实际用途决定是否使用。当前只支持有线 USB 串口 JSON 中的 IMU；无线接收器的二进制 IMU 不在本版本支持范围内。

按用途选择读取路径：

想做什么	读取路径
判断这一次读数能不能用	`payload.valid`
取三轴角速度原始计数	`payload.gyroscope_raw`
取三轴加速度原始计数	`payload.accelerometer_raw`

完整字段、类型和可空行为见 GloveImu 和 GloveImuPayload。

设备状态

device.status() 也是设备直接产出的读数，不经过算法处理：是否已连接、数据是否过期、最近一次错误和重连次数。字段含义和诊断用法见诊断与错误。