JointMoveOptions 参数

`JointMoveOptions` 参数#

JointMoveOptions 同时承载 planning、Servo 和 MIT 三类关节命令的参数。当前控制模式决定哪些字段生效；其余字段会被忽略。创建对象不代表参数组合适合当前机械臂，运动前仍要完成模式、状态和现场检查。

from arm_p7_sdk import JointMoveOptions

options = JointMoveOptions(
    motion_type="ptp",
    use_collision=True,
    velocity_scaling_factor=0.1,
    acceleration_scaling_factor=0.1,
    allow_planning_time=5.0,
    blocking=True,
)

参数在哪种模式生效#

字段组	planning	Servo	MIT
`eff`	规划轨迹执行的每关节执行阈值（单位随交付配置确认）	Servo 位置命令的每关节执行阈值	忽略
`motion_type`、规划缩放与采样参数	生效	忽略	忽略
`use_collision`、OMPL 与 seed 参数	按运动类型生效	忽略	忽略
`torque`、`kp`、`kd`	忽略	忽略	生效
`blocking`	`True` 等待轨迹执行完成；`False` 等待规划结果后返回	`True` 等待关节到达判据；`False` 只发送一帧目标	忽略

通用执行参数#

`eff`#

eff 是 7 个机械臂关节的执行阈值。SDK 模型没有声明物理单位；当前 route 工具把同名 current_threshold 参数按 A 展示，而服务端执行字段又称 max_torque。在所用产品版本的交付配置确认前，不要把数值换算成 N·m，也不要把它当作状态反馈或目标力矩。

关节	SDK 数值范围	默认值
J1、J2	`[0, 70]`	`70`
J3、J4	`[0, 40]`	`40`
J5、J6、J7	`[0, 12]`	`12`

每项超出范围时，JointMoveOptions 构造或赋值会抛出 ValueError。当前选项模型不检查数组长度； move_joint() 收到非 7 项 eff 时会静默改用整组默认值。为避免实际阈值与配置不符，始终显式传 7 项，或完整使用默认值。

`blocking`#

类型为 bool，默认 False。它不改变规划算法，只改变方法何时返回：

planning + False：route 等到规划结果后返回，轨迹可能仍在执行；True：等待执行完成或失败；
Servo + False：发送一帧流式目标；True：等待关节误差满足服务端完成判据；
MIT：请求中没有 blocking 字段，此值被忽略。

blocking=True 的 True 是当前命令完成判据成功，不是永久安全状态。返回后仍应检查关节反馈和 FSM 状态。timeout_ms 属于 move_joint()，不在选项对象中。

规划参数#

这些字段只在 Controller.planning_control 下使用。

字段	类型	默认值	允许值/单位	作用
`motion_type`	`str`	`"ptp"`	`"ptp"`、`"lin"`、`"ompl"`	选择关节规划类型
`use_collision`	`bool`	`False`	`True`/`False`	请求规划器执行碰撞检查；OMPL 会强制为 `True`
`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`	单次规划允许使用的最长计算时间
`max_retry_attempts`	`int`	`1`	`[1, 1000]`	规划失败后的最大尝试次数

标量越界会在构造或赋值时抛出 ValueError。缩放系数为比例，没有 rad/s 或 rad/s² 单位；实际速度和加速度还受规划模型、运行配置、关节限位及执行器约束限制。

motion_type 的行为：

"ptp"：确定性的关节空间点到点规划，是单次关节运动的默认选择；
"lin"：公开类型允许该值，但当前运行时会把关节 waypoint 的 LINEAR 请求归一为 PTP。它不保证末端沿笛卡尔直线运动；笛卡尔 LIN 由对应的笛卡尔接口处理；
"ompl"：使用 OMPL 搜索并自动启用碰撞检查，适合需要绕开模型内障碍的关节路径。

Python 的 Literal 注解不会在运行时校验字符串。当前后端会把其他字符串落到 OMPL 分支，但这不是公开兼容行为；不要使用 "rrt_connect" 等旧示例字符串代替 "ompl"。

allow_planning_time 只限制规划计算，不是整个 SDK 调用的 deadline，也不包含轨迹执行时间。二者的区别见阻塞、超时和完成。

OMPL 参数#

以下字段仅在 motion_type="ompl" 时生效。

字段	默认值	允许值/范围	作用
`ompl_planner_type`	`"rrt_connect"`	`"rrt_connect"`、`"rrt_star"`、`"prm"`、`"est"`	选择 OMPL 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]`	插值输出的最少 waypoint 数

SDK 会校验两个数值范围，但不会校验 ompl_optimization_objective 的名称。没有与所用规划服务版本匹配的取值说明时，保留默认 "path_length"。这些参数改变搜索过程，不构成规划必定成功或无碰撞的保证；规划模型没有包含的工装、线缆和现场障碍也不会凭空进入碰撞检查。

规划 seed#

字段	默认值	规则
`has_seed_start`	`False`	`True` 时才发送 `seed_start`
`seed_start`	`[]`	启用时必须为 7 个有限关节角，单位 rad
`has_seed_goal`	`False`	`True` 时才发送 `seed_goal`
`seed_goal`	`[]`	启用时必须为 7 个有限关节角，单位 rad

seed 角度超出关节命令限位时会先夹紧再发送。禁用对应 has_seed_* 时，数组内容被忽略。基础 PTP 运动通常不需要 seed；只有明确知道规划器如何使用 seed 时才启用。

circ_is_center 也是公开字段，类型为 bool、默认 False。move_joint() 不提供圆弧中间点，且公开 motion_type 不包含 "circ"，因此该字段对单次关节运动没有效果。

MIT 参数#

这些字段只在 Controller.mit_control 下生效，且都应传 7 项。

字段	默认值	每项范围	含义
`torque`	`[3.5] * 7`	`[-2, 7] N·m`	每关节前馈力矩命令
`kp`	`[0.1] * 7`	`[0, 5000]`	位置误差比例增益
`kd`	`[0.1] * 7`	`[0, 5000]`	速度误差微分增益

MIT 命令还使用 move_joint(pos=...) 作为目标位置，并把 SDK 当前关节速度数组作为目标速度；该数组初始为每轴 π/3 rad/s，调用 set_arm_speed() 会覆盖它。kp、kd 的有效量纲和稳定参数取决于电机控制实现、负载及整机配置，数值范围不能当作推荐调参区间。

数组元素越界会抛出 ValueError，但长度不等于 7 时，move_joint() 会把对应整组 torque、kp 或 kd 静默替换为 7 个零。此回退可能显著改变机械臂行为，因此不要依赖它纠正参数。

构造和修改时的错误#

标量或向量元素超出上述范围：抛出 ValueError；
向量不是 list，或元素不是数字：抛出 TypeError；
motion_type、planner 名和布尔字段主要依赖类型注解，运行时校验并不完整；
选项向量长度通常到 move_joint() 才处理，且不同字段的回退方式不同。

在发送命令前显式检查模式、所有数组长度和有限值。完整调用前置、关节限位和安全示例见关节运动。笛卡尔、EEF 和 waypoint 的 options 不与本模型完全相同，见运动参数参考。

JointMoveOptions 参数#