using XP.Hardware.MotionControl.Abstractions.Enums;

namespace XP.Hardware.MotionControl.Abstractions
{
    /// <summary>
    /// 直线轴策略接口 | Linear Axis Strategy Interface
    /// 定义直线轴的运动控制能力 | Defines linear axis motion control capabilities
    /// </summary>
    public interface ILinearAxis
    {
        /// <summary>轴标识 | Axis identifier</summary>
        AxisId Id { get; }

        /// <summary>实际位置（mm）| Actual position (mm)</summary>
        double ActualPosition { get; }

        /// <summary>轴状态 | Axis status</summary>
        AxisStatus Status { get; }

        /// <summary>正限位触发 | Positive limit triggered</summary>
        bool PositiveLimitHit { get; }

        /// <summary>负限位触发 | Negative limit triggered</summary>
        bool NegativeLimitHit { get; }

        /// <summary>移动到目标位置 | Move to target position</summary>
        /// <param name="target">目标位置（mm）| Target position (mm)</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult MoveToTarget(double target, double? speed = null);

        /// <summary>Jog 启动 | Jog start</summary>
        /// <param name="positive">true=正向，false=反向 | true=positive, false=negative</param>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult JogStart(bool positive);

        /// <summary>Jog 停止 | Jog stop</summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult JogStop();

        /// <summary>回零 | Home</summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult Home();

        /// <summary>停止 | Stop</summary>
        /// <returns>操作结果 | Operation result</returns>
        MotionResult Stop();

        /// <summary>从 PLC 更新状态 | Update status from PLC</summary>
        void UpdateStatus();
    }
}