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、Hamamatsu MFX 系列）
• Comet 225：基于 Named Pipe IPC 的进程隔离架构（.NET 8 主进程 ↔ .NET Framework 4.8 Host 进程）
• Hamamatsu MFX：基于 RS-232 串口直连的单进程架构（.NET 8 同进程内通讯）
• 完整的设备生命周期管理（初始化、连接变量、暖机、训机、灯丝校准、自动定心、开关射线）
• 一键初始化：按设备能力自动编排暖机→训机→灯丝校准流程，含倒计时确认窗口
• 精确的电压电流控制（范围由配置文件定义）
• 实时状态监控和错误检测
• 基于 Prism 事件聚合器的松耦合跨模块通讯
• 安全机制：紧急关闭优先级、参数范围验证
• 灯丝寿命管理：使用时长记录、累计统计、预警提醒
• TXI 开关控制、功率模式切换（Micro Focus / High Power）
• Hamamatsu 焦斑模式控制（Small / Middle / Large）
• 完整的日志记录和异常处理

---

框架架构 | Architecture

XP.Hardware.RaySource/
├── Abstractions/              # 抽象层 | Abstraction Layer
│   ├── IXRaySource.cs        # 策略接口（同步方法）
│   ├── XRaySourceBase.cs     # 抽象基类（含能力查询 GetSupportedInitSteps）
│   ├── XRayResult.cs         # 结果封装类
│   ├── IRaySourceFactory.cs  # 工厂接口
│   ├── OneClickInitStep.cs   # 一键初始化步骤枚举（WarmUp/Training/FilamentCalibration）
│   ├── 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 客户端
│   ├── SimulatedXRaySource.cs  # 模拟射线源实现（开发调试用）
│   └── Hamamatsu/            # Hamamatsu MFX 系列实现
│       ├── HamamatsuRaySource.cs      # Hamamatsu MFX 策略实现（IXRaySource）
│       ├── HamamatsuSerialClient.cs   # RS-232 串口通讯客户端
│       ├── HamamatsuStatusPoller.cs   # 后台状态轮询器（SAR/SNR）
│       ├── HamamatsuDeviceInfo.cs     # 设备型号数据库和参数匹配
│       └── HamamatsuSelfTestResult.cs # 自检结果数据模型
├── Factories/                 # 工厂层 | Factory Layer
│   └── RaySourceFactory.cs   # 射线源工厂
├── Services/                  # 业务服务层 | Service Layer
│   ├── IRaySourceService.cs  # 服务接口（含 OneClickInitializeAsync）
│   ├── RaySourceService.cs   # 服务实现（单例，含一键初始化编排）
│   ├── IFilamentLifetimeService.cs  # 灯丝寿命服务接口
│   ├── FilamentLifetimeService.cs   # 灯丝寿命服务实现
│   ├── OneClickInitProgress.cs      # 一键初始化进度模型
│   └── OperationProgressCalculator.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 接口定义统一操作，支持多种设备实现（Comet225RaySource、HamamatsuRaySource）
• 工厂模式：IRaySourceFactory 根据设备类型动态创建实例（支持 "Comet225"、"Hamamatsu"）
• 适配器模式：Comet225RaySource 将 IPC 通信适配为 IXRaySource 接口
• 进程隔离：通过 CometHostManager + CometIpcClient 实现 .NET 8 与 .NET Framework 4.8 的跨框架通信（仅 Comet）
• 直连模式：HamamatsuRaySource 通过 HamamatsuSerialClient 在同进程内直接与设备通讯
• 模板方法模式：XRaySourceBase 提供基础实现框架
• 单例模式：IRaySourceService、IFilamentLifetimeService 作为全局单例
• 依赖注入：通过 Prism 容器管理服务生命周期
• 事件聚合器：使用 Prism IEventAggregator 实现松耦合通讯

IPC 进程隔离架构 | IPC Process Isolation Architecture (Comet 225)

┌──────────────────────────────────────────────────────────────────────┐
│                    .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 变量）                         │
└──────────────────────────────────────────────────────────────────────┘

串口直连架构 | Serial Direct Connection Architecture (Hamamatsu MFX)

┌──────────────────────────────────────────────────────────────────────┐
│                    .NET 8 主进程 (XP.Hardware.RaySource)              │
│                                                                      │
│  ViewModel → RaySourceService → HamamatsuRaySource                   │
│                                      │                               │
│                         HamamatsuSerialClient（RS-232 串口通讯）      │
│                         HamamatsuStatusPoller（SAR/SNR 状态轮询）     │
│                         HamamatsuDeviceInfo（型号匹配+功率限制）      │
│                                      │                               │
│                              COM Port（38400, 8N1, 无流控）           │
└──────────────────────────────┬───────────────────────────────────────┘
                               │ RS-232 串口
                    ┌──────────┴──────────┐
                    │  Hamamatsu MFX 设备  │
                    └─────────────────────┘

---

核心功能 | 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. 一键初始化 | One-Click Initialization

// 查询当前射线源支持的初始化步骤
OneClickInitStep[] steps = _raySourceService.GetSupportedInitSteps();

// 执行一键初始化（暖机→训机→灯丝校准，按设备能力自动编排）
// 每步操作前弹出 5 秒倒计时确认窗口，可取消
XRayResult result = await _raySourceService.OneClickInitializeAsync(progress, cancellationToken);

4. 设备操作 | Device Operations

// TXI 开启/关闭
_raySourceService.TxiOn();
_raySourceService.TxiOff();

// 暖机
_raySourceService.WarmUp();

// 训机
_raySourceService.Training();

// 灯丝校准
_raySourceService.FilamentCalibration();

// 全部电压自动定心
_raySourceService.AutoCenter();

// 设置功率模式（1=Micro Focus，2=High Power）
_raySourceService.SetPowerMode(1);

5. 状态监控 | Status Monitoring

// 读取系统状态
_raySourceService.ReadSystemStatus();

// 检查错误
_raySourceService.CheckErrors();

// 清除错误
_raySourceService.ClearErrors();

// 检查状态属性
bool isInitialized = _raySourceService.IsInitialized;
bool isConnected = _raySourceService.IsConnected;
bool isXRayOn = _raySourceService.IsXRayOn;
RaySourceStatus status = _raySourceService.CurrentStatus;

6. 灯丝寿命管理 | Filament Lifetime Management

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

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

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

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

7. 事件通讯 | 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	射线源类型（Comet225 / Hamamatsu / Simulated）
PlcIpAddress	string	192.168.12.10	PLC IP 地址（Comet 专用）
PlcPort	int	11159	PLC 端口号（Comet 专用）
StationNumber	int	1	源站号（Comet 专用）
PortNumber	int	11	源端口号（Comet 专用）
CpuName	string	cpu	CPU 名称（Comet 专用）
ConnectionTimeout	int	5000	连接超时（毫秒）
MinVoltage	float	20	最小电压（kV）
MaxVoltage	float	225	最大电压（kV）
MinCurrent	float	10	最小电流（μA）
MaxCurrent	float	1000	最大电流（μA）
ComPort	string	空（全端口扫描）	Hamamatsu 串口名称（格式 COMn，n=1-256）
PollingInterval	int	500	Hamamatsu 状态轮询间隔（100-10000ms）
AdvanceExePath	string	FXEControl.exe 路径	高级设置外部程序路径
HostExePath	string	空（自动查找）	Host 进程可执行文件路径（Comet 专用）
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

初始化失败（Comet 225）

• 检查 Host 进程可执行文件是否存在（默认路径：{主程序目录}/Host/XP.Hardware.RaySource.Comet.Host.exe）
• 检查 PLC IP 地址和端口配置
• 确认 PLC 网络连接正常
• 查看日志中 Named Pipe 连接状态

初始化失败（Hamamatsu MFX）

• 检查 ComPort 配置是否正确（格式 COMn，n=1-256）
• 确认串口未被其他程序占用
• 检查 RS-232 线缆连接是否正常
• 若 ComPort 为空，系统会自动扫描所有可用串口
• 查看日志中设备验证响应（期望 "ERR 0 NOC"）

射线无法开启

• 确认已成功初始化并连接变量（IsInitialized && IsConnected）
• 检查设备错误状态
• 验证互锁信号
• Hamamatsu：检查设备状态码（STS 必须为 2=Standby）

电压电流设置失败

• 验证参数在配置文件定义的有效范围内
• 确认射线源已初始化
• Comet：检查 IPC 管道连接状态
• Hamamatsu：检查功率限制（电压×电流≤当前焦斑模式最大功率）

Host 进程异常（Comet 专用）

• 检查 Host 进程是否正常启动（查看日志中 PID 信息）
• 确认 BR.AN.PviServices.dll 已正确部署到 Host 目录
• 检查是否有残留的 Host 进程（CometHostManager 会自动清理）

Hamamatsu 设备断连

• 检查串口线缆物理连接
• 查看日志中连续轮询失败次数（连续 2 次失败判定为断连）
• 确认设备电源正常

详细故障排查请参考 GUIDENCE.md 第 14 节。

---

许可证 | License

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

---

最后更新 | Last Updated: 2026-07-06