主题
升降
启动前机构应位于可靠支撑的机械最低位置，上行路径必须无阻碍。 连接沿用设备已有位置，失能电机不会自动使能；已使能电机保持当前位置。运动前调用 enable()。 初始化失败时停止使用，保留异常联系技术支持。高度单位 m，角度单位 rad，角速度单位 rad/s。 升降按位置目标控制；带符号速度接口也是朝允许行程端点运动，并限制角速度。
| 调用形式 | 行为 / 返回值 |
|---|---|
lift.move_to(height_m, speed_percent=30, blocking=True, timeout_s=None) | SDK 管理高度运动；阻塞成功返回 True，非阻塞返回 LiftMotion |
lift.send_pos_vel(height_m, velocity_rad_s=None) | 单次位置命令；高度 m，正的角速度上限 rad/s；返回限幅后的高度，不表示到位 |
lift.set_velocity_rad_s(velocity_rad_s) | 单次带符号角速度命令，单位 rad/s；正值向上、负值向下、零值减速后保持；返回 None |
lift.get_height() | 当前高度 `float |
lift.get_state() | LiftState，.height_m 为高度，.motor 为反馈数据 |
lift.name | 升降组件名称 |
lift.max_height_m | 当前允许的最高目标高度，默认 1.033587950967 m |
lift.max_motor_velocity_rad_s | 电机角速度边界，41.88790204786391 rad/s |
lift.max_velocity_rad_s | 实际允许的角速度上限，37.69911184307752 rad/s |
lift.max_velocity_m_s | 升降机构线速度边界，当前为 0.06 m/s |
目标、速度与到位
speed_percent 为 1～100 的无单位比例，按实际允许角速度上限缩放，默认 30。 例如 10% 对应约 3.769911184 rad/s，默认 30% 对应约 11.309733553 rad/s。 升降按设备配置限制加/减速，接近目标时降速；短距离移动可能达不到设定速度。 运动和位置保持需要 SDK 进程持续运行；断开连接停止运动，不自动失能，不保证负载保持。 move_to() 自动刷新命令；两个单次命令接口需要调用方周期刷新，完整说明见升降位置与角速度控制。 send_pos_vel() 省略速度时使用 6.283185307179586 rad/s；高度或速度超出允许范围会警告并限幅。 位置命令的速度必须为有限正数，带符号速度命令必须为有限数；非有限输入拒绝执行。 速度接口的目标限定为精确上限 lift.max_height_m 或下限 0 m，角速度绝对值不超过 lift.max_velocity_rad_s。 接近相应端点时，SDK 根据剩余位置误差自动降低速度上限，低速请求不会被提高，也不会为减速预留行程。 当前配置下，40% 请求约为 15.08 rad/s / 24 mm/s，约在距端点 24 mm 时开始降速。 结束控制时显式调用 stop() 或 set_velocity_rad_s(0)；运动中停止会沿当前方向减速，再保持最新实测高度，避免回到松手瞬间的旧位置。 实测高度轻微越过上下限时仍允许向行程内运动；运动目标始终受原行程限制，不会下发继续向外的目标。 get_height() / get_state() 保留真实高度，越界时的停止保持目标取对应限位边界。 自动降速不提供碰撞力矩检测，停止刷新命令也不保证停车。限位行为见升降位置与角速度控制。 Lift 同样提供生命周期接口中的连接、使能、失能、停止、急停、复位与状态属性。 .motor.pos / vel / torq 的单位分别为 rad、rad/s、N·m，缺失反馈保持 None。 公开高度与 .motor.pos 都以机械最低点为零；最高点高度为 max_height_m，正速度表示上升。
高度误差不超过 1 mm、速度不超过 2 mm/s 且连续稳定 0.2 s 时返回 True；成功后持续保持目标。越界目标高度警告并抛 ValueError，不会启动或替换现有任务。默认期限按距离/命令速度再加 5 s；显式 timeout_s 为 (0,3600] 的秒数。缺少有效位置或速度反馈不能报告成功。
等待与取消
LiftMotion 提供 done/error/wait/cancel，成功等待返回 True。
取消抛 LiftMotionCancelled，执行或等待超时抛 LiftMotionTimeout（也是 TimeoutError），执行失败抛 LiftMotionError；停止同时失败时以 ExceptionGroup 保留错误。等待超时不取消运动，旧任务取消不影响新任务。反馈异常也可能导致停止保持失败，不能据此认定机构已停住。退出上下文停止并断开，不自动失能，不承诺主动保持负载。