KupaKuper_HMI_Device 3.5.1

IDeviceCore 接口文档

概述

IDeviceCore 接口是设备核心功能的抽象定义，提供了设备配置管理、系统状态监控、数据读写请求以及事件通知等功能。该接口作为设备系统与外部交互的桥梁，规范了设备通信、状态更新和数据交换的标准操作。

快速开始

依赖注入

// 在 Startup.cs 或 Program.cs 中添加服务注册
services.AddDeviceCores();

基本使用示例

// 创建设备配置
var deviceSetting = new DeviceSetting 
{ 
    ConfigPath = "path/to/device/config" 
};

// 实例化设备核心
IDeviceCore deviceCore = new DeviceCore(deviceSetting);

// 订阅连接状态变化事件
deviceCore.EtherConnectChanged += (isConnected) =>
{
    Console.WriteLine($"设备连接状态: {isConnected}");
};

// 订阅设备状态变化事件
deviceCore.DeviceModelChanged += () =>
{
    Console.WriteLine("设备状态已更新");
};

// 订阅报警事件
deviceCore.AlarmTrigger += (deviceId, alarm) =>
{
    Console.WriteLine($"设备 {deviceId} 触发报警: {alarm.Message}");
};

命名空间

namespace KupaKuper_HMI_Device.IDevice

接口成员详解

功能配置

DeviceSetting

DeviceSetting DeviceSetting { get; set; }

• 描述: 获取或设置设备的功能配置信息
• 类型: DeviceSetting
• 访问权限: 读/写
• 配置示例:

var setting = new DeviceSetting
{
    ConfigPath = @"C:\DeviceConfigs\Device1",
    AutoReconnect = true,
    ReconnectInterval = 5000,
    ReadTimeout = 3000,
    WriteTimeout = 3000
};
deviceCore.DeviceSetting = setting;

系统信息

Connected

bool Connected { get; }

• 描述: 获取设备的连接状态
• 返回值: bool，true 表示已连接，false 表示未连接
• 访问权限: 只读
• 使用示例:

if (deviceCore.Connected)
{
    Console.WriteLine("设备已连接");
}
else
{
    Console.WriteLine("设备未连接");
}

DeviceConfig

GetConfig DeviceConfig { get; }

• 描述: 获取设备的配置文件信息
• 返回值: GetConfig 类型的配置对象
• 访问权限: 只读
• 配置内容: 包含设备基本信息、IO配置、轴配置、气缸配置、参数配置等

Ethernet

BaseEthernet? Ethernet { get; }

• 描述: 获取设备的通讯类实例
• 返回值: BaseEthernet 类型的通讯对象，可为 null
• 访问权限: 只读
• 支持的协议: OPC UA、Modbus TCP 等

DeviceSystemModel

SystemConfig? DeviceSystemModel { get; }

• 描述: 获取设备的系统控制信息
• 返回值: SystemConfig 类型的系统配置对象，可为 null
• 访问权限: 只读

CurrentAlarmModels

ObservableCollection<Alarm> CurrentAlarmModels { get; }

• 描述: 获取当前设备的报警信息列表
• 返回值: ObservableCollection<Alarm> 类型的报警集合
• 访问权限: 只读
• 使用示例:

foreach (var alarm in deviceCore.CurrentAlarmModels)
{
    Console.WriteLine($"报警ID: {alarm.Id}, 消息: {alarm.Message}");
}

AxesName

List<string> AxesName { get; }

• 描述: 获取设备所有轴的名称列表
• 返回值: List<string> 类型的轴名称集合
• 访问权限: 只读

AxesModels

Dictionary<string, ObservableCollection<Axis>> AxesModels { get; }

• 描述: 获取设备所有轴的状态数据
• 返回值: 字典，键为轴名称，值为对应轴的状态集合
• 访问权限: 只读
• 使用示例:

foreach (var axisName in deviceCore.AxesName)
{
    var axisData = deviceCore.AxesModels[axisName];
    Console.WriteLine($"轴 {axisName} 有 {axisData.Count} 个状态项");
}

CylindersName

List<string> CylindersName { get; }

• 描述: 获取设备所有气缸组的名称列表
• 返回值: List<string> 类型的气缸组名称集合
• 访问权限: 只读

CylinderModels

Dictionary<string, ObservableCollection<Cylinder>> CylinderModels { get; }

• 描述: 获取设备所有气缸的状态数据
• 返回值: 字典，键为气缸组名称，值为对应气缸组的状态集合
• 访问权限: 只读

IoModels

Dictionary<string, ObservableCollection<Io>> IoModels { get; }

• 描述: 获取设备所有 IO 点的状态数据
• 返回值: 字典，键为 IO 类型（如 "input"、"output"），值为对应 IO 点的状态集合
• 访问权限: 只读
• 使用示例:

var inputIos = deviceCore.IoModels["input"];
var outputIos = deviceCore.IoModels["output"];
Console.WriteLine($"输入IO数量: {inputIos.Count}, 输出IO数量: {outputIos.Count}");

ParametersName

List<string> ParametersName { get; }

• 描述: 获取设备所有参数组的名称列表
• 返回值: List<string> 类型的参数组名称集合
• 访问权限: 只读

ParameterModels

Dictionary<string, ObservableCollection<Parameter>> ParameterModels { get; }

• 描述: 获取设备所有参数的状态数据
• 返回值: 字典，键为参数组名称，值为对应参数组的状态集合
• 访问权限: 只读

KeyValueModels

Dictionary<string, KeyVar> KeyValueModels { get; }

• 描述: 获取设备所有常驻变量的状态数据
• 返回值: 字典，键为变量名称，值为 KeyVar 类型的变量对象
• 访问权限: 只读

事件委托

AlarmTrigger

event Action<string, Alarm>? AlarmTrigger;

• 描述: 当系统读取到新的报警信息时触发
• 参数:
  • 第一个参数 string: 触发报警的设备标识
  • 第二个参数 Alarm: 报警信息对象
• 使用示例:

deviceCore.AlarmTrigger += (deviceId, alarm) =>
{
    // 处理报警逻辑
    LogAlarm(deviceId, alarm);
    ShowAlarmNotification(alarm);
};

EtherConnectChanged

event Action<bool>? EtherConnectChanged;

• 描述: 当设备连接状态发生变化时触发
• 参数: bool 类型，表示新的连接状态（true 表示已连接，false 表示断开连接）
• 使用示例:

deviceCore.EtherConnectChanged += (isConnected) =>
{
    UpdateConnectionStatus(isConnected);
    if (!isConnected)
    {
        StartReconnectionTimer();
    }
};

DeviceModelChanged

event Action? DeviceModelChanged;

• 描述: 当设备状态发生变化时触发。无参数
• 使用示例:

deviceCore.DeviceModelChanged += () =>
{
    // 刷新UI显示
    RefreshDeviceDataDisplay();
};

Error

event Action<string, string>? Error;

• 描述: 当系统执行过程中发生错误时触发，用于显示错误信息
• 参数:
  • 第一个参数 string: 错误来源
  • 第二个参数 string: 错误消息内容
• 使用示例:

deviceCore.Error += (source, message) =>
{
    LogError($"错误来源: {source}, 错误信息: {message}");
    ShowErrorMessage(message);
};

读取请求方法

RequestUpdataIo

void RequestUpdataIo(string RequestId, string IoType, Action? IsUpdata = null);

• 描述: 请求开启更新指定类型的 IO 数据
• 参数:
  • RequestId: 客户端的识别 ID，随机生成即可
  • IoType: IO 类型（如 "input"、"output"）
  • IsUpdata: 更新完成后的回调函数，可为 null
• 使用示例:

string requestId = Guid.NewGuid().ToString();
deviceCore.RequestUpdataIo(requestId, "input", () =>
{
    Console.WriteLine("输入IO数据已更新");
});

RequestUpdataAxis

void RequestUpdataAxis(string RequestId, string AxisName, Action? IsUpdata = null);

• 描述: 请求开启更新指定轴的状态数据
• 参数:
  • RequestId: 客户端的识别 ID，随机生成即可
  • AxisName: 轴的名称，必须存在于 AxesName 列表中
  • IsUpdata: 更新完成后的回调函数，可为 null
• 使用示例:

string requestId = Guid.NewGuid().ToString();
string axisName = deviceCore.AxesName.First();
deviceCore.RequestUpdataAxis(requestId, axisName, () =>
{
    Console.WriteLine($"轴 {axisName} 数据已更新");
});

RequestUpdataCylinders

void RequestUpdataCylinders(string RequestId, string Cylinders, Action? IsUpdata = null);

• 描述: 请求开启更新指定气缸组的状态数据
• 参数:
  • RequestId: 客户端的识别 ID，随机生成即可
  • Cylinders: 气缸组的名称，必须存在于 CylindersName 列表中
  • IsUpdata: 更新完成后的回调函数，可为 null

RequestUpdataParameters

void RequestUpdataParameters(string RequestId, string Parameters, Action? IsUpdata = null);

• 描述: 请求开启更新指定参数组的状态数据
• 参数:
  • RequestId: 客户端的识别 ID，随机生成即可
  • Parameters: 参数组的名称，必须存在于 ParametersName 列表中
  • IsUpdata: 更新完成后的回调函数，可为 null

RemoveUpdataIo

void RemoveUpdataIo(string RequestId, string IoType, Action? IsUpdata = null);

• 描述: 请求关闭指定类型 IO 数据的更新
• 参数:
  • RequestId: 客户端的识别 ID，必须与开启更新时使用的 ID 对应
  • IoType: IO 类型（如 "input"、"output"）
  • IsUpdata: 关闭更新后的回调函数，可为 null

RemoveUpdataAxis

void RemoveUpdataAxis(string RequestId, string AxisName, Action? IsUpdata = null);

• 描述: 请求关闭指定轴状态数据的更新
• 参数:
  • RequestId: 客户端的识别 ID，必须与开启更新时使用的 ID 对应
  • AxisName: 轴的名称，必须存在于 AxesName 列表中
  • IsUpdata: 关闭更新后的回调函数，可为 null

RemoveUpdataCylinders

void RemoveUpdataCylinders(string RequestId, string Cylinders, Action? IsUpdata = null);

• 描述: 请求关闭指定气缸组状态数据的更新
• 参数:
  • RequestId: 客户端的识别 ID，必须与开启更新时使用的 ID 对应
  • Cylinders: 气缸组的名称，必须存在于 CylindersName 列表中
  • IsUpdata: 关闭更新后的回调函数，可为 null

RemoveUpdataParameters

void RemoveUpdataParameters(string RequestId, string Parameters, Action? IsUpdata = null);

• 描述: 请求关闭指定参数组状态数据的更新
• 参数:
  • RequestId: 客户端的识别 ID，必须与开启更新时使用的 ID 对应
  • Parameters: 参数组的名称，必须存在于 ParametersName 列表中
  • IsUpdata: 关闭更新后的回调函数，可为 null

RequestUpataAll

void RequestUpataAll(string RequestId);

• 描述: 请求开启所有数据的读取更新
• 参数: RequestId: 客户端的识别 ID，随机生成即可
• 使用示例:

string requestId = Guid.NewGuid().ToString();
deviceCore.RequestUpataAll(requestId);

RemoveUpdataAll

void RemoveUpdataAll(string RequestId);

• 描述: 请求关闭所有数据的读取更新
• 参数: RequestId: 客户端的识别 ID，必须与开启更新时使用的 ID 对应

ReadAlarmLogAsync

Task<string[]?> ReadAlarmLogAsync(string laguage, DateTime dateTime);

• 描述: 异步获取指定语言和日期的报警日志记录数据
• 参数:
  • laguage: 语言标识
  • dateTime: 目标日期时间
• 返回值: Task<string[]?>，异步操作的结果，包含报警日志记录的字符串数组，可为 null
• 使用示例:

var alarmLogs = await deviceCore.ReadAlarmLogAsync("zh-CN", DateTime.Today);
if (alarmLogs != null)
{
    foreach (var log in alarmLogs)
    {
        Console.WriteLine(log);
    }
}

其他方法

GetT

bool GetT(VarModel mode, string? text, out dynamic value);

• 描述: 将指定的 VarModel 类型的文本值转换为对应的数据类型
• 参数:
  • mode: 变量模式，指定要转换的目标数据类型
  • text: 要转换的文本值，可为 null
  • value: 输出参数，转换后的动态类型值
• 返回值: bool，表示转换是否成功
• 使用示例:

if (deviceCore.GetT(VarModel.Int, "123", out dynamic result))
{
    Console.WriteLine($"转换成功: {result}");
}

AddDeviceLogItem

void AddDeviceLogItem(string logMessage);

• 描述: 向设备日志队列中添加一条日志记录
• 参数: logMessage: 日志消息内容
• 使用示例:

deviceCore.AddDeviceLogItem("设备初始化完成");

高级使用场景

多设备管理

// 使用 DeviceCores 类管理多个设备
var deviceCores = new DeviceCores();
var deviceSettings = new List<DeviceSetting>
{
    new DeviceSetting { ConfigPath = @"C:\DeviceConfigs\Device1" },
    new DeviceSetting { ConfigPath = @"C:\DeviceConfigs\Device2" }
};

if (deviceCores.InitializeDevice(deviceSettings))
{
    // 获取特定设备
    var device1 = deviceCores.TryChangeDevice("Device1");
    var device2 = deviceCores.TryChangeDevice("Device2");
    
    // 分别管理设备
    device1?.RequestUpdataAll(Guid.NewGuid().ToString());
    device2?.RequestUpdataAll(Guid.NewGuid().ToString());
}

数据更新管理

// 创建唯一的请求ID
string ioRequestId = Guid.NewGuid().ToString();
string axisRequestId = Guid.NewGuid().ToString();

// 请求数据更新
deviceCore.RequestUpdataIo(ioRequestId, "input", () =>
{
    // IO数据更新完成后的处理
    UpdateInputDisplay();
});

deviceCore.RequestUpdataAxis(axisRequestId, "X轴", () =>
{
    // 轴数据更新完成后的处理
    UpdateAxisPositionDisplay();
});

// 在适当的时候关闭更新
deviceCore.RemoveUpdataIo(ioRequestId, "input");
deviceCore.RemoveUpdataAxis(axisRequestId, "X轴");

错误处理策略

// 订阅错误事件
deviceCore.Error += (source, message) =>
{
    // 记录错误日志
    LogError($"[{DateTime.Now}] {source}: {message}");
    
    // 根据错误类型采取不同措施
    if (message.Contains("连接失败"))
    {
        // 尝试重新连接
        AttemptReconnection();
    }
    else if (message.Contains("数据读取失败"))
    {
        // 重试读取操作
        RetryReadOperation();
    }
};

配置说明

设备配置文件结构

设备配置文件应包含以下主要部分：

• device.DeviceMessage: 设备基本信息（设备类型、地址等）
• device.IoConfig: IO配置（输入输出点）
• device.AxesConfig: 轴配置
• device.CylindersConfig: 气缸配置
• device.ParametersConfig: 参数配置
• device.SystemConfig: 系统配置
• device.AlarmsConfig: 报警配置

配置文件示例

{
    "device": {
        "DeviceMessage": {
            "DeviceName": "设备1",
            "DeviceType": "OpcUa",
            "DeviceAddress": "opc.tcp://localhost:4840"
        },
        "IoConfig": {
            "InputIoList": [...],
            "OutputIoList": [...]
        },
        "AxesConfig": {
            "AxisList": [...]
        }
    }
}

最佳实践

1. 连接管理: 始终检查 Connected 属性后再进行数据操作
2. 资源释放: 使用完设备后调用 RemoveUpdataAll 释放资源
3. 错误处理: 订阅 Error 事件进行统一的错误处理
4. 异步操作: 对于耗时操作使用异步方法
5. 日志记录: 利用 AddDeviceLogItem 记录关键操作

常见问题

Q: 如何判断设备是否支持某种通讯协议？

A: 检查 DeviceConfig.device.DeviceMessage.DeviceType 属性

Q: 数据更新频率如何控制？

A: 通过 DeviceSetting 中的配置参数控制，如 ReadInterval

Q: 如何处理设备断开连接的情况？

A: 订阅 EtherConnectChanged 事件，在连接断开时进行相应处理

Q: 如何获取特定类型的数据？

A: 使用对应的 Models 属性，如 IoModels["input"] 获取输入IO数据

性能优化建议

1. 按需更新: 只请求需要的数据类型，避免不必要的资源消耗
2. 批量操作: 使用 RequestUpataAll 和 RemoveUpdataAll 进行批量管理
3. 事件处理: 合理使用事件回调，避免频繁的轮询操作
4. 内存管理: 及时释放不再使用的数据更新请求

版本信息

• 当前版本: 1.0
• 最后更新: 2024年
• 兼容性: .NET 6.0+

---

本文档基于实际代码实现编写，如有疑问请参考源代码或联系开发团队。