WebSocket 连接

接口说明

设备实时控制与遥测推送通过设备控制服务的 WebSocket 通道完成。本页说明连接地址、握手参数、心跳机制与下行消息类型。控制指令的具体格式见设备控制。

一、连接地址

wss://plus.fengshengshou.com/?deviceNo=<设备编号>&role=app&token=<JWT Token>

设备控制服务域名见快速开始。连接参数（均需 URL 编码）：

参数	必填	说明
deviceNo	是	设备编号，取自设备列表 / 详情的 device_no
role	是	连接角色，固定为 app
token	是	JWT Token，不带 Bearer 前缀
force	否	true = 强制接管已被他人占用的设备

Token 安全

连接地址中的 Token 使用 your_token_here 占位。Token 直接出现在 URL 查询参数中，请避免在日志或前端明文中泄露。

二、连接建立后的首个下行消息

连接成功后，设备控制服务会推送一条设备网络信息消息：

{
  "type": "device_net",
  "localIp": "192.168.1.100",
  "mac": "AA:BB:CC:DD:EE:FF"
}

字段	说明
localIp	设备局域网 IP，用于同网段视频流直连
mac	设备 MAC 地址

三、心跳机制

客户端每 3 秒发送一次 ping，设备控制服务回以 pong：

{ "type": "ping", "ts": 1720146600000 }

{ "type": "pong", "ts": 1720146600000 }

往返延迟（RTT）可由 pong 的 ts 与发送时刻计算。方向操控的 200ms keep_alive 与此 3 秒心跳是两套独立机制，详见设备控制。

四、下行消息类型

type	说明
device_net	连接后首帧，设备网络信息（见上）
pong	心跳响应
cmd_ack	控制指令回执，含 status、plus_robot_ms
telemetry	设备遥测推送，含 status、battery、pose（见实时遥测）
occupied	设备已被他人占用，携带 reason，可用 force=true 重连接管
kicked	连接被他人强制接管而断开，携带 reason，不应自动重连
error	错误消息，携带 code、msg

五、连接生命周期

1. 通过设备详情确认设备在线（online_status = 1）且具备控制权限（can_control = true）。
2. 使用 deviceNo + role=app + token 建立 WebSocket 连接。
3. 收到 device_net 后，发送 toggle_stand_pose 让设备站立。
4. 进行方向操控、遥测监听。
5. 操控结束后发送 toggle_stand_pose 让设备趴下。
6. 确认趴下后关闭 WebSocket 连接。

退出安全

断开连接前务必先让设备恢复趴下状态。站立状态下直接断开可能导致设备摔倒、损伤硬件。完整安全流程见设备控制。