Wheeled legs · docking API

3.10 Dual-Wheel-Leg Charging Dock Interface

3.10.1 Scan for Charging Docks

Supported on Dual-Wheel-Leg (WF) models only. The request performs a single scan → wait for any ongoing scan to time out → read the list transaction. It does not pair, light up the dock, enable the charging MOSFET, or send EV_GO_DOCKING, nor does it modify the autonomous-charging lifecycle state. The protocol currently returns only a 16-bit little-endian dock_id and has no RSSI field, so the response does not fabricate signal strength.

Scanning is mutually exclusive with charging-dock scan/pairing, docking, charging, and undocking; a conflict returns fail_dock_busy. The list is returned in hardware scan order and deduplicated, and the payload length must be exactly 1 + 2 * raw count. An empty list counts as a successful scan and is clearly distinguished from a hardware/protocol scan failure.

• Request: request_scan_docks

data must be an empty object:

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

• Response: 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
  }
}

An empty list still returns success=true / result="success", with docks=[], count=0, and message="no charging docks found". scanned_at is the Unix timestamp in milliseconds when the scan completed; for a rejection response where no hardware scan was actually initiated, it is 0.

3.10.2 Query the Full Charging Dock Status

This interface is a read-only operation that requires no developer mode and triggers no scanning, no controller switching, and no hardware side effects. The signaling layer calls dock/status on the snowball /tron2/service and, after validating the JSON, passes the fields and the message through unchanged.

• Request: request_get_docking_status

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

• Response: 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
  }
}

Field semantics:

• phase is a stable business-level enum: idle (no charging attempt has been initiated since the process started), preparing (scanning, dock selection, or pairing), docking (docking with the charging dock or performing an automatic retry), confirming (waiting for both controller and charging conditions), charging (both conditions are satisfied and the robot is in ST_DOCKING), undock_preparing, undocking, canceled, failed, manual_undock, and walking.

• robot_state preserves the original snowball ST_* state. Business phases and raw states are not forced into a one-to-one mapping; for example, after a failure the robot may already be back in ST_WALKING while phase remains failed.

• dock_id=null together with has_dock_id=false means no dock has been selected yet, or the state could not be restored after a process restart. The ID 0 is a valid value and must not be interpreted as unknown. requested_dock_id reflects only the value requested by the SDK; the final pairing result is determined by dock_id.

• attempt_token increments each time the RC or SDK initiates a new autonomous charging attempt. This clears the previous dock selection and failure records.confirm_attempt_token numbers each gocharge dual-condition window; automatic retries update it and increment retry_count.

• When an automatic retry starts, the errors from the current round move into previous_failure_*, while the final failure remains in failure_*. A new user attempt clears both failure groups; an explicit success clears the current failure.

• confirm_remaining_sec is a number only while the confirmation window is active, and null otherwise. It is computed from a monotonic clock; updated_at is the Unix timestamp in milliseconds of the most recent business-state update.

• battery_percent=null together with battery_known=false means no valid battery level has been received yet; an unknown battery level is never fabricated as 0.

On non-WF models, the response returns success=true, supported=false, phase=idle, and an explicit message; the query itself still succeeds.

State transitions:

idle/walking → preparing → docking → confirming → charging → undock_preparing → undocking → walking. Scan/pairing errors, controller errors, confirmation timeouts, low battery, or undocking errors enter failed; offcharge code=-1 enters manual_undock; a user cancellation enters canceled. The controller and charging confirmation signals are order-independent.

Query error codes:

3.10.3 Start Docking (Dual-Wheel-Leg Only)

• Request: request_start_docking

{
  "accid": "WF_TRON2A_001",
  "title": "request_start_docking",
  "guid": "d2c6521699e035949c9276cb17b62bdb",
  "timestamp": 1762771300000,
  "data": {"dock_id": 4660}  // Optionally specify the ID of the dock to dock with. If `dock_id` is omitted (`"data": {}`), the robot docks with the first charging dock discovered during the scan.
}

• Response: 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 Cancel Docking / Cancel Undocking

• Request: request_cancel_docking

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

• Response: 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 Undock (Dual-Wheel-Leg Only)

• Request: request_undock

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

• Response: response_undock

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