跳转到内容
English

开发指南

SDK 版本:2.3.3

本文介绍 Revo3 SDK 2.x 的异步调用、持续数据订阅、Servo 控制、运动命令的等待与取消、错误处理与重试,以及数据诊断与离线回放。示例以 Python 为主;C++ 对应接口请参阅 Revo3 API 参考手册。

完整对象架构、数据结构字段和方法签名请参阅 Revo3 API 参考手册。

Linux C/C++ 运行依赖

libusb、libudev 是 SDK 在 Linux 上使用的系统运行依赖库,可通过系统包管理器安装。默认 portable 分发包已携带这两个库,无需额外安装;使用 system 模式时,需要系统中已安装兼容版本:

终端窗口
# Debian / Ubuntu
sudo apt-get install libusb-1.0-0 libudev1
bash download-lib.sh --system-deps

请使用 examples 仓库中的下载脚本。system 模式在复用或替换 SDK 前检查动态依赖,缺失时终止并保留原有安装,不会安装或覆盖系统库。两种模式均保留 SDK 和第三方许可。此选项仅影响 C/C++ 分发,不影响 Python wheel。

Revo3 Python 2.x 的所有设备 I/O API 都是异步的,必须在 asyncio 事件循环中调用:

import asyncio
from bc_revo3_sdk import main_mod as sdk
async def main() -> None:
manager = sdk.Manager()
try:
hand = await manager.connect_auto()
state = await hand.state.snapshot()
print(state.positions_deg)
finally:
await manager.close()
asyncio.run(main())
  • 同步代码入口用 asyncio.run() 包装;不要在回调或库模块顶层直接创建事件循环。
  • SDK 的等待不会阻塞事件循环:等待期间其他协程(订阅、其他手的控制)照常调度,可用 asyncio.gather() 并发操作多台设备。
  • manager.discover() 的 on_found 回调在 SDK 扫描线程上同步执行,不是协程:回调内不能 await,返回 False 可提前终止扫描。
  • 对象方法与属性本身不是协程(如 hand.device_info、session.state),可直接使用;只有涉及设备 I/O 或等待的方法需要 await。

2. 状态与触觉持续订阅 (Subscription)

Section titled “2. 状态与触觉持续订阅 (Subscription)”

Revo3 Python 2.x 通过 Manager/Hand 对象 API 提供 State、Touch 和 Health 的异步拉取订阅。

from bc_revo3_sdk import main_mod as sdk
async def monitor_state(hand: sdk.Hand) -> None:
subscription = hand.state.subscribe(period=0.02)
try:
while True:
state = await subscription.next()
print(state.timestamp.clock, state.positions_deg)
finally:
subscription.close()

HandState 包含 operating_states、positions_deg、velocities_rpm、currents_ma 和 timestamp。逐电机原始状态码属于低频诊断数据,通过 (await hand.health.snapshot()).motor_fault_codes 读取;该兼容字段同时包含故障位和非故障状态位。

from bc_revo3_sdk import main_mod as sdk
async def monitor_touch(hand: sdk.Hand) -> None:
subscription = hand.touch.subscribe(period=0.05)
try:
while True:
frame = await subscription.next()
for module in frame.modules:
if module.sample_state != sdk.TouchSampleState.Valid:
print(module.module_id, module.sample_state)
continue
if module.points is not None:
print(module.module_id, "points:", module.points)
if module.force3d is not None:
print(module.module_id, "force (mN):", module.force3d)
if module.torque2d is not None:
print(module.module_id, "torque (Nm):", module.torque2d)
finally:
subscription.close()

TouchFrame 统一提供 modules 数组;每个 module 按能力选择性包含点阵、模块级合力 regional_forces_mn、三轴力、二轴力矩、合力 resultant_force_mn 和状态字段。三轴力和合力统一使用 mN。

按 module_id 识别模块,不依赖数组位置。先检查 sample_state,仅在字段非 None 时使用该信号;空模块列表不产生样本,非 Valid 状态不能作为有效测量值。

SDK 可完整读取压阻阵列 36/71 点掌心数据;空间显示还需要匹配的坐标映射。GUI 示例目前仍使用旧版 36 点掌心坐标,71 点数据的显示范围与限制见GUI 使用说明。

async def monitor_health(hand: sdk.Hand) -> None:
subscription = hand.health.subscribe(period=0.2)
try:
while True:
health = await subscription.next()
print(health.safety_state, health.error_code)
finally:
subscription.close()
  • subscribe() 返回拉取式订阅;调用 next() 等待下一次读取结果。
  • 首次 next() 直接读取当前 State、Touch 或 Health 快照;后续每次调用先等待配置间隔再读取。订阅不保留历史样本,也不在两次调用之间后台采集。
  • close() 可以重复调用;关闭后该订阅不再读取数据。
  • State、Touch 和 Health 的 period 相互独立,并且必须是有限正数(秒)。
  • Timestamp.clock 标识时钟域;只有 clock 相同时,timestamp 才能比较或相减。
  • 订阅只用于监控;Servo 命令仍从 hand.motion.open_servo() 进入。

对于机械臂视觉跟随、遥操作或实时算法控制场景,推荐使用 open_servo() 建立高频流式会话。

以下片段只展示会话生命周期和固定周期发送方式。执行前必须固定灵巧手、排除机构干涉、设置合理电源限流,并让独立断电开关保持可触达;目标生成、限位检查和异常后的安全恢复按应用要求实现。

import asyncio
period = 0.02
state = await hand.state.snapshot()
target_positions = list(state.positions_deg)
session = hand.motion.open_servo(command_timeout_ms=100)
try:
for _ in range(100):
await session.send_position(target_positions)
await asyncio.sleep(period)
except sdk.SdkError as error:
if error.operation_effect == sdk.OperationEffect.Indeterminate:
state = await hand.state.snapshot()
print("流式命令结果不确定,当前位置:", state.positions_deg)
raise
finally:
session.close()

除 send_position 外,Servo 会话还提供 send_velocity、send_current、send_impedance 与 send_mit,参数与单位见 API 参考手册 - Servo。

  • command_timeout_ms 监视相邻两次流式控制命令的时间间隔,不是后台心跳;未显式传入时使用 RuntimeOptions.servo_command_timeout_ms;
  • 超时后 ServoSession.state 变为 Expired,SDK 释放软件控制权,并拒绝该会话继续发送命令;
  • 该机制不发送停止命令,也不能证明电机已经停止、卸力或进入安全状态。固件通信 Watchdog 的触发条件和机械行为必须按固件规格及真机结果处理。

4. 运动命令的等待与取消 (OperationHandle)

Section titled “4. 运动命令的等待与取消 (OperationHandle)”

move_to、move_finger、move_thumb、move_joint 等运动命令返回 OperationHandle,用于跟踪一次运动的最终结果:

motion = await hand.motion.move_to(target_positions, duration=1.5)
try:
result = await motion.wait(timeout=5.0)
if result == sdk.OperationState.Succeeded:
print("运动完成")
elif result == sdk.OperationState.Indeterminate:
# 设备可能已在运动:先读实际位置,再决策,禁止直接重发
state = await hand.state.snapshot()
print("结果不确定,当前位置:", state.positions_deg)
except sdk.SdkError as error:
print(f"运动失败 [{error.code}]: {error.message}")
  • wait(timeout) 等待终态;超时仅表示停止等待,硬件已接收的物理运动仍会继续执行。
  • handle.state 随时可读;handle.error 在终态后携带绑定的 SdkError(无错误时为 None)。
  • handle.cancel() 请求协作式取消:SDK 会让当前寄存器请求完整结束,在下一个控制周期边界停止发送轨迹点并释放软件控制权,不会中途丢弃串口请求。取消请求发出后,若设备最终位置无法确认,终态为 Indeterminate。
  • 完整状态机(Pending/Running/Succeeded/Preempted/Failed/Indeterminate 等)见 API 参考手册 - 等待、取消和运动冲突。

5. 生产环境错误处理与重试策略

Section titled “5. 生产环境错误处理与重试策略”

对象调用失败时会抛出 SdkError。除 code 和 message 外,SdkError 还提供四个机器可读字段用于生产环境的自动化决策:

字段 类型 用途
operation_effect OperationEffect 写命令是否可能已生效(见下)
retryable bool SDK 确认可安全自动重试(仅限无副作用的只读操作遇连接/超时类错误)
recovery_requirement RecoveryRequirement 建议恢复动作:None_/Retry/Reconnect/OperatorAction(Python 中 None 为关键字,枚举成员名为 None_;C++ 为 None)
low_level_cause str | None 底层驱动原始原因,用于排障记录

写命令失败时必须先检查 operation_effect:

  • NotApplied:命令确定未被设备执行(只读失败或发包前校验失败),无副作用。
  • PartiallyApplied:部分生效(如 Manager 关闭未能释放全部传输)。
  • Indeterminate:命令已发出但响应丢失,无法确认是否执行。应先读取 hand.state.snapshot() 确认当前机械位置,禁止直接无脑重发写命令。

含重连决策的重试示例:

async def read_with_retry(hand: sdk.Hand, max_retries: int = 3):
for attempt in range(max_retries):
try:
return await hand.state.snapshot()
except sdk.SdkError as error:
print(f"[{error.code}] {error.message}")
if error.recovery_requirement == sdk.RecoveryRequirement.Reconnect:
# 传输层已失步或断开:先重建连接再重试
await hand.close()
raise # 由上层决定是否重新 connect
if not error.retryable or attempt + 1 >= max_retries:
raise
await asyncio.sleep(0.1 * (attempt + 1)) # 退避后重试

警告: 重试自动化仅限 retryable=True 的只读操作。写命令(运动、配置、固件)的 retryable 恒为 False:写失败时按 operation_effect 与 recovery_requirement 走人工确认或状态核实流程。

按照快速入门获取并安装公开示例后,在示例仓库根目录运行诊断与状态采集 CLI:

终端窗口
# Inspect device information and current state.
python \
python/revo3/manager_cli.py --port /dev/ttyUSB0 inspect
# Record state data as JSONL.
python \
python/revo3/manager_cli.py --port /dev/ttyUSB0 \
record state.jsonl --duration 10
# Replay the recording offline.
python \
python/revo3/manager_cli.py replay state.jsonl

回放默认只读取并展示记录,不向设备发送运动命令,避免把历史轨迹误当成已验证指令。

注意区分:上面的 manager_cli record/replay 是状态数据的离线查看;SDK 另提供示教运动 API,把人工拖动记录为轨迹并回放到设备执行:

try:
# 示教:拖动手部,SDK 按 dt 采样记录整手轨迹
trajectory = await asyncio.wait_for(
hand.motion.teach_hand(duration=10.0, dt=0.02),
timeout=15.0,
)
# 回放会产生真实运动;执行前必须完成固定、限流和独立断电检查
await asyncio.wait_for(
hand.motion.replay_hand(trajectory, dt=0.02),
timeout=15.0,
)
except (asyncio.TimeoutError, sdk.SdkError) as error:
# 超时或通信失败不能证明设备未执行,先读取实际状态再决定恢复动作
state = await hand.state.snapshot()
print("示教或回放未确认完成,当前位置:", state.positions_deg)
raise

单关节版本为 teach_joint / replay_joint。示教与回放的控制语义和安全边界见 API 参考手册。

7. 单次控制、升级进度与电机信息

Section titled “7. 单次控制、升级进度与电机信息”

21 自由度手型可使用 await hand.motion.set_position(position_deg)、 set_current(current_ma) 或 set_mit(position_deg, velocity_rpm, kp, kd, feedforward_current_ma) 单次下发整手目标,无需 open_servo() 或心跳。数组按逻辑关节顺序排列, 长度为 21;位置为度、速度为 rpm、电流及 MIT 第五项前馈电流为 mA。 SDK 不插值或自动重发;调用成功确认写入请求,不表示运动完成。目标保持、 模式切换及停止行为由固件决定,关闭连接不会自动停止控制。写入期间与 轨迹、Servo 及拖拽互斥;错误或取消后先读取状态,再决定恢复步骤。

Python discrete_control.py 和 C++ discrete_control 默认只读。 添加 --run 后下发当前姿态或零电流,MIT 使用 kp=1、kd=0.1、零速度和 零前馈电流;这些命令也可能改变电机行为或支撑状态,执行前应清空工作空间。

单次控制也提供与 move_* 同粒度的 set_joint_*、 set_finger_* 和 set_thumb_*。三种粒度均支持 position、current 和 mit。

粒度 选择器与目标参数 逻辑关节顺序
set_joint_* joint_index=0..20;各目标为标量 仅所选关节
set_finger_* finger_index=1..4;各目标数组长度 4 1=食指 J12–15,2=中指 J8–11,3=无名指 J4–7,4=小指 J0–3;每指 Abd、MCP、PIP、DIP
set_thumb_* 无手指选择器;各目标数组长度 5 J16–20:Flex、MCP、IP、Abd、Rotation

这些接口只写所选关节,不通过整手读改写保留其他目标。set_* 不规划轨迹, Python 返回 None、C++ 返回 void;move_* 执行插值运动并返回 OperationHandle。 局部单次下发仍持有整手控制权,与所有 move_*、Servo 和拖拽操作互斥, 即使选择了不同关节也不会同时获得控制权。

手指和拇指目标按逻辑顺序逐关节写入,非原子更新。SDK 在首个写入前检查 全部数组、数值及碰撞状态;写入失败即停止后续下发,不自动重发或回滚。 若已有关节确认写入、后续关节被拒绝,错误的 operation_effect 为 PartiallyApplied;响应丢失时为 Indeterminate。必须读取状态后再决定恢复。 取消已开始的 Python await 不撤回目标;后台完成该组请求的响应处理并保持 控制权,直到组内下发结束或失败。

hand.maintenance.update_firmware(..., on_progress=callback) 返回操作句柄, handle.progress 为 0 到 1 的传输进度。C++ 通过 operation.progress() 查询。 100% 表示传输完成,需等待操作成功,并重新发现设备、核对安装后的固件版本。

Python 回调在后台线程同步执行,不能直接更新 UI 或 await。 向 asyncio 事件循环投递通知时使用 loop.call_soon_threadsafe()。 通知通常每 100 ms 合并一次;回调异常交给 sys.unraisablehook,不取消升级。 wait() 不等待回调处理完毕;失败或取消后进度保留最后一个值。 firmware_update.py / firmware_update 已演示进度报告,并要求 --run 才刷机。

调用 await hand.refresh_device_info() 和 await hand.refresh_firmware_info() 显式刷新电机信息,再读取 hand.device_info.motor_serial_numbers 与 hand.firmware_info.motor_firmware_versions。成功读取的电机字段立即进入缓存; 后续触觉读取失败仍会报错,但不会丢弃电机结果。捕获错误后可读取属性检查 部分刷新结果,不能将其视为全部字段刷新成功。当前触觉固件版本读取尚未实现, 返回空列表;空列表不表示触觉硬件缺失。Python/C++ device_operations 示例 已包含刷新、错误报告和缓存读取。

完整签名、能力限制及错误语义见 API 参考。