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

6.2 KiB
Raw Permalink Blame History

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 请求

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