65 lines
4.4 KiB
Markdown
65 lines
4.4 KiB
Markdown
# ssp / VisionGuide 本机通信协议 v1
|
|||
|
|
|
||
|
|
两端使用 Qt 5.14 的 QLocalSocket / QLocalServer。每帧为 4 字节无符号大端长度,随后为 UTF-8 JSON object;长度必须为 1..1048576。支持分包和连续多帧,非法帧断开。一次只允许一个控制客户端、一个测量。消息不含图像。
|
||
|
|
|
||
|
|
## 公共字段
|
||
|
|
|
||
|
|
所有请求/响应含 `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 |
|
||
|
|
| measure | 本次拍照、识别、抓取计算;accepted 后返回终态 |
|
||
|
|
| cancel | 带 target_request_id,取消该测量;cancel 本身独立应答,测量返回 cancelled |
|
||
|
|
| show_window | 显示原视觉调试窗口 |
|
||
|
|
| shutdown | 正常关闭(ssp 只对自己启动的进程发送) |
|
||
|
|
|
||
|
|
服务端主动状态消息使用 `type:"status"`、`request_id:""`、当前 session。业务失败不丢失关联上下文。相同测量编号不得重新采图。
|
||
|
|
|
||
|
|
状态响应还提供字符串 `server_process_id`。ssp 只有在该值与自身 QProcess 启动的子进程 PID 一致时才发送 shutdown;连接外部实例时退出仅断开。
|
||
|
|
|
||
|
|
## 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(bool)` 使诊断入口与生产互斥;自动请求使用 `measure`,页面使用 `diagnose`。
|