# 水肥设备映射功能使用指南

## 📋 功能概述

水肥设备映射功能用于将系统中的逻辑控制对象（如阀门、泵、施肥机、传感器）与现场物理设备建立一一对应关系。通过配置设备地址、通信协议、控制点位等信息，确保系统下发的控制指令能够准确作用于目标设备，实现虚拟控制与实物动作的可靠联动。

## 🎯 核心功能

### 1. 映射关系管理
- **逻辑对象定义**：定义系统中的逻辑控制对象（阀门、泵、施肥机、传感器等）
- **物理设备关联**：关联现场实际的物理设备
- **一一映射**：确保每个逻辑对象唯一对应一个物理设备
- **映射状态**：已映射、未映射、异常三种状态管理

### 2. 通信配置 ⭐核心功能
- **设备地址**：配置物理设备的网络地址（IP:端口或COM端口）
- **通信协议**：支持多种工业通信协议
  - Modbus-RTU：串口通信
  - Modbus-TCP：以太网通信
  - HTTP：Web服务
  - MQTT：物联网消息队列
  - OPC-UA：工业互联标准
  - WebSocket：实时双向通信
- **超时设置**：配置通信超时时间（毫秒）
- **重试机制**：设置通信失败重试次数

### 3. 控制点位配置
- **控制点位**：定义设备的具体控制点（DI/DO/AI/AO + 通道号）
- **数据类型**：设置数据类型（Boolean/Int16/Int32/Float/String）
- **读地址**：Modbus寄存器读取地址
- **写地址**：Modbus寄存器写入地址
- **地址映射**：实现逻辑地址到物理地址的精确映射

### 4. 连接测试
- **单个测试**：测试单个映射的连接状态
- **批量测试**：批量测试所有映射的连接状态
- **测试内容**：
  - 网络连通性检测
  - 设备地址可达性验证
  - 通信协议握手测试
  - 数据读写功能测试
- **结果记录**：记录测试结果和测试时间

### 5. 完整CRUD操作
- **新增映射**：创建新的设备映射配置
- **编辑映射**：修改现有映射配置
- **查看详情**：查看映射完整信息
- **删除映射**：删除不再使用的映射（带警告确认）

### 6. 数据统计
- 映射总数统计
- 已映射/未映射/异常映射数量
- 测试成功数量
- 按设备类型分布统计

### 7. 搜索与筛选
- 关键词搜索（逻辑名称、编号、物理设备、设备地址）
- 按设备类型筛选
- 按映射状态筛选
- 按通信协议筛选

## 📍 访问路径

**导航路径**：水肥机管理 → 水肥机管理 → 水肥设备映射  
**URL路径**：`/irrigation/wf-management/mapping`

## 🔧 设备类型说明

### 1. 阀门 (Valve)
- **功能**：控制管道开关，调节流量
- **典型点位**：DO（数字输出）
- **数据类型**：Boolean
- **控制方式**：开/关（True/False）
- **示例**：主阀门、支阀门、电磁阀

### 2. 泵 (Pump)
- **功能**：提供液体动力，输送水肥
- **典型点位**：DO（数字输出）或AO（模拟输出）
- **数据类型**：Boolean（开关）或Float（变频）
- **控制方式**：启停控制或转速控制
- **示例**：主水泵、增压泵、循环泵

### 3. 施肥机 (Fertilizer Machine)
- **功能**：精确控制肥料施加量
- **典型点位**：AO（模拟输出）
- **数据类型**：Float
- **控制方式**：流量控制（mL/min）
- **示例**：A通道施肥泵、B通道施肥泵

### 4. 传感器 (Sensor)
- **功能**：监测各类参数
- **典型点位**：AI（模拟输入）或DI（数字输入）
- **数据类型**：Float（模拟量）或Boolean（开关量）
- **读取方式**：只读，无需写地址
- **示例**：EC传感器、PH传感器、温度传感器、压力传感器

### 5. 混合器 (Mixer)
- **功能**：混合肥料溶液
- **典型点位**：DO或AO
- **数据类型**：Boolean或Float
- **控制方式**：启停或转速控制
- **示例**：机械搅拌器、磁力搅拌器

### 6. 加热器 (Heater)
- **功能**：加热灌溉水
- **典型点位**：DO或AO
- **数据类型**：Boolean或Float
- **控制方式**：开关控制或功率控制
- **示例**：电加热器、热交换器

## 📊 通信协议详解

### Modbus-TCP
- **应用场景**：局域网内设备通信
- **地址格式**：IP:端口（如192.168.1.101:502）
- **默认端口**：502
- **特点**：基于TCP/IP，可靠性高
- **寄存器类型**：
  - 线圈（Coil）：01功能码，读写布尔量
  - 离散输入（Discrete Input）：02功能码，只读布尔量
  - 保持寄存器（Holding Register）：03/06/16功能码，读写16位整数
  - 输入寄存器（Input Register）：04功能码，只读16位整数

### Modbus-RTU
- **应用场景**：串口通信，多设备串联
- **地址格式**：COM端口（如COM1，从站地址1）
- **特点**：简单可靠，成本低
- **注意事项**：需要设置波特率、数据位、停止位、校验位

### MQTT
- **应用场景**：物联网设备，远程监控
- **地址格式**：mqtt://broker_address:1883
- **特点**：轻量级，支持订阅/发布模式
- **主题示例**：
  - 控制：irrigation/device/valve/control
  - 状态：irrigation/device/valve/status

### HTTP
- **应用场景**：Web服务，RESTful API
- **地址格式**：http://device_ip:port/api/endpoint
- **特点**：标准化，易于集成
- **方法**：GET（读取）、POST（写入）

### OPC-UA
- **应用场景**：工业自动化，跨平台互操作
- **地址格式**：opc.tcp://server_address:4840
- **特点**：安全、可靠、标准化
- **节点示例**：ns=2;s=WaterFertilizer.Valve1.Status

### WebSocket
- **应用场景**：实时双向通信
- **地址格式**：ws://device_ip:port/ws
- **特点**：低延迟，实时性好

## 📈 操作指南

### 新增映射流程

1. **点击"新增映射"按钮**

2. **填写基本信息**（必填项）：
   - 映射编号（自动生成，格式：MAP-YYYY-NNN）
   - 逻辑名称（如：1号主阀门）
   - 逻辑类型（从6种类型中选择）
   - 物理设备（如：1号大棚水肥机-电磁阀1）

3. **配置通信参数**（必填项）：
   - 设备地址（如：192.168.1.101:502）
   - 通信协议（选择合适的协议）
   - 超时时间（默认3000ms）
   - 重试次数（默认3次）

4. **设置控制点位**（必填项）：
   - 控制点位（如：DO0、AI0、AO0）
   - 数据类型（Boolean/Int16/Int32/Float/String）
   - 读地址（Modbus寄存器地址，如：40001）
   - 写地址（留空则与读地址相同）

5. **填写设备信息**（可选）：
   - 设备型号
   - 制造商

6. **填写功能描述**（必填项）：
   - 描述该映射的功能和用途

7. **填写备注**（可选）

8. **点击"保存"完成**

### 控制点位说明

#### DI (Digital Input) - 数字输入
- **用途**：读取开关量状态
- **示例**：DI0、DI1、DI2...
- **数据类型**：Boolean
- **应用**：限位开关、按钮状态

#### DO (Digital Output) - 数字输出
- **用途**：控制开关量输出
- **示例**：DO0、DO1、DO2...
- **数据类型**：Boolean
- **应用**：阀门开关、泵启停

#### AI (Analog Input) - 模拟输入
- **用途**：读取模拟量数据
- **示例**：AI0、AI1、AI2...
- **数据类型**：Float、Int16
- **应用**：传感器数值（EC、PH、温度、压力）

#### AO (Analog Output) - 模拟输出
- **用途**：输出模拟量控制信号
- **示例**：AO0、AO1、AO2...
- **数据类型**：Float、Int16
- **应用**：变频控制、流量控制

### Modbus寄存器地址说明

#### 常用地址范围
- **线圈（Coil）**：00001-09999
- **离散输入（Discrete Input）**：10001-19999
- **输入寄存器（Input Register）**：30001-39999
- **保持寄存器（Holding Register）**：40001-49999

#### 地址示例
```
DO0 → 40001 (保持寄存器，可读写)
DI0 → 10001 (离散输入，只读)
AI0 → 30001 (输入寄存器，只读)
AO0 → 40010 (保持寄存器，可读写)
```

### 连接测试流程

1. 在映射列表找到目标映射
2. 点击操作列的"连接测试"按钮（播放图标）
3. 在测试对话框中查看测试配置信息
4. 点击"开始测试"
5. 等待测试完成（约2秒）
6. 查看测试结果：
   - 成功：映射状态更新为"已映射"
   - 失败：映射状态更新为"异常"，查看备注中的错误信息

### 批量测试流程

1. 点击页面右上角的"批量测试"按钮
2. 系统自动依次测试所有映射
3. 等待测试完成
4. 查看每个映射的测试结果

### 编辑映射流程

1. 在映射列表找到目标映射
2. 点击操作列的"编辑"按钮
3. 修改需要更新的字段
4. 点击"保存"完成（会自动更新"更新时间"）

### 查看详情流程

1. 在映射列表找到目标映射
2. 点击操作列的"查看"按钮
3. 查看映射完整信息：
   - 基本信息
   - 通信配置
   - 点位配置
   - 设备信息
   - 测试信息
   - 功能描述
   - 备注说明
   - 时间信息
4. 可直接点击"编辑"按钮进行修改

### 删除映射流程

1. 在映射列表找到目标映射
2. 点击操作列的"删除"按钮（红色）
3. 在确认对话框中核对映射信息
4. 注意警告：删除后逻辑对象将无法控制物理设备
5. 点击"确认删除"完成

## 📊 数据示例

### 示例1：主阀门映射

```
基本信息：
- 映射编号：MAP-2024-001
- 逻辑名称：1号主阀门
- 逻辑类型：阀门
- 物理设备：1号大棚水肥机-电磁阀1

通信配置：
- 设备地址：192.168.1.101:502
- 通信协议：Modbus-TCP
- 超时时间：3000 ms
- 重试次数：3次

点位配置：
- 控制点位：DO0
- 数据类型：Boolean
- 读地址：40001
- 写地址：40001

设备信息：
- 设备型号：EV-DN25
- 制造商：亚德客

测试信息：
- 映射状态：已映射
- 测试结果：成功
- 最后测试时间：2024-10-23 10:30:00

功能描述：主管道控制阀门，控制灌溉开关
```

### 示例2：EC传感器映射

```
基本信息：
- 映射编号：MAP-2024-004
- 逻辑名称：EC传感器
- 逻辑类型：传感器
- 物理设备：1号大棚水肥机-EC传感器

通信配置：
- 设备地址：192.168.1.101:502
- 通信协议：Modbus-TCP
- 超时时间：5000 ms
- 重试次数：3次

点位配置：
- 控制点位：AI0
- 数据类型：Float
- 读地址：30001
- 写地址：（留空，传感器只读）

设备信息：
- 设备型号：EC-200Pro
- 制造商：梅特勒-托利多

测试信息：
- 映射状态：已映射
- 测试结果：成功
- 最后测试时间：2024-10-23 10:30:00

功能描述：EC值监测传感器，监测营养液电导率

备注：数值单位mS/cm，范围0-5
```

### 示例3：施肥机映射

```
基本信息：
- 映射编号：MAP-2024-003
- 逻辑名称：1号施肥机-A通道
- 逻辑类型：施肥机
- 物理设备：1号大棚水肥机-施肥泵A

通信配置：
- 设备地址：192.168.1.101:502
- 通信协议：Modbus-TCP
- 超时时间：3000 ms
- 重试次数：3次

点位配置：
- 控制点位：AO0
- 数据类型：Float
- 读地址：40010
- 写地址：40010

设备信息：
- 设备型号：FP-100
- 制造商：威乐

测试信息：
- 映射状态：已映射
- 测试结果：成功
- 最后测试时间：2024-10-23 10:30:00

功能描述：A通道施肥泵，控制氮肥施加量

备注：控制施肥量，单位mL/min，范围0-1000
```

## 🔍 搜索与筛选技巧

### 关键词搜索
- 搜索"主阀门" - 显示所有包含"主阀门"的映射
- 搜索"MAP-001" - 显示编号为MAP-001的映射
- 搜索"192.168.1.101" - 显示该地址的所有映射
- 搜索"EC传感器" - 显示EC传感器的映射

### 类型筛选
- 选择"阀门" - 显示所有阀门映射
- 选择"泵" - 显示所有泵映射
- 选择"施肥机" - 显示所有施肥机映射
- 选择"传感器" - 显示所有传感器映射

### 状态筛选
- 选择"已映射" - 显示所有已成功映射的配置
- 选择"未映射" - 显示所有未完成配置的映射
- 选择"异常" - 显示所有连接异常的映射

### 协议筛选
- 选择"Modbus-TCP" - 显示所有使用Modbus-TCP的映射
- 选择"MQTT" - 显示所有使用MQTT的映射

### 组合筛选
- 类型=阀门 + 状态=已映射 - 显示所有正常工作的阀门
- 类型=传感器 + 协议=Modbus-TCP - 显示所有Modbus-TCP传感器
- 状态=异常 - 快速定位需要检修的映射

## ⚠️ 注意事项

1. **映射唯一性**：每个逻辑对象应唯一对应一个物理设备
2. **地址冲突**：避免多个映射使用相同的设备地址和控制点位
3. **协议匹配**：通信协议必须与物理设备支持的协议一致
4. **地址格式**：严格按照协议要求配置地址格式
5. **超时设置**：根据网络状况合理设置超时时间
6. **测试验证**：新建或修改映射后，务必进行连接测试
7. **删除影响**：删除映射会导致逻辑对象无法控制物理设备
8. **安全性**：生产环境中，确保网络安全和设备访问权限

## 💡 最佳实践

### 1. 映射命名规范
```
格式：[区域编号]+[设备类型]+[功能描述]
示例：
- 1号主阀门
- 1号主水泵
- 1号施肥机-A通道
- EC传感器
```

### 2. 编号规范
```
格式：MAP-[年份]-[流水号]
示例：MAP-2024-001、MAP-2024-002
```

### 3. 地址规划
- **统一规划IP地址段**：如192.168.1.101-120
- **有序分配端口**：使用标准端口（Modbus-TCP:502）
- **文档化管理**：记录每个设备的地址分配

### 4. 点位分配
- **DO点位**：用于阀门、泵的开关控制
- **AI点位**：用于传感器数据读取
- **AO点位**：用于施肥机流量控制、变频器转速控制
- **连续分配**：相关设备使用连续的点位编号

### 5. 协议选择建议
- **局域网设备**：优先Modbus-TCP（可靠、快速）
- **串口设备**：使用Modbus-RTU（成本低、简单）
- **物联网设备**：使用MQTT（轻量级、远程）
- **Web服务**：使用HTTP（标准化、易集成）
- **工业标准**：使用OPC-UA（安全、互操作）

### 6. 测试策略
- **新映射必测**：创建新映射后立即测试
- **定期测试**：定期执行批量测试，确保所有映射正常
- **异常处理**：测试失败时，检查网络、地址、协议配置
- **记录日志**：保存测试记录，用于故障排查

### 7. 维护建议
- **文档同步**：映射配置变更时同步更新文档
- **备份导出**：定期导出映射配置文件备份
- **版本管理**：重要变更前备份当前配置
- **权限管理**：严格控制映射配置的修改权限

## 📊 功能特点

1. **虚实联动**：实现虚拟控制与实物动作的可靠联动
2. **协议丰富**：支持6种工业通信协议
3. **灵活配置**：支持各类设备类型和控制方式
4. **即时测试**：提供连接测试功能，确保配置正确
5. **状态监控**：实时监控映射状态和测试结果
6. **完整管理**：提供完整的CRUD操作界面

## 🔗 与其他功能的关系

### 映射是控制的基础
```
参数配置（Parameter）
    ↓
部件配置（Component）
    ↓
设备管理（Device）
    ↓
设备映射（Mapping）⭐核心桥梁
    ↓
实际控制（Control）
```

### 功能关联说明

**设备映射 ← 设备管理**：
- 映射配置引用设备管理中的物理设备信息
- 每个物理设备可以有多个映射（多个控制点）

**设备映射 → 控制系统**：
- 控制系统通过映射找到对应的物理设备
- 映射提供准确的地址、协议、点位信息
- 确保控制指令准确下发到目标设备

**设备映射 → 监控系统**：
- 监控系统通过映射读取传感器数据
- 映射提供数据采集的地址和格式信息

## 📞 技术支持

如有问题，请查阅相关文档或联系技术支持团队。

---

**版本**：v1.0.0  
**更新日期**：2024-10-23  
**所属系统**：智慧农业生产管理系统 - 水肥机管理子系统
