QI Mingxuan
414 lines
16 KiB
Markdown
414 lines
16 KiB
Markdown
# XP.Hardware.RaySource
|
||
|
||
工业 X 射线源控制模块 | Industrial X-Ray Source Control Module
|
||
|
||
---
|
||
|
||
## 项目概述 | Project Overview
|
||
|
||
XP.Hardware.RaySource 是 XplorePlane X 射线检测系统的核心硬件控制模块，负责与工业 X 射线源设备进行通讯和控制。该模块采用策略模式和工厂模式设计，支持多种 X 射线源型号的统一管理，提供完整的设备生命周期控制和安全机制。
|
||
|
||
### 主要特性 | Key Features
|
||
|
||
- 支持多种 X 射线源型号（当前支持 Comet 225kV）
|
||
- 基于 Named Pipe IPC 的进程隔离架构（.NET 8 主进程 ↔ .NET Framework 4.8 Host 进程）
|
||
- 完整的设备生命周期管理（初始化、连接变量、暖机、训机、灯丝校准、自动定心、开关射线）
|
||
- 精确的电压电流控制（20-225kV / 10-1000μA）
|
||
- 实时状态监控和错误检测
|
||
- 基于 Prism 事件聚合器的松耦合跨模块通讯
|
||
- 安全机制：紧急关闭优先级、参数范围验证
|
||
- 灯丝寿命管理：使用时长记录、累计统计、预警提醒
|
||
- TXI 开关控制、功率模式切换（Micro Focus / High Power）
|
||
- 完整的日志记录和异常处理
|
||
|
||
---
|
||
|
||
## 框架架构 | Architecture
|
||
|
||
```
|
||
XP.Hardware.RaySource/
|
||
├── Abstractions/ # 抽象层 | Abstraction Layer
|
||
│ ├── IXRaySource.cs # 策略接口（同步方法）
|
||
│ ├── XRaySourceBase.cs # 抽象基类
|
||
│ ├── XRayResult.cs # 结果封装类
|
||
│ ├── IRaySourceFactory.cs # 工厂接口
|
||
│ ├── Enums/ # 枚举定义
|
||
│ │ └── RaySourceStatus.cs # 三态枚举（Unavailable/Closed/Opened）
|
||
│ └── Events/ # Prism 事件定义
|
||
│ ├── StatusUpdatedEvent.cs # 系统状态更新事件
|
||
│ ├── ErrorOccurredEvent.cs # 错误触发事件
|
||
│ ├── OperationResultEvent.cs # 操作结果事件
|
||
│ ├── RaySourceStatusChangedEvent.cs # 射线源状态变更事件
|
||
│ └── VariablesConnectedEvent.cs # PVI 变量连接状态事件
|
||
├── Implementations/ # 实现层 | Implementation Layer
|
||
│ ├── Comet225RaySource.cs # Comet 225kV 适配器（委托 IPC 客户端）
|
||
│ ├── CometHostManager.cs # Host 进程生命周期管理器
|
||
│ └── CometIpcClient.cs # Named Pipe IPC 客户端
|
||
├── Factories/ # 工厂层 | Factory Layer
|
||
│ └── RaySourceFactory.cs # 射线源工厂
|
||
├── Services/ # 业务服务层 | Service Layer
|
||
│ ├── IRaySourceService.cs # 服务接口
|
||
│ ├── RaySourceService.cs # 服务实现（单例）
|
||
│ ├── IFilamentLifetimeService.cs # 灯丝寿命服务接口
|
||
│ └── FilamentLifetimeService.cs # 灯丝寿命服务实现
|
||
├── Config/ # 配置层 | Configuration Layer
|
||
│ ├── RaySourceConfig.cs # 配置实体
|
||
│ └── ConfigLoader.cs # 配置加载器（支持保存）
|
||
├── Module/ # Prism 模块 | Prism Module
|
||
│ └── RaySourceModule.cs # 模块注册
|
||
├── ViewModels/ # 视图模型 | View Models
|
||
│ ├── RaySourceConfigViewModel.cs # 配置视图模型（初始化/连接/断开/设备状态监控/灯丝寿命）
|
||
│ └── RaySourceOperateViewModel.cs # 操作视图模型（开关/电压电流调节）
|
||
├── Views/ # WPF 视图 | WPF Views
|
||
│ ├── RaySourceConfigView.xaml # 配置视图（设备状态面板）
|
||
│ ├── RaySourceConfigWindow.xaml # 配置窗口（包裹 ConfigView）
|
||
│ └── RaySourceOperateView.xaml # 操作视图（开关/滑块）
|
||
├── Converters/ # WPF 值转换器 | WPF Value Converters
|
||
│ ├── RaySourceOperateConverter.cs # 状态→颜色/边框色/启用状态
|
||
│ └── FilamentLifetimeColorConverter.cs # 灯丝寿命百分比→颜色
|
||
└── Documents/ # 文档 | Documentation
|
||
├── README.md # 项目说明（本文档）
|
||
├── ProjectStructure.md # 项目结构详解
|
||
├── GUIDENCE.md # 使用指南
|
||
├── README_RaySourceOperateView.md # 操作视图说明
|
||
└── App.config.example # 配置文件示例
|
||
```
|
||
|
||
|
||
### 设计模式 | Design Patterns
|
||
|
||
- **策略模式**：`IXRaySource` 接口定义统一操作，支持多种设备实现
|
||
- **工厂模式**：`IRaySourceFactory` 根据设备类型动态创建实例
|
||
- **适配器模式**：`Comet225RaySource` 将 IPC 通信适配为 `IXRaySource` 接口
|
||
- **进程隔离**：通过 `CometHostManager` + `CometIpcClient` 实现 .NET 8 与 .NET Framework 4.8 的跨框架通信
|
||
- **模板方法模式**：`XRaySourceBase` 提供基础实现框架
|
||
- **单例模式**：`IRaySourceService`、`IFilamentLifetimeService` 作为全局单例
|
||
- **依赖注入**：通过 Prism 容器管理服务生命周期
|
||
- **事件聚合器**：使用 Prism `IEventAggregator` 实现松耦合通讯
|
||
|
||
### IPC 进程隔离架构 | IPC Process Isolation Architecture
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ .NET 8 主进程 (XP.Hardware.RaySource) │
|
||
│ │
|
||
│ ViewModel → RaySourceService → Comet225RaySource │
|
||
│ │ │
|
||
│ CometHostManager（管理 Host 进程生命周期）│
|
||
│ CometIpcClient（Named Pipe 双管道通信） │
|
||
│ │ │
|
||
│ NamedPipe: Cmd（写入）/ Rsp（读取） │
|
||
└──────────────────────────────┬───────────────────────────────────────┘
|
||
│ Named Pipe IPC
|
||
┌──────────────────────────────┴───────────────────────────────────────┐
|
||
│ .NET Framework 4.8 Host 进程 (Comet.Host) │
|
||
│ │
|
||
│ CometPviClient ← BR.AN.PviServices.dll │
|
||
│ （PVI 通讯层，直接操作 PLC 变量） │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 核心功能 | Core Features
|
||
|
||
### 1. 设备生命周期管理 | Device Lifecycle Management
|
||
|
||
```csharp
|
||
// 初始化射线源（类型从配置文件读取）
|
||
XRayResult result = _raySourceService.Initialize();
|
||
|
||
// 连接 PVI 变量并启动实时状态通讯
|
||
XRayResult connectResult = _raySourceService.ConnectVariables();
|
||
|
||
// 异步执行初始化 + 连接变量的完整流程
|
||
XRayResult autoResult = await _raySourceService.InitializeAndConnectAsync();
|
||
|
||
// 开启射线
|
||
_raySourceService.TurnOn();
|
||
|
||
// 关闭射线
|
||
_raySourceService.TurnOff();
|
||
|
||
// 紧急关闭（最高优先级）
|
||
_raySourceService.EmergencyShutdown();
|
||
|
||
// 断开连接（保留实例以便重连）
|
||
_raySourceService.Disconnect();
|
||
```
|
||
|
||
### 2. 电压电流控制 | Voltage and Current Control
|
||
|
||
```csharp
|
||
// 设置电压（20-225kV）
|
||
_raySourceService.SetVoltage(100f);
|
||
|
||
// 设置电流（10-1000μA）
|
||
_raySourceService.SetCurrent(500f);
|
||
|
||
// 读取实际电压
|
||
XRayResult voltageResult = _raySourceService.ReadVoltage();
|
||
float voltage = voltageResult.GetFloat();
|
||
|
||
// 读取实际电流
|
||
XRayResult currentResult = _raySourceService.ReadCurrent();
|
||
float current = currentResult.GetFloat();
|
||
```
|
||
|
||
### 3. 设备操作 | Device Operations
|
||
|
||
```csharp
|
||
// TXI 开启/关闭
|
||
_raySourceService.TxiOn();
|
||
_raySourceService.TxiOff();
|
||
|
||
// 暖机
|
||
_raySourceService.WarmUp();
|
||
|
||
// 训机
|
||
_raySourceService.Training();
|
||
|
||
// 灯丝校准
|
||
_raySourceService.FilamentCalibration();
|
||
|
||
// 全部电压自动定心
|
||
_raySourceService.AutoCenter();
|
||
|
||
// 设置功率模式（1=Micro Focus，2=High Power）
|
||
_raySourceService.SetPowerMode(1);
|
||
```
|
||
|
||
### 4. 状态监控 | Status Monitoring
|
||
|
||
```csharp
|
||
// 读取系统状态
|
||
_raySourceService.ReadSystemStatus();
|
||
|
||
// 检查错误
|
||
_raySourceService.CheckErrors();
|
||
|
||
// 清除错误
|
||
_raySourceService.ClearErrors();
|
||
|
||
// 检查状态属性
|
||
bool isInitialized = _raySourceService.IsInitialized;
|
||
bool isConnected = _raySourceService.IsConnected;
|
||
bool isXRayOn = _raySourceService.IsXRayOn;
|
||
RaySourceStatus status = _raySourceService.CurrentStatus;
|
||
```
|
||
|
||
### 5. 灯丝寿命管理 | Filament Lifetime Management
|
||
|
||
```csharp
|
||
// 初始化灯丝寿命服务（模块启动时自动调用）
|
||
_filamentLifetimeService.Initialize();
|
||
|
||
// 获取累计使用秒数
|
||
double totalSeconds = _filamentLifetimeService.GetCurrentTotalLifeSeconds();
|
||
|
||
// 获取寿命百分比
|
||
double percentage = _filamentLifetimeService.GetLifetimePercentage();
|
||
|
||
// 检查是否需要预警（≥90%）
|
||
bool shouldWarn = _filamentLifetimeService.ShouldShowLifetimeWarning();
|
||
```
|
||
|
||
### 6. 事件通讯 | Event Communication
|
||
|
||
```csharp
|
||
// 订阅射线源状态变化事件（三态：Unavailable/Closed/Opened）
|
||
_eventAggregator.GetEvent<RaySourceStatusChangedEvent>()
|
||
.Subscribe(OnRaySourceStatusChanged, ThreadOption.UIThread);
|
||
|
||
// 订阅系统状态更新事件（电压/电流/各子系统状态）
|
||
_eventAggregator.GetEvent<StatusUpdatedEvent>()
|
||
.Subscribe(OnStatusUpdated, ThreadOption.UIThread);
|
||
|
||
// 订阅错误事件
|
||
_eventAggregator.GetEvent<ErrorOccurredEvent>()
|
||
.Subscribe(OnErrorOccurred, ThreadOption.UIThread);
|
||
|
||
// 订阅操作结果事件
|
||
_eventAggregator.GetEvent<OperationResultEvent>()
|
||
.Subscribe(OnOperationResult, ThreadOption.UIThread);
|
||
|
||
// 订阅 PVI 变量连接状态事件
|
||
_eventAggregator.GetEvent<VariablesConnectedEvent>()
|
||
.Subscribe(OnVariablesConnected, ThreadOption.UIThread);
|
||
```
|
||
|
||
---
|
||
|
||
## 技术要求 | Technical Requirements
|
||
|
||
### 运行环境 | Runtime Environment
|
||
|
||
- **.NET 8.0** (net8.0-windows7.0)
|
||
- **Windows 操作系统**（WPF 依赖）
|
||
- **Visual Studio 2022** 或更高版本
|
||
|
||
### 核心依赖 | Core Dependencies
|
||
|
||
| 依赖库 | 版本 | 用途 |
|
||
|--------|------|------|
|
||
| **Prism.Wpf** | 9.0.537 | MVVM 框架和依赖注入 |
|
||
| **Telerik UI for WPF** | 2024.1.408 | UI 控件库 |
|
||
| **System.Configuration.ConfigurationManager** | 8.0.0 | 配置文件管理 |
|
||
| **XP.Common** | - | 日志、数据库、多语言基础设施 |
|
||
| **XP.Hardware.RaySource.Comet.Messages** | - | IPC 消息定义（netstandard2.0 共享库） |
|
||
|
||
### 关联项目 | Related Projects
|
||
|
||
| 项目 | 框架 | 用途 |
|
||
|------|------|------|
|
||
| **XP.Hardware.RaySource.Comet.Host** | .NET Framework 4.8 | Host 子进程，运行 B&R PVI 通讯 |
|
||
| **XP.Hardware.RaySource.Comet.Messages** | netstandard2.0 | IPC 命令/响应消息定义 |
|
||
|
||
---
|
||
|
||
## 快速开始 | Quick Start
|
||
|
||
### 1. 配置文件设置
|
||
|
||
参见 [App.config.example](./App.config.example)
|
||
|
||
### 2. 注册模块
|
||
|
||
在 `App.xaml.cs` 中：
|
||
|
||
```csharp
|
||
protected override void ConfigureModuleCatalog(IModuleCatalog moduleCatalog)
|
||
{
|
||
moduleCatalog.AddModule<RaySourceModule>();
|
||
}
|
||
```
|
||
|
||
### 3. 使用服务
|
||
|
||
在 ViewModel 中注入并使用：
|
||
|
||
```csharp
|
||
public class YourViewModel : BindableBase
|
||
{
|
||
private readonly IRaySourceService _raySourceService;
|
||
private readonly IEventAggregator _eventAggregator;
|
||
|
||
public YourViewModel(
|
||
IRaySourceService raySourceService,
|
||
IEventAggregator eventAggregator)
|
||
{
|
||
_raySourceService = raySourceService;
|
||
_eventAggregator = eventAggregator;
|
||
|
||
_eventAggregator.GetEvent<RaySourceStatusChangedEvent>()
|
||
.Subscribe(OnStatusChanged, ThreadOption.UIThread);
|
||
}
|
||
|
||
public void Initialize()
|
||
{
|
||
XRayResult result = _raySourceService.Initialize();
|
||
if (result.Success)
|
||
{
|
||
_raySourceService.ConnectVariables();
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 配置参数说明 | Configuration Parameters
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| SourceType | string | Comet225 | 射线源类型 |
|
||
| PlcIpAddress | string | 192.168.12.10 | PLC IP 地址 |
|
||
| PlcPort | int | 11159 | PLC 端口号 |
|
||
| StationNumber | int | 1 | 源站号 |
|
||
| PortNumber | int | 11 | 源端口号 |
|
||
| CpuName | string | cpu | CPU 名称 |
|
||
| ConnectionTimeout | int | 5000 | 连接超时（毫秒）|
|
||
| MinVoltage | float | 20 | 最小电压（kV）|
|
||
| MaxVoltage | float | 225 | 最大电压（kV）|
|
||
| MinCurrent | float | 10 | 最小电流（μA）|
|
||
| MaxCurrent | float | 1000 | 最大电流（μA）|
|
||
| AdvanceExePath | string | FXEControl.exe 路径 | 高级设置外部程序路径 |
|
||
| HostExePath | string | 空（自动查找） | Host 进程可执行文件路径 |
|
||
| InitializationTimeout | int | 30000 | 初始化超时（毫秒）|
|
||
| WarmUpTimeout | int | 300000 | 暖机超时（5分钟）|
|
||
| StartUpTimeout | int | 180000 | 启动超时（3分钟）|
|
||
| AutoCenterTimeout | int | 120000 | 自动定心超时（2分钟）|
|
||
| FilamentAdjustTimeout | int | 120000 | 灯丝调整超时（2分钟）|
|
||
| GeneralOperationTimeout | int | 10000 | 一般操作超时（毫秒）|
|
||
| SerialNumber | string | 空 | 射线源序列号（灯丝寿命管理） |
|
||
| TotalLifeThreshold | int | 1000 | 灯丝总寿命阈值（小时） |
|
||
|
||
---
|
||
|
||
## 安全机制 | Safety Mechanisms
|
||
|
||
### 1. 参数范围验证
|
||
|
||
所有参数在设置前都会进行范围验证，超出范围返回错误结果。
|
||
|
||
### 2. 紧急关闭优先级
|
||
|
||
紧急关闭具有最高优先级，可以在任何状态下执行，会依次关闭射线、完全关闭设备。
|
||
|
||
### 3. 业务规则校验
|
||
|
||
- 未初始化禁止操作
|
||
- 防重复开启/关闭（双重检查锁定）
|
||
- 异常断联自动检测和状态重置
|
||
|
||
### 4. 灯丝寿命预警
|
||
|
||
灯丝使用时长达到阈值 90% 时，系统自动弹出预警对话框。
|
||
|
||
---
|
||
|
||
## 文档索引 | Documentation Index
|
||
|
||
- **[README.md](./README.md)** - 本文档，项目概述和快速参考
|
||
- **[ProjectStructure.md](./ProjectStructure.md)** - 项目结构详解和调用链路
|
||
- **[GUIDENCE.md](./GUIDENCE.md)** - 详细使用指南，包含完整代码示例
|
||
- **[README_RaySourceOperateView.md](./README_RaySourceOperateView.md)** - 操作视图使用说明
|
||
- **[App.config.example](./App.config.example)** - 配置文件示例
|
||
|
||
---
|
||
|
||
## 故障排查 | Troubleshooting
|
||
|
||
### 初始化失败
|
||
- 检查 Host 进程可执行文件是否存在（默认路径：`{主程序目录}/Host/XP.Hardware.RaySource.Comet.Host.exe`）
|
||
- 检查 PLC IP 地址和端口配置
|
||
- 确认 PLC 网络连接正常
|
||
- 查看日志中 Named Pipe 连接状态
|
||
|
||
### 射线无法开启
|
||
- 确认已成功初始化并连接变量（`IsInitialized && IsConnected`）
|
||
- 检查设备错误状态
|
||
- 验证互锁信号
|
||
|
||
### 电压电流设置失败
|
||
- 验证参数在有效范围内
|
||
- 确认射线源已初始化
|
||
- 检查 IPC 管道连接状态
|
||
|
||
### Host 进程异常
|
||
- 检查 Host 进程是否正常启动（查看日志中 PID 信息）
|
||
- 确认 BR.AN.PviServices.dll 已正确部署到 Host 目录
|
||
- 检查是否有残留的 Host 进程（CometHostManager 会自动清理）
|
||
|
||
详细故障排查请参考 [GUIDENCE.md](./GUIDENCE.md) 第 14 节。
|
||
|
||
---
|
||
|
||
## 许可证 | License
|
||
|
||
本模块是 XplorePlane 项目的一部分，遵循项目整体许可协议。
|
||
|
||
---
|
||
|
||
**最后更新 | Last Updated**: 2026-03-26
|