GrabBag/App/ParkingSpaceGuide/Doc/停机引导对接协议.md

停机引导对接协议

版本信息

项目	内容
文档版本	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. 成功数据示例

{
  "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。

{
  "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 节点配置：

<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 网卡的子网广播地址发送：

{"cmd":"discover","service":"ParkingSpaceGuide","protocol":"ParkingSpaceGuideRemote"}

App 响应发送方的源 IP 和源端口：

{
  "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	无	通信心跳。

开始请求示例：

{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":"A320"}

不指定期望机型时发送空值：

{"cmd":"start","protocol":"ParkingSpaceGuideRemote","modelType":""}

成功响应保留发现响应中的公共字段，并返回 ok=true、code=0、对应 cmd 和 guidanceRunning。失败响应示例：

{
  "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 项目：

./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 另外将同一图标安装到系统桌面图标目录，不依赖源码路径。