核心对象与生命周期 | Qnbot Docs Center

对象层级

Python SDK 的常用对象按以下层级组织：

Sdk                              # SDK 的统一入口
└── Glove                        # 管理所有已配置的手套
    └── device() → GloveDevice  # 选择一只实体手套及其功能
        ├── capture_status()     # 查询采集准备情况
        ├── start_capture()      # 开始采集
        ├── start_calibration()  # 使用已完成的采集开始标定
        ├── pose()               # 读取原始姿态
        ├── imu()                # 读取 IMU 数据（实验性功能）
        ├── skeleton()           # 读取 OpenXR 骨骼数据
        │   ├── joint_angles()   # 读取关节角
        │   └── pose()           # 读取骨骼节点姿态
        ├── output()             # 读取灵巧手输出
        ├── calibration_status() # 查看是否需要标定
        ├── capture_progress()   # 查看采集进度
        ├── capture_control()    # 确认、跳过、重试或取消采集
        ├── calibration_progress() # 查看标定进度
        ├── status()             # 查看设备连接状态
        └── haptics()            # 控制指尖震动

Sdk：完整的 SDK 对象，用于统一启动、停止、运行和查看健康状态。
Glove：所有已配置手套的操作入口，用于管理手套和选择设备。
GloveDevice：表示一只实体手套，提供单设备控制和数据读取；采集、标定也由选定的设备执行。

对象关系：Glove 不等同于一只手套。一个 Glove 可以管理多只 GloveDevice；一只 GloveDevice 也可以通过多个 target 驱动多个灵巧手或仿真目标。

生命周期

Sdk 管理已配置的全部设备和功能；只使用手套能力时，通过 sdk.glove() 取得统一操作入口：

from qnbot_sdk import Sdk
from qnbot_sdk.glove import GloveConfig

sdk = Sdk(devices=(GloveConfig(),))  # 创建：返回后即可选择设备，此时尚未连接
glove = sdk.glove()                  # 取得手套入口；只操作一只设备时用 device()

glove.start()                        # 启动：建立设备连接并启动所需数据流
try:
    glove.run_forever()              # 运行：持续接收数据
except KeyboardInterrupt:
    pass
finally:
    glove.close()                    # 关闭：回收订阅

创建：Sdk(...) 返回后即可选择设备和准备读取。
启动：功能配置与 callback 订阅在 start() 之前完成；start() 建立设备连接并启动所需数据流。
运行：数据来源与读取方式见数据来源与读取方式，推进 SDK 调度的三种运行方式见运行方式。
停止与关闭：stop() 停止运行并断开设备，close() 回收订阅；后台模式先调用 request_stop()。

Sdk、Glove 与 GloveDevice 各有自己的生命周期方法：

对象	作用范围
`Sdk`	完整 SDK：已配置的全部设备和功能
`Glove`	仅手套能力
`GloveDevice`	单个设备：`start()`、`stop()`、`health()` 和 `close()`

单设备 close() 释放该设备作用域，关闭后不能再启动；glove.close() 释放全部手套资源。方法与返回值见 GloveDevice 方法表。