XplorePlane/XP.Hardware.RaySource/Documents

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

// 初始化射线源（类型从配置文件读取）
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

// 设置电压（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

// 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

// 读取系统状态
_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

// 初始化灯丝寿命服务（模块启动时自动调用）
_filamentLifetimeService.Initialize();

// 获取累计使用秒数
double totalSeconds = _filamentLifetimeService.GetCurrentTotalLifeSeconds();

// 获取寿命百分比
double percentage = _filamentLifetimeService.GetLifetimePercentage();

// 检查是否需要预警（≥90%）
bool shouldWarn = _filamentLifetimeService.ShouldShowLifetimeWarning();

6. 事件通讯 | Event Communication

// 订阅射线源状态变化事件（三态：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

2. 注册模块

在 App.xaml.cs 中：

protected override void ConfigureModuleCatalog(IModuleCatalog moduleCatalog)
{
    moduleCatalog.AddModule<RaySourceModule>();
}

3. 使用服务

在 ViewModel 中注入并使用：

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 - 本文档，项目概述和快速参考
• ProjectStructure.md - 项目结构详解和调用链路
• GUIDENCE.md - 详细使用指南，包含完整代码示例
• README_RaySourceOperateView.md - 操作视图使用说明
• 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 第 14 节。

---

许可证 | License

本模块是 XplorePlane 项目的一部分，遵循项目整体许可协议。

---

最后更新 | Last Updated: 2026-03-26