机械臂

1.arm_set_speed - 手臂速度百分比

方法： ctrl.arm_set_speed(side, speed_pct)

参数：

• side：机械臂侧别，ArmSide 枚举
  • ArmSide.kLeft：左臂
  • ArmSide.kRight：右臂（single 单臂机型可能忽略侧别）
• speed_pct：速度百分比，int 类型，范围约 1 ~ 100

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 设置左臂速度为 50%
result = ctrl.arm_set_speed(ArmSide.kLeft, 50)
if result:
    print("左臂速度设置成功")
else:
    print("左臂速度设置失败")

2.arm_move_joints - 手臂关节运动（弧度）

方法： ctrl.arm_move_joints(side, joints_rad)

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• joints_rad：目标关节角数组，list[float] 类型，单位：弧度 (rad)，长度须等于该侧 DOF

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂 7 关节运动到目标弧度
joints = [0.0, -0.5, -1.0, -1.5, 0.0, 0.5, 0.0]
result = ctrl.arm_move_joints(ArmSide.kLeft, joints)
if result:
    print("关节运动指令发送成功")
else:
    print("关节运动指令发送失败")

注意： 入参长度须等于该侧 DOF（由机型 robot_profile 的 dof1/dof2 决定，缺省 7；部分机型为 6）。dual 双臂模式下通常需先收到关节状态后再下发。

3.arm_move_joints_deg - 手臂关节运动（角度）

方法： ctrl.arm_move_joints_deg(side, joints_deg)

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• joints_deg：目标关节角数组，list[float] 类型，单位：度 (°)，长度须等于该侧 DOF

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂 7 关节运动到目标角度（度）
joints = [0.0, -30.0, -60.0, -90.0, 0.0, 30.0, 0.0]
result = ctrl.arm_move_joints_deg(ArmSide.kLeft, joints)
if result:
    print("关节运动指令发送成功")
else:
    print("关节运动指令发送失败")

4.arm_joint_jog - 手臂单关节点动

方法： ctrl.arm_joint_jog(side, joint_1_to_n, direction, speed_pct)

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• joint_1_to_n：关节序号，int 类型，范围 1 ~ N（N = 该侧 DOF）
• direction：点动方向，int 类型，正负含义由驱动实现约定
• speed_pct：速度百分比，int 类型，范围约 1 ~ 100

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂第 3 关节正向点动，速度 30%
result = ctrl.arm_joint_jog(ArmSide.kLeft, 3, 1, 30)
if result:
    print("点动指令发送成功")
else:
    print("点动指令发送失败")

5.arm_joint_step_deg - 手臂单关节步进

方法： ctrl.arm_joint_step_deg(side, joint_1_to_n, direction, step_deg)

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• joint_1_to_n：关节序号，int 类型，范围 1 ~ N（N = 该侧 DOF）
• direction：步进方向，int 类型，-1 减角度，+1 加角度
• step_deg：步长，float 类型，单位：度 (°)，建议约 0.5 ~ 5.0

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂第 3 关节正向步进 5 度
result = ctrl.arm_joint_step_deg(ArmSide.kLeft, 3, 1, 5.0)
if result:
    print("步进指令发送成功")
else:
    print("步进指令发送失败")

6.arm_power_on - 单臂上电

方法： ctrl.arm_power_on(side)

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）。single 单臂机型忽略侧别

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂上电
result = ctrl.arm_power_on(ArmSide.kLeft)
if result:
    print("左臂上电指令发送成功")
else:
    print("左臂上电指令发送失败")

注意： 机械臂控制无反应时，优先检查是否已上电；若因急停导致掉使能，需重新调用上电接口。

7.arm_power_on_both - 双臂上电

方法： ctrl.arm_power_on_both()

说明： dual 双臂模式下同时上电；single 单臂模式下上电单臂。

参数：

• 无

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 双臂上电
result = ctrl.arm_power_on_both()
if result:
    print("双臂上电指令发送成功")
else:
    print("双臂上电指令发送失败")

8.arm_power_off_both - 双臂下电

方法： ctrl.arm_power_off_both()

说明： dual 双臂模式下同时下电；single 单臂模式下下电单臂。

参数：

• 无

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 双臂下电
result = ctrl.arm_power_off_both()
if result:
    print("双臂下电指令发送成功")
else:
    print("双臂下电指令发送失败")

9.arm_stop - 单臂停止（下电）

方法： ctrl.arm_stop(side)

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂停止（下电）
result = ctrl.arm_stop(ArmSide.kLeft)
if result:
    print("左臂停止指令发送成功")
else:
    print("左臂停止指令发送失败")

10.arm_move_axis_delta - 手臂沿轴平移

方法： ctrl.arm_move_axis_delta(side, axis, distance_m)

说明： 机械臂末端沿基坐标系指定轴做笛卡尔相对运动，依赖 arm_api_base 指向的 fd_arm_http 服务。

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• axis：平移轴，str 类型，如 "x" / "y" / "z"
• distance_m：平移距离，float 类型，单位：米 (m)，正负表示方向

返回值：

• bool：操作结果
  • True：请求成功
  • False：请求失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂末端沿基坐标系 x 轴正方向移动 0.05m
result = ctrl.arm_move_axis_delta(ArmSide.kLeft, "x", 0.05)
if result:
    print("平移请求成功")
else:
    print("平移请求失败")

11.arm_move_to_target - 手臂笛卡尔目标点

方法： ctrl.arm_move_to_target(side, x, y, z)

说明： 机械臂末端运动到笛卡尔坐标点，依赖 arm_api_base（默认 http://127.0.0.1:8000）。

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• x / y / z：目标位置，float 类型，单位：米 (m)

返回值：

• bool：操作结果
  • True：请求成功
  • False：请求失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂末端移动到笛卡尔点 (0.5, 0.1, 0.3)
result = ctrl.arm_move_to_target(ArmSide.kLeft, 0.5, 0.1, 0.3)
if result:
    print("目标点运动请求成功")
else:
    print("目标点运动请求失败")

12.arm_move_to_location - 手臂预置位置名运动

方法： ctrl.arm_move_to_location(side, location_name)

说明： 机械臂运动到已配置的预置位置（名称），依赖 arm_api_base。

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• location_name：预置位置名，str 类型，须已预先配置

返回值：

• bool：操作结果
  • True：请求成功
  • False：请求失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂运动到预置位置 "after_grasp"
result = ctrl.arm_move_to_location(ArmSide.kLeft, "after_grasp")
if result:
    print("预置位置运动请求成功")
else:
    print("预置位置运动请求失败")

13.arm_move_joints_traj - 手臂关节轨迹运动

方法： ctrl.arm_move_joints_traj(side, traj)

说明： 按多点关节轨迹运动，轨迹由多个关节角序列组成。

参数：

• side：机械臂侧别，ArmSide 枚举（kLeft / kRight）
• traj：轨迹点序列，list[list[float]] 类型，每个轨迹点为关节角数组（单位：弧度），每点长度 = 该侧 DOF

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, ArmSide

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 左臂 7 关节两点轨迹运动（弧度）
traj = [
    [0.0, -0.5, -1.0, -1.5, 0.0, 0.5, 0.0],
    [0.1, -0.4, -0.9, -1.4, 0.1, 0.6, 0.1],
]
result = ctrl.arm_move_joints_traj(ArmSide.kLeft, traj)
if result:
    print("轨迹运动指令发送成功")
else:
    print("轨迹运动指令发送失败")

机械臂状态接口： 机械臂关节角 / 末端位姿的同步读取（arm_get_joint_angles、arm_get_end_pose）与异步订阅（arm_sub_joint_angles、arm_sub_end_pose）当前仅 C++ 提供，Python State 暂未封装，如需要请使用 C++ 接口。