⚙ 开发指南
> SDK
> API
接口总览#
P7 Python SDK 的公开入口集中在 AirbotClient、状态数据模型、控制枚举、运动选项、异常和
utilities。普通状态 getter 不申请控制权；普通运动、模式切换和部分恢复命令需要当前客户端持有
有效租约。
客户端与控制权#
| 任务 | 主要入口 | 详细说明 |
|---|---|---|
| 创建和关闭客户端 | AirbotClient(...)、close()、context manager |
SDK 简介与架构 |
| 查看客户端身份 | get_client_id、get_source_name、get_client_instance_id、get_client_session_id |
控制权机制（Lease） |
| 获取、释放和交还控制权 | acquire_control()、release_control()、handover_to_previous() |
控制权机制（Lease） |
四个身份入口是只读属性，访问时不加括号。acquire_control() 成功只表示当次取得租约，不表示机械臂
已经处于所需模式。
状态读取#
| 状态 | Getter | 返回类型 |
|---|---|---|
| 服务与 FSM | get_service_state() |
ServiceState | None |
| 机械臂关节 | get_arm_joint_state() |
ArmJointState | None |
| 机械臂电机 | get_arm_motor_state() |
ArmMotorState | None |
| EEF 关节 | get_eef_joint_state() |
EEFJointState | None |
| EEF 电机 | get_eef_motor_state() |
EEFMotorState | None |
| IMU | get_imu_state() |
ImuState | None |
| 末端位姿 | get_end_pose() |
CartesianPose | None |
| 固件信息 | get_firmware_info() |
ArmFirmwareInfo | None |
这些方法均为只读操作。模型不统一携带源时间戳；非 None 结果不能单独证明数据满足实时控制的新鲜度
要求。字段分别见 ArmState（机械臂状态）、
EEFState（末端执行器状态）、CartesianPose（末端位姿）、
ServiceState（服务端状态）和 FirmwareInfo（固件信息）。
控制模式与运动#
| 任务 | 主要入口 | 详细说明 |
|---|---|---|
| 切换机械臂模式 | switch_controller()、enter_gravity_compensation_mode() |
控制模式说明 |
| 设置关节速度与发送关节目标 | set_arm_speed()、move_joint() |
PTP 点到点规划 |
| 发送单次笛卡尔目标 | move_end_pose()、move_end_pose_linear()、move_end_pose_circle() |
PTP / LIN / CIRC |
| 发送多路点序列 | move_joint_waypoints()、move_end_pose_waypoints() |
多段轨迹融合规划 |
| 查询和控制 EEF | get_eef_mode()、switch_eef_control_mode()、set_eef_speed()、move_eef() |
EEFState（末端执行器状态） |
关节入口使用 JointMoveOptions；笛卡尔、EEF 和路点入口分别使用对应的 options 类型。字段能被模型
接受不表示当前模式会发送它，详见运动选项。
安全与恢复#
| 任务 | 主要入口 | 重要限制 |
|---|---|---|
| 软件急停与复位 | set_arm_emergency_stop() |
依赖通信，不能替代实体急停 |
清除受支持的 UNKNOWN_ERROR |
clear_error()、clear_arm_motor_err() |
先记录并排除原因；需要控制权 |
| EEF 电机清错 | clear_eef_motor_err() |
当前 gRPC、DDS 均抛出 UnsupportedOperationError |
| 回到 7 轴零位 | return_zero() |
会主动运动，不是标定或通用故障恢复 |
前置、返回和失败处理见电机错误码查询。
包级入口#
顶层包还导出 Controller、EEF 模式、状态模型、五类运动 options、两个公开异常、关节限位常量、
__version__ 和 utilities。控制模式见控制模式（Controller），运动参数见
运动控制参数（ArmControlOptions），换算工具见支持的示教器与夹爪型号。
False、客户端超时和非阻塞返回都不能直接解释为“命令未执行”。运动或恢复请求失败后，应停止发送
新目标，并结合 FSM、关节反馈、电机状态和现场观察完成对账。