KupaKuper_HMI_DeviceServer 3.5.1

DeviceServer 系统文档

概述

DeviceServer 系统提供了完整的设备管理和消息通知框架，包含 IDeviceSystems 和 IDeviceSystemServer 两个核心接口。该系统作为设备管理与用户界面之间的桥梁，实现了多设备管理、消息通知、弹窗交互、用户权限控制等功能。

快速开始

依赖注入

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

基本使用示例

// 创建设备系统服务器
var deviceServer = new DeviceSystemServer();

// 初始化设备系统
var deviceSystems = new DeviceSystems();
// 配置设备系统...

deviceServer.SystemSevers = deviceSystems;

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

// 订阅设备切换事件
deviceServer.DeviceChanged += () =>
{
    Console.WriteLine("设备已切换");
};

// 订阅主题变化事件
deviceServer.ThemeChanged += (isDark) =>
{
    Console.WriteLine($"主题已切换为: {(isDark ? "深色" : "浅色")}");
};

IDeviceSystems 接口

接口概述

IDeviceSystems 接口定义了设备系统的核心功能，包括设备配置管理、消息通知、弹窗交互等。它作为设备系统与外部交互的桥梁，提供了统一的接口来处理设备连接状态变化、消息显示和用户交互等功能。

命名空间

namespace KupaKuper_DeviceSever.Server

接口成员详解

属性

DeviceCores

DeviceCores? DeviceCores { get; set; }

• 描述: 获取或设置设备配置文件，包含配置信息、配置信息语言包以及自动通讯和变量信息请求功能
• 类型: DeviceCores
• 访问权限: 读/写
• 使用示例:

var deviceCores = new DeviceCores();
// 初始化设备...
deviceSystems.DeviceCores = deviceCores;

AlarmPageName

string? AlarmPageName { get; set; }

• 描述: 报警页面的名称，用于报警消息的跳转
• 类型: string
• 访问权限: 读/写
• 使用示例:

deviceSystems.AlarmPageName = "AlarmPage";

CurrentShowPopup

Dictionary<string, (string, KeyVar, Device)> CurrentShowPopup { get; set; }

• 描述: 当前正在显示的弹窗集合
• 类型: 字典，键为弹窗标识符，值为包含标题、键变量和设备信息的元组
• 访问权限: 读/写

事件

ConnectChanged

event Action<bool>? ConnectChanged;

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

deviceSystems.ConnectChanged += (isConnected) =>
{
    UpdateConnectionStatus(isConnected);
    if (!isConnected)
    {
        ShowReconnectionDialog();
    }
};

ShowError

event Action<string, string, string?>? ShowError;

• 描述: 显示错误消息的委托
• 参数:
  • 第一个参数 string: 消息发送人
  • 第二个参数 string: 消息内容
  • 第三个参数 string?: 消息溯源页面名称，可为 null
• 使用示例:

deviceSystems.ShowError += (sender, message, viewName) =>
{
    LogError($"[{sender}] {message} (视图: {viewName ?? "未知"})");
    ShowErrorMessageDialog(message);
};

ShowInfo

event Action<string, string, string?>? ShowInfo;

• 描述: 显示提示消息的委托
• 参数: 与 ShowError 相同

ShowWarning

event Action<string, string, string?>? ShowWarning;

• 描述: 显示警告消息的委托
• 参数: 与 ShowError 相同

ShowSuccess

event Action<string, string, string?>? ShowSuccess;

• 描述: 显示成功消息的委托
• 参数: 与 ShowError 相同

ShowDisplay

event Action<string, string, Action<bool>?>? ShowDisplay;

• 描述: 显示确认型消息弹窗的委托
• 参数:
  • 第一个参数 string: 消息发送人
  • 第二个参数 string: 消息内容
  • 第三个参数 Action<bool>?: 执行的方法，接收一个 bool 参数，可为 null

ShowConfirmation

event Action<string, string, Action<bool>?>? ShowConfirmation;

• 描述: 显示判断型消息弹窗的委托
• 参数: 与 ShowDisplay 相同

ShowInput

event Action<string, string, Action<string>?>? ShowInput;

• 描述: 显示输入型消息弹窗的委托
• 参数:
  • 第一个参数 string: 消息发送人
  • 第二个参数 string: 消息内容
  • 第三个参数 Action<string>?: 执行的方法，接收一个 string 参数，可为 null

ShowChoose

event Action<string, string, List<string>, Action<string>?>? ShowChoose;

• 描述: 显示选择型弹窗的委托
• 参数:
  • 第一个参数 string: 消息发送人
  • 第二个参数 string: 消息内容
  • 第三个参数 List<string>: 选择项列表
  • 第四个参数 Action<string>?: 执行的方法，接收一个 string 参数，可为 null

CleanModal

event Action? CleanModal;

• 描述: 清除弹窗的委托。无参数

PopupsInstance

event Action<string, KeyVar, Device>? PopupsInstance;

• 描述: 弹窗触发初始化配置的委托
• 参数:
  • 第一个参数 string: 弹窗标识符
  • 第二个参数 KeyVar: 键变量
  • 第三个参数 Device: 设备信息

ShowAlarmCornerMarkers

event Action<int>? ShowAlarmCornerMarkers;

• 描述: 显示报警消息角标的委托
• 参数: int 类型，表示角标显示的数量

ShowAlarmPopup

event Action<string, string, string?>? ShowAlarmPopup;

• 描述: 设备报警触发的消息的委托
• 参数: 与 ShowError 相同

方法

RequestToSendError

void RequestToSendError(string requestDeviecName, string message, string? errorViewName = null);

• 描述: 请求给所有注册过错误消息的客户端发送错误信息
• 参数:
  • requestDeviecName: 请求设备名称
  • message: 错误消息内容
  • errorViewName: 错误视图名称，可为 null
• 使用示例:

deviceSystems.RequestToSendError("Device1", "连接失败，请检查网络", "HomeView");

RequestToSendInfo

void RequestToSendInfo(string requestDeviecName, string message, string? errorViewName = null);

• 描述: 请求给所有注册过提示消息的客户端发送提示信息
• 参数: 与 RequestToSendError 相同

RequestToSendWarning

void RequestToSendWarning(string requestDeviecName, string message, string? errorViewName = null);

• 描述: 请求给所有注册过警告消息的客户端发送警告信息
• 参数: 与 RequestToSendError 相同

RequestToSendSuccess

void RequestToSendSuccess(string requestDeviecName, string message, string? errorViewName = null);

• 描述: 请求给所有注册过成功消息的客户端发送成功信息
• 参数: 与 RequestToSendError 相同

RequestToSetAlarmCornerMarkers

void RequestToSetAlarmCornerMarkers(int n);

• 描述: 请求给所有注册过报警角标显示的客户端发送角标显示数量
• 参数: n 表示角标显示的数量

RequestToSendDisplay

void RequestToSendDisplay(string titl, string message, Action<bool> EndVoid);

• 描述: 请求给所有注册过确认型弹窗的客户端发送弹窗消息
• 参数:
  • titl: 弹窗标题
  • message: 弹窗消息内容
  • EndVoid: 弹窗关闭后执行的方法，接收一个 bool 参数

RequestToSendConfirmation

void RequestToSendConfirmation(string titl, string message, Action<bool> EndVoid);

• 描述: 请求给所有注册过判断型弹窗的客户端发送弹窗消息
• 参数: 与 RequestToSendDisplay 相同

RequestToSendInput

void RequestToSendInput(string titl, string message, Action<string> EndVoid);

• 描述: 请求给所有注册过输入型弹窗的客户端发送弹窗消息
• 参数:
  • titl: 弹窗标题
  • message: 弹窗消息内容
  • EndVoid: 用户输入后执行的方法，接收一个 string 参数

RequestToSendChoose

void RequestToSendChoose(string titl, string message, List<string> chooseData, Action<string> EndVoid);

• 描述: 请求给所有注册过选择型弹窗的客户端发送弹窗消息
• 参数:
  • titl: 弹窗标题
  • message: 弹窗消息内容
  • chooseData: 选择项列表
  • EndVoid: 用户选择后执行的方法，接收一个 string 参数

IDeviceSystemServer 接口

接口概述

IDeviceSystemServer 接口提供了设备系统服务器的完整功能，包括用户权限管理、设备切换、主题切换、语言切换等高级功能。

命名空间

namespace KupaKuper_DeviceSever.Server

接口成员详解

用户权限管理

UserType

public enum UserType
{
    Operator,    // 操作员
    Engineer,    // 工程师
    Admin        // 管理员
}

CurrentUserType

UserType CurrentUserType { get; }

• 描述: 获取当前用户类型
• 访问权限: 只读

ChangeUserType

void ChangeUserType(UserType userType);

• 描述: 更改用户类型
• 参数: userType - 目标用户类型

设备管理

CurrentDeviecName

string CurrentDeviecName { get; set; }

• 描述: 获取或设置当前设备名称
• 访问权限: 读/写

DeviceNameList

List<string> DeviceNameList { get; }

• 描述: 获取已加载的设备名称列表
• 访问权限: 只读

CurrentDevice

IDeviceCore CurrentDevice { get; }

• 描述: 获取当前显示设备数据
• 访问权限: 只读

SystemSevers

DeviceSystems SystemSevers { get; }

• 描述: 获取设备服务器数据
• 访问权限: 只读

主题和语言

ThemeIsDark

bool ThemeIsDark { get; set; }

• 描述: 获取或设置当前主题是否为深色模式
• 访问权限: 读/写

Language

string Language { get; set; }

• 描述: 获取或设置当前语言
• 访问权限: 读/写

LanguageType

Dictionary<string, string> LanguageType { get; set; }

• 描述: 获取或设置可选语言类型
• 访问权限: 读/写

事件

ConnectedChanged

event Action<bool>? ConnectedChanged;

• 描述: 连接状态改变时触发

LanguageChanged

event Action<string>? LanguageChanged;

• 描述: 语言切换触发事件

ThemeChanged

event Action<bool>? ThemeChanged;

• 描述: 主题切换触发事件

DeviceChanged

event Action? DeviceChanged;

• 描述: 设备切换事件-切换设备后

BeforeDeviceChanged

event Action? BeforeDeviceChanged;

• 描述: 设备切换事件-切换设备前

UserChanged

event Action<UserType>? UserChanged;

• 描述: 用户类型切换触发事件

UpdataMainPage

event Action? UpdataMainPage;

• 描述: 绑定主页面刷新事件

JumpPage

event Action<string, string?>? JumpPage;

• 描述: 跳转到指定设备的指定页面

UpdataAlarmCornerMarkers

event Action? UpdataAlarmCornerMarkers;

• 描述: 绑定主页面角标刷新事件

高级使用场景

多设备管理

// 创建设备系统服务器
var deviceServer = new DeviceSystemServer();

// 初始化设备系统
var deviceSystems = new DeviceSystems();
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))
{
    deviceSystems.DeviceCores = deviceCores;
    deviceServer.SystemSevers = deviceSystems;
    
    // 设置默认设备
    deviceServer.CurrentDeviecName = deviceServer.DeviceNameList.First();
    
    // 订阅设备切换事件
    deviceServer.DeviceChanged += () =>
    {
        Console.WriteLine($"已切换到设备: {deviceServer.CurrentDeviecName}");
        RefreshDeviceDisplay();
    };
}

消息通知系统

// 配置消息通知
deviceSystems.ShowError += (sender, message, viewName) =>
{
    // 记录错误日志
    LogError($"[{DateTime.Now}] {sender}: {message}");
    
    // 显示错误对话框
    ShowErrorDialog(message, viewName);
};

deviceSystems.ShowSuccess += (sender, message, viewName) =>
{
    // 显示成功提示
    ShowSuccessToast(message);
};

// 发送消息通知
deviceSystems.RequestToSendError("Device1", "设备连接失败", "HomeView");
deviceSystems.RequestToSendSuccess("Device1", "操作执行成功", "SettingsView");

弹窗交互系统

// 配置弹窗交互
deviceSystems.ShowConfirmation += (sender, message, callback) =>
{
    // 显示确认对话框
    ShowConfirmationDialog(sender, message, (result) =>
    {
        // 用户选择后的回调
        callback?.Invoke(result);
    });
};

deviceSystems.ShowInput += (sender, message, callback) =>
{
    // 显示输入对话框
    ShowInputDialog(sender, message, (inputValue) =>
    {
        // 用户输入后的回调
        callback?.Invoke(inputValue);
    });
};

// 发送弹窗消息
deviceSystems.RequestToSendConfirmation(
    "确认操作",
    "您确定要执行此操作吗？",
    (result) =>
    {
        if (result)
        {
            Console.WriteLine("用户确认了操作");
            ExecuteOperation();
        }
        else
        {
            Console.WriteLine("用户取消了操作");
        }
    }
);

用户权限管理

// 检查用户权限
if (deviceServer.CurrentUserType == UserType.Admin)
{
    // 管理员权限操作
    EnableAdminFeatures();
}
else if (deviceServer.CurrentUserType == UserType.Engineer)
{
    // 工程师权限操作
    EnableEngineerFeatures();
}
else
{
    // 操作员权限操作
    EnableOperatorFeatures();
}

// 切换用户类型
deviceServer.ChangeUserType(UserType.Engineer);

// 订阅用户类型变化事件
deviceServer.UserChanged += (userType) =>
{
    Console.WriteLine($"用户类型已切换为: {userType}");
    UpdateUIForUserType(userType);
};

主题和语言切换

// 配置主题切换
deviceServer.ThemeChanged += (isDark) =>
{
    ApplyTheme(isDark);
    SaveThemePreference(isDark);
};

// 配置语言切换
deviceServer.LanguageChanged += (language) =>
{
    ApplyLanguage(language);
    SaveLanguagePreference(language);
};

// 切换主题和语言
deviceServer.ThemeIsDark = true; // 切换到深色主题
deviceServer.Language = "zh-CN"; // 切换到中文

最佳实践

1. 设备管理

• 设备初始化: 在应用启动时初始化所有设备配置
• 设备切换: 使用 DeviceChanged 事件处理设备切换逻辑
• 资源管理: 及时释放不再使用的设备资源

2. 消息通知

• 统一处理: 集中处理所有类型的消息通知
• 用户友好: 根据消息类型提供不同的显示方式
• 日志记录: 记录重要的消息通知用于调试

3. 弹窗交互

• 异步处理: 弹窗操作应使用异步方式处理
• 用户反馈: 提供明确的用户操作反馈
• 错误处理: 处理弹窗操作中的异常情况

4. 权限管理

• 权限检查: 在执行敏感操作前检查用户权限
• 界面适配: 根据用户权限动态调整界面元素
• 安全审计: 记录重要的权限变更操作

5. 性能优化

• 事件管理: 合理管理事件订阅，避免内存泄漏
• 资源释放: 及时取消不再需要的事件订阅
• 异步操作: 使用异步方法处理耗时操作

常见问题

Q: 如何添加新的设备？

A: 通过 DeviceCores.InitializeDevice() 方法添加设备配置，然后设置到 DeviceSystems.DeviceCores 属性

Q: 如何实现多语言支持？

A: 使用 LanguageChanged 事件和 Language 属性来管理语言切换

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

A: 订阅 ConnectChanged 事件，在连接断开时进行重连或提示用户

Q: 如何实现用户权限控制？

A: 使用 CurrentUserType 属性和 ChangeUserType() 方法来管理用户权限

Q: 如何发送自定义消息？

A: 使用相应的 RequestToSend* 方法发送不同类型的消息

配置说明

软件配置文档

各平台路径详情表

平台	路径示例	适用场景	是否需要权限
Windows	C:\Users\[用户]\Documents\KupaKuper_HMI	桌面用户文档	无需
Android	/data/data/[包名]/files/KupaKuper_HMI	应用私有数据	无需
iOS	~/Documents/KupaKuper_HMI	应用沙盒数据	无需
macOS	~/Documents/KupaKuper_HMI	用户文档数据	无需
Linux	~/HmiConfig/KupaKuper_HMI	用户配置文件	无需
Tizen	/opt/usr/apps/[包名]/data/KupaKuper_HMI	应用数据	无需

配置文件说明

• Language: 软件本体需要使用的多语言配置文件
• AppConfig.json: 关键的软件配置，包含设备配置文件地址和相关系统配置
• AppConfigTemplate.json: 自动生成的配置文件模板
• AppGlobalParameter.json: 软件中需要使用的全局配置参数，由程序生成，可手动修改

设备配置文档

设备配置地址由上述的 AppConfig 中的 ConfigPath 参数决定：

"ConfigPath": "D:\\KupaKuper_HMI\\DeviceMode\\测试设备4"

注意: 设备配置地址为文件夹，以 Config.json 所在文件夹为准

设备配置结构

• DeviceLog: 设备配置中设置的设备 log 记录存储地址，该 log 为软件运行 log
• LocaLization: 多语言包配置
  • Packages: 设备配置的多语言包，可由工具生成
  • dictionary.csv: 配置多语言包的表格，填写完成后可在工具中生成语言包
  • UserLanguage.txt: 默认语言设置，无需更改
• Config.json: 主要的设备配置文档，由工具生成
• Config.xlsx: 生成配置文档需要的配置表格，填写好配置表格后可由工具生成 Config.json 文档
• GantryConfig.json: 配置设备龙门的文档，可修改配置来将多个轴显示在龙门操作界面
• LoginConfig.json: 配置设备登入密码的文档，内容加密，需要修改请在软件中设置

版本信息

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

---

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