SendMapCommand

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

12.1 方法签名

rpc SendMapCommand(MapCommandRequest)
    returns (stream MapCommandResponse);

12.2 Proto 定义

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

enum MapCommand {
  MAP_CMD_UNSPECIFIED = 0;
  MAP_CMD_LOAD = 1;
  MAP_CMD_SWITCH = 2;
  MAP_CMD_SET_INITIAL_POSE = 3;
  MAP_CMD_CLEAR_COSTMAP = 4;
  MAP_CMD_ADD_KEEP_OUT_ZONE = 5;
  MAP_CMD_REMOVE_KEEP_OUT_ZONE = 6;
}

enum MapStatus {
  MAP_STATUS_UNKNOWN = 0;
  MAP_STATUS_IDLE = 1;
  MAP_STATUS_LOADING = 2;
  MAP_STATUS_SUCCEEDED = 3;
  MAP_STATUS_FAILED = 4;
}

message MapCommandRequest {
  RequestHeader header = 1;
  MapCommand command = 2;
  oneof params {
    string map_name = 3;
    commsgs.proto.geometry_msgs.PoseWithCovarianceStamped initial_pose = 4;
    commsgs.proto.geometry_msgs.Polygon keep_out_zone = 5;
    string zone_id = 6;
  }
}

message MapCommandResponse {
  CommandAck ack = 1;
  MapStatus status = 2;
  string current_map_name = 3;
}

12.3 字段说明

Request · `MapCommandRequest`

字段	类型	必填	说明
`header`	`RequestHeader`	✓	03 §3.1
`command`	`MapCommand`	✓	子命令；见下表
`map_name`	`string`	`LOAD`/`SWITCH`	`oneof params`
`initial_pose`	`PoseWithCovarianceStamped`	`SET_INITIAL_POSE`	重定位初始位姿
`keep_out_zone`	`Polygon`	`ADD_KEEP_OUT_ZONE`	禁行区多边形
`zone_id`	`string`	`REMOVE_KEEP_OUT_ZONE`	待移除禁行区 ID

MapCommand 枚举

值	常量	`params` / 说明
1	`MAP_CMD_LOAD`	`map_name` — 加载地图
2	`MAP_CMD_SWITCH`	`map_name` — 切换地图
3	`MAP_CMD_SET_INITIAL_POSE`	`initial_pose` — 重定位
4	`MAP_CMD_CLEAR_COSTMAP`	清除代价地图
5	`MAP_CMD_ADD_KEEP_OUT_ZONE`	`keep_out_zone`
6	`MAP_CMD_REMOVE_KEEP_OUT_ZONE`	`zone_id`

Response · `MapCommandResponse`

字段	类型	说明
`ack`	`CommandAck`	流应答；末帧 `final=true` · 03 §3.2
`status`	`MapStatus`	地图操作阶段
`current_map_name`	`string`	当前加载地图名

MapStatus：IDLE(1) · LOADING(2) · SUCCEEDED(3) · FAILED(4)

        %%{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 --> LOADING: LOAD/SWITCH
    LOADING --> SUCCEEDED
    LOADING --> FAILED
    IDLE --> SUCCEEDED: SET_POSE/CLEAR/禁行区
    SUCCEEDED --> IDLE
    FAILED --> IDLE
    SUCCEEDED --> [*]

    classDef idle fill:#f5f7fa,stroke:#78909c,color:#455a64
    classDef run fill:#e0f2f2,stroke:#2d9294,color:#1a4d6e
    classDef ok fill:#e8f5e9,stroke:#43a047,color:#2e7d32
    classDef fail fill:#ffebee,stroke:#e53935,color:#c62828
    class IDLE idle
    class LOADING run
    class SUCCEEDED ok
    class FAILED fail

SET_INITIAL_POSE / CLEAR_COSTMAP / 禁行区等命令为瞬时操作，Stream 中通常 IDLE → SUCCEEDED，不经过 LOADING。

12.4 示例（grpcurl）

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

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

12.4.1 示例索引

编号	在干什么	`command`	末帧预期	TC
MAP-00	确认支持地图管理、无冲突任务	—	可地图管理 · 无活跃任务	—
MAP-01	加载静态地图	1	`SUCCEEDED` · `currentMapName`	`TC-MAP-001`
MAP-02	切换到另一张地图	2	`SUCCEEDED` · 地图名更新	`TC-MAP-002`
MAP-03	设置重定位位姿	3	`success=true`	`TC-MAP-003`
MAP-04	清除局部代价地图	4	`SUCCEEDED`	`TC-MAP-004`
MAP-05	添加禁行区	5	`SUCCEEDED`	`TC-MAP-005`
MAP-06	移除禁行区	6	`SUCCEEDED`	`TC-MAP-005`

12.4.2 MAP-00 · 前置检查

发地图 Command 前确认：Bridge 支持地图管理，且当前无进行中的 Command 任务。

GetCapabilities + GetActiveTask 可地图管理 · 无活跃任务

发送指令

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

收到结果

{ "supportsMapManagement": true }
{ "type": "TASK_TYPE_NONE" }

12.4.3 地图加载

12.4.3.1 MAP-01 · LOAD

从磁盘加载 named 地图，Stream 中可见 LOADING → SUCCEEDED。

command 1 LOAD map_name floor1 MAP_STATUS_SUCCEEDED

发送指令

# MAP-01 · LOAD(1)
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendMapCommand <<EOF
{
  "header": {
    "cmd_id": "${CMD_ID}"
  },
  "command": 1,
  "map_name": "floor1"
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true },
  "status": "MAP_STATUS_SUCCEEDED",
  "currentMapName": "floor1"
}

12.4.3.2 MAP-02 · SWITCH

已加载一张地图后，切换到另一张（无需重启导航栈）。

command 2 SWITCH map_name floor2 MAP_STATUS_SUCCEEDED

发送指令

# MAP-02 · SWITCH(2)
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendMapCommand <<EOF
{
  "header": {
    "cmd_id": "${CMD_ID}"
  },
  "command": 2,
  "map_name": "floor2"
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true },
  "status": "MAP_STATUS_SUCCEEDED",
  "currentMapName": "floor2"
}

12.4.4 定位与代价地图

12.4.4.1 MAP-03 · SET_INITIAL_POSE

手动设置机器人在地图中的初始位姿（重定位 / 开机放置）。

command 3 SET_INITIAL_POSE frame_id=map success=true

发送指令

# MAP-03 · SET_INITIAL_POSE(3)
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendMapCommand <<EOF
{
  "header": {
    "cmd_id": "${CMD_ID}"
  },
  "command": 3,
  "initial_pose": {
    "header": {
      "frame_id": "map"
    },
    "pose": {
      "pose": {
        "position": {
          "x": 2,
          "y": 3
        },
        "orientation": {
          "w": 1.0
        }
      }
    }
  }
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true },
  "status": "MAP_STATUS_SUCCEEDED"
}

12.4.4.2 MAP-04 · CLEAR_COSTMAP

清除局部代价地图中的动态障碍残留，常用于机器人被困后恢复。

command 4 CLEAR_COSTMAP MAP_STATUS_SUCCEEDED

发送指令

# MAP-04 · CLEAR_COSTMAP(4)
export CMD_ID=$(new_cmd_id)

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

收到结果 · 末帧

{
  "ack": { "success": true, "final": true },
  "status": "MAP_STATUS_SUCCEEDED"
}

12.4.5 禁行区

12.4.5.1 MAP-05 · ADD_KEEP_OUT_ZONE

在代价地图上添加多边形禁行区（导航规划将绕开）。

command 5 ADD Polygon ≥ 3 点 MAP_STATUS_SUCCEEDED

发送指令

# MAP-05 · ADD_KEEP_OUT_ZONE(5)
export CMD_ID=$(new_cmd_id)

grpcurl -plaintext $PROTO_OPTS \
  -d @- \
  $BRIDGE \
  $SVC/SendMapCommand <<EOF
{
  "header": {
    "cmd_id": "${CMD_ID}"
  },
  "command": 5,
  "keep_out_zone": {
    "points": [
      { "x": 5, "y": 5, "z": 0 },
      { "x": 6, "y": 5, "z": 0 },
      { "x": 6, "y": 6, "z": 0 }
    ]
  }
}
EOF

收到结果 · 末帧

{
  "ack": { "success": true, "final": true },
  "status": "MAP_STATUS_SUCCEEDED"
}

12.4.5.2 MAP-06 · REMOVE_KEEP_OUT_ZONE

按 zone_id 移除先前添加的禁行区。

command 6 REMOVE zone_id zone_001 MAP_STATUS_SUCCEEDED

发送指令

# MAP-06 · REMOVE_KEEP_OUT_ZONE(6)
export CMD_ID=$(new_cmd_id)

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

收到结果 · 末帧

{
  "ack": { "success": true, "final": true },
  "status": "MAP_STATUS_SUCCEEDED"
}

SendMapCommand

12.1 方法签名

12.2 Proto 定义

12.3 字段说明

Request · MapCommandRequest

Response · MapCommandResponse

12.4 示例（grpcurl）

12.4.1 示例索引

12.4.2 MAP-00 · 前置检查

12.4.3 地图加载

12.4.3.1 MAP-01 · LOAD

12.4.3.2 MAP-02 · SWITCH

12.4.4 定位与代价地图

12.4.4.1 MAP-03 · SET_INITIAL_POSE

12.4.4.2 MAP-04 · CLEAR_COSTMAP

12.4.5 禁行区

12.4.5.1 MAP-05 · ADD_KEEP_OUT_ZONE

12.4.5.2 MAP-06 · REMOVE_KEEP_OUT_ZONE

Request · `MapCommandRequest`

Response · `MapCommandResponse`