运动参数参考

运动参数参考#

运动 options 是可修改的 dataclass。构造和赋值时会检查部分数值范围，但当前控制模式和具体方法决定字段是否真正发送。应用应显式设置关键字段，不要根据“模型接受了参数”推断运行时会使用它。

共同校验规则#

超出已声明范围的标量或向量元素通常抛出 ValueError；类型明显错误通常抛出 TypeError；
当前范围比较不能可靠拒绝 NaN，发送前应对全部浮点数执行 math.isfinite()；
向量的元素范围与数组长度分开校验，错误长度可能直到发送时才被拒绝、忽略或替换；
Literal 类型注解不构成完整的运行时枚举校验，motion_type 和 planner 名称只能使用表中值；
timeout_ms 属于运动方法，不是 options 字段，也不等同轨迹执行时长。

`CartesianMoveOptions`#

CartesianMoveOptions 有 23 个公开字段，供 move_end_pose()、move_end_pose_linear() 和 move_end_pose_circle() 使用。

执行和模式字段#

字段	类型	默认值	范围/单位	当前行为
`eff`	`list[float]`	`[70,70,40,40,12,12,12]`	每轴范围依次为 `[0,70]`、`[0,70]`、`[0,40]`、`[0,40]`、后三轴 `[0,12]`；物理单位待版本确认	planning、Servo 和笛卡尔 MIT 兼容路径使用；应为 7 项
`torque`	`list[float]`	`[3.5] * 7`	每项 `[-7,7]`；模型称关节 torque	当前三个公开笛卡尔路径均不发送
`kp`	`list[float]`	`[0.1] * 7`	每项 `[0,5000]`	当前三个公开笛卡尔路径均不发送
`kd`	`list[float]`	`[0.1] * 7`	每项 `[0,5000]`	当前三个公开笛卡尔路径均不发送
`motion_type`	`str`	`"ptp"`	`"ptp"`、`"lin"`、`"ompl"`	`move_end_pose()` planning 使用；LIN/CIRCLE 专用方法忽略并固定路径类型
`blocking`	`bool`	`False`	`True`/`False`	planning/Servo 决定是否等待完成判据；笛卡尔 MIT 兼容路径也发送该值

eff 数量错误时，当前 route 可能整组换成默认值，而不是拒绝。始终传 7 项或保持完整默认值。 eff、current_threshold 和 max_torque 在不同层使用不同名称，未确认前不要换算成 A 或 N·m。

虽然 options 暴露 torque、kp 和 kd，当前 move_end_pose() 在机械臂 mit_control 下实际发送固定参数的 PTP 规划请求，不发送这三个字段。它不是笛卡尔 MIT 调参入口。

基础规划字段#

字段	类型	默认值	范围/单位	作用
`use_collision`	`bool`	`False`	`True`/`False`	请求使用模型碰撞检查；OMPL 自动启用
`velocity_scaling_factor`	`float`	`0.4`	`[0.01,1.0]`，比例	相对规划速度上限的缩放
`acceleration_scaling_factor`	`float`	`0.3`	`[0.01,1.0]`，比例	相对规划加速度上限的缩放
`sampling_time`	`float`	`0.01`	`[0.01,0.5] s`	规划和插值采样时间
`allow_planning_time`	`float`	`0.5`	`[0.01,60] s`	单次规划允许的最长计算时间
`circ_is_center`	`bool`	`False`	`True`/`False`	CIRCLE 中决定 `path` 是圆心参考还是中间点；LIN 忽略
`max_retry_attempts`	`int`	`1`	`[1,1000]`	规划最大尝试次数

缩放系数不是 m/s 或 rad/s，也不构成速度保证。allow_planning_time 不包含轨迹执行时间。

OMPL 字段#

字段	类型	默认值	范围/允许值	作用
`ompl_planner_type`	`str`	`"rrt_connect"`	`"rrt_connect"`、`"rrt_star"`、`"prm"`、`"est"`	选择 OMPL planner
`ompl_longest_valid_segment_fraction`	`float`	`0.01`	`[0.000001,1.0]`	碰撞离散检查的最长有效段比例
`ompl_optimization_objective`	`str`	`"path_length"`	当前模型不校验名称	选择优化目标；没有版本说明时保留默认值
`ompl_simplify_solutions`	`bool`	`True`	`True`/`False`	是否简化搜索路径
`ompl_interpolate`	`bool`	`True`	`True`/`False`	是否对搜索路径插值
`ompl_minimum_waypoint_count`	`int`	`64`	`[2,100000]`	OMPL 插值输出的最少 waypoint 数

这些字段只在实际选择 OMPL 时有意义。它们改变搜索过程，不保证规划成功，也不能检测模型外障碍物。

seed 字段#

字段	类型	默认值	规则
`has_seed_start`	`bool`	`False`	`True` 时才发送起点 seed
`has_seed_goal`	`bool`	`False`	`True` 时才发送终点 seed
`seed_start`	`list[float]`	`[]`	启用时恰好 7 个有限关节角，单位 rad
`seed_goal`	`list[float]`	`[]`	启用时恰好 7 个有限关节角，单位 rad

越过 SDK 关节命令限位的 seed 会夹紧。seed 关闭时，即使数组非空也不会发送。

方法适用矩阵#

字段组	`move_end_pose()` planning	`move_end_pose()` Servo	`move_end_pose()` MIT	LIN	CIRCLE
`eff`	是	是	是	是	是
`motion_type`	是	否	否	固定 LIN	固定 CIRCLE
缩放、采样、规划重试	是	否	使用固定值	是	是
`use_collision`、OMPL	按类型	否	使用固定值	发送基础碰撞字段；OMPL 参数通常不参与 LIN 算法	发送基础碰撞字段；OMPL 参数通常不参与圆弧算法
seed	是	否	否	是	是
`circ_is_center`	没有 path 时无实际圆弧作用	否	否	否	是
`blocking`	是	是	是	是	是
`torque`/`kp`/`kd`	否	否	否	否	否

`EEFMoveOptions`#

EEFMoveOptions 有 5 个字段。适用数组的长度必须等于运行时 eef_dof；模型构造阶段不会统一检查长度，move_eef() 会拒绝错误长度。

字段	类型	默认值	每项范围	CSP	MIT	单位说明
`eff`	`list[float]`	`[8.0]`	`[0,100]`	作为 current threshold 发送	忽略	EEF 驱动原生量，不声明 SI 单位
`torque`	`list[float]`	`[10.0]`	`[-30,30]`	忽略	发送	按具体 EEF 的批准契约确认
`kp`	`list[float]`	`[0.1]`	`[0,5000]`	忽略	发送	有效量纲和稳定范围取决于 EEF
`kd`	`list[float]`	`[0.1]`	`[0,5000]`	忽略	发送	有效量纲和稳定范围取决于 EEF
`blocking`	`bool`	`False`	`True`/`False`	发送，决定是否等待完成判据	忽略	无单位

模型默认数组只有 1 项，适合单自由度模型的形状；它不表示所有 EEF 都只有一个关节。EEF 目标位置和速度限制见末端执行器。

Waypoint options#

JointWaypointsMoveOptions 和 CartesianWaypointsMoveOptions 各有 23 个公开字段。字段结构相同， motion_type 的允许值不同。

序列和边界字段#

字段	类型	默认值	范围/允许值	当前行为
`eff`	`list[float]`	`[70,70,40,40,12,12,12]`	与机械臂 7 轴 `eff` 范围相同，单位待确认	只读取顶层值，应用于整个序列
`motion_type`	`str`	`"ptp"`	关节：`"ptp"`/`"ompl"`；笛卡尔：`"ptp"`/`"lin"`/`"ompl"`	选择顶层默认或当前 segment 类型
`sampling_time`	`float`	`0.01`	`[0.01,0.5] s`	每段发送；整个序列必须相同
`min_blend_radius`	`float`	`0.005`	`[0,10] m`	在末端笛卡尔空间配置当前段结束处的内部边界；关节序列也使用 m
`velocity_scaling_factor`	`float`	`0.4`	`[0.01,1.0]`	当前段速度缩放
`acceleration_scaling_factor`	`float`	`0.3`	`[0.01,1.0]`	当前段加速度缩放
`allow_planning_time`	`float`	`0.5`	`[0.01,60] s`	当前段最大规划计算时间
`enable_blend`	`bool`	`True`	`True`/`False`	是否请求在当前段结束边界混合；最后一段无后续边界
`use_collision`	`bool`	`False`	`True`/`False`	当前段模型碰撞检查；OMPL 自动启用
`circ_is_center`	`bool`	`False`	`True`/`False`	当前公开 waypoint 类型没有圆弧 path，不能据此构造 CIRCLE
`max_retry_attempts`	`int`	`1`	`[1,1000]`	当前段最大规划尝试次数

min_blend_radius 的数值范围不能当作机械臂一定能实现的混合范围；实际结果受段长、几何、速度和运行时约束影响。

Waypoint OMPL 字段#

字段	默认值	范围/允许值	当前行为
`ompl_planner_type`	`"rrt_connect"`	`"rrt_connect"`、`"rrt_star"`、`"prm"`、`"est"`	当前段 planner
`ompl_longest_valid_segment_fraction`	`0.01`	`[0.000001,1.0]`	当前段碰撞离散比例
`ompl_optimization_objective`	`"path_length"`	字符串，模型不校验名称	当前段优化目标
`ompl_simplify_solutions`	`True`	`bool`	是否简化当前段搜索路径
`ompl_interpolate`	`True`	`bool`	是否插值当前段路径
`ompl_minimum_waypoint_count`	`64`	`[2,100000]`	当前段 OMPL 插值最少点数

Waypoint seed、嵌套和完成字段#

字段	类型	默认值	当前行为
`has_seed_start`	`bool`	`False`	为当前段启用 `seed_start`
`has_seed_goal`	`bool`	`False`	为当前段启用 `seed_goal`
`seed_start`	`list[float]`	`[]`	启用时须为 7 个有限关节角，单位 rad；越界夹紧
`seed_goal`	`list[float]`	`[]`	启用时须为 7 个有限关节角，单位 rad；越界夹紧
`segments`	同类型 options 的 `list`	`[]`	长度恰好为 `waypoint_count - 1` 时逐段使用；其他长度静默回退顶层配置
`blocking`	`bool`	`False`	只读取顶层值，决定整个序列是否等待完成；segment 内值不发送

这 23 个字段在两类 waypoint options 中各出现一次。不要在 segments 的元素中继续嵌套 segments；route 只读取一层逐段参数。

路点数量、边界对应关系、错误长度回退和停止方法见路点运动。

发送前的统一检查#

import math


def require_finite(values: list[float], name: str) -> None:
    if not all(math.isfinite(float(value)) for value in values):
        raise ValueError(f"{name} contains a non-finite value")

实际应用还应按接口补齐：

检查 options 类型、全部标量有限值和正式枚举值；
检查 eff、seed、MIT/EEF 向量的预期长度；
检查 waypoint segments 的精确数量和统一 sampling_time；
检查 CartesianPose 的单位、坐标系和四元数；
打印最终将发送的配置，而不是只打印业务层原始输入；
根据笛卡尔运动、路点运动或末端执行器完成模式与安全检查。