状态数据模型#
状态 getter 返回冻结 dataclass 快照或 None。数组使用元组，固件信息中的版本和类型集合使用列表。
模型不包含采样时间戳；ServiceState.valid 只适用于 SDK 自己的服务状态缓存。
ServiceState#
| 字段 | 类型 | 取值与含义 |
|---|---|---|
service_state |
bool |
True 表示最近一次服务探测/状态读取认为服务可用；False 表示不可用或状态请求失败 |
fsm_state |
str |
UNKNOWN、IDLE、PLANNING_CONTROL、GRAVITY_COMPENSATION、SERVO_CONTROL、POSITION_CONTROL、FORCE_CONTROL、IN_COLLISION、EMERGENCY_STOPPED、UNKNOWN_ERROR；SDK 本地错误快照使用 ERROR |
controller_state |
str |
服务报告的活动机械臂 controller 名称；未知时为 UNKNOWN，SDK 本地错误快照为 ERROR。它不是封闭枚举 |
valid |
bool |
getter 调用时，缓存更新时间是否在 0.5 秒 TTL 内；不表示服务可用，也不表示其他遥测新鲜 |
fsm_state 描述高层任务状态，controller_state 描述当前机械臂控制器名称。两者都不表示当前 Python
客户端拥有控制权。
ArmJointState#
当前 P7 机械臂为 7 个转动关节，三个元组按同一关节顺序排列。SDK 不在模型中保留上游关节名。
| 字段 | 类型 | 长度 | 单位 | 含义 |
|---|---|---|---|---|
angles |
tuple[float, ...] |
7 | rad | 关节位置 |
velocities |
tuple[float, ...] |
7 | rad/s | 关节速度 |
efforts |
tuple[float, ...] |
7 | N·m | 上游 JointState 的转动关节 effort；机械臂侧以 torque 字段填充 |
这些值是反馈，不是命令上限。efforts 不能替代经过标定的外力传感或安全测量。
ArmMotorState#
| 字段 | 类型 | 长度 | 单位/取值 | 含义 |
|---|---|---|---|---|
motor_temperatures |
tuple[float, ...] |
通常 7；上游空数组时为 0 | °C | 各机械臂电机温度 |
error_ids |
tuple[int, ...] |
与温度相同 | 0 表示正常；非 0 为设备错误位/码 |
各电机错误标识 |
错误码的逐位含义取决于电机和固件版本。报告问题时保留原始整数，不要把未知非零值自行清零或映射。
EEFJointState#
| 字段 | 类型 | 长度 | 单位 | 含义 |
|---|---|---|---|---|
eef_pos |
tuple[float, ...] |
运行时 eef_dof |
mm（线性 EEF） |
EEF 关节位置 |
eef_vel |
tuple[float, ...] |
与位置相同 | mm/s（线性 EEF） |
EEF 关节速度 |
eef_eff |
tuple[float, ...] |
与位置相同 | EEF 驱动原生量 | EEF effort/current-like 反馈 |
线性 EEF 的 mm/mm/s 契约同时适用于 move_eef()、set_eef_speed() 和本模型的状态字段；SDK
与 route 交互时自动转换为 m/m/s。应用不应再次换算，也不能把 eef_eff 当作 A、N 或
N·m。旋转或自定义 EEF 在协议提供型号级 actuator/unit 元数据前，不应套用这份线性单位契约。
EEFMotorState#
| 字段 | 类型 | 长度 | 单位/取值 | 含义 |
|---|---|---|---|---|
eef_motor_temp |
tuple[float, ...] |
已安装 EEF 电机数，至少 1 | °C | EEF 电机温度 |
eef_error_id |
tuple[int, ...] |
与温度相同 | 0 表示正常；非 0 为设备错误位/码 |
EEF 电机错误标识 |
没有 EEF 电机数据时 getter 返回 None，不会返回空的 EEFMotorState。
ImuState#
| 字段 | 类型 | 长度 | 单位 | 坐标系/含义 |
|---|---|---|---|---|
angular_velocity |
tuple[float, ...] |
3，顺序 (x, y, z) |
rad/s | 原始 arm_imu 坐标系中的角速度 |
linear_acceleration |
tuple[float, ...] |
3，顺序 (x, y, z) |
m/s² | 原始 arm_imu 坐标系中的线加速度，包含传感器观测到的重力分量 |
SDK 丢弃了上游 frame_id、时间戳、姿态和协方差。返回的两个三元组不能单独说明 IMU 相对
base_link 的安装方向。
CartesianPose#
| 字段 | 类型 | 长度 | 单位 | 坐标系/顺序 |
|---|---|---|---|---|
position |
tuple[float, float, float] |
3 | m | 末端相对 base_link 的 (x, y, z) |
orientation |
tuple[float, float, float, float] |
4 | 无量纲 | 同一位姿的单位四元数 (qx, qy, qz, qw) |
位姿由关节反馈经过 FK 计算，不是末端独立传感器实测。模型本身不验证四元数归一化，也没有时间戳。
作为运动目标使用前，还要检查有限值、四元数范数和 base_link 转换；见
笛卡尔运动。
ArmFirmwareInfo#
缺失的字符串使用 ""，缺失的数组元素不会自动补占位值；因此列表可能短于当前机械臂自由度。
| 字段 | 类型 | 单位/长度 | 含义 |
|---|---|---|---|
arm_sn |
str |
无单位 | 机械臂序列号；不可用时为空字符串 |
base_board_sn |
str |
无单位 | 基座板序列号 |
end_board_sn |
str |
无单位 | 末端板序列号 |
arm_firmware_version |
list[str] |
通常每个机械臂关节一个，当前通常 7 个 | 各机械臂电机/组件固件版本 |
arm_motor_type |
list[str] |
与可用机械臂电机信息对应 | 各关节电机类型名 |
eef_type |
str |
无单位 | EEF 类型；没有或未知时为空字符串 |
eef_firmware_version |
str |
无单位 | EEF 固件版本；不可用时为空字符串 |
end_board_firmware_version |
str |
无单位 | 末端板固件版本；不可用时为空字符串 |
固件信息只在客户端构造时获取一次。它用于兼容性和问题报告，不参与控制权认证。
空值和错误处理#
- getter 返回
None：当前没有可用模型；按状态读取参考检查首帧、连接和字段布局。 - 模型中的空字符串/短列表：运行时信息调用成功，但对应字段未提供完整值。
error_ids/eef_error_id为非零：保留原值、停止需要该设备健康状态的后续操作，并使用对应固件 的错误码资料排查。- 不要把
None、空字符串或空元组替换为测量零值；“没有数据”和“测量值为零”含义不同。