FlyShotHost/docs/flyshot-system-guide.md

飞拍系统介绍说明与使用教程

1. 文档目的

本文档用于说明当前飞拍系统的整体组成、数据流、接口边界和现场使用步骤。文档原稿采用 Markdown 编写，适合后续导入或整理为飞书文档；流程图使用 Mermaid 源码保留，导入飞书时可按需要渲染为图片后插入。

系统当前分为三个主要单元：

单元	工程位置	主要职责
上位机单元	D:\Dev\Codes\MFD_Solution\FlyShot	控制相机、接收 PLC/MES 信息、发起飞拍任务、保存图片、调用 AI 检测、汇总结果并回传 MES/PLC
飞拍控制单元	D:\Dev\Codes\rvbust-code\FlyingShotPkg_3.15_VDA\flyshot-replacement	提供 HTTP 控制接口，负责机器人初始化、轨迹上传、ICSP/self-adapt-ICSP 规划、触发时序生成和 FANUC 运动执行
YOLO AI 识别模块	由上位机配置访问	接收图片检测请求，完成 AI 推理，返回图片级 OK/NG、原因、参数明细和结果图路径

2. 系统总览

flowchart LR
    PLC["PLC / OPC UA<br/>任务触发、状态反馈"]
    MES["MES<br/>换型下发、PartProcessed 上报"]
    PC["上位机单元 FlyShot<br/>WPF 主控程序"]
    Camera["工业相机<br/>采图与本地存图"]
    Control["飞拍控制单元<br/>ASP.NET Core HTTP API"]
    Robot["FANUC 机器人<br/>TCP 10010/10012 + UDP 60015"]
    AI["YOLO AI 识别模块<br/>HTTP + 文件传输目录"]
    Storage["本地/远端图片目录<br/>原图、结果图、任务 JSON"]
    Notify["飞书 / 审核平台 / ClickHouse<br/>异常通知与追溯"]

    PLC <--> PC
    MES <--> PC
    PC --> Camera
    Camera --> PC
    PC <--> Control
    Control <--> Robot
    PC <--> AI
    PC --> Storage
    AI --> Storage
    PC --> Notify

2.1 上位机单元

上位机是现场操作和生产流程的核心入口，当前是 WPF MVVM 程序。它负责：

• 初始化相机并注册图像回调。
• 读取 appConfig.json、Config\TypeData、Config\FlyTask 中的现场配置。
• 通过 MpcService 调用飞拍控制单元 HTTP 接口。
• 按飞拍任务配置设置相机曝光、增益和拍摄索引。
• 将图片保存到 CameraSavePath 下的任务目录。
• 通过 ImageProcessingService 上传图片到 AI 服务器目录并调用 AI 接口。
• 将 AI 结果合并回任务对象，保存任务 JSON。
• 根据结果回写 PLC、发送 MES PartProcessed、写入 ClickHouse、必要时发送飞书 NG 报警。

2.2 飞拍控制单元

飞拍控制单元是新的 replacement 服务端。它不恢复旧 50001/TCP+JSON 网关，而是提供 ASP.NET Core HTTP API。它负责：

• 机器人模型加载与初始化。
• 轨迹上传、查询、删除。
• 普通轨迹 ExecuteTrajectory。
• 飞拍轨迹 ExecuteFlyShotTraj。
• 通过 icsp 或 self-adapt-icsp 生成关节轨迹。
• 根据 shot_flags / offset_values / addrs 生成拍照触发时间轴。
• 将规划结果转换为 8ms 发送队列，通过 J519 通道控制机器人运动和 IO 脉冲。
• 提供 /status.html 状态页和 /debug.html 调试页。

2.3 YOLO AI 识别模块

YOLO AI 模块由上位机调用。上位机当前不是直接把所有图片以 multipart 方式传给 AI，而是：

1. 将图片上传到配置的 AI 输入目录。
2. 构造包含模型版本、配置版本、产品 ID 和图片明细的 JSON 请求。
3. 调用 Ai_Model.ApiUrl。
4. 根据 AI 响应中的 SubImgInfo 下载结果图。
5. 将图片级结果、原因、参数明细写回任务结果。
6. 清理远端上传图和结果图。

3. 生产主流程

sequenceDiagram
    participant PLC as PLC
    participant PC as 上位机 FlyShot
    participant CTRL as 飞拍控制单元
    participant ROBOT as FANUC 机器人
    participant CAM as 工业相机
    participant AI as YOLO AI
    participant MES as MES

    PLC->>PC: StartFlyShotTask 上升沿 + 产品/任务信息
    PC->>PC: 初始化 WorkStationTask / FlyShotTask
    PC->>CAM: 注册回调、设置曝光/增益
    PC->>CTRL: POST /execute_flyshot/
    CTRL->>ROBOT: move_to_start + J519 飞拍轨迹
    ROBOT-->>CAM: 轨迹 IO 脉冲触发拍照
    CAM-->>PC: 图像回调
    PC->>PC: 保存原图并加入待处理队列
    PC->>AI: 上传图片 + 发送 AI 请求
    AI-->>PC: 返回 OK/NG、原因、结果图路径
    PC->>PC: 下载结果图并汇总任务结果
    PC-->>PLC: TaskCompleted / TaskResult / WorkStationResult
    PC->>MES: PartProcessed 结果报文

4. 关键配置

4.1 上位机配置

上位机配置文件：

• 基础配置：D:\Dev\Codes\MFD_Solution\FlyShot\appConfig.json
• 调试覆盖：D:\Dev\Codes\MFD_Solution\FlyShot\appConfig.Debug.json

常用配置项：

配置路径	示例值	说明
MesConfig.EnableMes	true	是否启用 MES 通信
MesConfig.ServerIp / ServerPort	174.34.82.193 / 55065	MES 服务地址
MesConfig.LineNo / ProcessNo / StatNo	6958 / 993002 / 9930	MES 位置上下文
MesConfig.TelegramFolder	D:\MesTelegram	MES 报文保存目录
CameraIp / LocalIp	192.168.11.11 / 192.168.11.188	工业相机与本机网卡地址
CameraSavePath	D:\Images\flyShot	飞拍原图、结果图和任务 JSON 保存根目录
MPC.MpcInterfaceIp	192.168.11.12	飞拍控制单元 HTTP 地址
MPC.MpcInterfacePort	9001	上位机调用的飞拍控制单元端口
MPC.RobotName	LR_Mate_200iD_7L	机器人型号/名称
MPC.RobotIp	192.168.10.11	FANUC 控制柜 IP
Ai_Model.ApiUrl	http://127.0.0.1:8124/corebg	AI HTTP 接口地址
Ai_Model.AI_Model_Version	PEU	AI 模型版本
Ai_Model.AI_configVersion	peu_20241011	AI 配置版本
Ai_Model.ai_upload_path	/mnt/d/ai_images/ai-feed	AI 输入图片目录
Ai_Model.ai_result_path	/mnt/d/ai_images	AI 结果图片目录
FileTransfer.DefaultService	Primary	当前使用的文件传输服务
PLC.EnablePlc	true	是否启用 PLC 通信
PLC.OpcUaServer	opc.tcp://174.34.178.68:4840	OPC UA 服务地址

注意：如果飞拍控制单元实际监听端口是 5000，上位机的 MPC.MpcInterfacePort 需要同步改为 5000，或通过反向代理/部署配置把控制单元暴露为 9001。

4.2 飞拍控制单元配置

飞拍控制单元配置文件：

• D:\Dev\Codes\rvbust-code\FlyingShotPkg_3.15_VDA\flyshot-replacement\src\Flyshot.Server.Host\appsettings.json

常用配置项：

配置路径	示例值	说明
ControllerClientCompat.AutoInit.RobotName	FANUC_LR_Mate_200iD_7L	服务启动自动初始化的机器人名称
ControllerClientCompat.AutoInit.RobotIp	192.168.10.11	服务启动自动连接的机器人 IP
Kestrel.Endpoints.Http.Url	http://0.0.0.0:5000	HTTP 服务监听地址
Swagger.Enabled	true	是否启用 Swagger 和调试接口
Cors.AllowedOrigins	*	允许跨域调用的来源

5. 飞拍控制单元 HTTP 接口

5.1 初始化机器人

推荐使用聚合初始化接口：

POST /init_mpc_robot
Content-Type: application/json

{
  "robot_name": "FANUC_LR_Mate_200iD_7L",
  "robot_ip": "192.168.10.11"
}

内部执行顺序：

1. SetUpRobot：加载机器人模型和关节限制。
2. Connect：建立 FANUC 状态、命令、J519 三条通道。
3. EnableRobot(8)：启动机器人程序和运动循环。

也可以拆分调用：

POST /setup_robot/?robot_name=FANUC_LR_Mate_200iD_7L
POST /connect_robot/?ip=192.168.10.11
GET  /enable_robot/?buffer_size=8

5.2 上传飞拍轨迹

POST /upload_flyshot/
Content-Type: application/json

{
  "name": "UTTC_MS11",
  "waypoints": [[0, 0, 0, 0, 0, 0]],
  "shot_flags": [true],
  "offset_values": [0],
  "addrs": [[1, 3]]
}

字段说明：

字段	类型	说明
name	string	飞拍轨迹名称，上位机执行时使用
waypoints	number[][]	机器人关节路径点
shot_flags	bool[]	每个路径点是否拍照
offset_values	number[]	拍照触发偏移周期
addrs	number[][]	拍照触发 IO 地址组

5.3 执行飞拍轨迹

上位机 MpcService.ExecuteFlyShot 当前默认发送：

POST /execute_flyshot/
Content-Type: application/json

{
  "name": "UTTC_MS11",
  "move_to_start": true,
  "method": "icsp",
  "save_traj": false,
  "use_cache": false,
  "wait": false
}

字段说明：

字段	推荐值	说明
name	轨迹名称	必须已上传或存在于控制单元缓存
move_to_start	true	执行前先移动到规划起点，避免第一帧目标突变
method	icsp 或 self-adapt-icsp	轨迹规划方法
save_traj	false	是否保存本次规划轨迹
use_cache	false 或 true	是否复用缓存轨迹
wait	false 或 true	是否等待整条轨迹完成后再返回

5.4 常用调试接口

接口	方法	用途
/healthz	GET	服务健康检查
/status.html	GET	浏览器状态页
/debug.html	GET	浏览器接口调试页
/api/status/snapshot	GET	当前兼容层和运行时状态快照
/robot_info/	GET	查询机器人信息
/set_speedRatio/	POST	设置速度倍率
/list_flyShotTraj/	GET	查询可执行飞拍轨迹名称
/delete_flyshot/	POST	删除飞拍轨迹
/stop_move/	GET	停止当前运动
/disable_robot/	GET	禁用机器人
/disconnect_robot/	POST	断开机器人连接

6. 上位机使用教程

6.1 启动前检查

1. 确认工业相机、机器人控制柜、AI 服务、PLC、MES 网络可达。
2. 检查上位机 appConfig.json：
   • CameraIp 和 LocalIp 是否匹配现场网段。
   • CameraSavePath 是否存在或可创建。
   • MPC.MpcInterfaceIp / MpcInterfacePort 是否指向飞拍控制单元。
   • Ai_Model.ApiUrl 是否指向 YOLO AI 接口。
   • FileTransfer 是否能访问 AI 上传和结果目录。
3. 检查飞拍控制单元是否启动：
   • 浏览器访问 http://<控制单元IP>:<端口>/healthz。
   • 浏览器访问 http://<控制单元IP>:<端口>/status.html。
4. 检查机器人程序、控制柜状态和安全围栏。

6.2 上位机启动流程

flowchart TD
    A["启动 FlyShot 上位机"] --> B["读取 appConfig.json"]
    B --> C["初始化 MES<br/>可按 EnableMes 关闭"]
    B --> D["初始化相机"]
    B --> E["查询飞拍控制单元轨迹列表"]
    E --> F["设置机器人速度倍率<br/>默认 0.5"]
    D --> G["确认系统状态栏无关键 NG"]
    F --> G
    G --> H["等待手动或 PLC 触发任务"]

启动后，上位机会执行：

• 初始化 MES 连接。
• 初始化相机。
• 查询飞拍控制单元中的飞拍任务列表。
• 设置机器人速度倍率。
• 创建或检查图片保存目录。

6.3 手动执行飞拍任务

适用于调试、首件验证和现场排查。

1. 打开上位机。
2. 确认相机初始化成功。
3. 确认飞拍任务列表已加载。
4. 输入或扫码产品标识。
5. 选择飞拍任务名称。
6. 点击手动开始。
7. 上位机执行：
   • 初始化工位任务。
   • 注册相机回调。
   • 调用飞拍控制单元 /execute_flyshot/。
   • 接收相机回调并保存图片。
   • 批量调用 AI 检测。
   • 汇总 OK/NG。
   • 保存任务 JSON。
   • 如有 NG，打开人工复判界面并发送通知。

6.4 PLC 自动执行飞拍任务

适用于正式生产。

PLC 通过 OPC UA 写入任务触发信号，上位机收到 StartFlyShotTask 上升沿后执行任务。

PLC 输入给 PC 的核心信号：

信号	说明
StartFlyShotTask	飞拍任务启动，上升沿触发
WorkStationId	工位号
FlyShotTaskName	飞拍任务名称
CurrentTaskIndex	当前任务序号
TotalTaskCount	当前工位任务总数
ProductTypeNo	产品型号
ProductIdentifier	产品唯一标识
ProductBatch	产品批次
ResetSystem	系统重置信号

PC 回写给 PLC 的核心信号：

信号	说明
TaskCompleted	当前任务完成
TaskResult	当前任务结果，true=OK，false=NG
CompletedTaskIndex	已完成任务序号
TaskProcessingTime	当前任务耗时
WorkStationCompleted	工位所有任务是否完成
WorkStationResult	工位总结果
SystemReady	系统是否就绪
SystemBusy	系统是否忙碌
ErrorCode	错误码
ErrorMessage	错误信息
PcHeartbeat	PC 心跳

6.5 图片和结果保存规则

上位机会基于 CameraSavePath 生成任务目录：

{CameraSavePath}\{yyyyMMdd}\{TypeNo-TypeVar}\{ProductIdentifier}\{FlyShotName}\

任务目录内通常包含：

内容	说明
原始图片	相机回调保存的图片
result 子目录	AI 下载后的结果图
flyShotTask@...json	单个飞拍任务详情
WorkStationTask@...json	工位任务汇总

AI 结果图命名会带上检测结果，例如：

原图名@OK.jpeg
原图名@NG.jpeg

7. YOLO AI 识别流程

flowchart TD
    A["相机回调保存原图"] --> B["上位机收集待处理图片"]
    B --> C["达到 BatchSize 或采集结束"]
    C --> D["上传原图到 Ai_Model.ai_upload_path"]
    D --> E["构造 AiProcessRequestModel"]
    E --> F["POST Ai_Model.ApiUrl"]
    F --> G["解析 ProductResult / SubImgInfo / FailureModes"]
    G --> H["从 Ai_Model.ai_result_path 下载结果图"]
    H --> I["写回 ImageProcessOutcome"]
    I --> J["更新 UI 与任务结果"]
    J --> K["清理 AI 远端临时文件"]

7.1 AI 请求结构

AI 请求的典型结构：

{
  "ai_modelVersion": "PEU",
  "ai_configVersion": "peu_20241011",
  "key": "empty",
  "product_id": "20250228121929",
  "sub_img_info": [
    {
      "index": 1,
      "view": "pipe",
      "object": "spring",
      "image_path": "000001_161008_1.jpeg",
      "ai_image_path": null,
      "ai_result": null,
      "ai_reason": null,
      "ai_param_list:": {}
    }
  ]
}

字段说明：

字段	说明
ai_modelVersion	AI 模型版本，对应上位机 Ai_Model.AI_Model_Version
ai_configVersion	AI 配置版本，对应上位机 Ai_Model.AI_configVersion
product_id	本次 AI 任务 ID，通常由时间戳生成
sub_img_info[].index	图片序号
sub_img_info[].view	视角，例如 pipe、surface、connector
sub_img_info[].object	检测对象，例如 spring、top、side
sub_img_info[].image_path	上传到 AI 输入目录后的图片文件名

7.2 AI 响应处理

上位机按 index 将 AI 响应和原图对应起来，主要读取：

字段	说明
ProductResult	产品级检测结果
ErrorInfo	AI 处理错误信息
AiFailureModel	AI 不良模式集合
SubImgInfo[].AiResult	单张图片结果，OK 视为 OK，其他非空值视为 NG
SubImgInfo[].AiReason	单张图片 NG 原因
SubImgInfo[].AiParamList	AI 参数明细
SubImgInfo[].AiImagePath	AI 结果图远端路径

8. MES 交互说明

8.1 换型下发

上位机启动或手动换型时，会根据 MesConfig.TypeNo 和 MesConfig.TypeVar 发送 DataDownloadRequired。

主要用途：

• 获取或刷新当前型号配置。
• 更新本地 TypeNo / TypeVar。
• 加载对应 Config\TypeData 文件。

8.2 结果上报

飞拍任务完成后，上位机会发送 PartProcessed。

上报内容包括：

• 产品唯一标识。
• 产品型号和变体。
• 工位结果，1=OK，2=NG。
• 图片相对路径。
• 每张图片的 AI 结果和人工复判结果。
• 汇总后的 NIO bits。

9. 常见使用场景

9.1 首次联调

1. 启动飞拍控制单元。
2. 访问 /healthz 确认服务正常。
3. 访问 /status.html 查看模型和机器人状态。
4. 调用 /init_mpc_robot 初始化机器人。
5. 调用 /list_flyShotTraj/ 确认可用轨迹。
6. 启动上位机。
7. 检查上位机日志中相机、MPC、MES、PLC 状态。
8. 使用手动模式执行一次飞拍任务。
9. 检查图片目录、AI 结果图、任务 JSON 和 MES/PLC 反馈。

9.2 正式生产

1. 启动飞拍控制单元并确认状态正常。
2. 启动上位机并确认系统就绪。
3. PLC 写入产品和任务信息。
4. PLC 触发 StartFlyShotTask 上升沿。
5. 上位机执行飞拍、AI 检测和结果汇总。
6. 上位机回写 PLC 当前任务和工位结果。
7. 上位机发送 MES PartProcessed。
8. PLC 根据 WorkStationCompleted 和 WorkStationResult 决定后续流程。

9.3 离线排查 AI

1. 准备一组本地图片。
2. 在上位机调试页面或相关调试入口选择图片。
3. 确认 Ai_Model.ApiUrl、ai_upload_path、ai_result_path 正确。
4. 执行 AI 请求。
5. 检查 AI 响应、结果图下载、上位机日志和远端文件清理情况。

10. 故障排查

flowchart TD
    A["发现任务失败或结果异常"] --> B{"失败阶段"}
    B -->|相机无图| C["检查 CameraIp / LocalIp / 相机连接 / 触发源 / 曝光增益"]
    B -->|控制单元失败| D["检查 /healthz /status.html / MpcInterfaceIp / 端口 / 机器人状态"]
    B -->|机器人报警| E["检查 FANUC 控制柜 / RVBUSTSM / J519 通道 / 安全状态"]
    B -->|AI 无结果| F["检查 Ai_Model.ApiUrl / 文件传输目录 / AI 服务日志 / 结果图路径"]
    B -->|PLC 不触发| G["检查 OPC UA 地址 / ActiveProfile / StartFlyShotTask 上升沿 / SystemReady"]
    B -->|MES 失败| H["检查 EnableMes / ServerIp / ServerPort / TelegramFolder / 报文响应"]
    C --> I["查看上位机日志和图片目录"]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I

10.1 相机问题

现象	排查点
无图像回调	相机 IP、本机网卡、相机初始化、回调注册
图片曝光异常	飞拍点位配置中的曝光和增益
图片保存失败	CameraSavePath 权限、磁盘空间、路径是否存在

10.2 飞拍控制单元问题

现象	排查点
上位机无法连接 MPC	MPC.MpcInterfaceIp / MpcInterfacePort 是否指向控制单元
/execute_flyshot/ 失败	轨迹是否已上传、机器人是否初始化、method 是否支持
机器人不运动	/status.html 状态、FANUC 通道、使能状态、控制柜报警
轨迹执行后无拍照	shot_flags、offset_values、addrs、J519 IO 脉冲

10.3 AI 问题

现象	排查点
AI 请求失败	Ai_Model.ApiUrl、AI 服务是否启动、HTTP 是否可达
AI 找不到图片	ai_upload_path、文件传输服务、远端目录权限
结果图下载失败	ai_result_path、AiImagePath、SFTP/SMB/LOCAL 配置
结果和图片错位	检查 AI 响应中的 index 是否和请求一致

10.4 PLC/MES 问题

现象	排查点
PLC 不触发任务	PLC.EnablePlc、OPC UA 地址、变量映射、上升沿保持时间
PLC 反馈不更新	输出变量是否可写、SystemBusy/SystemReady 状态
MES 连接失败	MesConfig.EnableMes、IP、端口、防火墙
MES 报文异常	TelegramFolder 下保存的 XML 报文和响应

11. 交付与飞书整理建议

建议后续整理为飞书文档时采用以下方式：

1. 以本文档 Markdown 作为源稿。
2. 将 Mermaid 流程图渲染为 PNG 或 SVG 图片后插入飞书。
3. 保留接口表、配置表和操作步骤，适合现场培训。
4. 如果需要正式发布版本，可再从 Markdown 生成 Word，再导入飞书云文档。
5. 每次接口、配置或流程变更后，优先更新 Markdown 源稿，再同步飞书版本。

建议拆分飞书目录：

飞拍系统说明
├─ 1. 系统总览
├─ 2. 生产主流程
├─ 3. 上位机使用教程
├─ 4. 飞拍控制单元使用教程
├─ 5. YOLO AI 接口说明
├─ 6. PLC 与 MES 交互
└─ 7. 常见问题排查