API 参考 | Qnbot Docs Center

显式 close() 是主要清理方式，析构只提供不抛异常的最后保障。

Glove::close() 会回收仍然有效的 subscription。应用只需让对应的 Subscription 对象保持存活，最终关闭前不需要逐个取消订阅。只有所属对象继续运行、但需要提前停止单个 callback 时，才显式调用 subscription.unsubscribe()。

不要从该 subscription 自己的 callback 同步调用 unsubscribe() 或销毁它。

有限任务在正常路径结束时调用 Glove::close()；后台模式先调用 request_stop() 和 join()。Glove::close() 停止并关闭全部已配置手套，Sdk::close() 关闭剩余功能并释放整个 SDK。成功关闭后重复调用是 no-op。

Subscription、Glove 和 Sdk 的析构函数仍提供 RAII 兜底，但不能替代显式 close()，因为析构不能可靠报告清理失败。也不要在 callback 中销毁最后一个 Sdk 对象；将清理交给 callback 外的应用控制路径。

配置字段的完整说明见配置字段速查。

对象与方法总表

无参数方法在“参数、类型与默认值”列写“无”。

顶层函数

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`qnbot::discover_gloves()`	查看当前可发现的手套	无	`std::vector<DiscoveredGlove>`	创建 SDK 前	顶层发现错误；逐端口错误在结果中

`Sdk`

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`Sdk::glove()`	进入手套功能	无	`Glove`	SDK 未关闭	`ClosedHandleError`、能力不可用
`Sdk::start()`	启动已配置功能和设备数据流	无	`void`	准备读取数据后	连接、身份、数据流或生命周期错误
`Sdk::update()`	执行一次 SDK 任务调度	无	`UpdateResult`	已启动且未使用其他运行方式	`LifecycleError`
`Sdk::run_forever()`	在当前线程持续推进 SDK 调度	无	`void`	已启动且未使用其他运行方式	`LifecycleError`
`Sdk::run_background()`	在后台推进 SDK 调度	无	`void`	已启动且未使用其他运行方式	`LifecycleError`、后台运行错误
`Sdk::request_stop()` / `join()`	请求停止并等待后台运行结束	无	`void`	前台或后台运行期间	`LifecycleError`、后台错误
`Sdk::stop()`	停止运行并断开设备	无	`void`	SDK 已启动	停止过程错误
`Sdk::close()`	最终关闭 SDK	无	`void`	不再使用 SDK 时	关闭过程错误；关闭后对象失效
`Sdk::health()`	查看整个 SDK 的健康状态	无	`Health`	SDK 未关闭	`ClosedHandleError`

`Glove`

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`Glove::device()` / `device(name)` / `device(side)`	选择一只已配置手套	无、`const std::string&` 或 `Side`	`GloveDevice`	SDK 创建后	`NotFoundSelectionError`、`AmbiguousSelectionError`
`Glove::sync_time(reference_time_ms)`	为所有手套 source 设置统一的外部绝对时间基准	`double reference_time_ms`，有限的 Unix 毫秒值	`void`	建议在 `start()` 前；运行中可再次调用以重新授时	`InvalidArgumentError`、`ClosedHandleError` 或底层授时错误
`start()` / `stop()` / `close()`	启动、停止或最终关闭全部手套	无	`void`	对应生命周期阶段	连接、生命周期或关闭错误
`update()` / `run_forever()` / `run_background()`	推进 SDK 调度	无	`UpdateResult` / `void`	已启动，三种方式选一	`LifecycleError`、后台运行错误
`request_stop()` / `join()`	请求停止并等待后台运行结束	无	`void`	前台或后台运行期间	`LifecycleError`、后台错误
`health()`	查看全部手套的健康状态	无	`Health`	Glove 未关闭	`ClosedHandleError`

`GloveDevice`

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`source_id()`	读取运行时 source 标识	无	`std::string`	SDK 未关闭	`ClosedHandleError`
`get_device_info()`	读取已验证的设备信息快照	无	`GloveDeviceInfo`	SDK 创建后，可在 start 前	`UnavailableFeatureError`（身份未验证）
`start()` / `stop()`	只启动或停止当前手套	无	`void`	需要单独控制设备时	连接、身份、数据流或生命周期错误
`pose()` / `imu()` / `status()`	读取原始姿态、实验性 IMU 或设备状态	无	对应 `ReadChannel<T>`	SDK 创建后	生命周期、关闭或不支持错误
`skeleton()`	启用并访问 Skeleton 数据	无	`Skeleton`	必须在 start 前调用	`LifecycleError`、能力不可用
`Skeleton::joint_angles()` / `pose()`	读取 Skeleton 关节角或骨骼节点	无	对应 `ReadChannel<T>`	Skeleton 启用后	所属对象关闭或能力不可用
`output()` / `output(name)`	读取指定 target 的灵巧手输出	无或 `const std::string&`	`ReadChannel<HandJointCommand>`	SDK 创建后	target 未找到或歧义
`haptics()`	取得指尖震动控制入口	无	`StateChannel<Haptics>`	串口设备选择后	external、无线或断连时不支持或拒绝
`push_frame(frame)`	向 external source 提交一帧数据	`const ExternalGloveFrame&`，必填	`GlovePose`	external device 已 start	参数、时间戳或生命周期错误
`capture_status(package_ids, operator_id)`	检查该设备的手动采集是否可以开始	`package_ids`：`const std::vector<std::string>&`；`operator_id`：`const std::string&`，均必填	`CaptureReadiness`	创建 Capture Session 前	`InvalidArgumentError`、`WorkflowError`
`start_capture(package_ids, operator_id, force)`	在该设备上启动手动采集	`package_ids`、`operator_id` 必填；`force`：`bool` 默认 `false`，`true` 时重新完成当前计划中的采集动作	`CaptureSession`	准备开始采集时	`InvalidArgumentError`、`WorkflowError`
`start_calibration(session, targets)`	用该设备已完成的采集启动标定	`session`：`const CaptureSession&`，必须已完成；`targets`：非空 target 序列，均必填	`CalibrationSession`	Capture 完成且 Session 保持打开	Session 或 target 验证错误
`calibration_status(...)`	查看指定 target 的标定状态	无、name 或 `TargetName`	`CalibrationReadiness`	SDK 创建后	target 未找到或歧义
`capture_progress()` / `capture_control()`	读取进度或控制 Capture	无	`ReadChannel<CaptureProgress>` / `CaptureControl`	external 交互流程	生命周期或控制请求错误
`calibration_progress(...)`	读取指定 target 的标定进度	无、name 或 `TargetName`	`ReadChannel<CalibrationProgress>`	标定观察期间	target 未找到或歧义

Sdk、Glove 和 GloveDevice 仍提供 connect() 与 disconnect()。connect() 仅为兼容旧代码保留，不会打开设备；disconnect() 等同于 stop()。新代码直接使用 start() 和 stop()。

生命周期与作用域

对象	方法	作用域与行为
`Sdk`	`start()`	按配置顺序连接并启动所有已启用且尚未关闭的设备和功能；已满足的状态可以重复调用
`Sdk`	`update()`	对整个 SDK 执行一次手动更新，并返回一次性的等待结果
`Sdk`	`run_forever()` / `run_background()`	以前台或后台模式运行整个 SDK；两种模式与 manual update 互斥
`Sdk`	`request_stop()` / `join()`	请求当前运行循环停止；`join()` 等待后台运行结束，并报告后台错误
`Sdk`	`stop()`	停止所有已启动功能和数据流，再断开所有已连接设备；之后可再次 `start()`
`Sdk`	`health()`	返回全部未关闭设备和功能的聚合健康状态
`Sdk`	`close()`	请求停止、等待运行结束、清理订阅并释放全部 SDK 资源；完整清理后重复调用是 no-op
`Glove`	`start()` / `stop()`	只作用于所有已启用且尚未关闭的手套
`Glove`	`update()` / `run_forever()` / `run_background()`	只处理手套数据；运行模式规则与 `Sdk` 相同
`Glove`	`request_stop()` / `join()` / `health()`	停止或观察手套运行状态，不影响其他 SDK 功能
`Glove`	`close()`	停止并关闭全部已配置手套；`Sdk` 本身仍可用于其他未关闭功能
`GloveDevice`	`start()` / `stop()`	只作用于所选实体手套；不改变其他设备的状态
`GloveDevice`	`push_frame()`	只允许 external connection 在已连接且已启动时提交一帧输入

数据读取与订阅

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`ReadChannel<T>::latest()`	立即读取最近一条数据	无	`std::optional<Sample<T>>`	所属对象未关闭	关闭错误
`ReadChannel<T>::subscribe(callback)`	每次收到新数据时执行 callback	`std::function<void(const Sample<T>&)>`，必填	`Subscription`	建议在 start 前注册	参数或关闭错误
`ReadChannel<T>::next()`	创建一次下一条数据等待	无	`NextOperation<T>`	所属对象运行期间	取消、关闭或数据流错误
`StateChannel<T>::set(value)` / `clear()`	更新或清除震动设置	`const T&` / 无	`void`	设备已连接且支持震动	参数、拒绝或断连错误
`Subscription::unsubscribe()`	提前停止一个 callback	无	`void`	SDK 继续运行但不再需要该 callback 时	callback 内同步取消不安全
`NextOperation<T>::get()` / `cancel()`	阻塞取得数据或取消等待	无	`Sample<T>` / `void`	单次等待期间	取消、关闭或重复消费错误

Capture/Calibration 会话

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`CaptureControl::confirm()` / `skip()` / `cancel()`	确认、跳过或取消当前 Capture 请求	`const std::string& request_id`，必填	`void`	external 交互收到当前请求后	空、过期或状态不匹配
`CaptureControl::retry()`	重新执行一个 Capture 阶段	`const std::string& stage_id`，必填	`void`	external 交互需要重试时	空、未知或当前不可重试
`CaptureSession`	控制手动采集并读取状态或结果	`snapshot()`、`confirm()`、`skip()`、`retry()`、`cancel()`、`result()`、`close()`	快照、`std::optional<CaptureResult>` 或 `void`	Session 打开期间	过期请求、无效阶段、关闭错误
`CalibrationSession`	控制标定并读取或等待结果	`snapshot()`、`result()`、`wait()`、`cancel()`、`close()`	快照、可选结果或结果 vector	Session 打开期间	工作流、取消或关闭错误

数据与结果模型

下表说明公开 API 直接接收或返回的字段；std::optional 表示该字段可能不存在。

`TelemetryMeta`

字段	类型	说明
`source`	`std::string`	产生数据的 source ID
`timestamp`	`double`	数据时间戳
`sequence`	`std::optional<std::uint64_t>`	设备或数据源提供的序号
`frame_id`	`std::optional<std::string>`	设备或数据源提供的帧标识

`Sample<T>`

字段	类型	说明
`value`	`T`	当前业务数据
`sequence`	`std::uint64_t`	同一数据类别中单调递增的 SDK 序号
`source_time`	`std::optional<double>`	数据源时间
`observed_at`	`double`	SDK 接收到数据的单调时间

source_time 与 observed_at 都不是系统日历时间。

`DiscoveredGlove` 与 `GloveDiscoveryIssue`

类型	字段	说明
`DiscoveredGlove`	`port`、`hand`、`sn`、`error`	候选端口、左右手、设备 SN 和逐端口发现错误
`GloveDiscoveryIssue`	`code`、`message`	稳定错误分类和展示用说明；程序应按 `code` 判断

`GloveDeviceInfo`

字段	类型	说明
`canonical_sn`	`std::string`	经过身份验证的规范 SN
`device_type`	`std::string`	设备类型
`model`	`std::string`	设备型号
`firmware_version`	`std::string`	固件版本
`hand`	`Side`	设备左右手
`hand_source`	`std::string`	左右手信息来源

`GloveNodePose` 与 `ExternalGloveFrame`

类型	字段	类型与说明
`GloveNodePose`	`position`	`std::array<double, 3>`，三维位置
`GloveNodePose`	`quaternion_xyzw`	`std::array<double, 4>`，XYZW 四元数
`ExternalGloveFrame`	`thumb`、`index`、`middle`、`ring`、`pinky`	`GloveNodePose`，五指指尖姿态
`ExternalGloveFrame`	`timestamp_ms`	`std::optional<double>`，推荐的可选毫秒输入；省略时沿用当前共享时间基准；时间语义见时间戳与外部授时
`ExternalGloveFrame`	`timestamp_sec`	`std::optional<double>`，已废弃的兼容输入；乘以 `1000` 转为毫秒，不得与 `timestamp_ms` 同时设置

`GloveFeaturePayload`

字段	类型	说明
`glove_id`	`std::string`	手套数据标识
`timestamp_ms`	`double`	设备数据时间，单位为毫秒
`root_pose`	`GloveNodePose`	手部根节点姿态
`fingertip_world` / `fingertip_local`	`std::map<GloveFinger, GloveNodePose>`	五指世界姿态和相对根节点的局部姿态
`hand_side`	`Side`	帧中报告的左右手
`finger_names`	`std::vector<GloveFinger>`	当前帧包含的手指顺序
`raw_valid_mask` / `held_mask`	`std::map<GloveFinger, bool>`	原始数据有效性和是否沿用上一条有效值
`quality_flags`	`std::vector<std::string>`	当前帧的质量标记

`GlovePose`

字段	类型	说明
`meta`	`TelemetryMeta`	source、时间和帧标识
`payload`	`GloveFeaturePayload`	根节点、五指姿态和有效性信息
`quality`	`std::map<std::string, Value>`	可扩展质量信息

`GloveImuPayload`

字段	类型	说明
`valid`	`bool`	当前原始计数是否有效
`gyroscope_raw`	`std::array<std::int16_t, 3>`	三轴陀螺仪原始计数
`accelerometer_raw`	`std::array<std::int16_t, 3>`	三轴加速度计原始计数

`GloveImu`

字段	类型	说明
`meta`	`TelemetryMeta`	source、时间和帧标识
`payload`	`GloveImuPayload`	`valid`、三轴 `gyroscope_raw` 和三轴 `accelerometer_raw`
`quality`	`std::map<std::string, Value>`	可扩展质量信息

`HandJointCommand`

字段	类型	说明
`target`	`std::string`	目标标识
`joints`	`std::map<std::string, double>`	关节名称到目标位置的映射
`timestamp`	`double`	输出时间戳
`source`	`std::optional<std::string>`	产生输出的 source ID
`metadata`	`std::map<std::string, Value>`	算法附加信息

Skeleton 固定关节

来自 skeleton().joint_angles() 时，joints 固定包含以下 25 个 active joints。名称中的 <side> 替换为 left 或 right；应按关节名读取，不要把 std::map 的排序当作原生索引。

索引	关节名
0	`<side>_thumb_cmc_abduction`
1	`<side>_thumb_cmc_flexion`
2	`<side>_thumb_cmc_opposition`
3	`<side>_thumb_mcp_abduction`
4	`<side>_thumb_mcp_flexion`
5	`<side>_thumb_ip_flexion`
6	`<side>_index_mcp_abduction`
7	`<side>_index_mcp_flexion`
8	`<side>_index_pip_flexion`
9	`<side>_index_dip_flexion`
10	`<side>_middle_mcp_abduction`
11	`<side>_middle_mcp_flexion`
12	`<side>_middle_pip_flexion`
13	`<side>_middle_dip_flexion`
14	`<side>_ring_cmc_cup`
15	`<side>_ring_mcp_abduction`
16	`<side>_ring_mcp_flexion`
17	`<side>_ring_pip_flexion`
18	`<side>_ring_dip_flexion`
19	`<side>_little_cmc_opposition`
20	`<side>_little_cmc_cup`
21	`<side>_little_mcp_abduction`
22	`<side>_little_mcp_flexion`
23	`<side>_little_pip_flexion`
24	`<side>_little_dip_flexion`

`HandSkeletonPose`

字段	类型	说明
`timestamp_ms`	`double`	骨骼输出时间，单位为毫秒
`hand_side`	`Side`	左右手
`coordinate_frame`	`std::string`	当前为 `wrist_local`
`names`	`std::vector<std::string>`	25 个节点名称
`positions_local`	`std::vector<std::array<double, 3>>`	25 个局部位置
`orientations_local_xyzw`	`std::vector<std::array<double, 4>>`	25 个局部 XYZW 四元数

`Haptics`

字段	类型	说明
`strengths`	`std::map<GloveFinger, std::int32_t>`	手指到 `0..100` 震动强度的映射；可为空，手指可选 `thumb`、`index`、`middle`、`ring`、`pinky`

`GloveStatus`

字段	类型	说明
`device_type`	`std::string`	设备类型
`connected` / `stale`	`bool`	是否连接、数据是否过期
`timestamp`	`double`	状态时间戳
`last_error`	`std::optional<std::string>`	最近一次设备错误
`reconnect_count`	`std::uint64_t`	成功恢复次数
`fields`	`std::map<std::string, Value>`	设备类型相关的附加状态

`Health`

字段	类型	说明
`ok`	`bool`	当前汇总状态是否健康
`warning_count` / `error_count`	`std::uint64_t`	累计告警数和错误数
`devices`	`std::map<std::string, DeviceHealth>`	source ID 到设备健康摘要的映射
`last_error`	`std::optional<std::string>`	最近一次 SDK 错误
`runtime_overrun`	`bool`	SDK 调度是否发生过超时
`topic_callback_error`	`bool`	SDK 数据处理 callback 是否发生过未处理异常

DeviceHealth 包含 connected: bool、stale: bool 和 last_error: std::optional<std::string>。

`CalibrationReadiness` 与 `UpdateResult`

类型	字段或方法	类型与说明
`CalibrationReadiness`	`state`	`CalibrationReadinessState`：`not_required`、`ready` 或 `needs_calibration`
`CalibrationReadiness`	`operator_id`	`std::string`，本次判断使用的佩戴者标识
`UpdateResult`	`tick()`	`std::uint64_t`，当前调度序号
`UpdateResult`	`ran_task_count()`	`std::uint64_t`，本次执行的任务数
`UpdateResult`	`has_next_task()`	`bool`，是否还有后续任务
`UpdateResult`	`sleep()`	`SleepResult`，等待下一项任务到期；每个结果只能调用一次

Capture 模型

类型	字段	类型与说明
`CapturePlanStage`	`stage_id`、`prompt`	`std::string`，阶段标识和动作提示
	`required_sample_count`、`optional`	`std::uint64_t`、`bool`，所需样本数和是否可跳过
`CapturePlan`	`package_ids`、`stages`	`std::vector<std::string>`、`std::vector<CapturePlanStage>`，算法包和阶段顺序
`CaptureStageReadiness`	`stage_id`、`required_sample_count`、`state`	阶段标识、所需样本数和 `reusable` / `needs_capture` 状态
`CaptureReadiness`	`state`、`plan`、`stages`	整体准备状态、计划和各阶段准备状态
`CaptureStageProgress`	`stage_id`、`prompt`、`optional`	当前阶段标识、动作提示和是否可跳过
	`state`、`origin`	`CaptureStageState`、`CaptureStageOrigin`，阶段状态和数据来源
	`collected_sample_count`、`required_sample_count`	`std::uint64_t`，已采样数和所需样本数
	`request_id`	`std::optional<std::string>`，当前控制请求标识
`CaptureFailure`	`code`、`message`	`std::string`，稳定失败代码和展示说明
`CaptureProgress`	`session_id`、`session_state`、`failure`	Session 标识、状态和可选失败信息
	`source_id`、`side`、`operator_id`、`stage`	source、左右手、佩戴者和当前阶段进度
`CaptureSessionSnapshot`	`side`、`plan`、`state`	左右手、计划和 Session 状态
	`current_stage`、`request_id`	当前阶段和请求标识，均为 `std::optional<std::string>`
	`collected_sample_count`、`required_sample_count`	`std::uint64_t`，当前阶段采样进度
	`remaining_stages`、`stage_progress`、`allowed_operations`	剩余阶段、完整阶段进度和当前允许的控制操作
	`next_action`、`failure`	下一步提示和可选失败信息
`CaptureStageSamples`	`stage_id`、`frame_count`	阶段标识和最终帧数
`CaptureResult`	`operator_id`、`side`、`created_at`、`stage_samples`	佩戴者、左右手、创建时间和各阶段采集摘要

`CaptureReadiness`

capture_status(package_ids, operator_id) 在创建 Capture Session 前返回整体准备状态、采集计划和各阶段准备状态。

字段	类型	说明
`state`	`CaptureReadinessState`	`not_required`、`ready` 或 `needs_capture`
`plan`	`CapturePlan`	解析后的采集计划
`stages`	`std::vector<CaptureStageReadiness>`	各阶段准备状态

Calibration 模型

类型	字段	类型与说明
`CalibrationJobFailure`	`code`、`message`	`std::string`，稳定失败代码和展示说明
`CalibrationJobProgress`	`target_id`	`std::string`，target 标识
	`state`	`CalibrationJobState`：`pending`、`running`、`completed`、`failed` 或 `cancelled`
	`failure`	`std::optional<CalibrationJobFailure>`，当前失败信息
`CalibrationProgress`	`session_id`、`source_id`、`job`	Session 标识、source ID 和当前 target 进度
`CalibrationSessionSnapshot`	`state`、`jobs`	Session 状态和按 target 顺序排列的进度
`CalibrationResult`	`record_id`、`source_id`、`target_id`、`created_at`	记录 ID、source、target 和结果创建时间