# 糖包拆线 ModbusTCP 协议说明

**应用名称**: BagThreadPosition（糖包拆线）
**版本**: v1.0
**日期**: 2026-02-07

## 概述

糖包拆线应用作为 ModbusTCP 服务端，使用标准 ModbusTCP 协议（端口 502）与外部设备（客户端）通信，实现相机扫描控制和检测结果输出。

### 基本信息

- **服务端**: 糖包拆线应用（BagThreadPosition）
- **客户端**: PLC、机器人控制器或其他支持 ModbusTCP 的设备
- **协议**: ModbusTCP（基于 TCP/IP 的 Modbus 协议）
- **端口**: 502
- **功能码**: 0x03（读保持寄存器）、0x10（写多个保持寄存器）

## 寄存器地址映射

### 控制寄存器

| 地址 | 功能 | 读/写 | 数据类型 | 说明 |
|------|------|-------|----------|------|
| 0 | 启动扫描 | 写 | uint16 | 写入1启动相机扫描 |
| 2 | 检测状态 | 读 | uint16 | 0=未完成, 1=成功, 2=失败 |

### 数据寄存器

| 地址 | 功能 | 读/写 | 数据类型 | 说明 |
|------|------|-------|----------|------|
| 4+ | xyzu数据 | 读 | float[] | 拆线位置数据（每条拆线8个寄存器） |

## 使用流程

### 客户端操作步骤

### 1. 启动扫描

客户端写入寄存器[0] = 1

- 服务端启动相机扫描
- 寄存器[2]被重置为0（检测中）

### 2. 等待检测完成

客户端循环读取寄存器[2]，直到值不为0

- 值为1：检测成功，xyzu数据已自动写入寄存器[4]开始的位置
- 值为2：检测失败

### 3. 读取检测结果

当寄存器[2] = 1（成功）时，客户端直接从寄存器[4]开始读取 xyzu 数据。

## 数据格式

### 寄存器布局

每条拆线占用 8 个寄存器（4个float，每个float占2个寄存器）：

```
寄存器[4+i*8+0:1]   -> x (centerX, float)
寄存器[4+i*8+2:3]   -> y (centerY, float)
寄存器[4+i*8+4:5]   -> z (centerZ, float)
寄存器[4+i*8+6:7]   -> u (rotateAngle, float)
```

其中 i 为拆线索引（从0开始）。

### xyzu 含义

- **x (centerX)**: 拆线端部中心点的X坐标（毫米）
- **y (centerY)**: 拆线端部中心点的Y坐标（毫米）
- **z (centerZ)**: 拆线端部中心点的Z坐标（毫米）
- **u (rotateAngle)**: 拆线旋转角度（度，范围 -30° ~ 30°）

### Float 数据格式

每个 float 值占用 2 个 uint16 寄存器（IEEE 754 单精度浮点数）：
- 低位寄存器：float 的低16位
- 高位寄存器：float 的高16位

## 注意事项

1. **服务端**: 糖包拆线应用启动后自动开启 ModbusTCP 服务端，监听端口 502
2. **客户端**: 支持标准 ModbusTCP 协议的设备均可连接（PLC、机器人控制器等）
3. **数据顺序**: 拆线数据按检测顺序排列
4. **自动输出**: 检测成功后，服务端自动将 xyzu 数据写入寄存器[4]开始的位置，客户端无需额外请求
5. **字节序**: Float 数据使用小端字节序（Little Endian）
6. **连接数**: 支持多个客户端同时连接，但建议单客户端操作
7. **超时处理**: 建议客户端设置合理的超时时间（如30秒）等待检测完成

## 错误处理

如果寄存器[2]返回2（失败），可能的原因：
- 相机未连接
- 检测算法失败
- 检测处理器未初始化

建议客户端在失败后重新启动扫描或通知操作人员检查设备状态。