状态数据模型

状态数据模型#

状态 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、空字符串或空元组替换为测量零值；“没有数据”和“测量值为零”含义不同。

状态数据模型#

ServiceState#

ArmJointState#

ArmMotorState#

EEFJointState#

EEFMotorState#

ImuState#

CartesianPose#

ArmFirmwareInfo#