# HoleDetection 孔洞检测系统 - TCP通信协议


## 版本历史

| 版本 | 日期 | 修改内容 |
|------|------|----------|
| 1.0 | 2026-03-10 | 改为文本格式协议，增加机器人位姿（眼在手上） |

---

## 1. 协议概述

本文档定义了上位机与HoleDetection孔洞检测系统之间的TCP/IP通信协议。协议采用纯文本格式进行数据交换，支持眼在手上（Eye-in-Hand）坐标变换。

### 1.1 通信方式
- **传输协议**: TCP/IP
- **数据格式**: 纯文本
- **端口**: 7800（默认，可通过配置文件修改）
- **行分隔符**: `\n`（换行符）

### 1.2 通信模式
- 服务端：HoleDetection孔洞检测系统
- 客户端：上位机控制系统（机器人控制器/PLC）

### 1.3 坐标变换方式
采用 **眼在手上(Eye-in-Hand)** 方式：
```
P_base = T_base_to_end × T_end_to_cam × P_cam
```
- `T_base_to_end` = 机器人位姿（触发信号中的 RbtX/Y/Z/Roll/Pitch/Yaw）
- `T_end_to_cam` = 手眼标定矩阵（配置文件中的 4×4 矩阵）
- `P_cam` = 相机坐标系下的检测结果

## 2. 触发信号（客户端 → 服务端）

上位机发送触发信号，携带相机索引和当前机器人法兰位姿。

### 2.1 格式

```
X<相机索引> RbtX<值> RbtY<值> RbtZ<值> RbtRoll<值> RbtPitch<值> RbtYaw<值>\n
```

### 2.2 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| X | Integer | 相机索引。`1` = 相机1，`2` = 相机2 |
| RbtX | Float | 机器人法兰 X 坐标（mm） |
| RbtY | Float | 机器人法兰 Y 坐标（mm） |
| RbtZ | Float | 机器人法兰 Z 坐标（mm） |
| RbtRoll | Float | 机器人法兰 Roll 角度（°） |
| RbtPitch | Float | 机器人法兰 Pitch 角度（°） |
| RbtYaw | Float | 机器人法兰 Yaw 角度（°） |

> **注意**：
> - 各字段之间用**空格**分隔
> - 数值可以为负数，负号是值的一部分（如 `RbtX-23.45`）
> - 数值与前缀之间**无空格**（如 `RbtX100.0`，不是 `RbtX 100.0`）
> - 每条消息以 `\n` 结尾

### 2.3 示例

```
X1 RbtX100.0 RbtY200.0 RbtZ300.0 RbtRoll0.0 RbtPitch0.0 RbtYaw0.0
```

```
X2 RbtX-23.45 RbtY150.30 RbtZ-80.00 RbtRoll-12.50 RbtPitch45.00 RbtYaw-90.00
```

## 3. 返回信号（服务端 → 客户端）

检测完成后，服务端返回检测到的孔洞数量和各孔洞在机器人基坐标系下的位姿。

### 3.1 格式

```
<孔洞数量>_<X1>_<Y1>_<Z1>_<Roll1>_<Pitch1>_<Yaw1>/<X2>_<Y2>_<Z2>_<Roll2>_<Pitch2>_<Yaw2>/...\n
```

### 3.2 格式规则

| 符号 | 说明 |
|------|------|
| 第一个数值 | 检测到的孔洞数量 |
| `_` | 同一孔洞各分量之间的分隔符 |
| `/` | 不同孔洞之间的分隔符 |
| `\n` | 消息结尾 |

### 3.3 单个孔洞位姿字段

| 顺序 | 类型 | 说明 |
|------|------|------|
| 1 | Float | 机器人基坐标系下 X 坐标（mm） |
| 2 | Float | 机器人基坐标系下 Y 坐标（mm） |
| 3 | Float | 机器人基坐标系下 Z 坐标（mm） |
| 4 | Float | Roll 角度（°） |
| 5 | Float | Pitch 角度（°） |
| 6 | Float | Yaw 角度（°） |

> **注意**：姿态角（Roll/Pitch/Yaw）的输出顺序可通过配置文件中的 `poseOutputOrder` 参数调整。

### 3.4 示例

**检测到 2 个孔洞：**
```
2_100.50_200.30_50.20_1.23_4.56_7.89/110.00_210.00_60.00_1.00_5.00_8.00/
```

**检测到 0 个孔洞：**
```
0
```

**检测到 1 个孔洞：**
```
1_120.50_180.30_45.20_0.00_0.00_0.00/
```

## 4. 通信流程

### 4.1 正常检测流程

```
上位机(机器人控制器)               孔洞检测系统
  |                                     |
  |  X1 RbtX... RbtYaw...               |
  |------------------------------------>|
  |                                     |
  |                                     | (拍照+检测+坐标变换)
  |                                     |
  |  2_X1_Y1_Z1_R1_P1_Y1/X2_...         |
  |<------------------------------------|
  |                                     |
```

### 4.2 无检测结果

```
上位机(机器人控制器)               孔洞检测系统
  |                                     |
  |  X1 RbtX... RbtYaw...               |
  |------------------------------------>|
  |                                     |
  |                                     | (拍照+检测，未找到孔洞)
  |                                     |
  |  0                                  |
  |<------------------------------------|
  |                                     |
```


## 5. 注意事项

1. **连接管理**
   - 客户端应实现断线重连机制
   - 服务端支持多客户端连接，结果广播给所有已连接客户端

2. **粘包处理**
   - 协议以 `\n` 作为消息分隔符
   - 接收方应按 `\n` 分割完整行后再解析

3. **数据精度**
   - 坐标精度：小数点后2位（毫米）
   - 角度精度：小数点后2位（度）

4. **性能考虑**
   - 单次检测时间约 500ms - 2s
   - 建议客户端设置合理的超时时间（建议10秒）

5. **手眼标定**
   - 使用前需完成手眼标定，标定矩阵存储在 config.xml 的 `<HandEyeCalibMatrixList>` 中
   - 支持多相机独立标定