SendDockCommand

Unary 请求 → Server Stream 响应。START 前请先 GetCapabilities / GetActiveTask；Stream 以末帧 ack.final=true 结束。

---

11.1 方法签名

rpc SendDockCommand(DockCommandRequest)
    returns (stream DockCommandResponse);

---

11.2 Proto 定义

源文件：autonomy/bridge/proto/external_command_service.proto

enum DockCommand {
  DOCK_CMD_UNSPECIFIED = 0;
  DOCK_CMD_START = 1;
  DOCK_CMD_STOP = 2;
  DOCK_CMD_PAUSE = 3;
  DOCK_CMD_RESUME = 4;
  DOCK_CMD_CANCEL = 5;
  DOCK_CMD_UNDOCK = 6;
}

enum DockStatus {
  DOCK_STATUS_UNKNOWN = 0;
  DOCK_STATUS_IDLE = 1;
  DOCK_STATUS_SEARCHING = 2;
  DOCK_STATUS_APPROACHING = 3;
  DOCK_STATUS_DOCKING = 4;
  DOCK_STATUS_CHARGING = 5;
  DOCK_STATUS_UNDOCKING = 6;
  DOCK_STATUS_SUCCEEDED = 7;
  DOCK_STATUS_FAILED = 8;
  DOCK_STATUS_CANCELED = 9;
}

message DockCommandRequest {
  RequestHeader header = 1;
  DockCommand command = 2;
  float max_search_radius = 3;
  int32 max_retry_count = 4;
  oneof dock_target {
    string dock_station_id = 5;
    commsgs.proto.geometry_msgs.PoseStamped dock_pose = 6;
  }
}

message DockCommandResponse {
  CommandAck ack = 1;
  DockStatus status = 2;
  float battery_percent = 3;
  string dock_station_id = 4;
}

---

11.3 字段说明

Request · DockCommandRequest

字段	类型	必填	说明
header	RequestHeader	✓	03 §3.1
command	DockCommand	✓	子命令；见下表
max_search_radius	float	START	搜索充电桩半径 (m)
max_retry_count	int32	—	最大重试次数
dock_station_id	string	START	oneof dock_target：按 ID
dock_pose	PoseStamped	START	oneof dock_target：按位姿

DockCommand 枚举

值	常量	说明
1	DOCK_CMD_START	开始对接；需 dock_target 之一
2	DOCK_CMD_STOP	停止 → IDLE
3	DOCK_CMD_PAUSE	暂停
4	DOCK_CMD_RESUME	从 PAUSED 恢复
5	DOCK_CMD_CANCEL	取消任务
6	DOCK_CMD_UNDOCK	离桩（通常自 CHARGING）

Response · DockCommandResponse

字段	类型	说明
ack	CommandAck	流应答；末帧 final=true · 03 §3.2
status	DockStatus	对接阶段
battery_percent	float	当前电量 (%)
dock_station_id	string	已对接桩 ID

DockStatus：IDLE(1) · SEARCHING(2) · APPROACHING(3) · DOCKING(4) · CHARGING(5) · UNDOCKING(6) · SUCCEEDED(7) · FAILED(8) · CANCELED(9)

        %%{init: {"theme":"base","themeVariables":{"fontSize":"12px","primaryColor":"#e0f2f2","primaryTextColor":"#1a4d6e","primaryBorderColor":"#2d9294","lineColor":"#5a7289","stateBkg":"#e0f2f2","stateBorder":"#2d9294","stateLabelColor":"#1a4d6e","edgeLabelBackground":"#ffffff","labelTextColor":"#455a64"},"state":{"nodeSpacing":18,"rankSpacing":22,"padding":6,"fontSize":12}}}%%
stateDiagram-v2
    direction TB
    [*] --> IDLE
    IDLE --> SEARCHING: START
    SEARCHING --> APPROACHING
    APPROACHING --> DOCKING
    DOCKING --> CHARGING
    DOCKING --> SUCCEEDED
    CHARGING --> UNDOCKING: UNDOCK
    UNDOCKING --> SUCCEEDED
    SEARCHING --> IDLE: STOP
    APPROACHING --> IDLE: STOP
    DOCKING --> IDLE: STOP
    SEARCHING --> CANCELED: CANCEL
    DOCKING --> FAILED
    SUCCEEDED --> [*]
    FAILED --> [*]
    CANCELED --> [*]

    classDef idle fill:#f5f7fa,stroke:#78909c,color:#455a64
    classDef run fill:#e0f2f2,stroke:#2d9294,color:#1a4d6e
    classDef active fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    classDef charge fill:#e8f5e9,stroke:#43a047,color:#2e7d32
    classDef ok fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef fail fill:#ffebee,stroke:#e53935,color:#c62828
    classDef cancel fill:#eceff1,stroke:#607d8b,color:#546e7a
    class IDLE idle
    class SEARCHING,APPROACHING run
    class DOCKING,UNDOCKING active
    class CHARGING charge
    class SUCCEEDED ok
    class FAILED fail
    class CANCELED cancel
    

---

11.4 示例（grpcurl）

环境：01 §1.1 · TC 全集：13 §13.10 · JSON 参考：01 §1.4

每张卡片上方 发送指令（蓝）、下方 收到结果（绿）；Stream 响应以末帧 ack.final=true 为准。

11.4.1 示例索引

编号	在干什么	command	末帧预期	TC
DCK-01	确认可回充、无残留任务	—	可回充 · 无活跃任务	—
DCK-02	按站点 ID 自主对接	1	SUCCEEDED · 充电中	TC-DCK-001
DCK-03	按位姿自主对接	1	SUCCEEDED	TC-DCK-002
DCK-04	离桩脱离	6	UNDOCKING → SUCCEEDED	TC-DCK-003
DCK-05	取消对接任务	5	CANCELED	—

STOP(2) / PAUSE(3) / RESUME(4) 请求体字段同对应 command 枚举；STOP 末帧回 DOCK_STATUS_IDLE。

---

11.4.2 DCK-01 · 前置检查

发 START 前确认：Bridge 支持回充，且当前无进行中的任务。

GetCapabilities + GetActiveTask 可回充 · 无活跃任务

发送指令

# DCK-01 · GetCapabilities + GetActiveTask
grpcurl -plaintext $PROTO_OPTS -d '{}' $BRIDGE $SVC/GetCapabilities
grpcurl -plaintext $PROTO_OPTS -d '{}' $BRIDGE $SVC/GetActiveTask

收到结果

{ "supportsDocking": true }
{ "type": "TASK_TYPE_NONE" }

---

11.4.3 对接

11.4.3.1 DCK-02 · START 按站点

指定 dock_station_id，自主搜索并对接到充电桩。

command 1 START dock_station_id station_a SEARCHING → DOCKING → SUCCEEDED

发送指令

# DCK-02 · START(1) dock_station_id
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendDockCommand <<EOF
{
  "header": {
    "cmd_id": "${CMD_ID}"
  },
  "command": 1,
  "dock_station_id": "station_a",
  "max_search_radius": 5.0
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true, "taskStatus": "TASK_STATUS_SUCCEEDED" },
  "status": "DOCK_STATUS_SUCCEEDED",
  "batteryPercent": 45.0,
  "dockStationId": "station_a"
}

11.4.3.2 DCK-03 · START 按位姿

指定 dock_pose，自主搜索并对接到地图中的充电桩位姿。

command 1 START dock_pose · map SEARCHING → SUCCEEDED

发送指令

# DCK-03 · START(1) dock_pose
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendDockCommand <<EOF
{
  "header": {
    "cmd_id": "${CMD_ID}"
  },
  "command": 1,
  "dock_pose": {
    "header": { "frame_id": "map" },
    "pose": {
      "position": { "x": 0.5, "y": 0.0 },
      "orientation": { "w": 1.0 }
    }
  },
  "max_search_radius": 5.0
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true, "taskStatus": "TASK_STATUS_SUCCEEDED" },
  "status": "DOCK_STATUS_SUCCEEDED",
  "batteryPercent": 42.0
}

---

11.4.4 离桩与取消

11.4.4.1 DCK-04 · UNDOCK

前提：已对接（CHARGING 或 SUCCEEDED）。发送离桩指令，脱离充电桩。

command 6 UNDOCK 已对接 / 充电中 UNDOCKING → SUCCEEDED

发送指令

# DCK-04 · UNDOCK(6)
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendDockCommand <<EOF
{
  "header": {
    "cmd_id": "${CMD_ID}"
  },
  "command": 6
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true, "taskStatus": "TASK_STATUS_SUCCEEDED" },
  "status": "DOCK_STATUS_SUCCEEDED"
}

11.4.4.2 DCK-05 · CANCEL

取消进行中的对接任务，状态变为 CANCELED。

command 5 CANCEL 任务已取消

发送指令

# DCK-05 · CANCEL(5)
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendDockCommand <<EOF
{
  "header": { "cmd_id": "${CMD_ID}" },
  "command": 5
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true, "taskStatus": "TASK_STATUS_CANCELED" },
  "status": "DOCK_STATUS_CANCELED"
}