设备控制

接口说明

设备实时控制不是 REST 接口，而是通过设备控制服务的 WebSocket 通道下发指令。客户端先建立 WebSocket 连接（见 WebSocket 连接），再通过该连接持续发送控制指令帧。

本页说明各类控制指令的 JSON 格式与遥操作时序。

下发控制指令前须同时满足：

前提	说明
用户有控制权限	设备详情 `can_control = true`（或 `permission_type ≥ 2`）
设备在线	`online_status = 1`
设备未被他人占用	或使用 `force=true` 强制接管（见 WebSocket 连接）
设备已站立	趴下状态无法行走，需先 `toggle_stand_pose` 站起
:::

一、方向操控（move）

方向操控采用「按下 → 按住 → 抬起」三段式时序，模拟遥控摇杆的持续输入。

1. 按下（phase: down）

按下方向键时立即发送一帧 move：

{
  "action": "move",
  "phase": "down",
  "vx": 0.7,
  "vy": 0,
  "vyaw": 0,
  "ts": 1720146600000,
  "clientTs": 1720146600000
}

2. 按住（keep_alive）

持续按住期间，每 200ms 发送一帧心跳保活：

{ "action": "keep_alive" }

3. 抬起（phase: up）

松开方向键时，先发 stop，再补发一帧全零 move 确保设备归零：

{ "action": "stop", "phase": "up", "ts": 1720146601000, "clientTs": 1720146601000 }

{ "action": "move", "phase": "up", "vx": 0, "vy": 0, "vyaw": 0, "ts": 1720146601000, "clientTs": 1720146601000 }

速度映射表

速度值 speed 建议区间见下表，vy 在四足设备上恒为 0。

方向	vx	vyaw	speed 建议
▲ 前进	+speed	0	0.4 ~ 0.7
▼ 后退	-speed	0	0.4 ~ 0.7
◀ 左转	0	-speed	0.5 ~ 0.8
▶ 右转	0	+speed	0.5 ~ 0.8

二、站立 / 趴下（toggle_stand_pose）

切换设备的站立与趴下姿态：

{ "action": "toggle_stand_pose", "ts": 1720146600000 }

三、运动模式（switch_motion_mode）

切换行走模式与原地模式：

{ "action": "switch_motion_mode", "mode": "move" }

mode	说明
`move`	行走模式，可位移
`inplace`	原地模式，仅姿态调整，不产生位移

四、自主 / 手动模式（toggle_auto_mode）

{ "action": "toggle_auto_mode", "value": true, "ts": 1720146600000 }

value	说明
`true`	自主导航模式
`false`	手动遥操作模式

五、指令回执（cmd_ack）

每条控制指令，设备侧会通过下行消息回执执行结果：

{
  "type": "cmd_ack",
  "device_no": "DEV-2024-001",
  "action": "move",
  "phase": "down",
  "status": "success",
  "vx": 0.7,
  "vy": 0,
  "vyaw": 0,
  "plus_robot_ms": 42,
  "ts": 1720146600042
}

字段	说明
status	执行结果：`success` 成功，`error` 失败
plus_robot_ms	设备控制服务与设备之间的往返耗时（毫秒）

下行遥测消息（type: telemetry）格式见实时遥测。