# WeldSeam ModbusTCP 协议

## 1. 通信参数

| 项目 | 值 |
|---|---|
| 角色 | 视觉控制器为 ModbusTCP Server，主控/PLC 为 Client |
| 默认端口 | `5020` |
| Unit ID | `1`（服务端按标准 MBAP 头处理） |
| 数据区 | Holding Registers |
| 支持功能码 | `0x03` 读保持寄存器、`0x06` 写单寄存器、`0x10` 写多寄存器 |
| 地址表示 | 下表为 PDU 零基地址；PLC 若使用 4xxxx 表示法需按厂商规则换算 |

所有 32 位浮点数均使用 IEEE-754 `float32`，高 16 位寄存器在前；每个寄存器内部仍按 Modbus 网络字节序（大端）传输。

## 2. 寄存器映射

| PDU 地址 | 数量 | 读写 | 名称 | 说明 |
|---:|---:|---|---|---|
| `0` | 1 | R/W | Command | 写 `1` 开始扫描，写 `2` 停止扫描并计算；服务端受理后自动清零 |
| `1` | 1 | R | Status | `0`就绪，`1`扫描中，`2`计算中，`3`成功，`4`失败 |
| `2` | 1 | R | PointCount | 有效路径点数量，范围 `0..40` |
| `3..242` | 240 | R | PointData | 最多 40 个路径点，每点 6 个寄存器（X/Y/Z 三个 float32） |

第 `i` 个路径点（`i=0..39`）的地址：

| 坐标 | PDU 起始地址 | 寄存器数 |
|---|---:|---:|
| `Xi` | `3 + i*6` | 2 |
| `Yi` | `5 + i*6` | 2 |
| `Zi` | `7 + i*6` | 2 |

仅前 `PointCount` 个点有效；其余点寄存器为 `0`。TCP 文本协议不受 40 点限制，Modbus 超过 40 点时只发布前 40 点。

## 3. 操作流程

1. Client 读取 `Status(1)`，确认值为 `0`、`3` 或 `4`，并确认现场允许开始新任务。
2. Client 向 `Command(0)` 写 `1`。
3. Server 清空旧结果并将 `Status` 置为 `1`；主控随后移动相机，VzNLSDK 以非摆动动态模式采集。
4. 相机移动结束并停止后，Client 向 `Command(0)` 写 `2`。
5. Server 停止采集并将 `Status` 置为 `2`，随后自动调用算法计算。
6. 成功时 Server 写入 `PointCount/PointData` 并将 `Status` 置为 `3`；失败时清零点数并将 `Status` 置为 `4`。
7. Client 在 `Status=3` 后读取 `PointCount`，再按点数读取路径点。

按 Modbus 规范，功能码 `0x03` 单次最多读取 125 个寄存器。读取较多路径点时，Client 必须把 `PointData` 拆成多次连续读取，且不得拆开某个 float32 对应的两个寄存器。

## 4. float32 示例

数值 `12.5` 的 IEEE-754 十六进制为 `0x41480000`：

```text
高字寄存器 = 0x4148
低字寄存器 = 0x0000
```

若第 0 点 `X0=12.5`，则 PDU 地址 `3=0x4148`、地址 `4=0x0000`。

## 5. 异常处理

- 非就绪状态写开始命令、非扫描状态写停止命令或未知命令时，`Status` 置为 `4`。
- 扫描失败、点云为空、算法返回错误或无有效焊缝时，`PointCount=0`、`Status=4`。
- 通信断开不自动重复运动或扫描命令；Client 恢复连接后必须先核对现场设备状态。