⚙ 开发指南 > SDK > 概念指南

机械臂状态与灯效

ServiceState.fsm_state 表示 P7 当前的高层运行状态。它用于判断服务可以接受哪类命令；控制租约则 决定哪个客户端可以发送普通控制命令。两项条件都满足后，机械臂才会处理相应运动请求。

状态分组

状态	含义	建议动作
IDLE	不处理普通运动目标	取得控制权并切换所需模式
PLANNING_CONTROL	接受规划运动	发送单次或路点规划；busy 时先确认上一任务是否结束
SERVO_CONTROL	接受关节或笛卡尔 Servo 目标	保持稳定发送；结束后主动切回 IDLE
GRAVITY_COMPENSATION	重力补偿生效	托住机械臂进行示教；结束后切回 IDLE
FORCE_CONTROL	接受公开 SDK 的 MIT 关节命令	仅使用经当前整机和负载验证的参数
POSITION_CONTROL	线协议保留的直接位置控制状态	当前 SDK 无对应枚举；切回公开支持模式
EMERGENCY_STOPPED	软件急停请求已进入状态机	排除风险并按现场流程复位，再确认 IDLE
IN_COLLISION	碰撞监测触发保护	保持停止，记录现场和状态，按交付恢复流程处理
UNKNOWN_ERROR	通信、电机或其他硬件状态触发保护	先识别并排除原因，再执行受支持的清错流程
UNKNOWN	SDK 无法映射收到的状态值	不发送运动，记录版本与日志并检查兼容性

PLANNING_CONTROL 不区分“等待请求”和“轨迹执行中”。同样，IDLE 不表示当前没有其他客户端持有 控制权，也不表示实体急停已经复位。

只读检查

state = client.get_service_state()
if state is None:
    raise RuntimeError("服务状态缓存尚未建立")
if not state.valid or not state.service_state:
    raise RuntimeError("服务状态不可用或已经过期")

print("FSM:", state.fsm_state)
print("controller:", state.controller_state)

读取状态不申请控制权，也不会触发运动。DDS 后端的 valid 可能在健康连接的相邻轮询周期之间短暂为 False；连续诊断时还要结合 service_state 和后续样本判断。

保护状态

软件急停、碰撞和 UNKNOWN_ERROR 需要不同恢复流程。普通 stop、释放租约或关闭客户端不能代替保护 状态恢复；软件急停也不能替代实体急停。详细处理见电机错误码查询。

状态灯对照

P7 状态灯位于机械臂末端。灯色和动效可用于快速识别运行阶段，但不能替代 ServiceState、电机状态和现场安全检查。

运行状态	灯效
抱闸，robot_app 未启动	白色常亮
抱闸，robot_app 启动中	黄色呼吸
抱闸，控制服务处于 IDLE	黄色常亮
解抱闸，处于 SERVO_CONTROL	绿色常亮
示教重放处于准备、回到初始点或重放中	绿色呼吸、绿色常亮或绿色流水
处于 GRAVITY_COMPENSATION	青色常亮
重力补偿模式下正在录制	青色流水
处于 POSITION_CONTROL	灰绿常亮
处于 FORCE_CONTROL	紫色常亮
处于 UNKNOWN_ERROR	粉红常亮

灯效的产品使用说明另见机械臂状态指示；可编程状态字段见 ServiceState（服务端状态）。