BQP/srcs/RobotNet10/RobotApp/RobotNet10.RobotApp/Devices/IModbusTcpDevice.cs

using RobotNet10.RobotApp.Client.Shared.Devices;

namespace RobotNet10.RobotApp.Devices;

public enum ModbusRegisterType
{
    Holding,
    DiscreteInput,
    Input,
    Coil,
}

/// <summary>
/// Interface cho thiết bị ModbusTCP
/// </summary>
public interface IModbusTcpDevice
{
    /// <summary>
    /// IP Address của ModbusTCP server
    /// </summary>
    string IpAddress { get; }

    /// <summary>
    /// Port của ModbusTCP server (mặc định: 502)
    /// </summary>
    int Port { get; }

    /// <summary>
    /// Slave ID (Unit Identifier)
    /// </summary>
    byte SlaveId { get; }

    /// <summary>
    /// Trạng thái kết nối
    /// </summary>
    bool IsConnected { get; }

    // Configuration Properties

    event Action<ModbusRegisterType> DataRegisterChanged;

    /// <summary>
    /// Danh sách các vùng Holding Registers đã được cấu hình
    /// </summary>
    IReadOnlyList<ModbusRangeData> HoldingRegisterRanges { get; }

    /// <summary>
    /// Danh sách các vùng Input Registers đã được cấu hình
    /// </summary>
    IReadOnlyList<ModbusRangeData> InputRegisterRanges { get; }

    /// <summary>
    /// Danh sách các vùng Coils đã được cấu hình
    /// </summary>
    IReadOnlyList<ModbusRangeData> CoilRanges { get; }

    /// <summary>
    /// Danh sách các vùng Discrete Inputs đã được cấu hình
    /// </summary>
    IReadOnlyList<ModbusRangeData> DiscreteInputRanges { get; }

    // Holding Registers Methods

    /// <summary>
    /// Đọc một holding register từ cache
    /// </summary>
    /// <param name="address">Địa chỉ register</param>
    /// <returns>Giá trị register (16-bit unsigned)</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    ushort ReadHoldingRegister(ushort address);

    /// <summary>
    /// Đọc nhiều holding registers từ cache
    /// </summary>
    /// <param name="startAddress">Địa chỉ bắt đầu</param>
    /// <param name="quantity">Số lượng registers cần đọc</param>
    /// <returns>Mảng giá trị registers</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    ushort[] ReadHoldingRegisters(ushort startAddress, ushort quantity);

    /// <summary>
    /// Ghi một holding register vào cache (sẽ được đồng bộ bởi vòng lặp)
    /// </summary>
    /// <param name="address">Địa chỉ register</param>
    /// <param name="value">Giá trị cần ghi</param>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    Task WriteHoldingRegisterAsync(ushort address, ushort value, CancellationToken cancellationToken = default);

    /// <summary>
    /// Ghi nhiều holding registers vào cache (sẽ được đồng bộ bởi vòng lặp)
    /// </summary>
    /// <param name="startAddress">Địa chỉ bắt đầu</param>
    /// <param name="values">Mảng giá trị cần ghi</param>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    Task WriteHoldingRegistersAsync(ushort startAddress, ushort[] values, CancellationToken cancellationToken = default);

    // Input Registers Methods

    /// <summary>
    /// Đọc một input register từ cache
    /// </summary>
    /// <param name="address">Địa chỉ register</param>
    /// <returns>Giá trị register (16-bit unsigned)</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    ushort ReadInputRegister(ushort address);

    /// <summary>
    /// Đọc nhiều input registers từ cache
    /// </summary>
    /// <param name="startAddress">Địa chỉ bắt đầu</param>
    /// <param name="quantity">Số lượng registers cần đọc</param>
    /// <returns>Mảng giá trị registers</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    ushort[] ReadInputRegisters(ushort startAddress, ushort quantity);

    // Coils Methods

    /// <summary>
    /// Đọc một coil từ cache
    /// </summary>
    /// <param name="address">Địa chỉ coil</param>
    /// <returns>Giá trị coil (true/false)</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    bool ReadCoil(ushort address);

    /// <summary>
    /// Đọc nhiều coils từ cache
    /// </summary>
    /// <param name="startAddress">Địa chỉ bắt đầu</param>
    /// <param name="quantity">Số lượng coils cần đọc</param>
    /// <returns>Mảng giá trị coils</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    bool[] ReadCoils(ushort startAddress, ushort quantity);

    /// <summary>
    /// Ghi một coil vào cache (sẽ được đồng bộ bởi vòng lặp)
    /// </summary>
    /// <param name="address">Địa chỉ coil</param>
    /// <param name="value">Giá trị cần ghi</param>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    Task WriteCoilAsync(ushort address, bool value, CancellationToken cancellationToken = default);

    /// <summary>
    /// Ghi nhiều coils vào cache (sẽ được đồng bộ bởi vòng lặp)
    /// </summary>
    /// <param name="startAddress">Địa chỉ bắt đầu</param>
    /// <param name="values">Mảng giá trị cần ghi</param>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    Task WriteCoilsAsync(ushort startAddress, bool[] values, CancellationToken cancellationToken = default);

    /// <summary>
    /// Ghi một coil xuống PLC ngay lập tức (không qua queue). Dùng cho pulse (M815 alarm reset).
    /// </summary>
    /// <param name="address">Địa chỉ coil</param>
    /// <param name="value">Giá trị cần ghi</param>
    /// <param name="cancellationToken">Cancellation token</param>
    Task WriteCoilImmediateAsync(ushort address, bool value, CancellationToken cancellationToken = default);

    // Discrete Inputs Methods

    /// <summary>
    /// Đọc một discrete input từ cache
    /// </summary>
    /// <param name="address">Địa chỉ input</param>
    /// <returns>Giá trị input (true/false)</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    bool ReadDiscreteInput(ushort address);

    /// <summary>
    /// Đọc nhiều discrete inputs từ cache
    /// </summary>
    /// <param name="startAddress">Địa chỉ bắt đầu</param>
    /// <param name="quantity">Số lượng inputs cần đọc</param>
    /// <returns>Mảng giá trị inputs</returns>
    /// <exception cref="ArgumentException">Nếu địa chỉ không nằm trong vùng đã khai báo</exception>
    bool[] ReadDiscreteInputs(ushort startAddress, ushort quantity);
}