GrabBag/App/WorkpieceHole/Doc/MODBUS_PROTOCOL.md

# WorkpieceHole 工件孔定位 - Modbus TCP 通信协议

## 1. 系统架构

```
┌─────────────────┐      Modbus TCP      ┌─────────────────────┐
│                 │◄────────────────────►│                     │
│   3D视觉系统     │      192.168.0.88    │  汇川PLC-easy320    │
│  (Modbus客户端)  │         :502         │  (Modbus服务端)     │
│                 │                      │                     │
└─────────────────┘                      └─────────────────────┘
```

## 2. 网络配置

| 设备 | IP地址 | 端口 | 角色 |
|------|--------|------|------|
| 3D视觉系统 | - | - | Modbus TCP 客户端 |
| 汇川PLC-easy320 | 192.168.0.88 | 502 | Modbus TCP 服务端 |

## 3. 地址映射规则

汇川PLC D寄存器与Modbus保持寄存器地址映射关系：

```
代码协议地址 = D寄存器地址 + 1

示例：
  D1000 -> 代码协议地址 1001
  D1002 -> 代码协议地址 1003
  D2000 -> 代码协议地址 2001
```

## 4. 寄存器地址定义

### 4.1 控制寄存器

| PLC寄存器 | 代码协议地址 | 类型 | 读/写 | 说明 |
|-----------|------------|------|-------|------|
| D1000 | 1001 | uint16 | R/W | 拍照请求标志（1=请求拍照） |
| D1002 | 1003 | uint16 | W | 数据输出完成标志（1=完成） |

### 4.2 坐标数据寄存器（D2000开始，最多10个点）

每个点包含6个float值（X, Y, Z, Pitch, Roll, Yaw），每个float占用2个寄存器（大端序），共12个寄存器/点。

| 点序号 | PLC寄存器范围 | 代码协议地址范围 | 说明 |
|--------|--------------|-----------------|------|
| 点0 | D2000-D2011 | 2001-2012 | 第1个点坐标 |
| 点1 | D2012-D2023 | 2013-2024 | 第2个点坐标 |
| 点2 | D2024-D2035 | 2025-2036 | 第3个点坐标 |
| 点3 | D2036-D2047 | 2037-2048 | 第4个点坐标 |
| 点4 | D2048-D2059 | 2049-2060 | 第5个点坐标 |
| 点5 | D2060-D2071 | 2061-2072 | 第6个点坐标 |
| 点6 | D2072-D2083 | 2073-2084 | 第7个点坐标 |
| 点7 | D2084-D2095 | 2085-2096 | 第8个点坐标 |
| 点8 | D2096-D2107 | 2097-2108 | 第9个点坐标 |
| 点9 | D2108-D2119 | 2109-2120 | 第10个点坐标 |

### 4.3 单点坐标数据布局（以点0为例）

| PLC寄存器 | 代码协议地址 | 类型 | 说明 |
|-----------|------------|------|------|
| D2000-D2001 | 2001-2002 | float (大端) | X坐标 (mm) |
| D2002-D2003 | 2003-2004 | float (大端) | Y坐标 (mm) |
| D2004-D2005 | 2005-2006 | float (大端) | Z坐标 (mm) |
| D2006-D2007 | 2007-2008 | float (大端) | Pitch角度 (°) |
| D2008-D2009 | 2009-2010 | float (大端) | Roll角度 (°) |
| D2010-D2011 | 2011-2012 | float (大端) | Yaw角度 (°) |

> **注意**:
> - 每个float值占用2个寄存器，采用IEEE 754单精度浮点数格式
> - 大端序（Big-Endian）：高位字在低地址寄存器，低位字在高地址寄存器
> - 最多支持10个点，共120个寄存器（10 × 6 × 2 = 120）

## 5. 通信流程

```
时序图：

3D视觉系统                      汇川PLC
    │                              │
    │   轮询读取D1000(地址1001)    │
    │◄─────────────────────────────│
    │                              │
    │   D1000=1 (拍照请求)         │
    │◄─────────────────────────────│
    │                              │
    │   写0到D1000(地址1001)       │
    │─────────────────────────────►│
    │                              │
    │   [执行拍照和算法处理]        │
    │                              │
    │   写坐标到D2000(地址2001)开始│
    │─────────────────────────────►│
    │                              │
    │   写1到D1002(地址1003)       │
    │─────────────────────────────►│
    │                              │
```

### 5.1 详细流程说明

1. **轮询拍照请求**
   - 3D系统持续轮询读取PLC的D1000寄存器（代码协议地址1001）
   - 轮询间隔：100ms（可配置）
   - 使用边沿检测：只在0→1变化时触发

2. **拍照执行**
   - 检测到D1000=1后，立即写0到D1000清除请求
   - 触发相机拍照
   - 执行工件孔定位算法

3. **坐标输出**
   - 算法处理完成后，将坐标数据写入PLC的D2000开始的寄存器
   - 代码协议地址：2001-2012（单点12个寄存器，6个float值）
   - 数据格式：IEEE 754单精度浮点数，大端序

4. **完成通知**
   - 坐标数据写入成功后，写1到D1002（代码协议地址1003）
   - 通知PLC数据输出完成

## 6. 连接管理

### 6.1 自动重连机制

- 初始化时尝试连接PLC
- 连接失败时自动启动重连定时器
- 重连间隔：3000ms（可配置）
- 持续重连直到连接成功或软件关闭

### 6.2 优雅退出

- 设置关闭标志，阻止新的重连尝试
- 停止所有定时器（轮询、重连）
- 断开Modbus连接
- 释放资源

## 7. 错误处理

| 错误类型 | 处理方式 |
|----------|----------|
| 连接失败 | 自动重连，发送错误信号 |
| 读取失败 | 记录日志，下次轮询重试 |
| 写入失败 | 记录日志，返回失败状态 |
| 超时 | 默认1秒超时，触发重连 |