MIT 与周期控制

以下片段在已连接的 arm 上执行。完整程序和运行前提见 MIT 周期保持示例。

MIT 目标

arm.set_mode("mit")
arm.enable()
state = arm.get_state()
if not state.ok:
    raise RuntimeError("反馈不完整")
target = state.q7
# 在固定周期循环中调用
arm.send_mit(target)

send_mit(pos, vel=None, kp=None, kd=None, tau=None) 只控制七个臂关节，返回固定七维限位后角度列表，顺序为 j1..j7；未指定且缺位置反馈的关节不下发，对应返回值为 None。pos 为七维角度列表或非空关节名称映射；明确指定的关节必须有有效位置反馈，否则拒绝整次下发。映射未指定关节有位置反馈时保持该位置。其余参数接受标量或七维列表。八维输入及 gripper 名称拒绝执行。

参数	含义 / 单位	省略时
pos	目标角度，rad	必填
vel	目标角速度，rad/s	零
kp	位置增益，N·m/rad	交付默认值
kd	速度增益，N·m·s/rad	交付默认值
tau	前馈力矩，N·m	零

完整脚本见 MIT 周期控制示例。默认增益适合作为开始使用的配置，不建议在不了解控制效果时增大增益。示例只保持当前姿态，不注入力矩。周期建议从 50 Hz 开始；Python 循环不提供硬实时保证。

dual_arm.send_mit(left, right, vel=None, kp=None, kd=None, tau=None) 同时发送两臂目标，额外参数对两侧使用相同设置，返回两个角度列表。不同设置可分别调用 .left / .right。

set_mode(mode) 只切换七个臂关节，夹爪模式用 arm.set_gripper_mode(mode) 独立管理。关节周期接口要求本次下发的关节都处于对应模式，模式不匹配会拒绝整次下发；完整七维目标要求七关节模式一致。普通夹爪运动使用 move_gripper(width_mm, torque_limit_nm)，内部切换受限力位模式，对外状态仍标 "pos_vel"；send_gripper_pos_vel() 保留最近的夹爪限矩，显式 set_gripper_mode("pos_vel") 才恢复普通位置模式。恢复模式会移除该力矩限制，保持期间须先失能。

send_pos_vel(pos, vlim=None) 只控制七关节；pos 接受七维列表或非空名称映射，vlim 为正的速度上限（rad/s），省略取交付默认值。映射未指定关节有位置反馈时保持该位置，缺反馈时跳过、不下发；指定关节的目标必须是有限数，不能为 None，且必须有有效位置反馈，否则拒绝整次下发。完整七维序列发送要求七个有效目标和七关节位置反馈。返回固定七维实际发送角度，跳过轴为 None，不表示到位；用户负责周期刷新。双臂形式为 dual_arm.send_pos_vel(left, right, vlim=None)。

夹爪周期控制使用 send_gripper_mit(pos, vel=None, kp=None, kd=None, tau=None) 或 send_gripper_pos_vel(pos, vlim=None)，参数均为标量，单位 rad、rad/s、N·m，返回实际发送角度；必须有有效夹爪位置反馈，否则拒绝下发。反馈使用 get_gripper_state() 或毫米开口接口 get_gripper_width()。双臂对应方法接收 left/right 两个夹爪角度，共用可选参数并返回两个标量。

七关节和夹爪可以在同一客户端控制循环中分别发送，互不取消任务或保持。周期发送只下发一次，不等待到位；新目标只接管对应通道。控制程序需要持续刷新目标，Python 循环不保证硬实时。

限位规则：高层 move_*/规划的越界位置警告并拒绝；周期位置和连续速度按已有允许范围限幅，返回实际发送目标。发生限幅时会输出警告。非有限值、非法结构、非正速度上限、非法增益及夹爪力矩上限拒绝执行；不可达末端或越界路径不会被夹紧成另一条路径。

升降位置与角速度控制

启动前升降应位于可靠支撑的机械最低位置，上行路径无阻碍；连接后检查高度反馈，运动前显式调用 enable()。 高度使用 m，电机角度使用 rad，角速度使用 rad/s。 普通高度运动使用 lift.move_to(height_m, speed_percent=30)，SDK 自动发送命令并检查到位。 speed_percent 是无单位比例，绝对角速度接口不使用转速单位。

调用形式	参数与返回值
lift.send_pos_vel(height_m, velocity_rad_s=None)	高度 m、有限正的角速度上限 rad/s；省略速度取 6.283185307179586 rad/s；返回限幅后的高度
lift.set_velocity_rad_s(velocity_rad_s)	有限的带符号角速度 rad/s；正值向最高允许位置移动，负值向最低允许位置移动，零值调用 stop()；返回 None

两个接口都按位置目标控制，并限制角速度；角速度上限不代表电机一定以该速度运动。 单次发送不等待到位，调用方需要持续刷新，建议从 50 Hz 开始。需要 SDK 管理到位、超时和任务取消时使用 move_to()。 新的单次命令会接管此前的升降运动任务或保持，不要混用两种控制方式驱动同一次运动。

高度和角速度超限会警告并限幅。max_height_m 的单位为 m， max_motor_velocity_rad_s 和 max_velocity_rad_s 的单位为 rad/s，max_velocity_m_s 为机构线速度边界，单位 m/s。 当前实际角速度上限为 37.69911184307752 rad/s；周期命令直接使用 rad/s。

速度接口的上升目标始终为 lift.max_height_m，下降目标始终为 0 m，不会发送行程之外的目标。 接近相应端点时，SDK 根据当前高度到端点的位置误差连续降低速度上限；低于最低接近速度的用户请求保持原值，不会被提速。 当前配置下，40% 请求约为 15.08 rad/s / 24 mm/s，约在距端点 24 mm 时进入降速，最后约 0.8–1 mm 以低速接近。 目标仍是精确的 0 m 或 lift.max_height_m，因此不损失有效行程。反向命令会立即按另一端的位置误差重新计算限速。 目标限位和自动降速不保证实际机构不会超调，也不提供碰撞力矩检测；结束控制时仍应显式调用 stop() 或 set_velocity_rad_s(0)。 停止刷新命令不保证停车，电机可能继续向最后一次目标移动。速度命令需要有效高度反馈；读取失败会抛异常，调用方应停止控制并保留错误信息。

以下示例在当前高度持续发送位置保持命令，结束时普通停止并断开：

import time

from libark.robot.hw1.lift import Lift

with Lift() as lift:
    lift.enable()
    try:
        height = lift.get_height()
        if height is None:
            raise RuntimeError("升降反馈缺失，请联系技术支持")
        deadline = time.monotonic() + 1.0
        while time.monotonic() < deadline:
            lift.send_pos_vel(height, velocity_rad_s=3.141592653589793)
            time.sleep(0.02)
        lift.stop()
    except BaseException:
        lift.stop()
        raise

stop() 在运动中会先沿当前方向减速，再保持减速结束时的最新实测高度，避免将松手瞬间的旧位置当作保持点而回拉；若实测高度越界，保持目标取对应限位边界。 它不是机械制动器；disable() 移除主动驱动力，不保证负载继续保持。 with 退出停止并断开，不自动失能；运动和位置保持需要 SDK 进程持续运行。 速度点动缺少有效高度反馈会报错；反馈异常也可能导致停止保持失败，不能据此认定机构已停住。异常时请联系技术支持。 Python 循环不提供硬实时保证；硬件验证状态见使用限制。