从 Revo 3 SDK v1.x 迁移到 v2.x

本文以正式发布的 Revo 3 SDK v1.5.1 Python 存根和 C 头文件为 v1.x 核验基线。更早版本的应用应先确认实际使用的符号。Revo 3 SDK v2.x 移除了 v1.x Python 模块级 API、DeviceContext 和旧 C 连接接口；迁移需要调整对象生命周期、异步调用、运动等待、订阅和错误恢复。

入口与生命周期

1.x	2.x	迁移动作
Python DeviceContext + slave_id	Manager -> Hand	把设备身份和功能调用收敛到 Hand
C DeviceHandler * 和手动 transport	Revo3ManagerHandle * / Revo3DeviceHandle *	由 Manager 管理连接和共享传输
模块级 revo3_* / stark_*	hand.motion、hand.state 等领域对象	按功能域迁移调用
应用重复传入 slave_id	Hand 保存设备身份	删除领域调用中的设备 ID 参数
手动关闭共享通信对象	关闭 Hand，再关闭 Manager	统一所有退出和异常路径

Python 2.x 示例：

import asyncio

from bc_revo3_sdk import main_mod as sdk


async def main():
    manager = sdk.Manager()
    hand = None
    try:
        hand = await manager.connect_auto()
        state = await hand.state.snapshot()
        print(state.positions_deg)
    finally:
        if hand is not None:
            await hand.close()
        await manager.close()


asyncio.run(main())

运动 API

1.x 方法族	2.x API
revo3_move_hand*	await hand.motion.move_to(...)
revo3_move_joint*	await hand.motion.move_joint(...)
revo3_move_finger*	await hand.motion.move_finger(...)
revo3_move_thumb*	await hand.motion.move_thumb(...)
_wait 变体	对 MotionHandle 调用 await handle.wait(timeout=...)
_with_speed 变体	使用 speed= 参数
_with_gains 变体	使用 kp= 和 kd= 参数
高频连续目标	hand.motion.open_servo() 和 session.send_*()

目标运动返回句柄，不代表运动已经完成。高频更新不要循环调用 move_to()；应使用 ServoSession，并显式处理超时和会话关闭。

speed= 只用于 move_to() 和 move_joint()；move_finger() 和 move_thumb() 使用 duration，不能机械套用 hand/joint 的 speed 迁移规则。

State 与连续采集

2.x 不再使用 1.x collector 或 shared buffer。快照和订阅统一从 hand.state 获取：

subscription = hand.state.subscribe(period=0.02)
try:
    while True:
        state = await subscription.next()
        print(state.positions_deg)
finally:
    subscription.close()

订阅不会保存历史数据。需要历史记录时，应用应建立有界队列或写入外部存储。

Touch、Health 和设备操作

1.x 能力	2.x 入口
Touch 原始数据和摘要	await hand.touch.snapshot()
Touch 连续读取	hand.touch.subscribe()
系统状态和电气量	await hand.health.snapshot()
设备配置	hand.config.snapshot() 和逐项 setter
标定与零位	hand.calibration
重启、恢复出厂和固件更新	hand.maintenance

Touch API 已按类型化布局统一。应用应从 TouchLayout.modules 读取 module_id、区域、点数和信号能力，不要继续硬编码旧版纯触觉阵列的模组顺序。

以下对照使用 v1.5.1 DeviceContext 的正式方法名：

旧入口	2.x 入口
revo3_calibrate_touch_zero* / revo3_calibrate_pressure_touch_zero*	hand.touch.tare(module_index=None)
revo3_set_touch_data_type / revo3_get_touch_data_type	hand.touch.set_read_mode() / read_mode()
revo3_set_touch_module_value_type / revo3_get_touch_module_value_type	hand.touch.set_value_mode() / value_mode()
revo3_get_all_matrix_touch_module_point_counts	hand.touch.point_counts()
revo3_get_all_matrix_touch_module_serial_numbers	hand.device_info.touch_serial_numbers
revo3_restart_matrix_touch_modules*	hand.touch.restart(module_index=None)

1.x 的 revo3_set_pressure_touch_force_tare 和 revo3_set_pressure_touch_module_force_tare 用于二次标定清除或恢复，2.x 没有公共替代，不能改写为 tare()。使用这些入口的项目必须登记为阻塞迁移项，由设备或固件负责人确认维护流程。

C ABI 对应使用统一的 revo3_device_touch_* 符号。2.x 不为移除的 1.x C 符号提供链接别名，升级后必须使用 2.x 头文件重新编译；不得混用 1.x 动态库和 2.x 头文件。

错误和断线恢复

• 捕获结构化 SdkError，同时检查 operation_effect 和 recovery_requirement。
• operation_effect = Indeterminate 时先读取 State，不直接重试写命令。
• 断线重连后，旧 Hand、MotionHandle、订阅和 ServoSession 全部失效。
• Python 和 C++ 对象方法不使用 revo3_ 前缀；C ABI 符号继续使用该前缀。

迁移验证顺序

1. 仅连接并读取设备信息、State 和 Health。
2. 验证物理单位、关节数量和布局。
3. 验证超时、取消、断线和资源关闭。
4. 使用显式开关执行小范围运动。
5. 验证触觉、Servo、标定和固件维护等可选能力。

mock 测试只能验证应用流程，不能替代目标设备和固件上的真机验证。接口定位见 API 导航，完整契约见完整 API 手册。