运动控制

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

控制入口选择

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

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

单次控制（SDK 2.1.2）

hand.motion.set_position()、set_current() 和 set_mit() 下发一次整手命令，无需 open_servo()，不提供心跳或自动重发。当前仅支持已开放控制能力的 21 自由度型号。位置单位为 degree、速度为 rpm、电流及 MIT 前馈电流为 mA，数组按逻辑关节顺序排列。

局部控制使用 set_joint_*、set_finger_* 或 set_thumb_*。关节索引为 0–20；手指索引 1–4 分别为食指、中指、无名指和小指，拇指单独选择。手指和拇指的写入是顺序执行的，不是原子操作；失败后应检查设备状态。

在公开示例仓库根目录运行以下只读命令：

python python/revo3/discrete_control.py --scope joint --joint-index 0 --mode position
python python/revo3/discrete_control.py --scope finger --finger-index 1 --mode mit
./c/build/demo/discrete_control --scope thumb --mode current

仅添加 --run 才发送控制命令。位置模式发送当前姿态，电流模式发送零电流，MIT 模式发送当前姿态、kp=1、kd=0.1、零速度和零前馈电流。这些命令仍可能改变支撑状态或电机行为；执行前清空工作空间并确认停止方式。目标保持由固件决定，关闭连接不会自动停止控制。错误不保证命令未生效，检查状态后再决定是否重试。

上游记录的最终 2.1.2 wheel 局部控制验证范围是 UV5 固件 0.1.2、CAN FD。Modbus 仅有候选实现通过的记录，最终 wheel 复测未发现设备，不能据此宣称完成最终版 Modbus 验证。详见公开示例说明。

整手控制模式（SDK 2.3.0）

仅在已确认固件支持整手控制模式时，显式调用 await hand.motion.get_control_mode() 或 await hand.motion.set_control_mode(sdk.HandControlMode.Mit)。枚举值为 Position=0、Damping=5、Mit=6。切换作用于整手，可能改变支撑状态；先固定设备并确认停止方式。setter 本身不发送运动目标。

整手模式与原 set_mit()／set_joint_mit() 的命令类型不同。原 MIT 接口继续发送位置、速度、Kp、Kd 和前馈电流，不会自动切换整手模式；新固件若已处于 Position 或 Damping，应在使用 MIT 控制前显式切回 Mit。MIT 位置跟踪误差受增益和机械状态影响，需要按实际关节调参。

旧固件继续使用原控制入口，不调用新增模式接口；SDK 连接和原有控制不会自动访问模式寄存器。界面应按已确认的固件能力隐藏或禁用切换入口，不把通信错误当作能力检测结果。示例见公开仓库的 python/revo3/control_mode.py；精确行为以完整 API 契约为准。

运动前检查

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

运行示例

从公开示例仓库根目录预览动作，不连接设备：

python python/revo3/gesture_dance_demo.py

对指、手指动作、手势编排和正弦 Servo 示例仅在传入 --run 后连接并运动。 候选姿态需要针对实际设备校准，左右手分别验证。 命令与调参方式见运动演示指南。

MIT 往返控制应检查整手目标，包括保持不动的关节，并分别校验去程和回程的速度限值。 示例的初始位置容差默认为 0.1°；接受的反馈越界量应收敛到设备限位内，再作为发送目标。 Python 示教示例使用 teaching_mode.py read FILE 记录并保存轨迹，使用 teaching_mode.py load FILE 加载并立即回放；回放前先确认运动范围与停止方式。

等待与结果

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。