机械臂操作

本模块提供双臂机械臂的操作功能,包括关节/笛卡尔空间运动、运动学解算、轨迹规划与执行、位姿库与轨迹库管理、轨迹录制回放、关节读取以及控制器切换等。

Note

move_joint / move_tool / move_to_pose / execute_path / play_trajectory 为可阻塞函数：block=True（默认）同步阻塞至运动完成，block=False 立即返回、运动在后台继续。 timeout 为等待 Umi 服务应答的最长秒数,``block=True`` 时须 >= 整段运动时长; 超时不等于停止,主动取消请调用 stop_motion`(通用任务被 task_template 暂停/停止时会自动经 ``stop_motion`() 协作取消)。

核心功能

关节与末端运动

move_joint(joint_names=[], target_positions=[], velocity=0.0, acceleration=0.0, block=True, relative=False, profile='', planning_group='', timeout=60)

关节空间运动到目标关节角。block=True（默认）同步阻塞直到运动完成（通用任务脚本会在此处等待）；block=False 立即返回，运动在机器人后台继续执行。timeout 为等待 Umi 服务应答的最长秒数：block=True 时必须 >= 整段运动预计时长，否则客户端超时但机械臂仍在运动；超时不等于停止，主动取消请调用 stop_motion（通用任务被 task_template 暂停/停止时会自动经 stop_motion 协作取消）。

Parameters:

• joint_names (list[str]) – 关节名称列表，与 target_positions 一一对应；不填/传空列表/传 ALL_JOINTS 表示作用于所有关节（default: ALL_JOINTS，即 []）

• target_positions (list[float]) – 目标关节角度列表（单位：度），必填不可为空；joint_names 非空时长度需与之一致

• velocity (float) – 关节速度比例（0.0 表示使用默认速度）（default: 0.0）

• acceleration (float) – 关节加速度比例（0.0 表示使用默认加速度）（default: 0.0）

• block (bool) – True 同步阻塞至运动完成，False 立即返回后台执行（default: True）

• relative (bool) – True 时 target_positions 为相对当前关节角的增量（default: False）

• profile (str) – 运动规划配置档名称，空表示默认（default: “”）

• planning_group (str) – 规划组名称，空表示默认规划组（default: “”）

• timeout (int) – 等待服务应答的最长秒数，block=True 时须 >= 运动时长（default: 60）

Returns:

关节运动响应，state.code==0 表示成功；response 为 UmiMoveJointResponse（success/message）

Return type:

MoveJointResponse

Examples:

from daystar_api.lowlevel_skills import move_joint

resp = move_joint(
    joint_names=["joint1", "joint2", "joint3"],
    target_positions=[0.0, 0.5, -0.3],
    block=True,
    timeout=60,
)
if resp.state.code == 0:
    print("关节运动完成")
else:
    print("运动失败:", resp.state.describe)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/MoveJoint

• 名称: /umi/move_joint

• 参数映射:

封装参数	原生字段（Request）
joint_names	joint_names（关节名列表；空列表/ALL_JOINTS = 作用于全部关节）
target_positions	target_positions（目标关节角列表；封装接口按度传入，C++ 原样透传无换算；.srv 注释称单位取决于服务端配置 “in radians or degrees based on configuration”）
velocity	velocity（速度比例，0 = 服务端默认）
acceleration	acceleration（加速度比例，0 = 服务端默认）
block	block（服务端据此决定是否等运动完成后再应答）
relative	relative（True = 相对当前关节角的增量）
profile	profile（轨迹 profile 类型，空 = 默认）
planning_group	planning_group（规划组，如 “left_arm”/”right_arm”/”dual_arm”，空 = 默认）
timeout	客户端等待服务应答时长，不下发

move_tool(left_pose={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, right_pose={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, velocity=0.0, acceleration=0.0, block=True, profile='', relative=False, frame_id='', cartesian=False, timeout=60)

笛卡尔空间末端运动，控制左/右臂末端运动到指定 CartesianTarget 位姿。block=True（默认）同步阻塞至运动完成，block=False 立即返回后台执行。timeout 为等待 Umi 服务应答的最长秒数，block=True 时须 >= 运动时长，否则客户端超时但机械臂仍在运动；超时不等于停止，主动取消请调用 stop_motion（通用任务被 task_template 暂停/停止时会自动经 stop_motion 协作取消）。

Parameters:

• left_pose (CartesianTarget) – 左臂目标末端位姿（x/y/z 米、rpy 角度（单位：度）），默认空目标表示不动左臂（default: CartesianTarget()）

• right_pose (CartesianTarget) – 右臂目标末端位姿，默认空目标表示不动右臂（default: CartesianTarget()）

• velocity (float) – 末端速度比例（0.0 表示使用默认速度）（default: 0.0）

• acceleration (float) – 末端加速度比例（0.0 表示使用默认加速度）（default: 0.0）

• block (bool) – True 同步阻塞至运动完成，False 立即返回后台执行（default: True）

• profile (str) – 运动规划配置档名称，空表示默认（default: “”）

• relative (bool) – True 时目标位姿为相对当前位姿的增量（default: False）

• frame_id (str) – 目标位姿参考坐标系，空表示默认（default: “”）

• cartesian (bool) – True 时走笛卡尔直线插补路径（default: False）

• timeout (int) – 等待服务应答的最长秒数，block=True 时须 >= 运动时长（default: 60）

Returns:

末端运动响应，state.code==0 表示成功；response 为 UmiMoveToolResponse（success/message）

Return type:

MoveToolResponse

Examples:

from daystar_api.lowlevel_skills import move_tool, CartesianTarget

target = CartesianTarget()
target.x = 0.4
target.y = 0.1
target.z = 0.3
resp = move_tool(left_pose=target, block=True, timeout=60)
if resp.state.code == 0:
    print("末端运动完成")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/MoveTool

• 名称: /umi/move_tool

• 参数映射:

封装参数	原生字段（Request）
left_pose	left_pose（umi_msgs/CartesianTarget：x/y/z 米、rpy 度——封装层约定单位，透传无换算；空目标 = 不动左臂）
right_pose	right_pose（同 left_pose，作用于右臂）
velocity	velocity（速度比例 0-1，0 = 服务端默认）
acceleration	acceleration（加速度比例 0-1，0 = 服务端默认）
block	block（服务端据此决定是否等运动完成后再应答）
profile	profile（轨迹 profile 类型，如 “trapezoidal”/”spring_damper”）
relative	relative（True = 相对当前位姿的增量）
frame_id	frame_id（目标位姿参考坐标系）
cartesian	cartesian（True = 笛卡尔直线插补路径）
timeout	客户端等待服务应答时长，不下发

move_to_pose(pose_name, velocity=0.0, acceleration=0.0, block=True, left_offset={'x': 0.0, 'y': 0.0, 'z': 0.0}, right_offset={'x': 0.0, 'y': 0.0, 'z': 0.0}, timeout=60)

运动到位姿库中已保存的命名位姿，可对左/右臂施加额外平移偏移。block=True（默认）同步阻塞至到位，block=False 立即返回后台执行。timeout 为等待 Umi 服务应答的最长秒数，block=True 时须 >= 运动时长，否则客户端超时但机械臂仍在运动；超时不等于停止，主动取消请调用 stop_motion（通用任务被 task_template 暂停/停止时会自动经 stop_motion 协作取消）。

Parameters:

• pose_name (str) – 位姿库中已保存的位姿名称

• velocity (float) – 运动速度比例（0.0 表示使用默认速度）（default: 0.0）

• acceleration (float) – 运动加速度比例（0.0 表示使用默认加速度）（default: 0.0）

• block (bool) – True 同步阻塞至到位，False 立即返回后台执行（default: True）

• left_offset (Vector3) – 左臂目标位姿的平移偏移（米）（default: Vector3()）

• right_offset (Vector3) – 右臂目标位姿的平移偏移（米）（default: Vector3()）

• timeout (int) – 等待服务应答的最长秒数，block=True 时须 >= 运动时长（default: 60）

Returns:

运动到位姿响应，state.code==0 表示成功；response 为 UmiMoveToPoseResponse（success/message）

Return type:

MoveToPoseResponse

Examples:

from daystar_api.lowlevel_skills import move_to_pose, Vector3

offset = Vector3()
offset.z = 0.05
resp = move_to_pose(pose_name="home", left_offset=offset, block=True, timeout=60)
if resp.state.code == 0:
    print("已到达目标位姿")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/MoveToPose

• 名称: /umi/move_to_pose

• 参数映射:

封装参数	原生字段（Request）
pose_name	pose_name（位姿库中的位姿名）
velocity	velocity（速度比例 0-1，0 = 服务端默认）
acceleration	acceleration（加速度比例 0-1，0 = 服务端默认）
block	block（服务端据此决定是否等运动完成后再应答）
left_offset	left_offset（geometry_msgs/Vector3，相对位姿的平移偏移，米）
right_offset	right_offset（同 left_offset，作用于右臂）
timeout	客户端等待服务应答时长，不下发

stop_motion(timeout=5)

立即停止机械臂当前运动。可用于取消 block=False 后台运动，或在异常情况下急停。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 5）

Returns:

停止响应，state.code==0 表示成功；response 为 UmiStopMotionResponse（success/message）

Return type:

StopMotionResponse

Examples:

from daystar_api.lowlevel_skills import move_joint, stop_motion

move_joint(joint_names=["joint1"], target_positions=[1.0], block=False)
# 后台运动中，需要时立即停止
resp = stop_motion()
if resp.state.code == 0:
    print("已停止运动")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/StopMotion

• 名称: /umi/stop_motion

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

夹爪控制

open_gripper(timeout=10)

打开夹爪到完全张开位（仅 piper 单臂执行器支持夹爪服务；不支持时 service_appear_timeout）。底层走 umi /open_gripper（std_srvs/Trigger），由 piper 端默认力 1.5N 推到 GRIPPER_OPEN_POSITION（0.035m），同步等待到位（容差 1mm）或超时（3s）。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

打开夹爪响应，state.code==0 表示成功；response 为 Trigger_Response（success/message）

Return type:

OpenGripperResponse

Examples:

from daystar_api.lowlevel_skills import open_gripper

resp = open_gripper()
if resp.state.code == 0:
    print("夹爪已打开")
else:
    print("失败:", resp.state.describe)

底层 ROS2 接口

• 类型: Service std_srvs/srv/Trigger

• 名称: /umi/open_gripper

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

close_gripper(timeout=10)

关闭夹爪到完全闭合位（；不支持时 service_appear_timeout）。底层走 umi /close_gripper（std_srvs/Trigger），由 piper 端默认力 1.5N 推到 GRIPPER_CLOSE_POSITION（0.0m），同步等待到位（容差 1mm）或超时（3s）。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

关闭夹爪响应，state.code==0 表示成功；response 为 Trigger_Response（success/message）

Return type:

CloseGripperResponse

Examples:

from daystar_api.lowlevel_skills import close_gripper

resp = close_gripper()
if resp.state.code == 0:
    print("夹爪已关闭")
else:
    print("失败:", resp.state.describe)

底层 ROS2 接口

• 类型: Service std_srvs/srv/Trigger

• 名称: /umi/close_gripper

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

move_gripper(position, effort=0.0, block=True, timeout=10)

把夹爪移动到指定开度（米）。不支持时 service_appear_timeout。底层走 umi /move_gripper（umi_msgs/MoveGripper.srv）：position 取值 [0, 0.035] 米（0 = 闭合，0.035 = 完全张开，越界由服务端裁剪）；effort 单位 N，服务端钳制到 [0.5, 3.0]，传 0 用 piper_ctrl_single_node 默认 1.5N。block=True 等到位（1mm 容差）或 3s 服务端超时；block=False 立即返回。

Parameters:

• position (float) – 目标夹爪开度（米），有效区间 [0, 0.035]，越界自动裁剪

• effort (float) – 夹持力（N），传 0 用默认 1.5N；非 0 时服务端钳到 [0.5, 3.0]（default: 0.0）

• block (bool) – True 等到位/超时再返回，False 立即返回（default: True）

• timeout (int) – 等待服务应答的最长秒数，block=True 时须 >= 服务端 3s 内置超时（default: 10）

Returns:

移动夹爪响应，state.code==0 表示成功；response 为 UmiMoveGripperResponse（success/message/final_position）

Return type:

MoveGripperResponse

Examples:

from daystar_api.lowlevel_skills import move_gripper

# 半开，用默认力，等到位
resp = move_gripper(position=0.02)
if resp.state.code == 0:
    print("到位，实际位置:", resp.response.final_position)

# 加大夹持力到 2N 闭合
move_gripper(position=0.0, effort=2.0)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/MoveGripper

• 名称: /umi/move_gripper

• 参数映射:

封装参数	原生字段（Request）
position	position（米，有效区间 0~0.035，越界由服务端裁剪；0 = 闭合，0.035 = 完全张开）
effort	effort（牛，服务端钳制到 [0.5, 3.0]；0 = 节点默认 1.5 N）
block	block（true = 服务端等到位或其内置超时后再应答）
timeout	客户端等待服务应答时长，不下发

操作技能

操作团队提供的整体技能服务（/umi/*_skill）：一次调用走完识别→移臂→夹取/放置/按压 的完整流程，无需手动拼微操接口。三个接口均支持 block=False 异步：立即返回， resp.future 挂结果句柄。等待取回用统一手势 resp.wait_for(timeout)``（True=完成）/ ``resp.get(timeout)``（取回 srv Response，超时或取消返回 ``None；同步调用直接返回 已有结果，下游代码无需区分 block 模式），等价于 resp.future.wait_for/get。

grasp_skill(timeout=90, block=True)

整体抓取技能：对眼前物体执行完整抓取流程（识别、移臂、闭合夹爪一气呵成），无需手动拼微操接口。调用前机器人应已到位、物体在可抓范围内。

Parameters:

• timeout (int) – block=True 时等待技能完成的最长秒数（default: 90）

• block (bool) – True 同步阻塞至技能完成；False 异步发出立即返回，结果经 resp.future 取回（default: True）

Returns:

block=True 时 state.code==0 表示成功，response 为 Trigger_Response（success/message，message 常含抓到了什么/夹持力等信息）；block=False 时 resp.future 非空（GraspSkillFuture）；等待取回用统一手势 resp.wait_for(timeout)（True=完成）与 resp.get(timeout)（返回 Trigger_Response，超时/取消返回 None；同步调用直接返回已有结果），等价于 resp.future.wait_for/get

Return type:

GraspSkillResponse

Examples:

from daystar_api.lowlevel_skills import grasp_skill

# 同步：等抓完
resp = grasp_skill(timeout=90)
if resp.state.code == 0:
    print("抓取完成：", resp.response.message)

# 异步：立即返回，先干别的，稍后取结果
resp = grasp_skill(block=False)
...  # 其他步骤
result = resp.get(timeout=120)
if result and result.success:
    print("抓取完成：", result.message)

底层 ROS2 接口

• 类型: Service std_srvs/srv/Trigger

• 名称: /umi/grasp_skill

• 参数映射:

place_skill(tableheight, timeout=60, block=True)

整体放置技能：把已抓取的物体放到指定高度的台面上。调用前夹爪应已持有物体。

Parameters:

• tableheight (float) – 目标台面高度（米），如桌面 0.75

• timeout (int) – block=True 时等待技能完成的最长秒数（default: 60）

• block (bool) – True 同步阻塞至技能完成；False 异步发出立即返回，结果经 resp.future 取回（default: True）

Returns:

block=True 时 state.code==0 表示成功，response 为 UmiPlaceInputResponse（success/message）；block=False 时 resp.future 非空（PlaceSkillFuture）；等待取回用统一手势 resp.wait_for(timeout)（True=完成）与 resp.get(timeout)（返回 UmiPlaceInputResponse，超时/取消返回 None；同步调用直接返回已有结果），等价于 resp.future.wait_for/get

Return type:

PlaceSkillResponse

Examples:

from daystar_api.lowlevel_skills import place_skill

resp = place_skill(tableheight=0.75)
if resp.state.code == 0:
    print("已放置到台面")

# 异步
resp = place_skill(tableheight=0.75, block=False)
result = resp.get(timeout=90)
if result and result.success:
    print("已放置到台面")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/PlaceInput

• 名称: /umi/place_skill

• 参数映射:

封装参数	原生字段（Request）
tableheight	tableheight（目标台面高度，米）
timeout	客户端等待服务应答时长，不下发
block	客户端行为参数，不下发；同 grasp_skill

push_skill(button_id, pre_offset={'x': 0.0, 'y': 0.0, 'z': 0.0}, push_offset={'x': 0.0, 'y': 0.0, 'z': 0.0}, timeout=60, block=True)

按压按钮技能：对识别到的按钮执行预压+按压动作。pre_offset / push_offset 为相对按钮检测点的三维偏移（米），按需微调按压落点。

Parameters:

• button_id (int) – 目标按钮编号

• pre_offset (Vector3) – 预压点相对按钮检测点的偏移（米）（default: Vector3()）

• push_offset (Vector3) – 按压点相对按钮检测点的偏移（米）（default: Vector3()）

• timeout (int) – block=True 时等待技能完成的最长秒数（default: 60）

• block (bool) – True 同步阻塞至技能完成；False 异步发出立即返回，结果经 resp.future 取回（default: True）

Returns:

block=True 时 state.code==0 表示成功，response 为 UmiPushButtonResponse（success/message/pre_push_point/push_point）；block=False 时 resp.future 非空（PushSkillFuture）；等待取回用统一手势 resp.wait_for(timeout)（True=完成）与 resp.get(timeout)（返回 UmiPushButtonResponse，超时/取消返回 None；同步调用直接返回已有结果），等价于 resp.future.wait_for/get

Return type:

PushSkillResponse

Examples:

from daystar_api.lowlevel_skills import push_skill, Vector3

pre = Vector3()   # x=0.0, y=0.019, z=-0.005 按需设置
push = Vector3()
push.x = 0.025
resp = push_skill(button_id=0, pre_offset=pre, push_offset=push)
if resp.state.code == 0:
    print("按压完成，按点：", resp.response.push_point)

# 异步
resp = push_skill(button_id=0, block=False)
result = resp.get(timeout=90)
if result and result.success:
    print("按压完成，按点：", result.push_point)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/PushButton

• 名称: /umi/push_skill

• 参数映射:

封装参数	原生字段（Request）
button_id	button_id（目标按钮编号）
pre_offset	pre_offset（预压点相对按钮检测点的偏移，米）
push_offset	push_offset（按压点相对按钮检测点的偏移，米）
timeout	客户端等待服务应答时长，不下发
block	客户端行为参数，不下发；同 grasp_skill

运动学解算

compute_fk(joint_positions, timeout=10)

正运动学计算：根据给定关节角解算左/右臂末端位姿。纯计算请求，不产生机械臂运动。

Parameters:

• joint_positions (list[float]) – 关节角度列表（单位：度）

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

正运动学响应，state.code==0 表示成功；response 为 UmiComputeFKResponse，关键 payload 为 left_target_pose / right_target_pose（CartesianTarget）

Return type:

ComputeFKResponse

Examples:

from daystar_api.lowlevel_skills import compute_fk

resp = compute_fk(joint_positions=[0.0, 0.5, -0.3, 0.0, 0.0, 0.0])
if resp.state.code == 0:
    left = resp.response.left_target_pose
    print("左臂末端位置:", left.x, left.y, left.z)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/ComputeFK

• 名称: /umi/compute_forward_kinematics

• 参数映射:

封装参数	原生字段（Request）
joint_positions	joint_positions（关节角列表；封装接口按度传入，C++ 原样透传无换算；.srv 未注明单位）
timeout	客户端等待服务应答时长，不下发

compute_ik(left_target_pose={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, right_target_pose={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, timeout=10)

逆运动学计算：根据给定左/右臂末端位姿解算关节角。纯计算请求，不产生机械臂运动。

Parameters:

• left_target_pose (CartesianTarget) – 左臂目标末端位姿，默认空目标（default: CartesianTarget()）

• right_target_pose (CartesianTarget) – 右臂目标末端位姿，默认空目标（default: CartesianTarget()）

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

逆运动学响应，state.code==0 表示成功；response 为 UmiComputeIKResponse，关键 payload 为 joint_positions（list[float]）

Return type:

ComputeIKResponse

Examples:

from daystar_api.lowlevel_skills import compute_ik, CartesianTarget

target = CartesianTarget()
target.x = 0.4
target.z = 0.3
resp = compute_ik(left_target_pose=target)
if resp.state.code == 0:
    print("解算关节角:", resp.response.joint_positions)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/ComputeIK

• 名称: /umi/compute_inverse_kinematics

• 参数映射:

封装参数	原生字段（Request）
left_target_pose	left_target_pose（umi_msgs/CartesianTarget：x/y/z 米、rpy 度——封装层约定单位，透传无换算）
right_target_pose	right_target_pose（同 left_target_pose，作用于右臂）
timeout	客户端等待服务应答时长，不下发

轨迹规划与执行

plan_trajectory(left_target={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, right_target={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, joint_positions=[], joint_names=[], cartesian=False, max_step=0.0025, cartesian_fraction_threshold=0.0, frame_id='base_link', tolerance_position=0.001, tolerance_orientation=0.0, tolerance_joint_position=0.0, velocity=0.0, acceleration=0.0, timeout=30)

规划一段运动轨迹（关节空间或笛卡尔空间），仅做规划不执行运动；规划结果可交由 execute_path 执行。

Parameters:

• left_target (CartesianTarget) – 左臂笛卡尔目标位姿，默认空目标（default: CartesianTarget()）

• right_target (CartesianTarget) – 右臂笛卡尔目标位姿，默认空目标（default: CartesianTarget()）

• joint_positions (list[float]) – 关节空间目标角度（单位：度），与 joint_names 配合（default: []）

• joint_names (list[str]) – 关节名称列表，与 joint_positions 一一对应（default: []）

• cartesian (bool) – True 时走笛卡尔直线插补规划（default: False）

• max_step (float) – 笛卡尔插补步长（米）（default: 0.0025）

• cartesian_fraction_threshold (float) – 笛卡尔规划可接受的最小完成比例阈值（default: 0.0）

• frame_id (str) – 目标位姿参考坐标系（default: “base_link”）

• tolerance_position (float) – 位置容差（米）（default: 0.001）

• tolerance_orientation (float) – 姿态容差（单位：度），传 0 用服务端默认（约 0.057°，即 0.001 rad）（default: 0.0）

• tolerance_joint_position (float) – 关节位置容差（单位：度），传 0 用服务端默认（约 0.057°，即 0.001 rad）（default: 0.0）

• velocity (float) – 时间参数化的速度缩放比例（0~1），决定规划出的轨迹时序——也就是这条轨迹后续交给 execute_path 执行时的快慢；传 0 用服务端节点默认（<group>.velocity_scaling）（default: 0.0）

• acceleration (float) – 时间参数化的加速度缩放比例（0~1），同样只影响轨迹时序；传 0 用服务端节点默认（<group>.acceleration_scaling）（default: 0.0）

• timeout (int) – 等待服务应答的最长秒数（default: 30）

Returns:

轨迹规划响应，state.code==0 表示成功；response 为 UmiPlanTrajectoryResponse，关键 payload 为 trajectory（JointTrajectory）/ fraction_achieved（float）

• trajectory: trajectory_msgs/JointTrajectory，规划出的关节轨迹，可直接传给 execute_path

• fraction_achieved: 笛卡尔直线规划的完成度（0~1）

Return type:

PlanTrajectoryResponse

Examples:

from daystar_api.lowlevel_skills import plan_trajectory, CartesianTarget

target = CartesianTarget()
target.x = 0.4
target.z = 0.3
# velocity=0.3 让规划出的轨迹时序放慢到 30%，execute_path 执行时更平缓
resp = plan_trajectory(left_target=target, cartesian=True, velocity=0.3)
if resp.state.code == 0:
    print("规划完成比例:", resp.response.fraction_achieved)
    traj = resp.response.trajectory

Note

• 轨迹快慢由本函数的 velocity/acceleration 在**规划期**定死（写进轨迹点的 time_from_start）； execute_path 只按既定时序执行，无法再调速。想改速度必须重新 plan_trajectory。

• cartesian=True 时 MoveIt 沿直线逐点求 IK，中途遇关节限位/奇异/碰撞不报错，只返回走了一部分的 轨迹。fraction_achieved < 1.0 表示执行这条轨迹到不了请求的目标位姿——要求严格直线到位的场景 （如按压）必须检查此值。关节空间规划无此概念，成功时为 1.0。

底层 ROS2 接口

• 类型: Service umi_msgs/srv/PlanTrajectory

• 名称: /umi/plan_trajectory

• 参数映射:

封装参数	原生字段（Request）
left_target	left_target（umi_msgs/CartesianTarget，左臂笛卡尔目标）
right_target	right_target（umi_msgs/CartesianTarget，右臂笛卡尔目标）
joint_positions	joint_positions（关节空间目标角度，度——.srv 注明 degrees，透传无换算）
joint_names	joint_names（与 joint_positions 一一对应）
cartesian	cartesian（True = 笛卡尔插补规划，False = 关节空间规划）
max_step	max_step（笛卡尔插补步长，米）
cartesian_fraction_threshold	cartesian_fraction_threshold（可接受的最小规划完成比例 0-1）
frame_id	frame_id（笛卡尔目标参考坐标系）
tolerance_position	tolerance_position（位置容差，米）
tolerance_orientation	tolerance_orientation（姿态容差，度；0 = 服务端默认约 0.057°/0.001 rad）
tolerance_joint_position	tolerance_joint_position（关节位置容差，度；0 = 服务端默认约 0.057°/0.001 rad）
velocity	velocity（时间参数化的速度缩放 0-1，决定规划出的轨迹时序；0 = 服务端节点默认 <group>.velocity_scaling）
acceleration	acceleration（时间参数化的加速度缩放 0-1，同样只影响轨迹时序；0 = 服务端节点默认 <group>.acceleration_scaling）
timeout	客户端等待服务应答时长，不下发

execute_path(trajectory, block=True, timeout=120)

执行给定的 JointTrajectory 关节轨迹路径（通常来自 plan_trajectory 的结果）。block=True（默认）同步阻塞至执行完成，block=False 立即返回后台执行。timeout 为等待 Umi 服务应答的最长秒数，block=True 时须 >= 整段轨迹执行时长（默认 120s，长轨迹请调大），否则客户端超时但机械臂仍在运动；超时不等于停止，主动取消请调用 stop_motion（通用任务被 task_template 暂停/停止时会自动经 stop_motion 协作取消）。

Parameters:

• trajectory (JointTrajectory) – 待执行的关节轨迹（含 joint_names 与 points）

• block (bool) – True 同步阻塞至执行完成，False 立即返回后台执行（default: True）

• timeout (int) – 等待服务应答的最长秒数，block=True 时须 >= 轨迹执行时长（default: 120）

Returns:

路径执行响应，state.code==0 表示成功；response 为 UmiExecutePathResponse（success/message）

Return type:

ExecutePathResponse

Examples:

from daystar_api.lowlevel_skills import plan_trajectory, execute_path, CartesianTarget

target = CartesianTarget()
target.x = 0.4
target.z = 0.3
plan = plan_trajectory(left_target=target)
if plan.state.code == 0:
    resp = execute_path(trajectory=plan.response.trajectory, block=True, timeout=120)
    if resp.state.code == 0:
        print("轨迹执行完成")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/ExecutePath

• 名称: /umi/execute_path

• 参数映射:

封装参数	原生字段（Request）
trajectory	trajectory（trajectory_msgs/JointTrajectory，整条轨迹原样下发）
block	block（服务端据此决定是否等执行完成后再应答）
timeout	客户端等待服务应答时长，不下发

位姿库管理

save_pose(pose_name, joint_names=[], joint_positions=[], left_cartesian_target={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, right_cartesian_target={'rpy': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'x': 0.0, 'y': 0.0, 'z': 0.0}, reference_frame='base_link', description='', timeout=10)

将一个命名位姿保存到位姿库。可保存关节空间数据（joint_names/joint_positions）或笛卡尔空间目标（left/right_cartesian_target）。

Parameters:

• pose_name (str) – 位姿名称，作为位姿库中的唯一标识

• joint_names (list[str]) – 关节名称列表（default: []）

• joint_positions (list[float]) – 关节角度列表（单位：度），与 joint_names 对应（default: []）

• left_cartesian_target (CartesianTarget) – 左臂笛卡尔目标位姿（default: CartesianTarget()）

• right_cartesian_target (CartesianTarget) – 右臂笛卡尔目标位姿（default: CartesianTarget()）

• reference_frame (str) – 参考坐标系（default: “base_link”）

• description (str) – 位姿描述文本（default: “”）

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

保存位姿响应，state.code==0 表示成功；response 为 UmiSavePoseResponse（success/message）

Return type:

SavePoseResponse

Examples:

from daystar_api.lowlevel_skills import save_pose

resp = save_pose(
    pose_name="home",
    joint_names=["joint1", "joint2"],
    joint_positions=[0.0, 0.0],
    description="初始位姿",
)
if resp.state.code == 0:
    print("位姿已保存")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/SavePose

• 名称: /umi/save_pose

• 参数映射:

封装参数	原生字段（Request）
pose_name	pose_name（位姿库唯一标识）
joint_names	joint_names（关节名列表）
joint_positions	joint_positions（关节角列表；封装接口按度传入，透传无换算；.srv 未注明单位）
left_cartesian_target	left_cartesian_target（umi_msgs/CartesianTarget；.srv 注释：不提供时留空）
right_cartesian_target	right_cartesian_target（同 left_cartesian_target）
reference_frame	reference_frame（参考坐标系，.srv 默认 “base_link”）
description	description（位姿描述文本）
timeout	客户端等待服务应答时长，不下发

record_pose(pose_name, description='', timeout=10)

记录机械臂当前的末端位姿并以命名方式保存到位姿库（无需手动填写位姿数据，由系统读取当前实际位姿）。

Parameters:

• pose_name (str) – 位姿名称，作为位姿库中的唯一标识

• description (str) – 位姿描述文本（default: “”）

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

记录位姿响应，state.code==0 表示成功；response 为 UmiRecordPoseResponse，关键 payload 为 left_cartesian_target / right_cartesian_target（CartesianTarget）

Return type:

RecordPoseResponse

Examples:

from daystar_api.lowlevel_skills import record_pose

resp = record_pose(pose_name="grasp_ready", description="抓取就绪位姿")
if resp.state.code == 0:
    left = resp.response.left_cartesian_target
    print("已记录左臂位姿:", left.x, left.y, left.z)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/RecordPose

• 名称: /umi/record_current_pose

• 参数映射:

封装参数	原生字段（Request）
pose_name	pose_name（位姿库唯一标识）
description	description（位姿描述文本）
timeout	客户端等待服务应答时长，不下发

get_pose(pose_name, timeout=10)

从位姿库读取指定命名位姿的完整数据（关节角与笛卡尔目标）。

Parameters:

• pose_name (str) – 要查询的位姿名称

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

获取位姿响应，state.code==0 表示成功；response 为 UmiGetPoseResponse，关键 payload 为 joint_names / joint_positions / left_cartesian_target / right_cartesian_target / reference_frame / description

Return type:

GetPoseResponse

Examples:

from daystar_api.lowlevel_skills import get_pose

resp = get_pose(pose_name="home")
if resp.state.code == 0:
    print("关节名:", resp.response.joint_names)
    print("关节角:", resp.response.joint_positions)
    print("描述:", resp.response.description)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/GetPose

• 名称: /umi/get_pose

• 参数映射:

封装参数	原生字段（Request）
pose_name	pose_name（要查询的位姿名）
timeout	客户端等待服务应答时长，不下发

list_poses(timeout=10)

列出位姿库中所有已保存的位姿名称。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

位姿列表响应，state.code==0 表示成功；response 为 UmiListPosesResponse，关键 payload 为 pose_names（list[str]）

Return type:

ListPosesResponse

Examples:

from daystar_api.lowlevel_skills import list_poses

resp = list_poses()
if resp.state.code == 0:
    for name in resp.response.pose_names:
        print("位姿:", name)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/ListPoses

• 名称: /umi/list_poses

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

delete_pose(pose_name, timeout=10)

从位姿库删除指定命名位姿。

Parameters:

• pose_name (str) – 要删除的位姿名称

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

删除位姿响应，state.code==0 表示成功；response 为 UmiDeletePoseResponse（success/message）

Return type:

DeletePoseResponse

Examples:

from daystar_api.lowlevel_skills import delete_pose

resp = delete_pose(pose_name="home")
if resp.state.code == 0:
    print("位姿已删除")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/DeletePose

• 名称: /umi/delete_pose

• 参数映射:

封装参数	原生字段（Request）
pose_name	pose_name（要删除的位姿名）
timeout	客户端等待服务应答时长，不下发

轨迹录制与回放

start_recording(trajectory_name, description='', recording_frequency=0.0, timeout=10)

开始以指定名称录制关节轨迹。配合 stop_recording 结束录制并保存。

Parameters:

• trajectory_name (str) – 轨迹名称，作为轨迹库中的唯一标识

• description (str) – 轨迹描述文本（default: “”）

• recording_frequency (float) – 录制采样频率（Hz），0.0 表示使用默认频率（default: 0.0）

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

开始录制响应，state.code==0 表示成功；response 为 UmiStartRecordingResponse（success/message）

Return type:

StartRecordingResponse

Examples:

from daystar_api.lowlevel_skills import start_recording

resp = start_recording(trajectory_name="wave", description="挥手动作", recording_frequency=50.0)
if resp.state.code == 0:
    print("开始录制轨迹")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/StartRecording

• 名称: /umi/start_recording

• 参数映射:

封装参数	原生字段（Request）
trajectory_name	trajectory_name（轨迹库唯一标识）
description	description（轨迹描述文本）
recording_frequency	recording_frequency（录制采样频率 Hz，0 = 服务端默认 10 Hz）
timeout	客户端等待服务应答时长，不下发

stop_recording(save_trajectory=True, timeout=10)

停止当前轨迹录制，可选择是否保存录制结果到轨迹库。

Parameters:

• save_trajectory (bool) – True 保存录制的轨迹，False 丢弃（default: True）

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

停止录制响应，state.code==0 表示成功；response 为 UmiStopRecordingResponse，关键 payload 为 num_points（int，录制点数）

Return type:

StopRecordingResponse

Examples:

from daystar_api.lowlevel_skills import stop_recording

resp = stop_recording(save_trajectory=True)
if resp.state.code == 0:
    print("录制点数:", resp.response.num_points)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/StopRecording

• 名称: /umi/stop_recording

• 参数映射:

封装参数	原生字段（Request）
save_trajectory	save_trajectory（true = 保存录制结果，false = 丢弃）
timeout	客户端等待服务应答时长，不下发

list_trajectories(timeout=10)

列出轨迹库中所有已保存的轨迹名称及其描述。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

轨迹列表响应，state.code==0 表示成功；response 为 UmiListTrajectoriesResponse，关键 payload 为 trajectory_names（list[str]）/ descriptions（list[str]）

• trajectory_names: 轨迹名列表，可直接交给 play_trajectory / get_trajectory / delete_trajectory

• descriptions: 与 trajectory_names 一一对应（同索引）的描述文本，内容是录制时 start_recording 传入的 description；未填则为空串

Return type:

ListTrajectoriesResponse

Examples:

from daystar_api.lowlevel_skills import list_trajectories

resp = list_trajectories()
if resp.state.code == 0:
    for name, desc in zip(resp.response.trajectory_names, resp.response.descriptions):
        print("轨迹:", name, "描述:", desc)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/ListTrajectories

• 名称: /umi/list_trajectories

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

Response 关键 payload：trajectory_names / descriptions——两者一一对应（同索引）， descriptions 的内容是录制时 start_recording 传入的 description，未填则为空串。

get_trajectory(trajectory_name, timeout=10)

从轨迹库读取指定命名轨迹的完整数据（JointTrajectory）。

Parameters:

• trajectory_name (str) – 要查询的轨迹名称

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

获取轨迹响应，state.code==0 表示成功；response 为 UmiGetTrajectoryResponse，关键 payload 为 trajectory（JointTrajectory）/ description（str）

Return type:

GetTrajectoryResponse

Examples:

from daystar_api.lowlevel_skills import get_trajectory, execute_path

resp = get_trajectory(trajectory_name="wave")
if resp.state.code == 0:
    print("轨迹描述:", resp.response.description)
    execute_path(trajectory=resp.response.trajectory)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/GetTrajectory

• 名称: /umi/get_trajectory

• 参数映射:

封装参数	原生字段（Request）
trajectory_name	trajectory_name（要查询的轨迹名）
timeout	客户端等待服务应答时长，不下发

delete_trajectory(trajectory_name, timeout=10)

从轨迹库删除指定命名轨迹。

Parameters:

• trajectory_name (str) – 要删除的轨迹名称

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

删除轨迹响应，state.code==0 表示成功；response 为 UmiDeleteTrajectoryResponse（success/message）

Return type:

DeleteTrajectoryResponse

Examples:

from daystar_api.lowlevel_skills import delete_trajectory

resp = delete_trajectory(trajectory_name="wave")
if resp.state.code == 0:
    print("轨迹已删除")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/DeleteTrajectory

• 名称: /umi/delete_trajectory

• 参数映射:

封装参数	原生字段（Request）
trajectory_name	trajectory_name（要删除的轨迹名）
timeout	客户端等待服务应答时长，不下发

play_trajectory(trajectory_name, block=True, velocity=0.0, acceleration=0.0, timeout=120)

回放轨迹库中已保存的命名轨迹。block=True（默认）同步阻塞至回放完成，block=False 立即返回后台执行。timeout 为等待 Umi 服务应答的最长秒数，block=True 时须 >= 整段回放时长（默认 120s，长轨迹请调大），否则客户端超时但机械臂仍在运动；超时不等于停止，主动取消请调用 stop_motion（通用任务被 task_template 暂停/停止时会自动经 stop_motion 协作取消）。

Parameters:

• trajectory_name (str) – 轨迹库中已保存的轨迹名称

• block (bool) – True 同步阻塞至回放完成，False 立即返回后台执行（default: True）

• velocity (float) – 回放速度缩放比例。0.0 表示按录制时的原始时序回放；有效范围 (0, 1.0]，传 >1.0 会被服务端压到 1.0——**只允许放慢，不允许加速**（加速回放控制器跟不上录制路径）（default: 0.0）

• acceleration (float) – 加速度缩放比例。当前为空操作（no-op），不产生实际效果——回放会剥掉录制点上的 velocity/acceleration（只保留 position + time_from_start），本参数保留仅为接口兼容（default: 0.0）

• timeout (int) – 等待服务应答的最长秒数，block=True 时须 >= 回放时长（default: 120）

Returns:

轨迹回放响应，state.code==0 表示成功；response 为 UmiPlayTrajectoryResponse（success/message）

Return type:

PlayTrajectoryResponse

Examples:

from daystar_api.lowlevel_skills import play_trajectory

# 原始录制速度回放
resp = play_trajectory(trajectory_name="wave", block=True, timeout=120)
if resp.state.code == 0:
    print("轨迹回放完成")

# 放慢到一半速度回放（相应把 timeout 调大，回放时长翻倍）
play_trajectory(trajectory_name="wave", velocity=0.5, timeout=240)

Note

• 想调回放快慢只用 velocity；acceleration 目前无效，别指望它。

• velocity 变小会让整段回放时长变长，block=True 时 timeout 要同步调大，否则客户端超时但臂仍在动。

底层 ROS2 接口

• 类型: Service umi_msgs/srv/PlayTrajectory

• 名称: /umi/play_trajectory

• 参数映射:

封装参数	原生字段（Request）
trajectory_name	trajectory_name（轨迹库中已保存的轨迹名）
block	block（服务端据此决定是否等回放完成后再应答）
velocity	velocity（回放速度缩放；0 = 按录制原始时序，有效范围 (0, 1.0]，>1.0 被服务端压到 1.0——只允许放慢）
acceleration	acceleration（当前为空操作 no-op，不产生实际效果；回放会剥掉录制点上的 velocity/acceleration，保留仅为接口兼容）
timeout	客户端等待服务应答时长，不下发

状态与读取

read_tcp_pose(timeout=10)

读取机械臂当前 TCP 末端位姿，姿态以四元数表示（Pose）。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

TCP 位姿响应，state.code==0 表示成功；response 为 UmiReadTcpPoseResponse，关键 payload 为 left_pose / right_pose（Pose，含 position 与 orientation 四元数）

Return type:

ReadTcpPoseResponse

Examples:

from daystar_api.lowlevel_skills import read_tcp_pose

resp = read_tcp_pose()
if resp.state.code == 0:
    p = resp.response.left_pose.position
    print("左臂 TCP 位置:", p.x, p.y, p.z)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/ReadTcpPose

• 名称: /umi/read_tcp_pose

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

Response 关键 payload：left_pose / right_pose（geometry_msgs/Pose，base_link 坐标系，姿态为四元数）。

read_tcp_rpy(timeout=10)

读取机械臂当前 TCP 末端位姿，姿态以欧拉角 RPY 表示（CartesianTarget）。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

TCP 位姿响应，state.code==0 表示成功；response 为 UmiReadTcpRPYResponse，关键 payload 为 left_pose / right_pose（CartesianTarget，含 x/y/z 与 rpy）

Return type:

ReadTcpRPYResponse

Examples:

from daystar_api.lowlevel_skills import read_tcp_rpy

resp = read_tcp_rpy()
if resp.state.code == 0:
    left = resp.response.left_pose
    print("左臂位置:", left.x, left.y, left.z, "rpy:", left.rpy.x, left.rpy.y, left.rpy.z)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/ReadTcpRPY

• 名称: /umi/read_tcp_rpy

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

Response 关键 payload：left_pose / right_pose（umi_msgs/CartesianTarget，base_link 坐标系，姿态为 rpy）。

get_current_joints(timeout=10)

获取机械臂**当前规划组**关节的名称与对应角度值（单位：度）。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

当前关节响应，state.code==0 表示成功；response 为 UmiGetCurrentJointsResponse，关键 payload 为 joint_names（list[str]）/ joint_positions（list[float]）

• joint_names: 关节名，顺序与规划组一致，可直接回传给 move_joint / plan_trajectory

• joint_positions: 关节角，单位为**度**，与 joint_names 一一对应

Return type:

GetCurrentJointsResponse

Examples:

from daystar_api.lowlevel_skills import get_current_joints, move_joint

resp = get_current_joints()
if resp.state.code == 0:
    for name, pos in zip(resp.response.joint_names, resp.response.joint_positions):
        print(name, "=", pos, "度")
    # joint_names 与 move_joint 的关节集完全一致，可直接回传
    move_joint(joint_names=resp.response.joint_names,
               target_positions=resp.response.joint_positions)

Note

• 只返回当前规划组的关节，与 move_joint / plan_trajectory 的关节集完全一致： Piper（含夹爪）为 joint1..joint6，**不含夹爪 joint7**（夹爪走 move_gripper）；LX 双臂为左右臂共 14 个关节。

• 与原始 /joint_states 话题**不是一回事**：/joint_states 由 joint_state_broadcaster 发布，含 全部硬件关节（Piper 上多一个夹爪 joint7），单位是**弧度**；本函数只含规划组关节、单位是**度**。 需要按本函数的关节集过滤原始话题时，以本函数返回的 joint_names 为准。

底层 ROS2 接口

• 类型: Service umi_msgs/srv/GetCurrentJoints

• 名称: /umi/get_current_joints

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

Response 关键 payload：joint_names / joint_positions（.srv 注明单位为度）。 作用域为当前规划组——Piper（含夹爪）为 joint1``~``joint6，不含夹爪 joint7（夹爪走 move_gripper）；LX 双臂为左右臂共 14 关节。关节集与 move_joint / plan_trajectory 完全一致， joint_names 可直接回传。注意与原始 /joint_states 话题区分：后者含全部硬件关节、单位是**弧度**。

模式与故障

request_mode(mode, detail='', source='sdk', timeout=10)

切换机械臂模式（替代旧 set_state）。mode 取 “IDLE” / “MOTION” / “SERVO”；SERVO 时 detail 必填 “CARTESIAN” 或 “JOINT”。TEACH / FAULT 不能经此进入。

Parameters:

• mode (str) – 目标模式 “IDLE” / “MOTION” / “SERVO”

• detail (str) – 子状态，SERVO 必填 “CARTESIAN” / “JOINT”（default: “”）

• source (str) – 调用方标识，仅用于日志/审计（default: “sdk”）

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

state.code==0 表示成功；response 为 UmiRequestModeResponse（success/current_mode/current_detail/reason）

Return type:

RequestModeResponse

Examples:

from daystar_api.lowlevel_skills import request_mode

resp = request_mode(mode="SERVO", detail="JOINT")
if resp.state.code == 0:
    print("已进入 SERVO/JOINT，当前模式：", resp.response.current_mode)

底层 ROS2 接口

• 类型: Service umi_msgs/srv/RequestMode

• 名称: /umi/request_mode

• 参数映射:

封装参数	原生字段（Request）
mode	mode（目标模式：”IDLE” / “MOTION” / “SERVO”）
detail	detail（子状态，SERVO 时必填 “CARTESIAN” / “JOINT”）
source	source（调用方标识，仅用于日志/审计）
timeout	客户端等待服务应答时长，不下发

raise_fault(source, reason, timeout=10)

主动把机械臂打入 FAULT 模式（软急停 / 异常上报）。硬抢占：任何当前模式都会被覆盖为 FAULT。恢复需调用 clear_fault。

Parameters:

• source (str) – 来源标识，如 “sdk:user_estop”

• reason (str) – 人类可读的原因描述

• timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

state.code==0 表示成功；response 为 UmiRaiseFaultResponse（success/current_mode，current_mode 恒为 “FAULT”）

Return type:

RaiseFaultResponse

Examples:

from daystar_api.lowlevel_skills import raise_fault

resp = raise_fault(source="sdk:user_estop", reason="操作员急停")
if resp.state.code == 0:
    print("已进入 FAULT")

底层 ROS2 接口

• 类型: Service umi_msgs/srv/RaiseFault

• 名称: /umi/raise_fault

• 参数映射:

封装参数	原生字段（Request）
source	source（来源标识，如 “sdk:user_estop”）
reason	reason（人类可读的原因描述）
timeout	客户端等待服务应答时长，不下发

clear_fault(timeout=10)

清除 FAULT 状态，恢复到 IDLE（运维在排除故障后调用）。

Parameters:

timeout (int) – 等待服务应答的最长秒数（default: 10）

Returns:

state.code==0 表示成功；response 为 Trigger_Response（success/message）

Return type:

ClearFaultResponse

Examples:

from daystar_api.lowlevel_skills import clear_fault

resp = clear_fault()
if resp.state.code == 0:
    print("故障已清除")

底层 ROS2 接口

• 类型: Service std_srvs/srv/Trigger

• 名称: /umi/clear_fault

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待服务应答时长，不下发（Request 为空，无下发字段）

相关数据类型

机械臂操作相关的响应类型和消息类型的详细说明请参见 数据结构 文档：

接口层响应类型:

• _lowlevel_skills.MoveJointResponse - 关节运动响应

• _lowlevel_skills.MoveToolResponse - 末端运动响应

• _lowlevel_skills.MoveToPoseResponse - 运动到位姿响应

• _lowlevel_skills.StopMotionResponse - 停止运动响应

• _lowlevel_skills.ComputeFKResponse - 正运动学响应

• _lowlevel_skills.ComputeIKResponse - 逆运动学响应

• _lowlevel_skills.PlanTrajectoryResponse - 轨迹规划响应

• _lowlevel_skills.ExecutePathResponse - 路径执行响应

• _lowlevel_skills.SavePoseResponse - 保存位姿响应

• _lowlevel_skills.RecordPoseResponse - 记录位姿响应

• _lowlevel_skills.GetPoseResponse - 获取位姿响应

• _lowlevel_skills.ListPosesResponse - 位姿列表响应

• _lowlevel_skills.DeletePoseResponse - 删除位姿响应

• _lowlevel_skills.StartRecordingResponse - 开始录制响应

• _lowlevel_skills.StopRecordingResponse - 停止录制响应

• _lowlevel_skills.ListTrajectoriesResponse - 轨迹列表响应

• _lowlevel_skills.GetTrajectoryResponse - 获取轨迹响应

• _lowlevel_skills.DeleteTrajectoryResponse - 删除轨迹响应

• _lowlevel_skills.PlayTrajectoryResponse - 轨迹回放响应

• _lowlevel_skills.ReadTcpPoseResponse - 读取 TCP 四元数位姿响应

• _lowlevel_skills.ReadTcpRPYResponse - 读取 TCP 欧拉角位姿响应

• _lowlevel_skills.GetCurrentJointsResponse - 获取当前关节响应

• _lowlevel_skills.RequestModeResponse - 模式切换响应

• _lowlevel_skills.RaiseFaultResponse - 进入故障响应

• _lowlevel_skills.ClearFaultResponse - 清除故障响应

• _lowlevel_skills.GraspSkillResponse - 整体抓取响应

• _lowlevel_skills.PlaceSkillResponse - 整体放置响应

• _lowlevel_skills.PushSkillResponse - 按压按钮响应

消息类型:

• _lowlevel_skills.CartesianTarget - 笛卡尔空间末端目标（位置 + RPY）

• _lowlevel_skills.JointTrajectory - 关节轨迹

• _lowlevel_skills.JointTrajectoryPoint - 关节轨迹点

常量:

• _lowlevel_skills.ALL_JOINTS - 全部关节标记（move_joint 的 joint_names 默认值，等价 []）

各接口层响应的 response 字段为对应的 UmiXxxResponse ROS 层结构(承载具体 payload),详见 数据结构 文档「机械臂操作 ROS 层响应」一节。