28. 接口总览#
类AirbotClient为AIRBOT Play SDK的统一入口类，提供机械臂的控制与状态查询API接口实现。
| 功能 | 子功能 | 接口 | 参数说明 |
|---|---|---|---|
| 初始化 | 初始化并连接机械臂服务端 | init(self, host: str = "localhost", port: int = 50051, arm_dof: int = 6) -> None |
- host：服务端ip地址 - port：服务端端口 - arm_dof：机械臂的自由度 |
| GRPC控制权接口 | 获取服务端控制服务权限 | acquire_control(lease_ms: int = 15000, renew_period_s: float = 5.0) -> bool |
- 功能：获取服务端控制服务句柄，使得客户端可以控制机械臂进行运动 - lease_ms：向服务端申请的“独占控制权”的有效期/租约时长 - renew_period_s：客户端在后台自动“续租/续约”的周期/频率 - 返回：若成功获取句柄，返回 True，反之则返回 False |
| 释放服务端控制服务权限，变为只读状态 | release_control() -> None |
- 功能：释放服务端控制服务句柄，使得客户端只能读取机械臂状态信息，而不能控制 | |
| 关闭客户端连接，释放客户端相关资源 | close() -> None |
- 功能：对客户端做一次安全收尾清理，释放线程、控制权和网络资源，让客户端安全退出 | |
| 数据反馈获取接口 | 获取当前机械臂关节数据 | get_arm_joint_state() -> Optional[ArmJointState] |
- 功能：获取机械臂关节的当前状态 - 返回：若成功获取，则返回 ArmJointState 结构数据（参考 机械臂状态），包含位置、速度、电流的关节状态对象；若获取失败，则返回 None |
| 获取当前机械臂电机数据 | get_arm_motor_state() -> Optional[ArmMotorState] |
- 功能：获取机械臂电机的当前状态 - 返回：若成功获取，则返回 ArmMotorState 结构数据（参考 机械臂状态），包含电机温度、MOS管温度和错误码的电机状态对象；若获取失败，则返回 None |
|
| 获取当前末端执行器关节数据 | get_eef_joint_state() -> Optional[EEFJointState] |
- 功能：获取末端执行器关节的当前状态 - 返回：若成功获取，则返回 EEFJointState 结构数据（参考 末端执行器状态），包含位置、速度、电流的关节状态对象；若获取失败，则返回 None |
|
| 获取当前末端执行器电机数据 | get_eef_motor_state() -> Optional[EEFMotorState] |
- 功能：获取末端执行器电机的当前状态 - 返回：若成功获取，则返回 EEFMotorState 结构数据（参考 末端执行器状态），包含电机温度、MOS管温度和错误码的电机状态对象；若获取失败，则返回 None |
|
| 获取当前机械臂末端的笛卡尔空间位姿 | get_end_pose() -> Optional[CartesianPose] |
- 功能：获取当前机械臂末端的笛卡尔空间位姿 - 返回：若成功获取，则返回 CartesianPose 结构数据（参考 末端位姿），包含位置和姿态的状态对象；若获取失败，则返回 None |
|
| 获取当前机械臂服务端的运行状态 | get_service_state() -> Optional[ServiceState] |
- 功能：获取当前机械臂服务端的运行状态 - 返回：若成功获取，则返回 ServiceState 结构数据（参考 服务端状态），包含服务端运行状态、服务端状态机状态和服务端控制器状态的数据对象；若获取失败，则返回 None |
|
| 获取当前机械臂固件信息 | get_firmware_info(self) -> Optional[ArmFirmwareInfo] |
- 功能：获取当前机械臂的固件信息 - 返回：若成功获取，则返回 ArmFirmwareInfo 结构数据（参考 固件信息），包含固件类型、SN码和固件版本等数据；若获取失败，则返回 None |
|
| 客户端参数设置接口 | 设置机械臂关节的最大运动速度 | set_arm_speed(self, arm_speed: list[float]) -> bool |
- 功能：设置机械臂电机最大运行速度 - arm_speed：电机最大运行速度（0 到 2.0 * pi） - 返回：是否设置成功 |
| 机械臂控制接口 | 设置机械臂控制器（需要控制权） | switch_controller(controller: Controller, timeout_ms: int = 1000) -> bool |
- 功能：设置机械臂控制器类型 - controller： Controller 类型的控制器名称（参考 控制器）- timeout_ms：超时时间，单位 ms - 返回：若成功设置，则返回 True，否则返回 False |
| 进入重力补偿模式（需要控制权） | enter_gravity_compensation_mode(timeout_ms: int = 1000) -> bool |
- 功能：进入重力补偿模式，可通过调用 switch_controller 接口切换到别的控制器退出该模式- timeout_ms：超时时间，单位 ms - 返回：若成功设置，则返回 True，否则返回 False |
|
| 机械臂关节空间控制（需要控制权） | move_joint(pos: list[float], options: ArmControlOptions, timeout_ms: int = 1000) -> bool |
- 功能：机械臂关节空间控制 - pos：机械臂各个电机的目标关节空间位置（关节位置限制参考 关节限位值说明） - options： ArmControlOptions 数据类型的控制参数（参考控制选项），各控制模式的必需参数参见控制模式说明- timeout_ms：超时时间，单位 ms - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 末端执行器关节空间控制（需要控制权） | move_eef(pos: float, options: ArmControlOptions, timeout_ms: int = 1000) -> bool |
- 功能：末端执行器关节空间控制（关节位置限制参考 关节限位值说明） - pos：末端执行器的目标关节空间位置 - options： ArmControlOptions 数据类型的控制参数（参考控制选项），各控制模式的必需参数参见控制模式说明- timeout_ms：超时时间，单位 ms - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 机械臂笛卡尔空间控制（需要控制权） | move_end_pose(pos: CartesianPose, options: ArmControlOptions, timeout_ms: int = 1000) -> bool |
- 功能：机械臂笛卡尔空间控制 - pos：数据结构为 CartesianPose 的机械臂目标末端位姿（参考 末端位姿）- options： ArmControlOptions 数据类型的控制参数（参考 控制选项），各个控制模式的必需参数参见 控制模式说明- timeout_ms：超时时间，单位 ms - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 机械臂笛卡尔空间直线轨迹规划控制（需要控制权） | move_end_pose_linear(start: CartesianPose, target: CartesianPose, options: ArmControlOptions, timeout_ms: int = 1000) -> bool |
- 功能：机械臂笛卡尔空间直线轨迹规划控制 - start：数据结构为 CartesianPose 的机械臂起始末端位姿（参考 末端位姿）- target：数据结构为 CartesianPose 的机械臂目标末端位姿（参考 末端位姿）- options： ArmControlOptions 数据类型的控制参数（参考 控制选项），各个控制模式的必需参数参见 控制模式说明- timeout_ms：超时时间，单位 ms - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 机械臂笛卡尔空间圆弧轨迹规划控制（需要控制权） | move_end_pose_circle(start: CartesianPose, path: CartesianPose, target: CartesianPose, options: ArmControlOptions, timeout_ms: int = 1000) -> bool |
- 功能：机械臂笛卡尔空间圆弧轨迹规划控制 - start：数据结构为 CartesianPose 的机械臂起始末端位姿（参考 末端位姿）- path：数据结构为 CartesianPose 的机械臂途经点末端位姿（参考 末端位姿）- target：数据结构为 CartesianPose 的机械臂目标末端位姿（参考 末端位姿）- options： ArmControlOptions 数据类型的控制参数（参考 控制选项），各个控制模式的必需参数参见 控制模式说明- timeout_ms：超时时间，单位 ms - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 机械臂关节空间多路点规划控制（需要控制权） | move_joint_waypoints(waypoints: list[list[float]], options: ArmControlOptions, timeout_ms: int = 1000) -> bool |
- 功能：机械臂关节空间多路点规划控制 - waypoints：机械臂关节空间位置点集，关节位置限制（参考 关节限位值说明） - options： ArmControlOptions 数据类型的控制参数（参考 控制选项），各个控制模式的必需参数参见 控制模式说明- timeout_ms：超时时间，单位 ms - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 机械臂笛卡尔空间多路点规划控制（需要控制权） | move_end_pose_waypoints(waypoints: list[CartesianPose], options: ArmControlOptions, timeout_ms: int = 1000) -> bool |
- 功能：机械臂笛卡尔空间多路点规划控制 - waypoints：数据结构为 CartesianPose 的机械臂笛卡尔空间位置点集- options： ArmControlOptions 数据类型的控制参数（参考 控制选项），各个控制模式的必需参数参见 控制模式说明- timeout_ms：超时时间，单位 ms - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 机械臂重置功能 | 机械臂回零（需要控制权） | return_zero() -> bool |
- 功能：机械臂各个关节回到零点 - 返回：若成功发送控制指令，则返回 True，否则返回 False |
| 机械臂急停与恢复（急停需要控制权，恢复不需要） | set_arm_emergency_stop(mode: bool) -> bool |
- 功能：机械臂急停与恢复 - mode：选择急停还是恢复， True 为急停模式，False 为急停后的恢复模式- 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 清除机械臂电机错误码（需要控制权） | clear_arm_motor_err() -> bool |
- 功能：清除机械臂电机错误码 - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 清除末端执行器电机错误码（需要控制权） | clear_eef_motor_err() -> bool |
- 功能：清除末端执行器电机错误码 - 返回：若成功发送控制指令，则返回 True，否则返回 False |
|
| 工具类函数 | 在 utilities 子模块中，主要用于各个末端执行器之间的行程映射 |
def map_pendant_to_gripper(pos: float, *, from_pendant: str, to_gripper: str, clamp: bool = True) -> float |
- 功能：提供从示教器返回值转换到末端执行器实际控制量的映射 - pos：示教器输入值 - from_pendant：示教器类型 - to_gripper：夹爪类型 - 返回：夹爪实际控制量 - 当前支持的所有示教器和夹爪型号可参考附录 |
Note
轨迹规划的速度不受最大限制速度影响，轨迹规划的最大速度为 4π。
Note
末端执行器在不同控制器工况下采用的控制方式存在差异，请注意以下事项：
① 在未调用 set_arm_speed 和 set_eef_speed 接口设置最大执行速度之前，机械臂与末端执行器的默认最大运行速度为 π / 3 rad/s。
② 当 options.blocking = False（即采用非阻塞方式调用末端执行器运动控制接口）时，正在执行的末端执行器指令可能会被控制器切换所中断。
例如，在 direct_control 控制器下发送末端执行器运动指令后，如果切换到 planning_control 控制器，则此前下发的指令将被中断。
因此，请根据任务需求合理选择是否采用阻塞执行方式。
③ 在 servo_control 控制器下进行笛卡尔空间或关节空间控制时，末端执行器的运动会受到 options.eef_pos 参数的影响。当采用 options.blocking = False 即非阻塞方式时，如果同时调用 move_end_pose（或 move_joint）与 move_eef 接口，后一个指令会中断前一个任务的执行。而 direct_control 的末端执行器控制则只接受 move_end_pose 的指令。
请务必区分 servo_control 与 direct_control 两种控制模式的使用方法，以避免控制冲突。