IO-Control-API.md 13.8 KB

原文件审查历史永久链接



IO控制 API 文档


1. 概述

本文档详细介绍了 SISO 系统中 IO 控制相关的 API 接口，包括 IO 管理器接口、IO 信号读写方法、状态监控以及相关数据结构。这些 API 提供了对系统输入输出信号的统一管理和控制功能。


2. IO管理器接口


2.1 I_IOManager 接口

I_IOManager 是 IO 控制模块的核心接口，定义了对 IO 信号进行管理和操作的基本方法。

public interface I_IOManager
{
    #region 初始化与关闭

    /// <summary>
    /// 初始化IO管理器
    /// </summary>
    /// <returns>初始化是否成功</returns>
    bool Initialize();

    /// <summary>
    /// 使用指定配置初始化IO管理器
    /// </summary>
    /// <param name="configPath">配置文件路径</param>
    /// <returns>初始化是否成功</returns>
    bool Initialize(string configPath);

    /// <summary>
    /// 关闭IO管理器，释放资源
    /// </summary>
    void Close();

    #endregion

    #region 单个IO操作

    /// <summary>
    /// 读取输入信号状态
    /// </summary>
    /// <param name="ioId">IO点ID</param>
    /// <returns>IO点状态，true表示信号有效，false表示信号无效</returns>
    bool ReadInput(int ioId);

    /// <summary>
    /// 写入输出信号状态
    /// </summary>
    /// <param name="ioId">IO点ID</param>
    /// <param name="value">要写入的状态值，true表示信号有效，false表示信号无效</param>
    /// <returns>写入是否成功</returns>
    bool WriteOutput(int ioId, bool value);

    /// <summary>
    /// 切换输出信号状态
    /// </summary>
    /// <param name="ioId">IO点ID</param>
    /// <returns>切换是否成功</returns>
    bool ToggleOutput(int ioId);

    #endregion

    #region 批量IO操作

    /// <summary>
    /// 批量读取输入信号状态
    /// </summary>
    /// <param name="ioIds">要读取的IO点ID列表</param>
    /// <returns>IO点ID与状态值的映射字典</returns>
    Dictionary<int, bool> ReadInputs(List<int> ioIds);

    /// <summary>
    /// 批量写入输出信号状态
    /// </summary>
    /// <param name="ioValues">IO点ID与要写入状态值的映射字典</param>
    /// <returns>写入是否全部成功</returns>
    bool WriteOutputs(Dictionary<int, bool> ioValues);

    /// <summary>
    /// 读取所有输入信号状态
    /// </summary>
    /// <returns>所有输入IO点ID与状态值的映射字典</returns>
    Dictionary<int, bool> ReadAllInputs();

    /// <summary>
    /// 读取所有输出信号状态
    /// </summary>
    /// <returns>所有输出IO点ID与状态值的映射字典</returns>
    Dictionary<int, bool> ReadAllOutputs();

    #endregion

    #region IO信息获取

    /// <summary>
    /// 获取所有IO点信息
    /// </summary>
    /// <returns>IO点信息列表</returns>
    List<IOInfo> GetAllIOs();

    /// <summary>
    /// 根据IO点ID获取IO点信息
    /// </summary>
    /// <param name="ioId">IO点ID</param>
    /// <returns>IO点信息对象，如果未找到返回null</returns>
    IOInfo GetIOInfo(int ioId);

    /// <summary>
    /// 根据IO点名获取IO点信息
    /// </summary>
    /// <param name="ioName">IO点名</param>
    /// <returns>IO点信息对象，如果未找到返回null</returns>
    IOInfo GetIOInfoByName(string ioName);

    #endregion

    #region IO映射

    /// <summary>
    /// 根据IO点名获取IO点ID
    /// </summary>
    /// <param name="ioName">IO点名</param>
    /// <returns>IO点ID，如果未找到返回-1</returns>
    int GetIOIdByName(string ioName);

    /// <summary>
    /// 根据IO点ID获取IO点名
    /// </summary>
    /// <param name="ioId">IO点ID</param>
    /// <returns>IO点名，如果未找到返回空字符串</returns>
    string GetIONameById(int ioId);

    #endregion

    #region 事件处理

    /// <summary>
    /// 注册IO状态变化事件处理器
    /// </summary>
    /// <param name="ioId">IO点ID，传入-1表示监听所有IO点变化</param>
    /// <param name="handler">事件处理函数，参数为IO点ID和新状态值</param>
    void RegisterIOChangeHandler(int ioId, Action<int, bool> handler);

    /// <summary>
    /// 注销IO状态变化事件处理器
    /// </summary>
    /// <param name="ioId">IO点ID，传入-1表示注销所有IO点的处理器</param>
    /// <param name="handler">事件处理函数，如果为null则注销该IO点的所有处理器</param>
    void UnregisterIOChangeHandler(int ioId, Action<int, bool> handler = null);

    #endregion

    #region 高级功能

    /// <summary>
    /// 设置输出点闪烁
    /// </summary>
    /// <param name="ioId">IO点ID</param>
    /// <param name="onTimeMs">亮的时间（毫秒）</param>
    /// <param name="offTimeMs">灭的时间（毫秒）</param>
    /// <param name="repeatCount">闪烁次数，0表示无限循环</param>
    /// <returns>设置是否成功</returns>
    bool BlinkOutput(int ioId, int onTimeMs, int offTimeMs, int repeatCount = 0);

    /// <summary>
    /// 停止输出点闪烁
    /// </summary>
    /// <param name="ioId">IO点ID，传入-1表示停止所有闪烁的输出点</param>
    /// <returns>停止是否成功</returns>
    bool StopBlinkOutput(int ioId = -1);

    /// <summary>
    /// 延时输出
    /// </summary>
    /// <param name="ioId">IO点ID</param>
    /// <param name="value">要写入的状态值</param>
    /// <param name="delayMs">延时时间（毫秒）</param>
    /// <returns>设置是否成功</returns>
    bool DelayedWriteOutput(int ioId, bool value, int delayMs);

    #endregion
}


3. 数据结构


3.1 IOInfo 类

IOInfo 类用于表示 IO 点的属性和配置信息。

public class IOInfo
{
    /// <summary>
    /// IO点ID
    /// </summary>
    public int Id { get; set; }

    /// <summary>
    /// IO点名
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// IO点类型（输入/输出）
    /// </summary>
    public IOType Type { get; set; }

    /// <summary>
    /// IO点描述
    /// </summary>
    public string Description { get; set; }

    /// <summary>
    /// 物理地址
    /// </summary>
    public string PhysicalAddress { get; set; }

    /// <summary>
    /// 是否反转（取反）
    /// </summary>
    public bool IsInverted { get; set; }

    /// <summary>
    /// 默认值
    /// </summary>
    public bool DefaultValue { get; set; }

    /// <summary>
    /// 是否是安全相关IO
    /// </summary>
    public bool IsSafetyRelated { get; set; }

    /// <summary>
    /// 当前值（仅用于信息展示，不保证实时性）
    /// </summary>
    public bool CurrentValue { get; set; }
}


3.2 枚举类型


3.2.1 IOType 枚举

表示 IO 点类型。

public enum IOType
{
    /// <summary>
    /// 输入点
    /// </summary>
    Input = 0,

    /// <summary>
    /// 输出点
    /// </summary>
    Output = 1,

    /// <summary>
    /// 模拟输入
    /// </summary>
    AnalogInput = 2,

    /// <summary>
    /// 模拟输出
    /// </summary>
    AnalogOutput = 3
}


4. 监控接口


4.1 IOMonitor 类

IOMonitor 类用于监控 IO 状态变化，提供实时的 IO 状态更新和事件通知。

public class IOMonitor
{
    /// <summary>
    /// 初始化IO监控器
    /// </summary>
    /// <param name="ioManager">IO管理器实例</param>
    public IOMonitor(I_IOManager ioManager);

    /// <summary>
    /// 开始监控
    /// </summary>
    /// <param name="scanIntervalMs">扫描间隔（毫秒）</param>
    public void StartMonitoring(int scanIntervalMs = 50);

    /// <summary>
    /// 停止监控
    /// </summary>
    public void StopMonitoring();

    /// <summary>
    /// IO状态变化事件
    /// </summary>
    public event Action<int, bool, bool> IOStateChanged; // 参数：IO点ID，旧状态，新状态

    /// <summary>
    /// 监控状态事件
    /// </summary>
    public event Action<bool> MonitoringStateChanged; // 参数：是否正在监控
}


5. 具体实现类


5.1 IOManager 类

IOManager 是 I_IOManager 接口的具体实现类，负责实际的 IO 控制操作。

public class IOManager : I_IOManager
{
    // 实现 I_IOManager 接口的所有方法
    // ...
}


6. 异常处理

IO 控制模块定义了特定的异常类型，用于表示不同类型的 IO 操作异常：


IOInitializationException：IO 初始化异常

IOCommunicationException：IO 通信异常

IOOperationException：IO 操作异常

IOTimeoutException：IO 操作超时异常

IOConfigException：IO 配置异常


这些异常都继承自 DeviceException 基类。


7. 使用示例


7.1 基本用法

// 创建并初始化IO管理器
I_IOManager ioManager = new IOManager();
if (ioManager.Initialize())
{
    try
    {
        // 读取输入点10的状态
        bool inputState = ioManager.ReadInput(10);
        Console.WriteLine($"Input 10 state: {inputState}");

        // 写入输出点5为true
        if (ioManager.WriteOutput(5, true))
        {
            Console.WriteLine("Output 5 set to true successfully.");
        }

        // 延时1秒后将输出点5设为false
        Thread.Sleep(1000);
        ioManager.WriteOutput(5, false);
    }
    catch (IOException ex)
    {
        Console.WriteLine($"IO error: {ex.Message}");
    }
    finally
    {
        // 关闭IO管理器
        ioManager.Close();
    }
}
else
{
    Console.WriteLine("Failed to initialize IO manager.");
}


7.2 事件处理

// 创建并初始化IO管理器
I_IOManager ioManager = new IOManager();
if (ioManager.Initialize())
{
    // 注册IO状态变化事件处理函数
    ioManager.RegisterIOChangeHandler(10, (ioId, value) => {
        Console.WriteLine($"IO {ioId} changed to: {value}");
    });

    // 注册所有IO点的变化事件（-1表示所有IO点）
    ioManager.RegisterIOChangeHandler(-1, (ioId, value) => {
        Console.WriteLine($"[Global] IO {ioId} changed to: {value}");
    });

    // 执行IO操作
    // ...
}


7.3 批量操作

// 创建并初始化IO管理器
I_IOManager ioManager = new IOManager();
if (ioManager.Initialize())
{
    try
    {
        // 批量读取输入点状态
        List<int> inputIds = new List<int> { 10, 11, 12, 13 };
        Dictionary<int, bool> inputStates = ioManager.ReadInputs(inputIds);

        foreach (var kvp in inputStates)
        {
            Console.WriteLine($"Input {kvp.Key} state: {kvp.Value}");
        }

        // 批量写入输出点状态
        Dictionary<int, bool> outputValues = new Dictionary<int, bool>
        {
            { 1, true },
            { 2, false },
            { 3, true },
            { 4, false }
        };

        if (ioManager.WriteOutputs(outputValues))
        {
            Console.WriteLine("All outputs written successfully.");
        }
    }
    catch (IOException ex)
    {
        Console.WriteLine($"IO batch operation error: {ex.Message}");
    }
    finally
    {
        // 关闭IO管理器
        ioManager.Close();
    }
}


7.4 高级功能

// 创建并初始化IO管理器
I_IOManager ioManager = new IOManager();
if (ioManager.Initialize())
{
    try
    {
        // 设置输出点闪烁（亮500ms，灭500ms，闪烁5次）
        ioManager.BlinkOutput(5, 500, 500, 5);

        // 延时输出（5秒后将输出点6设为true）
        ioManager.DelayedWriteOutput(6, true, 5000);

        Console.WriteLine("Advanced IO functions set up successfully.");
    }
    catch (IOException ex)
    {
        Console.WriteLine($"Advanced IO error: {ex.Message}");
    }
    finally
    {
        // 关闭IO管理器前停止所有闪烁
        ioManager.StopBlinkOutput();
        // 关闭IO管理器
        ioManager.Close();
    }
}


7.5 使用IO监控器

// 创建并初始化IO管理器
I_IOManager ioManager = new IOManager();
if (ioManager.Initialize())
{
    // 创建IO监控器
    IOMonitor ioMonitor = new IOMonitor(ioManager);

    // 注册IO状态变化事件
    ioMonitor.IOStateChanged += (ioId, oldValue, newValue) => {
        Console.WriteLine($"IO {ioId} changed from {oldValue} to {newValue}");
    };

    // 开始监控，扫描间隔为100ms
    ioMonitor.StartMonitoring(100);

    Console.WriteLine("IO monitoring started. Press any key to stop.");
    Console.ReadKey();

    // 停止监控
    ioMonitor.StopMonitoring();

    // 关闭IO管理器
    ioManager.Close();
}


8. 最佳实践


初始化和资源释放：始终确保在使用 IO 管理器后正确关闭它，以释放资源。
错误处理：捕获并处理所有可能的 IO 操作异常，确保系统稳定运行。
批量操作：对于多个 IO 点的操作，优先使用批量操作方法，提高效率。
事件驱动：使用事件机制响应 IO 状态变化，避免频繁轮询。
命名规范：使用有意义的 IO 点名，便于系统维护和故障排查。
配置管理：通过配置文件管理 IO 映射关系，提高系统的可配置性和可维护性。


9. 注意事项


IO 操作通常是实时性要求较高的任务，应避免在主线程中频繁执行 IO 操作。
对于需要实时监控的场景，建议使用 IOMonitor 类而不是自行实现轮询逻辑。
批量读写操作比单个操作更高效，特别是在需要同时访问多个 IO 点时。
某些高级功能（如闪烁、延时输出）可能需要占用额外的系统资源，应谨慎使用。
在多线程环境中使用 IO 管理器时，需要注意线程安全问题。