双轮足 · 回充接口 | 机器人技术学习笔记

3.10 双轮足回充基座接口

3.10.1 扫描充电桩

仅 WF 支持。请求只执行一次 扫描 → 等待既有扫描超时 → 读取列表 事务，不配对、不点灯、不开充电 MOS、不发送 EV_GO_DOCKING，也不修改回充生命周期状态。协议当前仅返回 16 位 little-endian dock_id，没有 RSSI 字段，因此响应不伪造信号强度。

扫描与回充扫描/配对、上桩、充电中和下桩互斥；冲突返回 fail_dock_busy。列表按硬件扫描顺序返回并去重，payload 长度必须严格等于 1 + 2 * 原始数量。空列表是一次成功扫描，与硬件/协议扫描失败明确区分。

请求：request_scan_docks

data 必须为空对象：

{ 
"accid": "WF_TRON2A_001", 
"title": "request_scan_docks",
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000, 
 "data": {} 
}

响应：response_scan_docks

{
  "accid": "WF_TRON2A_001",
  "title": "response_scan_docks",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "success": true,
    "result": "success",
    "message": "charging dock scan completed",
    "docks": [{"dock_id": 0}, {"dock_id": 4660}, {"dock_id": 65535}],
    "count": 3,
    "scanned_at": 1787106660123
  }
}

空列表仍为 success=true/result="success"，docks=[]、count=0、message="no charging docks found"。scanned_at 是完成扫描的 Unix 毫秒；未实际发起硬件扫描的拒绝响应为 0。

`result`	含义
`success`	扫描事务成功；`count` 可为 0
`fail_dock_scan`	启动扫描或读取扫描结果失败
`fail_dock_scan_list`	payload 为空、截断、带多余字节或长度不匹配
`fail_dock_busy`	已在扫描、配对、回充/充电或下桩
`fail_unsupported_robot`	非 WF 机型
`fail_invalid_cmd`	`data` 不是空对象
`fail_service_call`	`/tron2/service` 不可达或调用超时
`fail_remote`	snowball 服务明确拒绝
`fail_invalid_response`	snowball 返回非法 JSON；signaling 不重做列表解析

3.10.2 查询完整回充状态

该接口为只读操作，免开发者模式，不触发扫描、控制器切换或任何硬件副作用。signaling 调用 snowball /tron2/service 的 dock/status，校验 JSON 后原样透传字段和 message。

请求：request_get_docking_status

{ "accid": "WF_TRON2A_001", 
"title": "request_get_docking_status", 
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000, "data": {} 
 }

响应：response_get_docking_status

{
  "accid": "WF_TRON2A_001",
  "title": "response_get_docking_status",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {
    "success": true,
    "result": "success",
    "message": "waiting for charging confirmation",
    "supported": true,
    "phase": "confirming",
    "robot_state": "ST_GO_DOCKING",
    "in_progress": true,
    "has_dock_id": true,
    "dock_id": 4660,
    "has_requested_dock_id": true,
    "requested_dock_id": 4660,
    "dock_selection": "requested",
    "controller_confirmed": true,
    "charging_confirmed": false,
    "confirm_timeout_sec": 60,
    "confirm_remaining_sec": 42.381,
    "failure_code": 0,
    "failure_source": "",
    "failure_reason": "",
    "previous_failure_code": 7,
    "previous_failure_source": "wheelfoot_gocharge",
    "previous_failure_reason": "docking controller reported an error (code 7)",
    "battery_known": true,
    "battery_percent": 63,
    "minimum_undock_battery_percent": 15,
    "attempt_token": 12,
    "confirm_attempt_token": 2,
    "retry_count": 1,
    "attempt_source": "sdk",
    "updated_at": 1787106660123
  }
}

字段语义：

phase 是稳定业务枚举：idle（进程启动后尚未发起）、preparing（扫描/选桩/配对）、docking（上桩或自动重试）、confirming（等待 controller + charging 双条件）、charging（双条件成功并处于 ST_DOCKING）、undock_preparing、undocking、canceled、failed、manual_undock、walking。

robot_state 保留 snowball 原始 ST_* 状态。业务阶段和原始状态不强制一一对应，例如失败已回 ST_WALKING 时仍可保持 phase=failed。

dock_id=null 且 has_dock_id=false 表示尚未选中或进程重启后无法恢复；ID 0 是合法值，不能表示未知。requested_dock_id 仅表示 SDK 请求值，最终配对结果以 dock_id 为准。

attempt_token 每次 RC/SDK 新发起回充递增并清除旧选桩和失败；confirm_attempt_token 是每次 gocharge 双条件窗口编号，自动重试会更新它并递增 retry_count。

自动重试开始时，本轮错误移入 previous_failure_*；最终失败保留在 failure_*。新用户 attempt 清空两组失败；明确成功清空当前失败。

confirm_remaining_sec 仅确认窗口活动时为数字，否则为 null。它基于单调时钟计算；updated_at 是最近业务状态更新时间的 Unix 毫秒。

battery_percent=null 且 battery_known=false 表示尚未收到有效电量；未知电量不会伪造为 0。

非 WF 返回 success=true、supported=false、phase=idle 和明确 message，查询本身仍成功。

状态流转：

idle/walking → preparing → docking → confirming → charging → undock_preparing → undocking → walking。扫描/配对、控制器、确认超时、低电量或下桩错误进入 failed；offcharge code=-1 进入 manual_undock；用户取消进入 canceled。controller 与 charging 两个确认信号顺序无关。

查询错误码：

`result`	含义
`fail_service_call`	`/tron2/service` 不可达或调用超时
`fail_remote`	snowball 服务明确拒绝查询
`fail_invalid_response`	snowball 返回无法解析或缺少基础字段的 JSON；signaling 不崩溃且不改写失败原因

3.10.3 开始回充（仅轮足）

请求：request_start_docking

{ 
"accid": "WF_TRON2A_001",
 "title": "request_start_docking", 
 "guid": "d2c6521699e035949c9276cb17b62bdb", 
 "timestamp": 1762771300000, 
 "data": {"dock_id":4660} // 可指定要回充的基座ID, 若不赋值，*"data": {}，*则对接机器人搜索到的第一个回充底座
}

响应：response_start_docking

{
 "accid": "WF_TRON2A_001", 
 "title": "response_start_docking", 
 "guid": "d2c6521699e035949c9276cb17b62bdb", 
 "timestamp": 1762771300000,
 "data": { 
 "result": "success", 
 "success": true,
  "message": "docking started; docking prepared (dock_id:4660)" 
   } 
}

3.10.4 取消回充 / 取消下桩（仅轮足）

请求：request_cancel_docking

{ 
"accid": "WF_TRON2A_001", 
"title": "request_cancel_docking", 
"guid": "d2c6521699e035949c9276cb17b62bdb", 
"timestamp": 1762771300000, 
"data": {} 
}

响应：response_cancel_docking

{ 
"accid": "WF_TRON2A_001", 
"title": "response_cancel_docking", 
"guid": "d2c6521699e035949c9276cb17b62bdb",
 "timestamp": 1762771300000,
  "data": { 
  "result": "success",
   "success": true, 
   "message": "docking canceled" } 
}

3.10.5 下桩（仅轮足）

请求：request_undock

{ 
"accid": "WF_TRON2A_001", 
"title": "request_undock", 
"guid": "d2c6521699e035949c9276cb17b62bdb", 
"timestamp": 1762771300000, 
"data": {} 
}

响应：response_undock

{
 "accid": "WF_TRON2A_001", 
 "title": "response_undock", 
 "guid": "d2c6521699e035949c9276cb17b62bdb", 
 "timestamp": 1762771300000,
  "data": { 
  "result": "success", 
  "success": true, 
  "message": "undocking started" 
  } 
}

双轮足 · 回充接口