YangOne/GrabBag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
GrabBag/App/ParkingSpaceGuide/Doc/停机引导对接协议.md
杰仔 243a24a253 提交ParkingSpaceGuide 飞机引导
2026-07-11 16:02:57 +08:00

8.6 KiB
Raw Blame History

停机引导对接协议

版本信息

项目 内容
文档版本 V1.0
更新日期 2026-07-10
适用范围 UDP 组播状态包、HTTP 当前状态查询
说明 初版，对接数据内容以本文字段定义为准。

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. 成功数据示例

{
  "protocol": "ParkingSpaceGuideResult",
  "version": "1.0",
  "success": true,
  "hasResult": true,
  "targetId": "T001",
  "parkId": "P01",
  "modelType": "A320",
  "guideStateCode": 8,
  "distanceToStop": 500.0,
  "bodyYawAngle": 0.0,
  "lateralOffset": 0.0,
  "aircraftSpeed": 0.4,
  "hasException": false,
  "guideText": "STOP",
  "message": "正常",
  "errorCode": 0,
  "timestamp": 1783339200000
}

6. 失败或无结果数据示例

检测失败、无有效目标、视野受阻等情况下，系统仍可发送状态包。此时 success=false，hasResult=false。

{
  "protocol": "ParkingSpaceGuideResult",
  "version": "1.0",
  "success": false,
  "hasResult": false,
  "targetId": "T001",
  "parkId": "P01",
  "modelType": "未知",
  "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.0。
success bool - 软件根据检测结果生成 errorCode=0 且存在有效结果时为 true。
hasResult bool - 软件根据检测结果生成 本包是否包含有效结果。
targetId string - 软件界面组播参数配置 目标编号，默认 T001。
parkId string - 软件界面组播参数配置 当前停机位编号，默认 P01。
modelType string - 算法识别结果 机型；算法未识别成功时为 未知。
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显示式样开发交底-0707.xlsx 中“序号”列。

序号 流程/功能 显示式样说明
1 泊位引导启动 WAIT
2 捕获 浮动垂直运行箭头+飞机类型
3 跟踪 黄色中心线指示器；偏离中心线时显示闪烁红色转向箭头
4 接近率 数字显示距离+米
5 对准中心线 距离显示；不显示方向箭头
6 慢速 SLOW
7 方位引导 黄色位置箭头+闪烁红色转向箭头
8 到达停止位置 STOP
9 泊位引导完成 OK
10 越位 TOOFAR
11 提前停止 STOPOK
12 等待 WAIT
13 异常慢速-恶劣天气 SLOW+飞机类型；禁用浮动箭头
14 异常慢速-泊位引导中飞机丢失 SLOW
15 飞机验证失败 先WAIT并进行第二次验证；若仍失败，显示STOP+IDFAIL
16 机位受阻 WAIT+GATEBLOCK
17 视野受阻 VIEWBLOCKED
18 SBU停止 STOPSBU
19 速度过快 STOPTOOFAST
20 紧急停止 STOP
21 挡轮挡 CHOCKON
22 系统错误 ERROR+错误代码
23 系统故障 黑屏
24 电源故障 完全黑屏

当前协议中，guideStateCode 为 10 至 24 时按异常情况处理，并使 hasException=true。

9. 对接说明

现场系统如果只需要核心结果，建议优先解析以下字段：

  • targetId
  • parkId
  • modelType
  • 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 增加字段，避免因协议扩展导致解析失败。
  • 数值单位以本协议字段定义为准。
  • 文本状态建议按原字符串解析。