369 lines
16 KiB
Markdown
369 lines
16 KiB
Markdown
# 停机引导对接协议
|
||
|
||
## 版本信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 文档版本 | V1.1 |
|
||
| 更新日期 | 2026-07-21 |
|
||
| 适用范围 | UDP 组播状态包、HTTP 当前状态查询 |
|
||
| 说明 | 按 0720 LED 显示式样更新引导流程和显示规则。 |
|
||
|
||
## 1. 协议概述
|
||
|
||
停机引导系统支持通过组播主动发送检测结果，也支持作为 HTTP 服务端，由现场系统按需查询当前停机状态。现场系统获取数据后，可解析当前停机位、目标编号、机型、到停止线距离、机身偏转角等信息。
|
||
|
||
协议特点：
|
||
|
||
- 传输方式：组播，基于 UDP 数据报
|
||
- 查询方式：HTTP，停机引导系统作为服务端，现场系统作为客户端
|
||
- 数据格式：JSON
|
||
- 字符编码：UTF-8
|
||
- 组播数据方向：停机引导系统发送，现场系统接收
|
||
- HTTP 数据方向：现场系统请求，停机引导系统响应
|
||
- 组播应答机制：无应答
|
||
- HTTP 应答机制：请求-响应
|
||
- 组播重发机制：无重发
|
||
- 组播发送时机：每次检测结果更新时发送 1 包数据
|
||
|
||
## 2. 组播网络参数
|
||
|
||
组播网络参数由停机引导系统配置。
|
||
|
||
| 参数 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| enabled | true | 是否启用组播发送。 |
|
||
| address | 239.255.0.1 | 组播地址。 |
|
||
| port | 8800 | 组播端口。 |
|
||
| targetId | T001 | 目标编号，由软件配置或现场系统约定。 |
|
||
| parkId | P01 | 当前停机位编号，由软件配置。 |
|
||
|
||
配置兜底规则：
|
||
|
||
- 组播地址为空时使用 `239.255.0.1`
|
||
- 端口非法时使用 `8800`
|
||
- `targetId` 为空时使用 `T001`
|
||
- `parkId` 为空时使用 `P01`
|
||
|
||
## 3. HTTP 查询对接
|
||
|
||
HTTP 查询用于现场系统主动获取当前停机状态。停机引导系统作为 HTTP 服务端，返回最近一次检测状态；如果系统刚启动且尚未产生检测结果，则返回失败或无结果数据示例中的状态包。
|
||
|
||
HTTP 服务参数由停机引导系统配置，不放在参数配置界面。
|
||
|
||
| 参数 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| enabled | true | 是否启用 HTTP 状态服务。 |
|
||
| address | 0.0.0.0 | HTTP 服务监听地址；`0.0.0.0` 表示监听本机所有网卡。 |
|
||
| port | 8801 | HTTP 服务端口。 |
|
||
| maxQueued | 16 | 等待处理的最大连接队列数。 |
|
||
| maxThreads | 4 | 最大处理线程数。 |
|
||
|
||
请求方式：
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| URL | `http://<停机引导设备IP>:8801/api/parking/status` |
|
||
| Method | `GET` |
|
||
| Request Body | 无 |
|
||
| Response Content-Type | `application/json; charset=utf-8` |
|
||
|
||
兼容路径：
|
||
|
||
- `/`
|
||
- `/status`
|
||
- `/api/status`
|
||
- `/api/parking/status`
|
||
|
||
响应数据：
|
||
|
||
- HTTP 状态码 `200`：返回当前停机状态 JSON，数据内容与 UDP 组播状态包一致，字段与第 4 至第 7 节定义一致。
|
||
- HTTP 状态码 `404`：请求路径不存在。
|
||
- HTTP 状态码 `405`：请求方法不支持。
|
||
|
||
现场系统建议按 `timestamp` 判断数据是否更新，避免重复处理同一包状态。
|
||
|
||
## 4. JSON 数据格式
|
||
|
||
每包组播数据为一个 JSON 对象。实际发送时为紧凑 JSON，不包含格式化换行。
|
||
|
||
HTTP 查询接口返回的数据内容与 UDP 组播数据一致，字段、含义、单位和取值规则相同，仅传输方式不同。
|
||
|
||
本软件每次只检测一个飞机停机位，因此结果字段直接放在顶层对象中，不包含结果数组。
|
||
|
||
## 5. 成功数据示例
|
||
|
||
```json
|
||
{
|
||
"protocol": "ParkingSpaceGuideResult",
|
||
"version": "1.1",
|
||
"success": true,
|
||
"hasResult": true,
|
||
"targetId": "T001",
|
||
"parkId": "P01",
|
||
"expectedModelType": "A320",
|
||
"modelType": "飞机",
|
||
"modelMatched": false,
|
||
"modelVerificationSupported": false,
|
||
"modelConfidence": 0.932,
|
||
"personInChockRegion": true,
|
||
"chocksConfirmed": true,
|
||
"personCount": 1,
|
||
"personConfidence": 0.907,
|
||
"guideStateCode": 21,
|
||
"distanceToStop": 50.0,
|
||
"bodyYawAngle": 0.0,
|
||
"lateralOffset": 0.0,
|
||
"aircraftSpeed": 0.4,
|
||
"hasException": false,
|
||
"guideText": "CHOCK ON",
|
||
"message": "轮挡区域人员检测已确认，轮挡固定流程完成",
|
||
"errorCode": 0,
|
||
"timestamp": 1783339200000
|
||
}
|
||
```
|
||
|
||
## 6. 失败或无结果数据示例
|
||
|
||
检测失败、无有效目标、视野受阻等情况下，系统仍可发送状态包。此时 `success=false`，`hasResult=false`。
|
||
|
||
```json
|
||
{
|
||
"protocol": "ParkingSpaceGuideResult",
|
||
"version": "1.1",
|
||
"success": false,
|
||
"hasResult": false,
|
||
"targetId": "T001",
|
||
"parkId": "P01",
|
||
"expectedModelType": "",
|
||
"modelType": "未知",
|
||
"modelMatched": false,
|
||
"modelVerificationSupported": true,
|
||
"modelConfidence": 0.0,
|
||
"personInChockRegion": false,
|
||
"chocksConfirmed": false,
|
||
"personCount": 0,
|
||
"personConfidence": 0.0,
|
||
"guideStateCode": 0,
|
||
"distanceToStop": 0.0,
|
||
"bodyYawAngle": 0.0,
|
||
"lateralOffset": 0.0,
|
||
"aircraftSpeed": 0.0,
|
||
"hasException": true,
|
||
"guideText": "",
|
||
"message": "无有效结果",
|
||
"errorCode": -1,
|
||
"timestamp": 1783339200000
|
||
}
|
||
```
|
||
|
||
## 7. 字段定义
|
||
|
||
| 字段 | 类型 | 单位 | 来源 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| protocol | string | - | 软件固定值 | 协议名称，固定为 `ParkingSpaceGuideResult`。 |
|
||
| version | string | - | 软件固定值 | 协议版本，当前为 `1.1`。 |
|
||
| success | bool | - | 软件根据检测结果生成 | `errorCode=0` 且存在有效结果时为 `true`。 |
|
||
| hasResult | bool | - | 软件根据检测结果生成 | 本包是否包含有效结果。 |
|
||
| targetId | string | - | 软件界面组播参数配置 | 目标编号，默认 `T001`。 |
|
||
| parkId | string | - | 软件界面组播参数配置 | 当前停机位编号，默认 `P01`。 |
|
||
| expectedModelType | string | - | 操作员开始前选择 | 本次引导的期望机型；当前支持 `A320`、`B737`。 |
|
||
| modelType | string | - | 平面相机识别结果 | 当前通用模型检测到飞机时为“飞机”；未来细分模型可返回 A320/B737；尚无结果时为“未知”。 |
|
||
| modelMatched | bool | - | 软件校验结果 | 实际机型与期望机型一致且置信度达到阈值时为 `true`。 |
|
||
| modelVerificationSupported | bool | - | 模型能力 | 当前模型是否支持 A320/B737 细分机型校验；通用飞机检测模型为 `false`。 |
|
||
| modelConfidence | number | - | 平面相机识别结果 | 实际识别置信度；未识别时为 `0`。 |
|
||
| personInChockRegion | bool | - | 平面相机检测结果 | 裁剪后的轮挡 ROI 内是否检测到人员。 |
|
||
| chocksConfirmed | bool | - | 软件连续帧判定 | 人员连续进入轮挡 ROI 达到配置次数后为 `true`。 |
|
||
| personCount | number | 人 | 平面相机检测结果 | 本次检测中位于轮挡 ROI 的人数。 |
|
||
| personConfidence | number | - | 平面相机检测结果 | 轮挡 ROI 内人员的最高置信度。 |
|
||
| guideStateCode | number | - | 算法检测结果或软件状态 | 引导状态序号；取值见“引导状态枚举”，无有效状态时为 `0`。 |
|
||
| distanceToStop | number | 毫米 | 算法检测结果 | 到停止线距离。正负方向按现场标定坐标定义执行。 |
|
||
| bodyYawAngle | number | 度 | 算法检测结果 | 机身偏转角。正负方向按现场标定坐标定义执行。 |
|
||
| lateralOffset | number | 毫米 | 算法检测结果 | 相对引导中心线的横向偏移。 |
|
||
| aircraftSpeed | number | 米/秒 | 算法检测结果 | 飞机接近速度。 |
|
||
| hasException | bool | - | 软件根据 `errorCode` 和 `guideStateCode` 生成 | 是否有异常；`errorCode != 0` 或 `guideStateCode` 属于异常情况时为 `true`。 |
|
||
| guideText | string | - | 算法检测结果 | 引导状态或显示文本。 |
|
||
| message | string | - | 算法结果或软件状态 | 本次数据说明或异常原因。 |
|
||
| errorCode | number | - | 算法返回值或软件状态 | 错误码。`0` 表示正常，非 `0` 表示异常或无有效结果。 |
|
||
| timestamp | number | 毫秒 | 软件发送时系统时间 | Unix 毫秒时间戳。 |
|
||
|
||
## 8. 引导状态枚举
|
||
|
||
`guideStateCode` 取值来源于 `App/ParkingSpaceGuide/Demand/T1-42_LED显示式样开发交底-0720.xlsx` 中“序号”列。绿色行发送 LED 内容，白色行发送空白动态区内容使 LED 清屏；清屏不影响 UI、UDP 或 HTTP 中的状态数据。
|
||
|
||
| 序号 | 流程/功能 | LED 输出 | 进入条件 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | 泊位引导启动 | START + 选择机型 | 已点击开始，且有效点云测得距离不大于 100 m；尚无有效测量时保持序号 12 等待状态。 |
|
||
| 2 | 捕获 | CAPTURE + 选择机型 | 距离大于 25 m 且不大于 80 m。 |
|
||
| 3 | 跟踪 | 清屏 | 内部跟踪状态。 |
|
||
| 4 | 接近率 | 清屏 | 内部接近率状态。 |
|
||
| 5 | 对准中心线 | 距离 + 选择机型 | 距离不大于 25 m，横向和航向在配置容差内。 |
|
||
| 6 | 慢速 | SLOW + 距离 | 距离不大于 15 m，接近速度不小于 2 m/s。 |
|
||
| 7 | 方位引导 | 距离 + 横向偏差 | 距离不大于 25 m，横向或航向超出配置容差。 |
|
||
| 8 | 到达停止位置 | STOP | 到停止线距离在正负 0.1 m 内。 |
|
||
| 9 | 泊位引导完成 | 清屏 | 停止位置稳定，且人员检测功能被禁用时结束会话。 |
|
||
| 10 | 越位 | TOO FAR | 越过停止线不小于 0.5 m。 |
|
||
| 11 | 提前停止 | 清屏 | 内部提前停止判定。 |
|
||
| 12 | 等待 | 清屏 | 尚未进入 100 m 引导范围或系统空闲。 |
|
||
| 13 | 异常慢速-恶劣天气 | 清屏 | 外部或内部天气状态。 |
|
||
| 14 | 异常慢速-泊位引导中飞机丢失 | 清屏 | 连续丢失达到配置帧数。 |
|
||
| 15 | 飞机验证失败 | STOP + ID FAIL | 距离不大于 25 m，平面相机两次验证仍与选择机型不一致。 |
|
||
| 16 | 机位受阻 | WAIT + GATE BLOCK | 外部机位受阻输入。 |
|
||
| 17 | 视野受阻 | WAIT + VIEW BLOCK | 外部视野受阻输入。 |
|
||
| 18 | SBU停止 | 清屏 | 外部 SBU 状态。 |
|
||
| 19 | 速度过快 | 清屏 | 内部速度状态。 |
|
||
| 20 | 紧急停止 | STOP | 板载急停输入有效。 |
|
||
| 21 | 挡轮挡 | CHOCK ON | 飞机停稳后，轮挡 ROI 裁剪图连续检测到人员达到稳定次数。发布本状态后结束会话并进入休眠。 |
|
||
| 22 | 系统错误 | ERROR + 错误代码 | 系统自检或算法错误。 |
|
||
| 23 | 系统故障 | 清屏 | 系统故障。 |
|
||
| 24 | 电源故障 | 清屏 | 电源故障。 |
|
||
|
||
当前协议中，`guideStateCode` 为 `10` 至 `20` 或 `22` 至 `24` 时按异常情况处理，并使 `hasException=true`；状态 `21 / CHOCK ON` 是正常完成状态。
|
||
|
||
## 9. 对接说明
|
||
|
||
现场系统如果只需要核心结果，建议优先解析以下字段：
|
||
|
||
- `targetId`
|
||
- `parkId`
|
||
- `expectedModelType`
|
||
- `modelType`
|
||
- `modelMatched`
|
||
- `modelVerificationSupported`
|
||
- `modelConfidence`
|
||
- `personInChockRegion`
|
||
- `chocksConfirmed`
|
||
- `personCount`
|
||
- `personConfidence`
|
||
- `guideStateCode`
|
||
- `distanceToStop`
|
||
- `bodyYawAngle`
|
||
- `lateralOffset`
|
||
- `aircraftSpeed`
|
||
- `hasException`
|
||
- `guideText`
|
||
- `errorCode`
|
||
- `timestamp`
|
||
|
||
状态判断建议：
|
||
|
||
- `success=true` 且 `hasResult=true`：本包包含有效引导结果。
|
||
- `success=false`：本包为异常、无目标或无有效结果状态包。
|
||
- `errorCode=0`：系统正常输出。
|
||
- `errorCode != 0`：接收端应结合 `message` 和 `guideText` 做异常显示或记录。
|
||
- `hasException=true`：本包存在异常，对应 `errorCode != 0` 或引导状态枚举中的异常情况。
|
||
|
||
注意事项：
|
||
|
||
- 组播数据不保证到达和顺序，接收端应以最新 `timestamp` 数据为准。
|
||
- 接收端应允许 JSON 增加字段，避免因协议扩展导致解析失败。
|
||
- 数值单位以本协议字段定义为准。
|
||
- 文本状态建议按原字符串解析。
|
||
|
||
## 10. ParkingSpaceGuideView 远程发现、控制和订阅协议
|
||
|
||
`ParkingSpaceGuideApp` 在后台提供远程服务，不改变本机现有页面和操作逻辑。独立程序 `ParkingSpaceGuideView` 通过 UDP 发现服务端，通过 ZeroMQ REQ/REP 发送控制命令，并通过 ZeroMQ PUB/SUB 接收实时引导结果。
|
||
|
||
默认参数由 `ParkingSpaceGuideConfig/config/config.xml` 的 `RemoteView` 节点配置：
|
||
|
||
```xml
|
||
<RemoteView enabled="true" discoveryPort="5555" controlPort="15655"
|
||
publishPort="15656" topic="parking_guide"/>
|
||
```
|
||
|
||
端口用途：
|
||
|
||
| 参数 | 默认值 | 传输方式 | 用途 |
|
||
| --- | ---: | --- | --- |
|
||
| discoveryPort | 5555 | UDP | View 广播搜索，App 单播响应。 |
|
||
| controlPort | 15655 | ZeroMQ REQ/REP | 选择机型、开始、停止和查询状态。 |
|
||
| publishPort | 15656 | ZeroMQ PUB/SUB | 发布完整引导状态。 |
|
||
| topic | parking_guide | ZeroMQ topic | 状态订阅主题，客户端按完整主题校验。 |
|
||
|
||
### 10.1 UDP 发现
|
||
|
||
View 未连接设备时每 1 秒向全局广播地址和所有活动 IPv4 网卡的子网广播地址发送：
|
||
|
||
```json
|
||
{"cmd":"discover","service":"ParkingSpaceGuide","protocol":"ParkingSpaceGuideRemote"}
|
||
```
|
||
|
||
App 响应发送方的源 IP 和源端口：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"code": 0,
|
||
"cmd": "discover",
|
||
"protocol": "ParkingSpaceGuideRemote",
|
||
"version": "1.0",
|
||
"service": "ParkingSpaceGuide",
|
||
"deviceName": "ParkingSpaceGuideApp",
|
||
"deviceId": "设备唯一标识",
|
||
"controlPort": 15655,
|
||
"publishPort": 15656,
|
||
"topic": "parking_guide",
|
||
"guidanceRunning": false,
|
||
"timestamp": 1783339200000
|
||
}
|
||
```
|
||
|
||
客户端必须同时校验 `ok`、`cmd`、`protocol` 和 `service`，控制端口、发布端口及主题有效后才建立连接。未发现设备时持续广播；通信超时后释放旧订阅并恢复搜索。
|
||
|
||
### 10.2 ZeroMQ 控制
|
||
|
||
控制请求和应答均为单个紧凑 JSON。当前命令如下：
|
||
|
||
| cmd | 请求附加字段 | 说明 |
|
||
| --- | --- | --- |
|
||
| start | `modelType`，允许空值、`A320` 或 `B737` | 开始完整停机引导；空值表示以实际识别机型完成流程。 |
|
||
| stop | 无 | 停止当前引导。 |
|
||
| get_status | 无 | 获取当前完整结果，供刚连接时补首帧。 |
|
||
| get_info | 无 | 获取服务端和端口信息。 |
|
||
| ping | 无 | 通信心跳。 |
|
||
|
||
开始请求示例：
|
||
|
||
```json
|
||
{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":"A320"}
|
||
```
|
||
|
||
不指定期望机型时发送空值：
|
||
|
||
```json
|
||
{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":""}
|
||
```
|
||
|
||
成功响应保留发现响应中的公共字段，并返回 `ok=true`、`code=0`、对应 `cmd` 和 `guidanceRunning`。失败响应示例：
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"code": -3,
|
||
"cmd": "start",
|
||
"message": "服务端拒绝启动停机引导，请检查设备或安全状态",
|
||
"protocol": "ParkingSpaceGuideRemote",
|
||
"version": "1.0"
|
||
}
|
||
```
|
||
|
||
`get_status` 成功响应在 `status` 字段内携带第 4～8 节定义的完整 `ParkingSpaceGuideResult` 对象。View 的控制请求在后台线程执行，界面线程不会等待 ZeroMQ 超时。
|
||
|
||
### 10.3 ZeroMQ 状态订阅
|
||
|
||
App 在配置的 topic 下发布双帧消息：第一帧为 UTF-8 topic `parking_guide`，第二帧为第 4～8 节定义的完整结果 JSON。View 只接受完整 topic 匹配，并把接收线程的数据排队投递到界面线程。
|
||
|
||
View 每 3 秒发送一次 `ping`。请求或应答失败、3 秒内未收到控制应答、协议不匹配时，View 将当前连接标记为异常，关闭订阅并重新进入每秒一次的 UDP 搜索。
|
||
|
||
### 10.4 ARM 程序与 DEB
|
||
|
||
`ParkingSpaceGuideView` 是独立 ARM AArch64 桌面程序和独立 deb 项目：
|
||
|
||
```text
|
||
./GrabBagPrj/project_release.sh ParkingSpaceGuideView
|
||
```
|
||
|
||
打包注册表会安装 View 可执行文件、桌面入口、程序图标及 ARM `libzmq.so`。ZeroMQClient、ZeroMQPubSub 和 VrUtils 为静态工程，链接进入可执行文件。View 的 deb 配置为 `opencv=none`、`device_copy=none`，不会带入服务端的 OpenCV、相机 SDK、算法模型或 GPIO 文件。
|
||
|
||
引导显示内容由 `GuideDisplayWidget` 使用 `QPainter` 实时绘制，不依赖 24 张状态 PNG，因此在 ARM 显示器上放大或高 DPI 缩放时不会产生位图模糊。qrc 中的程序图标编译进可执行文件，deb 另外将同一图标安装到系统桌面图标目录，不依赖源码路径。
|