FIX AXI UDP 通信协议

作者：JTX　|　维护：JTX　|　最近更新：2026-08-24　|　协议实现核对基线：当前工作区源码

本文档是 FIX AXI 对外 UDP 通信协议的统一维护入口。命令号以
FIX/fixUDPCommon.h 为准，报文解析与回包以 FIX/fixRemoteTask.cpp、
FIX/fixUDPServer.cpp 为准，命令行为以 FIX/fixOperationController.cpp
为准。

修改 UDP 端口、报文布局、编码、ACK、命令号、参数、响应或错误码时，必须在同一改动中更新本文档。320/321 或 400 的详细行为变化时，还应同步更新对应专题文档。

1. 传输约定

1.1 UDP 端口与地址

• FIX 监听地址： 127.0.0.1:6924
• Client 回包监听端口： 7000
• FIX 把普通响应发到请求来源 IP 的固定端口 7000，不会发回请求的源端口。
• 当前 FIX 只绑定本机回环地址，不接受其它计算机通过局域网直接访问。
• 普通请求响应会保留该请求的来源 IP；6000/5001 等历史异步通知使用最近一次请求的来源 IP，因此多 Client 并发时不应依赖异步通知的准确路由。

Client 应先绑定 7000 再发送请求，否则可能漏掉快速回包。

1.2 16 字节包头

所有整数均为当前 Windows x86/x64 实现的小端序。Parameter Length 是字节数，不是字符数；Payload 后不附加 \0。

历史 Client 常先向前 8 字节写入 FIXFIXFI，随后在 Offset 6 覆盖 ACK 高 16 位。因此线上实际内容不是固定的 8 字节 FIXFIXFI。当前 Server 只校验报文至少 16 字节、前三个字节为 FIX，并严格要求声明的 Payload 长度等于 UDP 报文剩余长度。

Payload 不是无限长。IPv4 UDP 数据报理论上最多 65,507 字节，本协议包头占 16 字节；实际集成应远低于该上限，避免 IP 分片。

1.3 ACK

• Client 应为请求分配 ACK，用它关联异步回包；推荐使用 1..65535 循环并跳过当前未完成的值。
• 协议预留了 ACK 高 16 位，但 FIX 仅在 Floatech 内部计算机模式下组合为 32 位 ACK。对外兼容 Client 必须把高 16 位设为 0，只使用低 16 位。
• 普通响应会回传请求 ACK。
• ACK 6000 用于历史点料计数异步通知，详见第 2.3 节。
• 5001 是异步事件的 Command，不是 ACK。

1.4 字符编码

• 命令 320、321、400 的请求和响应 Payload 明确使用 UTF-8 JSON。
• 其它请求 Payload 当前通过 Windows 本地 8-bit 编码解析；普通响应当前使用 Latin-1 写包。
• 为避免跨机器区域设置和中文文本回包问题，非 JSON 命令的路径、组名和教学文件名优先使用 ASCII；如必须使用非 ASCII，Client 与目标 FIX 必须做实际联调。

1.5 普通响应

普通响应沿用同一个 16 字节包头，但 Offset 10 不再是原请求命令号，而是 FIXUDP_RET 结果码。Client 必须以 ACK 关联请求，不能用响应 Offset 10 识别原命令。

部分旧命令默认不回包。在发送 1302、Payload=1 后，FIX 会强制所有命令回包；该设置会持久化。表格中的“无（默认）”表示 1302=0 时不回包。

2. 异步通知

2.1 通知包格式

异步通知同样发送到 Client 的 7000 端口。其 Offset 10 可能是事件 Command，而不是 FIXUDP_RET；Client 应先按 ACK/Command 识别下列保留事件，再把其它普通包按结果码处理。

2.2 教学文件保存通知：Command 5001

保存教学文件后，FIX 可主动发送：

开关的设计命令也是 5001，设计参数为 0（关闭）或 1（开启），设置键为 sd_ReturnUDPCMD5001AfterSaving。

即使开关已开启，当前实现也只在正在保存的图像最初由 UDP 加载时发送该通知。

当前实现限制： 当前源码中的 5001 开关命令误用了图像路径参数解析器，普通 0/1 Payload 无法通过该分支。因此目前不要依赖 UDP 命令 5001 来修改开关；注册表/QSettings 中已存在非零设置时，保存通知本身仍按上表发送。修复实现时必须同步删除本限制说明。

2.3 点料计数修改通知：ACK 6000

历史点料流程修改计数后可主动发送：

该通知只在当前图像由 UDP 加载时发送，属于 Counter 历史集成功能，不是 AXI 检测请求的普通响应。

3. 常用检测与教学命令

表格中的参数以分号 ; 分隔，除非另有说明。

3.1 命令 1100 参数

尾随空分号会被忽略。超过 4 段返回 RET_ParameterError。

4. 3D 通信命令

4.1 命令汇总

301/302/321 支持的 cvType 写法如下：

301/302 对未知字符串会兼容性回退为 16u；321 会严格拒绝未知类型。

4.2 命令 320：从投影创建教学文件

请求 Payload：

{
  "schemaVersion": 1,
  "teachingFile": "ProjectionTeaching",
  "group": "Default",
  "projectionDirectory": "D:/Data/Projection",
  "reconConfigPath": "D:/Data/Projection/ReconstructionConfig.json",
  "autoReconstruct": false,
  "overwrite": false
}

字段说明：

重建配置优先从根对象读取 width、height、depth、cvType；宽高可回退到 detector.sizeU/sizeV，张数可回退到 geometry.scanCount，类型可回退到 detector.dataType。RAW 数据需要有效宽高。加载后的投影堆栈必须匹配配置中声明的尺寸。

autoReconstruct=false 时不会启动重建；autoReconstruct=true 时，单队列调用本机重建，ExternalReconDualQueue 调用 ReconService。后者直到物理重建完成且教学文件保存成功后才回包；重建失败时不保存目标教学文件。

成功响应示例：

{"command":320,"status":"created","teachingFile":"ProjectionTeaching","group":"Default","sourceType":"projection","sourceDirectory":"D:/Data/Projection","autoReconstruct":true,"reconstructed":true,"overwrite":false,"reconConfigPath":"D:/Data/Projection/ReconstructionConfig.json","reconConfigSha256":"..."}

失败时 Offset 10 为相应结果码，Payload 示例：

{"command":320,"status":"error","message":"..."}

4.3 命令 321：从体数据创建教学文件

请求 Payload：

{
  "schemaVersion": 1,
  "teachingFile": "VolumeTeaching",
  "group": "Default",
  "dataDirectory": "D:/Data/Volume",
  "width": 2400,
  "height": 2400,
  "depth": 120,
  "cvType": "u16",
  "spacingX": 0.005,
  "spacingY": 0.005,
  "spacingZ": 0.005,
  "overwrite": false
}

• teachingFile、dataDirectory、cvType、width、height、depth 和三个 spacing 均必填。
• 三个尺寸必须为正整数；三个 spacing 必须为正的有限数，单位为 mm。
• group 默认 Default，overwrite 默认 false，schemaVersion 规则与 320 相同。
• 目录只能包含 RAW 或 TIFF/TIFF，不能混放；实际加载结果的尺寸和类型必须与请求完全一致。
• 321 不启动重建，也没有 autoReconstruct 选项。

成功响应结构与 320 相同，但 command=321、sourceType=volume、autoReconstruct=false、reconstructed=false，且没有重建配置路径和哈希。

更集中的 320/321 示例见 UDP_320_321_3D教学文件.md。

5. 图像效果命令

详细字段、Viewer 行为和错误说明见 UDP_400_效果JSON说明.md。

6. 窗口、面板和设置命令

1301～1303 和 2302～2304 的当前控制器函数没有完整的非法参数验证；其中部分函数也不主动清空此前的结果状态。Client 应只发送表中规定值，并只在查询模式下解释查询 Payload。

7. 错误码

结果码是位标志，部分检测流程会用按位或组合多个错误。0、1、2 也可作为完整检测状态使用。

例如 RET_NG | RET_ImageNotExists = 18。Client 解析组合结果时应逐位检查，不应只枚举表内单值。

8. 主窗口和参数面板集成

8.1 启动与嵌入流程

1. 启动控制软件。
2. 控制软件启动 FIX.exe --passive --hideall。
   • --passive：切换到用于外部嵌入的运行模式。
   • --hideall：启动后隐藏界面。
   • 当前源码没有 --build 后立即显示版本并退出的实现；请使用 UDP 2301 查询 Build 号。
3. Client 绑定 127.0.0.1:7000，启动接收线程。
4. 获取或准备控制软件内的父窗口句柄和显示区域。
5. 发送 1213 和 1214，把 FIX 主窗口和参数面板嵌入控制软件。
6. 按需使用 1200/1201 和 1204/1205 控制显示。

8.2 交互创建 2D 教学文件

1. 控制软件采图并保存到硬盘。
2. 发送 1002，在 FIX 中加载并显示图像。
3. 显示 FIX 主窗口和参数面板。
4. 用户在 FIX 中配置教学链并保存；或由 Client 发送 1100 自动保存当前状态。

8.3 直接创建 3D 教学文件

• 投影数据：发送 320。通过 autoReconstruct 选择是否先执行重建。
• 体数据：发送 321。该命令不重建。
• 两种命令都应等待匹配 ACK 的最终响应后再使用生成的教学文件；尤其 320 的 autoReconstruct=true 可能长时间无中间回包。

9. 文档范围和非公开命令

本文档描述 FIX AXI 对外集成所需的稳定命令。共享枚举中还包含 Counter 专用检测命令、内部测试命令和历史命令；它们不是本协议的 AXI 对外承诺，不应仅凭枚举值直接接入。其中：

• 1106 已废弃并保留编号，不得复用；调用会落入未知命令处理。
• 8000..8004 为内部命令；8003 当前只有枚举，没有执行分支。
• Counter 专用命令的行为应由单独的 Counter 集成文档维护。