Files
ssp/docs/visionguide-ipc-protocol.md

71 lines
6.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ssp / VisionGuide 本机通信协议 v1
两端使用 Qt 5.14 的 QLocalSocket / QLocalServer。每帧为 4 字节无符号大端长度,随后为 UTF-8 JSON object;长度必须为 1..1048576。支持分包和连续多帧,非法帧断开。一次只允许一个控制客户端、一个测量。消息不含图像。
VisionGuide 默认监听 `ssp_visionguide_v1`,可用 `--ipc-name` 覆盖。启动时在 SDK 初始化和主窗口创建前,使用用户数据目录下的固定 QLockFile 保证同用户单实例;不同 IPC 名及程序副本也不能同时初始化相机。重复实例正常退出。ssp“启动”先尝试连接,只有端点不存在或拒绝连接才启动一次程序;握手失败不再启动进程。“连接”仅连接已有程序。复用外部实例时不发送 shutdown;仅自身启动且 PID 匹配的子进程可由 ssp 关闭。
## 公共字段
所有请求/响应含 `protocol_version:1`、字符串 `type`、字符串 `request_id`、字符串 `server_session_id`。服务进程每次启动产生新 session。`hello` 请求的 session 为空;响应提供本进程 session。后续请求必须使用该 session。所有 request_id 不重复使用;断线不自动重发,旧 session / 已终止请求的结果不可使用。
响应 `status` 为 `ok`、`accepted`、`error`、`cancelled` 或 `timeout`,包含 `ready` 和 `resource_busy` 两个独立 bool。失败含字符串 `error_code`、`message`。`accepted` 不是终态;每个测量最多一个终态。终态取消不代表底层已退出,资源未释放时 `resource_busy` 仍为 true。
## 命令
| type | 含义 |
| --- | --- |
| hello | 协议握手及进程 session;不初始化设备 |
| get_status | 返回 ready/resource_busy 以及可选 initialization 对象 |
| initialize | 显式初始化/维护入口;accepted 后返回 ok/error;VisionGuide 启动也自动执行相机初始化 |
| measure | 本次拍照、识别、抓取计算;相机未初始化成功时先重试一次初始化,成功继续同一请求,失败返回 error/INITIALIZATION;accepted 后返回终态 |
| cancel | 带 target_request_id,取消该测量;cancel 本身独立应答,测量返回 cancelled |
| show_window | 显示原视觉调试窗口 |
| shutdown | 正常关闭(ssp 只对自己启动的进程发送) |
服务端主动状态消息使用 `type:"status"`、`request_id:""`、当前 session。业务失败不丢失关联上下文。相同测量编号不得重新采图。
状态增加 `initialization_in_progress` bool。启动初始化时 `resource_busy:true`,允许接收一个测量请求等待初始化结束,其他测量仍返回 BUSY。ssp 不以 ready=false 直接拒绝测量;测量请求可触发一次初始化重试。客户端总等待预算为 `requestTimeoutMs + 2 * initializeTimeoutMs`,不改变采图/识别的 5 秒截止。初始化失败返回结构化 `status:"error"`、`error_code:"INITIALIZATION"`、`robot_valid:false`,保留 request_id/context。ssp 将视觉失败转换为 M852=0 的普通取料路径,不写 R60。
状态响应还提供字符串 `server_process_id`。ssp 只有在该值与自身 QProcess 启动的子进程 PID 一致时才发送 shutdown;连接外部实例时退出仅断开。
向自身实例发送 shutdown 后保持管道,直到子进程退出;保留原有 3 秒强杀兜底,回调仅针对该启动代次。关闭期间不再处理业务应答,避免清空会话后误把退出应答当作会话错误而提前断管道。
## measure 请求
```json
{
"protocol_version":1,"type":"measure","request_id":"unique-id","server_session_id":"session",
"context":{"workpiece_id":"42","task_id":"run/action","tray_no":1,"generation":"1"},
"robot_pose":[1.0,2.0,3.0,4.0,5.0,6.0],
"pose_source":"plc_r40","pose_read_at":"2026-10-27T10:00:00.000Z",
"convention":{"frame":"world","tool":"TOOL1","rotation":"Rz(A)Ry(B)Rx(C)","linear_unit":"mm","angular_unit":"deg"},
"parameters":{"camera_mode":"left_only","refinement":"least_squares_high","deadline_ms":5000,"min_score":0.70,"greediness":0.80,"yolo_selection":"center","pose_display":"model_origin","grasp_offset_mm":4.40},
"require_robot_pose":true
}
```
`robot_pose` 是恰好 6 个有限数,顺序 XYZABC。`pose_source` 自动生产为 `plc_r40`,手动只读诊断为 `diagnostic`。context 的 id 为非空字符串,tray_no 为 1..99 整数。context 整体须原样返回。服务端检查固定 parameters 和 convention 后使用冻结快照,不以 UI 后来改动覆盖快照。5 秒仅为采图/识别截止;客户端整次请求另设超时。
## measure 成功响应
公共字段中 `type:"measure"`、`status:"ok"`;再含以下字段:
| 字段 | 内容 |
| --- | --- |
| context | 请求 context 原样返回 |
| camera_pose / robot_pose | 各 6 个有限 double;相机原点位姿 / 机器人抓取 XYZABC |
| camera_valid / robot_valid | 独立 bool,成功自动提交必须两者 true |
| source / pose_type | `LEFT` / `model_origin` |
| score | 有限数且不低于请求 min_score |
| parameters / convention | 本次实际使用值,必须与请求匹配 |
| calibration_fingerprint | 非空标定/料盘配置指纹 |
| run_id | 非空视觉运行标识 |
| capture_begin / capture_end | UTC ISO 时间字符串 |
| measure_elapsed_ms / grasp_elapsed_ms | 非负整数 |
只得到 camera_pose 时返回 error/partial 类错误,`robot_valid:false`,绝不复制相机坐标冒充机器人坐标。客户端只发布经过校验的结构化结果;R60 写入由生产流程决定。
## ssp 线程接口
VisionService 及其 QLocalSocket/QProcess 在 GUI 线程中创建使用。生产线程通过 queued connection 传 `QJsonObject` 值快照:`measure(request)`、`cancel(requestId)`,接收 `measurementFinished(result)`、`availabilityChanged(ready,busy,session)`。无阻塞等待,退出不依赖生产线程等 GUI 回答。`setProductionActive(active, maintenanceAllowed)` 使诊断入口与生产互斥;待人工核对时保持 active,只有 PLC 暂停已确认或任务已终止到 Idle 才允许维护连接和初始化,仍禁止测量。自动请求使用 `measure`,页面使用 `diagnose`。此变更仅为 ssp 内部线程接口,线上的 IPC 协议版本仍为 1。