Revo 3 SDK v2.x API 导航

文档系列 2.x当前版本 2.0.0正式版

本节按能力域帮助你找到接口并理解关键约束，不重复维护完整的方法签名、参数表和数据结构。

完整接口契约

查询精确签名、参数约束、返回值、枚举、错误语义及 Python、C++、C ABI 对照时，请使用版本化的 Revo 3 SDK v2.0.0 完整 API 手册。完整手册是 API 契约的唯一权威来源。

当前索引对应 Revo 3 SDK v2.0.0；其 Python wheel 包名为 bc-revo3-sdk。

文档边界

需要解决的问题	使用的文档
选择功能域、了解对象关系和关键风险	本站 API 导航
查询精确签名、字段、枚举和跨语言差异	完整 API 手册
按任务完成连接、运动、触觉或维护流程	开发指南

核心入口

• Manager、Hand 与设备元数据

对象	主要接口
Manager	发现设备、自动连接、按参数连接、关闭共享资源
Hand	设备身份、关节布局、固件信息和功能域入口
DetectedDevice	端口、协议、设备 ID、型号和序列号

Python 使用异步 Manager；C++ 使用 revo3::Manager；C ABI 使用 revo3_manager_*。

Hand 功能域

Motion

完整索引：Motion、MotionHandle 与 ServoSession。

• move_to()：整手目标运动。
• move_joint()：单关节运动。
• move_finger() / flex_finger()：四指之一的运动。
• move_thumb()：拇指运动。
• open_servo()：应用主动发送高频目标的 ServoSession。
• start_servo_drag()：SDK 托管的拖拽控制。
• 示教、轨迹记录和回放。

目标运动返回 MotionHandle。调用方负责等待、超时、取消和冲突处理。

State

State、Touch 和 Health 的类型与入口集中在遥测 API。

• snapshot()：读取一次电机状态。
• subscribe()：按周期拉取状态快照。
• HandState：位置、速度、电流、运行状态、故障码和时间戳。

Touch

• 触觉布局查询和显式布局设置。
• snapshot() 与 subscribe()。
• 模组启停、读取模式、数值模式和零点标定。
• TouchFrame、TouchModuleData 和各类信号数据。

使用 TouchLayout 提供的 module_id 和能力信息，不要在应用中假定所有型号都使用相同的模组编号和点数。

Health

• 系统状态、电流、电压、功率和温度。
• 电机在线状态与模组温度。
• SafetyState 与安全状态监控。
• 运行时统计信息。

Config、Calibration 与 Maintenance

完整索引：设备操作 API。

• 设备配置快照和逐项设置。
• 保护电流、关节位置和速度限制。
• 关节标定、零位和默认参数恢复。
• 重启、恢复出厂设置和固件更新。

实验性接口：ExperimentalCollision

ExperimentalCollision 可能在后续版本中变更或移除，不保证向后兼容。它不能替代设备级限位、急停或其他安全保护，也不应作为应用的唯一碰撞保护。使用前必须针对目标设备、固件、负载和运行场景完成真机验证。

错误与恢复

枚举、单位、时间戳和错误结构见类型、枚举与错误。

2.x 使用结构化 SdkError。除错误码外，调用方还应处理：

• operation_effect：失败操作是否可能已经在设备上生效。
• recovery_requirement：是否需要重连、复位或其他恢复动作。
• OperationState：运动等待的成功、取消、抢占、失败或不确定结果。

Indeterminate 不等同于“未执行”。写指令响应丢失时，先读取设备状态，再决定是否重试。

语言差异

语义	Python	C++	C ABI
生命周期	await close() / 异步上下文	RAII / close()	显式释放句柄
等待	Awaitable	阻塞等待并使用 std::chrono 超时	同步函数或回调
命名	对象方法无 revo3_ 前缀	对象方法无 revo3_ 前缀	导出符号使用 revo3_
错误	SdkError	revo3::SdkError	错误结构和状态码