# 焊缝视觉 TCP 协议

## 1. 概述

- 传输协议：TCP/IP
- 数据编码：UTF-8 文本
- 机械臂服务端端口：由机械臂侧确定并提供
- 视觉控制器服务端监听端口：`7800`
- 报文字段分隔符：`_`
- 报文结束符：`\r\n`
- 一条 TCP 连接同一时刻只处理一个请求

本协议包含两组独立的对接关系：

| 使用场景 | 客户端 | 服务端 | 服务端端口 | 用途 |
|---------|-------|-------|--------|---------|
| 手眼标定 | 标定软件</br>Windows | 机械臂 | 机械臂侧确定 | 标定软件主动连接机械臂读取机械臂当前坐标 |
| 正常工作 | 主控软件 | 视觉控制器 | `7800` | 主控软件主动连接视觉控制器计算，视觉控制器返回计算结果 |

服务端与客户端职责：

- 服务端绑定本机 IP 地址并监听约定端口，等待客户端连接。
- 客户端配置服务端 IP 地址和端口，主动发起 TCP 连接。
- 连接建立后，客户端发送请求，服务端返回应答或计算结果。
- 连接断开后，由客户端负责重新建立连接。

> 两组对接关系使用两条相互独立的 TCP 连接。机械臂服务端端口不受本协议限制，由机械臂侧确定；视觉控制器服务端固定监听端口 `7800`。
> **特别说明：视觉只负责检测，不负责运动控制，可获取运动部分的坐标信息。**

## 2. 通用报文约定

报文格式：

```text
命令_字段1_字段2_...\r\n
```

约定：

- 命令名称使用大写英文字母。
- 每条报文必须以 `\r\n` 结束。
- 字段之间使用半角下划线 `_` 分隔。
- 字段内容不得包含 `_`、回车或换行。
- 接收方应按结束符拆分报文，不能假定一次 TCP 接收操作恰好得到一条完整报文。
- 未识别命令、字段数量错误或字段格式错误时，接收方返回错误报文。

通用错误报文：

```text
ERROR_错误码\r\n
```

| 错误码 | 说明 |
|---|---|
| `UNKNOWN_COMMAND` | 命令无法识别 |
| `INVALID_FORMAT` | 报文格式或字段数量错误 |
| `INVALID_VALUE` | 字段值无法解析或超出允许范围 |
| `BUSY` | 接收方正在处理其他任务 |
| `NOT_READY` | 设备或算法尚未就绪 |
| `CALC_FAILED` | 视觉计算失败 |
| `INTERNAL_ERROR` | 接收方内部错误 |

## 3. 手眼标定协议

### 3.1 场景说明

- 标定工具运行在 Windows 标定软件中，并通过 TCP/IP 对接机械臂。
- 机械臂作为 TCP 服务端，监听端口由机械臂侧确定并提供。
- Windows 标定软件作为 TCP 客户端，按照机械臂侧提供的 IP 地址和端口主动连接机械臂。
- 标定物为多个圆柱。
- 相机一次性扫描全部圆柱；扫描完成后，机械臂依次移动到每个圆柱中心并逐点获取坐标，不对每个圆柱重复扫描。
- 机械臂由现场人员手动移动；视觉系统不发送机械臂运动指令，也不参与机械臂运动控制。
- 进行手眼标定前，必须先完成机械臂工具中心点（Tool Center Point，以下简称“工具 TCP”）标定。
- 标定软件只在采集标定点时读取当前工具 TCP 的机械臂坐标。

> 本节中的“工具 TCP”指机械臂工具中心点；第 1 节中的“TCP/IP”指网络传输协议，两者含义不同。

### 3.2 前置步骤：工具 TCP 标定

1. 在机械臂上安装手眼标定过程中实际使用的工具。
2. 按机械臂厂商提供的方法完成工具 TCP 标定。
3. 在机械臂控制器中保存并启用该工具 TCP。
4. 确认机械臂对外返回的 `X/Y/Z/RX/RY/RZ` 是已启用工具 TCP 的位姿，而不是机械臂法兰盘位姿。
5. 工具 TCP 确认无误后，方可开始相机扫描及手眼标定数据采集。

注意：

- 整个手眼标定过程中必须使用同一个工具和同一组工具 TCP 参数。
- 更换工具、重新安装工具或修改工具 TCP 参数后，之前采集的手眼标定数据全部失效，必须重新采集并重新计算手眼标定结果。

### 3.3 通信时序

```text
标定软件                              机械臂
   |                                    |
   |  相机一次性扫描全部圆柱              |
   |  扫描完成                           |
   |                                    |
   |  手动移动工具 TCP 到圆柱 1 中心      |
   |------------ GET_POSE ------------->|
   |<------ POSE_X_Y_Z_RX_RY_RZ --------|
   |  保存圆柱 1 对应坐标                |
   |                                    |
   |  手动移动工具 TCP 到圆柱 2 中心     |
   |------------ GET_POSE ------------->|
   |<------ POSE_X_Y_Z_RX_RY_RZ --------|
   |  保存圆柱 2 对应坐标                |
   |                                    |
   |      ...依次完成其余圆柱...         |
   |                                    |
```

### 3.4 手眼标定流程

1. 确认机械臂已经启用完成标定的工具 TCP。
2. 将相机移动到扫描起点。
3. 移动相机，通过编码器触发方式一次性扫描全部圆柱。
4. 完成本次扫描并保存所有圆柱的相机数据；后续逐点取坐标过程中不再移动相机或重复扫描。
5. 手动拖动机械臂，使工具 TCP 到达第 1 个圆柱的中心点。
6. 标定软件向机械臂请求当前工具 TCP 的坐标。
7. 机械臂返回当前工具 TCP 位姿，标定软件将该坐标与第 1 个圆柱的相机数据对应保存。
8. 手动拖动机械臂到下一个圆柱中心，再读取并保存一次工具 TCP 坐标。
9. 重复步骤 8，直至所有圆柱均完成坐标获取。

> 整个手眼标定过程只进行一次相机扫描；机械臂移动和 `GET_POSE` 坐标读取按圆柱数量重复执行。

### 3.5 读取机械臂坐标

标定软件请求：

```text
GET_POSE\r\n
```

机械臂返回：

```text
POSE_X_Y_Z_RX_RY_RZ\r\n
```

示例：

```text
GET_POSE\r\n
POSE_-500.920_1553.084_267.836_89.211_74.550_176.850\r\n
```

字段说明：

| 字段 | 说明 |
|---|---|
| `X` | 当前工具 TCP 的 X 坐标，单位 mm |
| `Y` | 当前工具 TCP 的 Y 坐标，单位 mm |
| `Z` | 当前工具 TCP 的 Z 坐标，单位 mm |
| `RX` | 当前工具 TCP 绕 X 轴的姿态角，单位 deg |
| `RY` | 当前工具 TCP 绕 Y 轴的姿态角，单位 deg |
| `RZ` | 当前工具 TCP 绕 Z 轴的姿态角，单位 deg |

说明：

- 位姿数值建议至少保留 3 位小数。
- 基坐标系、已启用的工具 TCP、欧拉角旋转顺序和角度正方向必须在联调前由机械臂方确认。
- 机械臂无法读取当前位姿时，返回对应的 `ERROR` 报文。

## 4. 视觉计算协议

### 4.1 场景说明

- 视觉控制器与主控软件通过 TCP/IP 对接。
- 视觉控制器作为 TCP 服务端，监听端口 `7800`。
- 主控软件作为 TCP 客户端，主动连接视觉控制器的 IP 地址和监听端口。
- 主控软件发送开始扫描命令，并在收到视觉控制器确认后控制相机从起点开始移动。
- 相机移动距离由现场确定；相机移动结束后，主控软件发送结束扫描命令。
- 视觉控制器收到结束扫描命令后自动进入计算，无需主控软件另行发送计算命令。
- 视觉控制器完成计算后，将由首点、中间修正点和末点组成的分段直线点集发送给主控软件。
- 主控软件负责现场运动控制，视觉控制器不通过本协议控制相机或机械臂运动。

### 4.2 通信时序

```text
主控软件                            视觉控制器
   |                                    |
   |  相机到达扫描起点                   |
   |------------ START_SCAN ----------->|
   |<------------ START_ACK ------------|
   |                                    |
   |  收到确认后开始移动相机              | 扫描采集
   |  相机移动结束并停止                  |
   |------------- STOP_SCAN ----------->|
   |<------------- STOP_ACK ------------|
   |                                    | 自动计算
   |<---- RESULT_OK_PointNum_点集 ------|
   |                                    |
```

### 4.3 工作流程

1. 相机到达扫描起点后，主控软件发送 `START_SCAN` 报文。
2. 视觉控制器进入扫描采集状态，并返回 `START_ACK` 报文。
3. 主控软件收到 `START_ACK` 后，方可控制相机从起点开始移动。
4. 相机移动指定距离并停止后，主控软件发送 `STOP_SCAN` 报文。
5. 视觉控制器结束扫描，返回 `STOP_ACK` 报文，并自动进入计算状态。
6. 视觉控制器计算完成后主动发送 `RESULT` 报文，结果包含首点、中间修正点和末点。
7. 扫描或计算失败时，视觉控制器发送 `ERROR` 报文。

### 4.4 开始扫描

主控软件请求：

```text
START_SCAN\r\n
```

视觉控制器应答：

```text
START_ACK\r\n
```

说明：

- `START_ACK` 表示视觉控制器已经进入扫描采集状态。
- 主控软件必须收到 `START_ACK` 后才能开始移动相机，不得在发送 `START_SCAN` 后立即移动。
- 视觉控制器尚未就绪时返回 `ERROR_NOT_READY\r\n`。
- 视觉控制器正在扫描或计算上一次任务时返回 `ERROR_BUSY\r\n`。

### 4.5 结束扫描并自动计算

相机移动结束并停止后，主控软件请求：

```text
STOP_SCAN\r\n
```

视觉控制器应答：

```text
STOP_ACK\r\n
```

说明：

- `STOP_ACK` 表示视觉控制器已结束扫描采集并开始计算，不表示计算已经完成。
- 主控软件不需要再发送计算命令。
- 未处于扫描状态时收到 `STOP_SCAN`，视觉控制器返回 `ERROR_NOT_READY\r\n`。

### 4.6 返回计算结果

视觉控制器计算完成后返回：

```text
RESULT_OK_PointNum_X1_Y1_Z1_X2_Y2_Z2_..._Xn_Yn_Zn\r\n
```

字段说明：

| 字段 | 说明 |
|---|---|
| `OK` | 计算成功 |
| `PointNum` | 返回的路径点总数，必须与后续坐标点数量一致 |
| `Xn/Yn/Zn` | 第 n 个路径点的坐标，单位 mm |

路径点按焊接行进方向依次排列：

```text
首点 -> 中间修正点1 -> 中间修正点2 -> ... -> 末点
```

每相邻两个路径点构成一段直线。分段间距由现场配置，例如分段间距为 1 m、焊缝总长为 10 m 时，共有 10 段直线，返回首尾在内的 11 个路径点：

```text
RESULT_OK_11_X1_Y1_Z1_X2_Y2_Z2_X3_Y3_Z3_..._X11_Y11_Z11\r\n
```

说明：

- 第 1 个点为焊缝首点，第 `PointNum` 个点为焊缝末点，其余点为中间修正点。
- 当焊缝长度不能被分段间距整除时，末点必须单独返回，最后一段长度可以小于配置的分段间距。
- 坐标值建议保留 3 位小数。
- 路径点所使用的坐标系需要在联调前确认。

未得到有效结果时返回：


```text
RESULT_NG\r\n
```

## 5. 超时与重连

- 建议建立 TCP 连接的超时时间为 5 s。
- `GET_POSE` 应答超时时间建议为 3 s。
- `START_SCAN` 和 `STOP_SCAN` 的应答超时时间建议为 3 s。
- 主控软件未收到 `START_ACK` 时不得移动相机，应检查连接及视觉控制器状态。
- 视觉计算耗时与现场数据量有关，计算结果超时时间由双方根据现场节拍配置。
- TCP 连接断开后，由 TCP 客户端重新建立连接；TCP 服务端继续监听并等待连接。
- 扫描过程中连接断开时，本次扫描数据无效。连接恢复后，相机应重新回到扫描起点，再开始新的扫描任务。
- 连接断开或结果超时后，不应自动重复发送运动相关指令；主控软件应先确认现场设备状态，再决定是否重新扫描。