包导出、常量与异常

包导出、常量与异常#

arm_p7_sdk 顶层包导出客户端、数据模型、控制枚举、关节限位常量、两个公开异常、版本号和一个末端位置换算工具。应用优先从顶层包导入；未列入本页的内部模块名称不属于当前公开导入契约。

导出总览#

客户端：AirbotClient。
公开异常：ClientNameConflictError、UnsupportedOperationError。
控制枚举：Controller、EEFControlMode。
状态模型：ArmJointState、ArmFirmwareInfo、ArmMotorState、EEFJointState、 EEFMotorState、ServiceState、ImuState、CartesianPose。
运动选项：JointMoveOptions、EEFMoveOptions、CartesianMoveOptions、 JointWaypointsMoveOptions、CartesianWaypointsMoveOptions；字段见关节参数和运动参数参考。
关节限位常量：9 个 ARM_JOINT_* 名称。
包信息和工具：__version__、utilities。

当前顶层 __all__ 共 29 项。具体整机是否支持某个控制模式或 EEF 仍由兼容性矩阵和运行时状态决定；名称能够导入不等于目标设备支持该操作。

包版本#

from arm_p7_sdk import __version__

print(__version__)

__version__ 来自已安装的 arm-p7-sdk 分发包元数据。直接从没有安装元数据的源码目录导入时，回退值为 "0.0.0"。该值只能标识 Python 包，不能单独证明它与 Arm App、CORA、系统镜像或固件兼容。

公开异常#

from arm_p7_sdk import ClientNameConflictError, UnsupportedOperationError

异常	触发条件	处理方式
`ClientNameConflictError`	同一注册域中已有活动客户端使用相同的 `client_name`	确认旧进程是否仍在运行；为并行进程分配唯一名称，不要复用实例 UUID 绕过冲突
`UnsupportedOperationError`	当前后端或协议版本没有实现请求能力，例如 legacy 控制权抢占或 EEF 电机清错	停止当前流程，核对后端和版本；不要把它当作可重试的临时传输错误

构造和调用还可能抛出 Python ValueError、ConnectionError 或后端原生传输异常。捕获异常后不要继续使用构造未完成或状态未知的客户端；连接类问题按连接检查处理。顶层包没有导出其他 SDK 异常类型，应用不应依赖内部异常模块来判断跨版本行为。

关节限位常量#

所有关节限位均按 J1 到 J7 排列，单位为 rad。

名称	类型	含义
`ARM_JOINT_LIMIT_MARGIN`	`float`	SDK 从原始上下限两端各收紧的余量，当前为 `0.004 rad`
`ARM_JOINT_RAW_LIMITS_V3`	`tuple[tuple[float, float], ...]`	P7C V3 的 7 组原始关节上下限
`ARM_JOINT_RAW_LIMITS_V4`	同上	P7C V4 的 7 组原始关节上下限
`ARM_JOINT_LIMITS_V3`	同上	V3 原始上下限应用 `ARM_JOINT_LIMIT_MARGIN` 后的 SDK 命令范围
`ARM_JOINT_LIMITS_V4`	同上	V4 原始上下限应用余量后的 SDK 命令范围
`ARM_JOINT_RAW_LIMITS`	同上	兼容名称，当前等同 `ARM_JOINT_RAW_LIMITS_V3`
`ARM_JOINT_LIMITS`	同上	兼容名称，当前等同 `ARM_JOINT_LIMITS_V3`
`ARM_JOINT_EFFORT_LIMITS`	`tuple[tuple[float, float], ...]`	7 组 `eff`/current-threshold 数值范围；物理单位尚未形成统一发布契约
`ARM_JOINT_DEFAULT_EFFORTS`	`tuple[float, ...]`	每组 effort 范围绝对值的最大值，作为 SDK 选项默认数组

SDK 会根据运行时读取到的机械臂序列号选择 V3 或 V4 命令限位；序列号缺失或不匹配已知规则时使用 V3。应用不应只读取兼容别名来判断整机硬件版本。发送关节目标时仍应让当前 SDK 完成最终校验，并在具体工位检查整条路径。

ARM_JOINT_EFFORT_LIMITS 和 ARM_JOINT_DEFAULT_EFFORTS 不能与状态模型中的关节 efforts 直接作物理量比较。eff、协议 current_threshold 和运行配置 max_torque 的单位尚未统一；见关节参数。

末端位置换算#

顶层导出的 utilities 模块当前提供一个纯数值换算函数：

from arm_p7_sdk import utilities

target_mm = utilities.map_pendant_to_gripper(
    20.0,
    from_pendant="E2",
    to_gripper="G2",
    clamp=True,
)

map_pendant_to_gripper(
    pos: float,
    *,
    from_pendant: str,
    to_gripper: str,
    clamp: bool = True,
) -> float

pos 和返回值都使用 mm。函数把示教器行程按线性比例映射到夹爪行程，不创建客户端、不读取设备，也不发送控制命令。

参数	当前可识别值	失败与限制
`from_pendant`	`E2`、`REPLAY`、`REPLAY_MINI`	未知名称抛出 `ValueError`
`to_gripper`	`G2`、`G2L`、`G2P`	未知名称抛出 `ValueError`；G2P 上限仍有版本差异
`clamp`	默认 `True`	`True` 会把输入和输出夹紧到模块内置范围；`False` 允许线性外推

内置行程表不能替代整机交付参数。当前 G2P 的工具表上限为 95 mm，而已核对的整机配置为 96 mm；这两个行程来源仍待统一。SDK 的线性 EEF 输入和反馈已统一使用 mm/mm/s，但发送前仍须按型号核对行程、自由度和控制模式。不要把该函数的返回值未经范围检查直接传给 move_eef()。发送 EEF 目标前，先按末端执行器核对型号、自由度、单位、行程和控制模式。