机械臂操作

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

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)
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("末端运动完成")
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("已到达目标位姿")
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("已停止运动")

夹爪控制

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)
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)
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)

运动学解算

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)
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)

轨迹规划与执行

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, 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）

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

Returns:

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

Return type:

PlanTrajectoryResponse

Examples:

from daystar_api.lowlevel_skills import plan_trajectory, CartesianTarget

target = CartesianTarget()
target.x = 0.4
target.z = 0.3
resp = plan_trajectory(left_target=target, cartesian=True)
if resp.state.code == 0:
    print("规划完成比例:", resp.response.fraction_achieved)
    traj = resp.response.trajectory
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("轨迹执行完成")

位姿库管理

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("位姿已保存")
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)
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)
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)
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("位姿已删除")

轨迹录制与回放

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("开始录制轨迹")
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)
list_trajectories(timeout=10)

列出轨迹库中所有已保存的轨迹名称。

Parameters:

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

Returns:

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

Return type:

ListTrajectoriesResponse

Examples:

from daystar_api.lowlevel_skills import list_trajectories

resp = list_trajectories()
if resp.state.code == 0:
    for name in resp.response.trajectory_names:
        print("轨迹:", name)
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)
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("轨迹已删除")
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 表示使用默认速度）（default: 0.0）

  • acceleration (float) – 回放加速度比例（0.0 表示使用默认加速度）（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("轨迹回放完成")

状态与读取

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)
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)
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]）

Return type:

GetCurrentJointsResponse

Examples:

from daystar_api.lowlevel_skills import get_current_joints

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)

模式与故障

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)
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")
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("故障已清除")

相关数据类型

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

接口层响应类型:

消息类型:

常量:

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