运动控制

选择运动入口时，先判断目标是一次性到位、应用主动流式更新，还是 SDK 托管拖拽。

控制入口选择

任务	入口	特点
整手或局部目标运动	move_to()、move_joint()、move_finger()、move_thumb()	返回 MotionHandle，可等待或取消
连续高频目标	open_servo()	应用负责发送节奏、超时和关闭
托管拖拽	start_servo_drag()	SDK 管理拖拽控制循环
示教与回放	Teach / Replay API	记录并重放整手轨迹

不要通过高频循环调用 move_to() 模拟 Servo。目标运动之间存在控制权冲突，新命令可能抢占旧命令；应用必须检查最终 OperationState。

运动前检查

• 确认 joint_layout 与目标数组长度一致。
• 读取 State，保留不希望改变的关节当前位置。
• 检查 Health 和电机故障码。
• 使用设备布局定义的 degree、rpm 和 mA，不应用寄存器缩放。
• 为运动等待设置有限超时。

等待与结果

handle = await hand.motion.move_joint(
    joint_index=0,
    target_position=20.0,
    duration=1.0,
)
result = await handle.wait(timeout=3.0)
if result != sdk.OperationState.Succeeded:
    raise RuntimeError(f"Motion ended in {result}")

等待超时只表示调用方停止等待，不保证设备已经停止。结果为 Indeterminate 时，先读取 State 判断设备效果，不直接重复发送同一命令。

中断与恢复

取消、抢占、断线和设备故障是不同结果。应用应记录命令、最终状态、错误的 operation_effect 和恢复要求。只有确认旧控制会话已经关闭，才能建立新的 Servo 或拖拽会话。

完整契约见Motion API。