# 设备交互工具

<cite>
**本文档引用的文件**
- [GD10OperCmd.cpp](file://cpp/Tools/GD10OperCmd.cpp)
- [GD10OperCmd.h](file://h/GD10OperCmd.h)
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp)
- [NetWorkOper.h](file://h/NetWorkOper.h)
- [OperPLC.cpp](file://cpp/Tools/OperPLC.cpp)
- [OperPLC.h](file://h/OperPLC.h)
- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp)
- [HandleProcessor.h](file://h/HandleProcessor.h)
- [StateProcessor.cpp](file://cpp/Tools/StateProcessor.cpp)
- [StateProcessor.h](file://h/StateProcessor.h)
- [TransferCtrl.cpp](file://cpp/Tools/TransferCtrl.cpp)
- [TransferCtrl.h](file://h/TransferCtrl.h)
- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h)
- [Constant.h](file://h/Constant.h)
- [TcpClient.h](file://h/TcpClient.h)
- [DetcGD10Dev.h](file://h/DetcGD10Dev.h)
</cite>

## 目录
1. [引言](#引言)
2. [GD10设备通信指令集](#gd10设备通信指令集)
3. [网络设备发现与远程控制](#网络设备发现与远程控制)
4. [PLC设备读写操作](#plc设备读写操作)
5. [设备状态机与消息处理](#设备状态机与消息处理)
6. [数据传输控制](#数据传输控制)
7. [典型交互流程](#典型交互流程)
8. [最佳实践](#最佳实践)
9. [结论](#结论)

## 引言
GeomativeStudio系统通过一系列工具组件实现与外部设备的交互，包括GD10主机、PLC控制器和网络设备。本文档系统化记录了这些工具组件的设计与实现，重点分析GD10设备通信指令集、网络设备发现与控制、PLC设备读写操作，以及设备状态管理、消息分发和数据传输控制机制。这些组件共同构成了系统与外部设备通信的核心基础设施。

## GD10设备通信指令集

`GD10OperCmd`组件定义了与GD10设备交互的完整指令集，通过模拟微机操作来管理设备上的文件和配置。该组件采用单例模式，确保全局唯一实例。

指令集主要包括：
- **工程管理**：`project_add`和`project_delete`方法用于在GD10设备上创建和删除工程，通过操作`localhost.xml`和MAC地址对应的XML文件来维护工程目录映射。
- **测区管理**：`testzone_add`和`testzone_delete`方法用于管理测区，创建相应的目录并在`project.xml`中添加或删除测区记录。
- **脚本管理**：`script_add`和`script_delete`方法用于管理测量脚本，支持VES、ERI、ERT等不同类型，操作`scripts.xml`文件和脚本文件。
- **任务管理**：`meas_delete`方法用于删除测量任务，同时清理XML配置和相关数据文件。
- **参数配置**：`set_param`方法用于设置设备参数，解析以分号分隔的参数字符串，并更新`equipment.xml`文件中的相应节点。
- **设备注册管理**：`unregister_user`方法用于注销用户，删除对应的用户配置文件。

所有操作都包含详细的错误处理和日志记录，确保操作的可靠性和可追溯性。

**Section sources**
- [GD10OperCmd.cpp](file://cpp/Tools/GD10OperCmd.cpp#L53-L1213)
- [GD10OperCmd.h](file://h/GD10OperCmd.h#L18-L52)

## 网络设备发现与远程控制

`NetWorkOper`组件实现了网络设备的发现、状态查询和远程控制功能。该组件基于TCP通信，通过`CTransferCtrl`进行底层数据传输。

主要功能包括：
- **连接管理**：`StartConnect`方法建立与服务器的TCP连接，`StartWork`方法启动数据处理线程。
- **设备发现**：通过监听特定控制命令（如`EN_RECV_NOTIFY_DEVICE_ONLINE`）来发现网络上的设备，并通过`CDetcGD10Dev`管理器注册设备。
- **状态查询**：`TransferOper`方法用于发送状态查询命令，支持同步和异步模式，通过回调函数通知结果。
- **远程控制**：`SendCtrlMsgDirect`方法用于发送控制命令，`RecvMsgDirect`方法用于接收响应。
- **实时数据处理**：通过`RegeditRealMsgCall`注册实时数据接收窗口，当接收到实时测量数据时，通过Windows消息机制通知注册的窗口。

该组件采用生产者-消费者模式，通过临界区保护共享数据，确保多线程环境下的数据一致性。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant NetWorkOper as "NetWorkOper"
participant TransferCtrl as "TransferCtrl"
participant Server as "服务器"
Client->>NetWorkOper : StartConnect(IP, Port)
NetWorkOper->>TransferCtrl : ConnectToServer()
TransferCtrl->>Server : TCP连接
Server-->>TransferCtrl : 连接成功
TransferCtrl-->>NetWorkOper : 连接状态
NetWorkOper->>NetWorkOper : StartWork()
NetWorkOper->>NetWorkOper : ThreadFunction()
loop 消息循环
NetWorkOper->>TransferCtrl : RecvCtrlMsg()
alt 设备上线通知
TransferCtrl-->>NetWorkOper : EN_RECV_NOTIFY_DEVICE_ONLINE
NetWorkOper->>DevManager : AddRemoteDevice()
NetWorkOper->>MainFrm : WM_MSG_NOTIFY_DEVICE_ON_OR_OFF
else PLC状态
TransferCtrl-->>NetWorkOper : EN_RECV_PLC_STATUS
NetWorkOper->>TaskDataOper : InsertPlcStatusData()
else 实时测量数据
TransferCtrl-->>NetWorkOper : EN_REAL_TIME_TESTING_DATA
NetWorkOper->>RealWnd : WM_NET_RECV_REAL_TIME_DATA
else 控制命令
TransferCtrl-->>NetWorkOper : EN_RECV_CTRL_CMD
NetWorkOper->>DevNotify : 回调通知
end
alt 需要发送命令
NetWorkOper->>TransferCtrl : SendCtrlInfo()
TransferCtrl->>Server : 发送控制命令
TransferCtrl->>TransferCtrl : RecvRspMsg()
TransferCtrl-->>NetWorkOper : 响应数据
NetWorkOper->>NotifyFunc : 回调通知
end
end
```

**Diagram sources**
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L26-L706)
- [NetWorkOper.h](file://h/NetWorkOper.h#L107-L173)

**Section sources**
- [NetWorkOper.cpp](file://cpp/Tools/NetWorkOper.cpp#L26-L706)
- [NetWorkOper.h](file://h/NetWorkOper.h#L107-L173)

## PLC设备读写操作

`OperPLC`组件封装了对PLC设备的读写操作，提供了一个简洁的接口来控制PLC的电源状态。

主要功能包括：
- **命令生成**：`GetPlcCmdInfo`方法根据命令类型生成相应的PLC控制数据包，支持`EN_PLC_POWER_ON`和`EN_PLC_POWER_OFF`命令。
- **响应解析**：`ParsePlcOperResInfo`方法解析PLC返回的状态信息，验证数据长度并提取操作结果。
- **具体命令实现**：`GetPowerOnCmd`和`GetPowerOffCmd`方法构建具体的控制数据包，设置相应的控制位。

该组件通过`STRemPlcDataInfo`结构体定义PLC数据格式，确保与设备的通信协议一致。

```mermaid
classDiagram
class COperPLC {
+GetInstance() COperPLC*
+GetPlcCmdInfo(BYTE, char*, int&, int) void
+ParsePlcOperResInfo(char*, int) int
-GetPowerOnCmd(char*, int&) void
-GetPowerOffCmd(char*, int&) void
-m_pOperPlc COperPLC*
}
class STRemPlcDataInfo {
+ucPacketIndex BYTE
+ucCtrlK1 BYTE
+ucCtrlK2 BYTE
+ucCtrlK3 BYTE
+ucCtrlK4 BYTE
+ucCtrlK5 BYTE
+ucCtrlK6 BYTE
+ucResult BYTE
}
COperPLC --> STRemPlcDataInfo : "使用"
```

**Diagram sources**
- [OperPLC.cpp](file://cpp/Tools/OperPLC.cpp#L18-L121)
- [OperPLC.h](file://h/OperPLC.h#L24-L39)
- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h)

**Section sources**
- [OperPLC.cpp](file://cpp/Tools/OperPLC.cpp#L18-L121)
- [OperPLC.h](file://h/OperPLC.h#L24-L39)

## 设备状态机与消息处理

`HandleProcessor`和`StateProcessor`组件在设备状态机管理、消息分发和事件处理中扮演关键角色。

`HandleProcessor`负责句柄的生成和解析，将ID和类型信息编码到32位DWORD中：
- **句柄生成**：`GenerateHandle`方法将27位ID和5位类型组合成一个唯一的句柄。
- **句柄解析**：`AnalyseHandle`、`GetIDFromHandle`和`GetStyleFromHandle`方法从句柄中提取ID和类型信息。

`StateProcessor`负责状态与图像索引之间的转换：
- **状态转换**：`ChangeToImageState`和`ChangeToItemState`方法在树控件的状态图像索引和内部状态值之间进行转换。

这些组件为系统提供了统一的标识和状态管理机制，简化了设备和对象的管理和显示。

```mermaid
classDiagram
class CHandleProcessor {
+GenerateHandle(DWORD, UINT) DWORD
+GenerateNewHandle(DWORD, UINT) DWORD
+AnalyseHandle(DWORD, DWORD&, UINT&) void
+GetIDFromHandle(DWORD) DWORD
+GetStyleFromHandle(DWORD) UINT
}
class CStateProcessor {
+ChangeToImageState(UINT) UINT
+ChangeToItemState(UINT) UINT
}
CHandleProcessor : HANDLE_OFFSET = 27
CStateProcessor : STATE_OFFSET = 12
```

**Diagram sources**
- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L19-L96)
- [HandleProcessor.h](file://h/HandleProcessor.h#L12-L28)
- [StateProcessor.cpp](file://cpp/Tools/StateProcessor.cpp#L19-L41)
- [StateProcessor.h](file://h/StateProcessor.h#L12-L22)
- [Constant.h](file://h/Constant.h)

**Section sources**
- [HandleProcessor.cpp](file://cpp/Tools/HandleProcessor.cpp#L19-L96)
- [HandleProcessor.h](file://h/HandleProcessor.h#L12-L28)
- [StateProcessor.cpp](file://cpp/Tools/StateProcessor.cpp#L19-L41)
- [StateProcessor.h](file://h/StateProcessor.h#L12-L22)

## 数据传输控制

`TransferCtrl`组件负责数据传输过程的流量控制与状态监控，继承自`CTcpClient`，实现了协议特定的通信逻辑。

主要功能包括：
- **协议封装**：`SendCtrlInfoToDev`方法构建符合`STCtrlProtoHeader`格式的数据包，包含ID码、源/目的地址、命令码、序列号和CRC校验。
- **数据接收**：`RecvCommRspMsg`方法处理接收的数据，包括查找协议头、长度校验、CRC校验和命令类型识别。
- **状态管理**：维护当前命令、设备类型、序列号等状态信息，用于响应匹配和错误检测。
- **错误处理**：实现超时、数据错序、CRC错误等多种错误处理机制。

该组件通过`RecvEnoughMsg`确保完整接收数据包，并通过`IsCtrlMsg`和`IsPlcStatusMsg`识别特殊类型的控制消息。

```mermaid
flowchart TD
A[开始发送] --> B[构建STCtrlProtoHeader]
B --> C[计算总长度]
C --> D[复制数据内容]
D --> E[计算CRC校验]
E --> F[发送数据]
F --> G{发送成功?}
G --> |是| H[更新状态信息]
G --> |否| I[记录错误日志]
H --> J[结束]
I --> J
K[开始接收] --> L[接收协议头]
L --> M{找到ID码?}
M --> |否| N[跳过字节]
N --> O{超过最大跳过字节?}
O --> |是| P[返回错误]
O --> |否| L
M --> |是| Q[校验长度]
Q --> R{长度有效?}
R --> |否| P
R --> |是| S[接收剩余数据]
S --> T[校验CRC]
T --> U{CRC正确?}
U --> |否| P
U --> |是| V[解析命令类型]
V --> W[返回结果]
```

**Diagram sources**
- [TransferCtrl.cpp](file://cpp/Tools/TransferCtrl.cpp#L27-L615)
- [TransferCtrl.h](file://h/TransferCtrl.h#L34-L78)
- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h)

**Section sources**
- [TransferCtrl.cpp](file://cpp/Tools/TransferCtrl.cpp#L27-L615)
- [TransferCtrl.h](file://h/TransferCtrl.h#L34-L78)

## 典型交互流程

### 设备连接初始化
1. 调用`NetWorkOper::StartConnect`建立TCP连接
2. 调用`NetWorkOper::StartWork`启动消息处理线程
3. 系统自动发现在线设备并更新设备列表

### 参数配置
1. 调用`GD10OperCmd::set_param`设置参数
2. 构造参数字符串（如`"gain,2;range,1"`）
3. 方法解析参数并更新`equipment.xml`

### 实时监控
1. 调用`NetWorkOper::RegeditRealMsgCall`注册实时数据窗口
2. 当接收到实时测量数据时，系统发送`WM_NET_RECV_REAL_TIME_DATA`消息
3. 注册窗口处理消息并更新显示

## 最佳实践

### 超时处理
- 所有网络操作都应设置合理的超时时间
- 使用`STRespDataInfo`中的`iTimeout`字段配置超时
- 超时后应进行重试或错误处理

### 指令重发
- 对于关键操作，实现自动重试机制
- 使用序列号跟踪命令，避免重复执行
- 在`TransferCtrl`中维护命令状态，确保可靠性

### 状态同步
- 通过`NetWorkOper`的设备上线/下线通知保持状态同步
- 使用`HandleProcessor`确保对象标识的一致性
- 定期查询设备状态，验证同步状态

## 结论
GeomativeStudio的设备交互工具组件提供了一个完整、可靠的外部设备通信框架。通过`GD10OperCmd`、`NetWorkOper`、`OperPLC`等组件的协同工作，系统能够有效地管理GD10设备、网络设备和PLC控制器。`HandleProcessor`和`StateProcessor`提供了统一的状态和标识管理，而`TransferCtrl`确保了数据传输的可靠性和效率。这些组件的设计体现了良好的分层架构和关注点分离原则，为系统的稳定运行提供了坚实的基础。