GrabBag/App/StatorWorkpiecePosition/Doc/工件定位TCP通信协议.md

# 锥形工件定位 / 转子钢芯定位 TCP 协议

## 1. 概述

- 传输协议：TCP/IP
- 数据编码：UTF-8 文本
- 服务模式：视觉侧作为 TCP 服务端
- 默认端口：`7800`
- 报文结束符：`\r\n`
- 字段分隔符：`_`
- 当前模式：眼在手外
- 请求和响应均不使用 JSON

## 2. 请求报文

以下尺寸序号扩展仅适用于 `WorkpieceRotorApp`，`WorkpieceTaperedApp` 请求格式不变。

转子工件检测格式：

```text
S相机索引_工件序号\r\n
```

示例：

```text
S1_2\r\n
```

字段说明：

| 字段 | 说明 |
|---|---|
| `S1` | `S`=工件检测，`1` 为相机索引，从 1 开始 |
| `2` | 工件尺寸序号，对应“工件尺寸”Tab 中的序号，范围 `1–65535` |

`S1_2` 表示使用相机 1，按列表中 2 号工件的标称半径和高度检测。
序号按“工件尺寸”Tab 的行顺序从 1 连续编号；上下移动或删除后会重新编号，默认工件跟随尺寸项移动，删除默认项后改为第一项。保存后请同步调整 PLC 中引用的工件序号。尺寸序号不是结果中的 `Type` 或算法目标编号。
未配置的序号、无效尺寸列表会拒绝启动；格式错误返回 `Error_-3_...`，启动失败返回 `Error_-5_...`。
例如 `S1_0`、`S1_`、`S1__2` 均为非法请求。

兼容旧请求 `S1\r\n`，省略工件序号时使用配置的默认工件；界面“开始”和离线复检也使用默认工件。
本轮启动后固定半径、高度，期间修改列表或收到重复请求不会改变正在执行的检测。
结果报文格式保持不变，不额外插入尺寸序号字段。

本项目为眼在手外，检测请求不需要传入机械臂当前 `X/Y/Z/A/B/C`。
工件检测算法会在定位过程中同步计算所需的料框信息，不需要发送单独的料框检测请求，
也不通过 TCP/IP 返回料框几何数据。

## 3. 工件检测返回报文

格式（每次检测最多返回当前抓取目标 1 个工件）：

```text
PointNum_Type_X_Y_Z_A_B_C\r\n
```

在 `WorkpieceRotorApp` 中，算法结果可能包含多个候选/上层工件，但 TCP 每次只返回本次抓取目标（算法结果中的第一个工件），不会把全部候选结果拼接到同一帧。协议字段布局不变，因此有目标时 `PointNum` 固定为 `1`；`PointNum=0` 时表示未检测到有效抓取目标，报文只有一个字段：

```text
0\r\n
```

示例：

```text
1_2_100.500_200.300_50.100_15.500_-2.300_45.000\r\n
0\r\n
```

字段说明：

| 字段 | 说明 |
|---|---|
| `PointNum` | 本次返回的抓取工件数量；有有效抓取目标时固定为 `1`，无目标时为 `0` |
| `Type` | 工件类型 `workpieceType` |
| `X/Y/Z` | 工件位置，单位 mm，保留 3 位小数 |
| `A/B/C` | 工件姿态，单位 deg，保留 3 位小数 |

`Type`（`workpieceType`）取值含义如下：

| `workpieceType` | 含义 |
|---:|---|
| `0` | 中央 |
| `1` | 上边 |
| `2` | 下边 |
| `3` | 左边 |
| `4` | 右边 |
| `5` | 左上角 |
| `6` | 右上角 |
| `7` | 左下角 |
| `8` | 右下角 |
| `9` | 隔板 |

本项目不输出接近点坐标，只输出工件定位结果。

## 4. 错误响应

格式：

```text
Error_code_message\r\n
```

示例：

```text
Error_-5_工件检测启动失败\r\n
```

## 5. 姿态输出顺序

返回报文中的 `A/B/C` 由网络配置中的 `poseOutputOrder` 控制。

支持顺序：

- `RPY`
- `RYP`
- `PRY`
- `PYR`
- `YRP`
- `YPR`

## 6. 配置相关

`config.xml` 中与协议相关的关键项：

- `TcpServerConfig.robotServerPort`：本 TCP/IP 协议服务端监听端口，默认 `7800`。
- `TcpServerConfig.poseOutputOrder`：TCP 和 Modbus 姿态输出顺序。
- `AlgorithmParams/RotorCoreParam/WorkpieceSizes.defaultIndex`：默认工件尺寸序号。
- `WorkpieceSizes/Workpiece`：每项包含 `index`、`radius`、`height`；尺寸单位 mm，必须为有限正数，界面上限为 `1000000`。

配置示例（第二项为示例尺寸，请按实际工件填写）：

```xml
<WorkpieceSizes defaultIndex="1">
    <Workpiece index="1" radius="45.0" height="20.0"/>
    <Workpiece index="2" radius="60.0" height="70.0"/>
</WorkpieceSizes>
```

旧配置没有 `WorkpieceSizes` 时，将原 `RotorCoreParam.radius/height` 迁移为 1 号工件。
隔板长宽、分层系数、边距系数和地面去除偏置仍是公共转子参数。

## 7. Modbus TCP 对接

除本 TCP/IP 服务端协议外，项目还支持 Modbus TCP Server 对接：

- 应用只作为 Modbus TCP Server/从设备。
- 客户 PLC/上位机作为 Modbus TCP Client，写触发寄存器并读取状态和结果。
- Modbus TCP Server 端口固定为应用内 `5020`；现场需要标准 `502` 时由系统映射到 `5020`。
- `robotServerPort` 不控制 Modbus 端口，只控制本 TCP/IP 文本协议端口。

寄存器地址配置和结果格式详见 `工件定位ModbusTCP协议.md`。