接入与验证

系统测试与研发联调 AutonomyService 的标准接入流程。完整用例库（含预期 JSON、E2E 场景）见 13 集成测试参考。

1.1 环境配置

参数	默认值	说明
地址	`127.0.0.1:5005`	机载 §1 Bridge 配置
服务	`autonomy.bridge.proto.AutonomyService`	gRPC 全名
Proto	`autonomy/bridge/proto/external_command_service.proto`	需 `-import-path` 指向仓库根

export REPO=/path/to/autonomy          # 改为本机仓库路径
export BRIDGE=127.0.0.1:5005
export PROTO_OPTS="-import-path $REPO -proto autonomy/bridge/proto/external_command_service.proto"
export SVC=autonomy.bridge.proto.AutonomyService
new_cmd_id() { echo "test-$(date +%s)-$RANDOM"; }

# 推荐：JSON 用 heredoc + -d @-，避免 shell 转义导致可读性下降
grpc_call() {
  grpcurl -plaintext $PROTO_OPTS -d @- "$BRIDGE" "$SVC/$1"
}

安装 grpcurl：brew install grpcurl 或 go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

1.2 服务发现

确认 Bridge 可达、Proto 路径正确（无需机载任务）。

命令	判定
`list`	输出含 `autonomy.bridge.proto.AutonomyService`
`list $SVC`	13 个 RPC 方法
`describe $SVC.Method`	请求/响应类型签名
`describe autonomy.bridge.proto.Message`	消息字段定义

grpcurl -plaintext $PROTO_OPTS $BRIDGE list
grpcurl -plaintext $PROTO_OPTS $BRIDGE list $SVC
grpcurl -plaintext $PROTO_OPTS $BRIDGE describe $SVC.GetCapabilities
grpcurl -plaintext $PROTO_OPTS $BRIDGE describe autonomy.bridge.proto.NavigationCommandRequest

1.3 快速冒烟（5 步）

Query → Nav STOP → EmergencyStop → Stream。响应 JSON → §1.4；自动化脚本 → 13 §13.13。

#	RPC	判定
1	`GetCapabilities`	`bridgeVersion` 非空
2	`GetActiveTask`	`type=NONE`, `status=IDLE`
3	`SendNavigationCommand` STOP(2)	末帧 `NAV_STATUS_IDLE`
4	`EmergencyStop`	`success=true`
5	`ReceiveBotStates`	持续输出 JSON，Ctrl+C 结束

# 1 GetCapabilities
grpcurl -plaintext $PROTO_OPTS -d '{}' $BRIDGE $SVC/GetCapabilities

# 2 GetActiveTask
grpcurl -plaintext $PROTO_OPTS -d '{}' $BRIDGE $SVC/GetActiveTask

# 3 Nav STOP
export CMD_ID=$(new_cmd_id)
grpcurl -plaintext $PROTO_OPTS -d @- $BRIDGE $SVC/SendNavigationCommand <<EOF
{ "header": { "cmd_id": "${CMD_ID}" }, "command": 2 }
EOF

# 4 EmergencyStop
export CMD_ID=$(new_cmd_id)
grpcurl -plaintext $PROTO_OPTS -d @- $BRIDGE $SVC/EmergencyStop <<EOF
{ "header": { "cmd_id": "${CMD_ID}" }, "reason": "smoke" }
EOF

# 5 ReceiveBotStates（Ctrl+C 结束）
grpcurl -plaintext $PROTO_OPTS -d '{}' $BRIDGE $SVC/ReceiveBotStates

1.4 响应 JSON 参考

GetCapabilities

{
  "plannerIds": ["navfn_planner"],
  "controllerIds": ["graceful_controller"],
  "supportsNavigation": true,
  "supportsMapManagement": true,
  "bridgeVersion": "0.1.0",
  "autonomyVersion": "0.1.0"
}

GetActiveTask（空闲）

{ "type": "TASK_TYPE_NONE", "status": "TASK_STATUS_IDLE" }

Command Stream — 进度帧

{
  "ack": {
    "success": true,
    "final": false,
    "cmdId": "test-1710000001-1234",
    "taskType": "TASK_TYPE_NAVIGATION",
    "taskStatus": "TASK_STATUS_RUNNING"
  },
  "status": "NAV_STATUS_NAVIGATING",
  "distanceRemaining": 12.5,
  "currentWaypointIndex": 0,
  "totalWaypoints": 1
}

Command Stream — 成功末帧

{
  "ack": {
    "success": true,
    "final": true,
    "cmdId": "test-1710000001-1234",
    "taskType": "TASK_TYPE_NAVIGATION",
    "taskStatus": "TASK_STATUS_SUCCEEDED"
  },
  "status": "NAV_STATUS_SUCCEEDED",
  "distanceRemaining": 0.0
}

Command Stream — 失败末帧

{
  "ack": {
    "success": false,
    "final": true,
    "errorCode": "PLANNING_NO_PATH_FOUND",
    "message": "No path found",
    "taskStatus": "TASK_STATUS_FAILED"
  },
  "status": "NAV_STATUS_FAILED"
}

System — EmergencyStop

{
  "success": true,
  "message": "Emergency stop acknowledged",
  "errorCode": "OK",
  "taskType": "TASK_TYPE_NONE",
  "taskStatus": "TASK_STATUS_IDLE"
}

任务结束判据：Command Stream 末帧 ack.final=true。失败时 ack.success=false，查 errorCode（03 §3.6）。

1.5 客户端开发（Python）

Stub 调用与 Bidi Teleop 示例 → 13 §13.14。

1.6 代码生成

pip install grpcio-tools
python -m grpc_tools.protoc -I$REPO \
  --python_out=./gen --grpc_python_out=./gen \
  autonomy/bridge/proto/external_command_service.proto \
  autonomy/commsgs/proto/builtin_interfaces.proto \
  autonomy/commsgs/proto/geometry_msgs.proto \
  autonomy/commsgs/proto/vehicle_msgs.proto \
  autonomy/commsgs/proto/error_code.proto \
  autonomy/commsgs/proto/std_msgs.proto