139 lines
4.9 KiB
Markdown
139 lines
4.9 KiB
Markdown
# 停机引导远程控制协议
|
||
|
||
## 版本信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 文档版本 | V1.1 |
|
||
| 更新日期 | 2026-09-09 |
|
||
| 适用范围 | ParkingSpaceGuideView 远程发现、控制和状态订阅 |
|
||
| 说明 | 控制端协议。引导结果字段见《停机引导对接协议》。 |
|
||
|
||
远程协议名称为 `ParkingSpaceGuideRemote`，版本 `1.1`。
|
||
|
||
## 1. 协议概述
|
||
|
||
`ParkingSpaceGuideApp` 提供远程服务。`ParkingSpaceGuideView` 通过 UDP 发现服务端，通过 ZeroMQ REQ/REP 发送控制命令，通过 ZeroMQ PUB/SUB 接收实时引导结果。
|
||
|
||
状态数据与《停机引导对接协议》中的 `ParkingSpaceGuideResult` 相同。
|
||
|
||
默认参数：
|
||
|
||
| 参数 | 默认值 | 传输方式 | 用途 |
|
||
| --- | ---: | --- | --- |
|
||
| discoveryPort | 5555 | UDP | 控制端广播搜索，服务端单播响应。 |
|
||
| controlPort | 15655 | ZeroMQ REQ/REP | 选择机型、开始/停止、维护模式、轮挡时间、历史回放。 |
|
||
| publishPort | 15656 | ZeroMQ PUB/SUB | 发布完整引导状态。 |
|
||
| topic | parking_guide | ZeroMQ topic | 状态订阅主题。 |
|
||
|
||
## 2. UDP 发现
|
||
|
||
请求：
|
||
|
||
```json
|
||
{"cmd":"discover","service":"ParkingSpaceGuide","protocol":"ParkingSpaceGuideRemote"}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"code": 0,
|
||
"cmd": "discover",
|
||
"protocol": "ParkingSpaceGuideRemote",
|
||
"version": "1.1",
|
||
"service": "ParkingSpaceGuide",
|
||
"deviceName": "ParkingSpaceGuideApp",
|
||
"deviceId": "设备唯一标识",
|
||
"controlPort": 15655,
|
||
"publishPort": 15656,
|
||
"topic": "parking_guide",
|
||
"activated": false,
|
||
"workMode": "normal",
|
||
"timestamp": 1783339200000
|
||
}
|
||
```
|
||
|
||
须校验 `ok`、`cmd`、`protocol`、`service`，并确认端口和主题有效。
|
||
|
||
## 3. ZeroMQ 控制
|
||
|
||
请求和应答均为单个紧凑 JSON。请求包含 `cmd`、`protocol`（固定 `ParkingSpaceGuideRemote`）。
|
||
|
||
| cmd | 请求字段 | 说明 |
|
||
| --- | --- | --- |
|
||
| select_model | `modelType` | 选择机型，须为当前配置中的可选机型。此处 `modelType` 为选择值，不是检测结果。 |
|
||
| start | `modelType`，可空 | 开始引导。空表示不选机型、不校验。 |
|
||
| stop | 无 | 停止引导。 |
|
||
| set_maintenance | `enabled` | `true` 进入维护模式，`false` 退出。 |
|
||
| chock_on / chock_off | 无 | 记录上/下轮挡时间。 |
|
||
| get_panel_config | 无 | 获取机型表和当前运行状态。 |
|
||
| list_sessions | `limit` | 列出历史会话，默认 50 条。 |
|
||
| get_session_samples | `sessionUuid` | 获取会话引导明细，按时间排序，用于还原该次引导过程。 |
|
||
| get_status | 无 | 获取当前完整 `ParkingSpaceGuideResult`。 |
|
||
| get_info | 无 | 获取服务信息，字段同发现响应。 |
|
||
| ping | 无 | 心跳。 |
|
||
|
||
成功：`ok=true`，`code=0`。失败：
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"code": -3,
|
||
"cmd": "start",
|
||
"message": "服务端拒绝启动停机引导，请检查设备或安全状态",
|
||
"protocol": "ParkingSpaceGuideRemote",
|
||
"version": "1.1"
|
||
}
|
||
```
|
||
|
||
| code | 含义 |
|
||
| ---: | --- |
|
||
| 0 | 成功 |
|
||
| -1 | 请求不是有效 JSON |
|
||
| -2 | 参数错误 |
|
||
| -3 | 服务端拒绝执行 |
|
||
| -4 | 不支持的命令 |
|
||
| -5 | 协议名称不匹配 |
|
||
|
||
开始（`modelType` 须为当前配置中的机型名称，下面 `C919` 仅为示例）：
|
||
|
||
```json
|
||
{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":"C919"}
|
||
```
|
||
|
||
不选机型开始：
|
||
|
||
```json
|
||
{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":""}
|
||
```
|
||
|
||
开始成功时返回 `activated=true`、`workMode`。停止成功时 `activated=false`。
|
||
|
||
`get_status` 的 `status` 为《停机引导对接协议》定义的完整结果对象。
|
||
|
||
`get_panel_config` 的 `panel`：`models` 为当前配置的可选机型，不是协议写死的清单。`C919` 仅为示例。
|
||
|
||
```json
|
||
{
|
||
"models": [
|
||
{ "name": "A320", "verifiable": true },
|
||
{ "name": "B737", "verifiable": true },
|
||
{ "name": "C919", "verifiable": false }
|
||
],
|
||
"workMode": "normal",
|
||
"activated": false
|
||
}
|
||
```
|
||
|
||
`verifiable=true` 表示选择名称包含 `A320` 或 `B737`，按检测家族匹配，例如 `A320-200` 对应检测 `A320`。其余配置机型为 `false`。
|
||
|
||
`list_sessions` 返回 `sessions` 数组。字段与《停机引导对接协议》第 7 节对齐，另含 `sessionUuid`、`startTime`、`endTime`。`sessionUuid` 仅用于回放关联，不是结果协议字段。`startTime`、`endTime` 及轮挡时间为设备本地 `yyyy-MM-dd HH:mm:ss`；未记录或进行中的时间为空。
|
||
|
||
`get_session_samples` 返回 `samples` 数组，按 `timestamp` 升序。元素为当时完整 `ParkingSpaceGuideResult`，字段与《停机引导对接协议》第 7 节一致，不含点云和图像。
|
||
|
||
## 4. ZeroMQ 状态订阅
|
||
|
||
发布为双帧消息：第一帧为主题 `parking_guide`，第二帧为完整 `ParkingSpaceGuideResult` JSON。客户端须按完整主题匹配。
|