aivfo-tl-3.0/ivf_tl_control_2.0/IvfTl.Hardware/ISerialChannel.cs

using System;

namespace IvfTl.Hardware
{
    /// <summary>
    /// 单 COM 口的唯一持有者。封装 SerialPort 打开/独占 + 同步请求-响应收发。
    /// 蓝本：autofocustool SerialMotor + HouseMotor + Protocol（最权威），
    /// 并补回 control/operate 的温压门 / 写EEPROM / 气阀 能力。
    /// 所有方法同步阻塞到下位机回复；内部对该口的收发用实例锁串行化（一个 COM 口同一时刻一条在途指令）。
    /// 接口签名权威：13 文档 §3.2。返回值约定：位置/计数失败 -1，温压失败 -1m，布尔操作失败 false。
    /// </summary>
    public interface ISerialChannel : IDisposable
    {
        string PortName { get; }
        bool IsOpen { get; }
        Action<string> Log { get; set; }

        // ── 生命周期 ──
        /// <summary>打开串口（含 DiscardIn/OutBuffer）。已开返回 true。独占失败返回 false。</summary>
        bool Open();
        void Close();

        // ── 读超时策略（按命令类型分超时，13 §3.5/3；属性化，禁止写死单一超时）──
        /// <summary>移动类命令(0x05)读超时(ms)，需覆盖最大行程开环回复，默认 12000。</summary>
        int MoveReadTimeoutMs { get; set; }
        /// <summary>查询类命令读超时(ms)，下位机立即回复，默认 3000。</summary>
        int QueryReadTimeoutMs { get; set; }
        /// <summary>电机到位后默认稳定延时(ms)，移动后等机械停稳再抓图，默认 1500（真机标定）。</summary>
        int MotorSettleMs { get; set; }

        // ── 通用收发（底层）──
        /// <summary>发送完整命令帧（含校验），按命令码定长阻塞收帧并校验。extraWaitMs：收到回复后额外等待。失败返回 null。</summary>
        byte[] SendWait(byte[] frame, int extraWaitMs = 0);

        // ── 握手 / 自检 ──
        /// <summary>握手，返回下位机自报 houseSn。失败 -1。</summary>
        int ShakeHandsWait();

        // ── EEPROM ──
        /// <summary>读本舱相机序列号 CCDSN（EEPROM int）。失败 -1。</summary>
        int ReadCcdSnWait();
        /// <summary>读 EEPROM 灯光亮度（只读）。失败 -1。</summary>
        int ReadLightBrightnessWait();
        /// <summary>读第 well(1-16) 的水平电机位置脉冲（EEPROM）。失败 -1。</summary>
        int ReadWellHorizontalPosWait(int well);
        /// <summary>读第 well(1-16) 的 Z 对焦零点脉冲（EEPROM）。失败 -1。</summary>
        int ReadWellFocusZeroWait(int well);
        /// <summary>读垂直电机扫描间隔脉冲（每层 Z 步距，EEPROM）。失败 -1。</summary>
        int ReadScanStepWait();
        /// <summary>写第 well(1-16) 的水平电机位置脉冲（命令码 0x12）。
        /// ⚠ 需真机验证：写命令字节序/地址表须按 control Commander.cs 复核（13 §⑤ V1）。</summary>
        bool WriteWellHorizontalPosWait(int well, int pulseValue);

        // ── 电机：垂直（Z=对焦轴）/ 水平（皿孔定位）──
        /// <summary>Z 绝对运动到脉冲，delayMs 缺省用 MotorSettleMs；扫描小步可传短延时提速。失败 false。</summary>
        bool VerticalMoveToWait(int pulse, int delayMs = -1);
        bool VerticalForwardWait(int pulse, int delayMs = -1);
        bool VerticalBackwardWait(int pulse, int delayMs = -1);
        bool VerticalResetWait(int delayMs = -1);
        /// <summary>读 Z 当前位置脉冲。失败 -1。</summary>
        int ReadVerticalPositionWait();

        bool HorizontalMoveToWait(int pulse, int delayMs = -1);
        bool HorizontalForwardWait(int pulse, int delayMs = -1);
        bool HorizontalBackwardWait(int pulse, int delayMs = -1);
        bool HorizontalResetWait(int delayMs = -1);
        int ReadHorizontalPositionWait();

        // ── 环境量（温压门，control/operate 有，af 无）──
        /// <summary>下盖板温度(℃)，失败 -1m。</summary>
        decimal TemperatureWait();
        decimal ShangTemperatureWait();   // 上盖板
        decimal BoLiTemperatureWait();    // 玻璃片下方
        decimal PressureWait();           // 舱内气压
        (decimal pressure, decimal t1, decimal t2) BufferBottleStateWait(); // 缓冲瓶
        /// <summary>仓门状态。失败返回 未知。</summary>
        DoorState DoorStatusWait();

        // ── IO / LED / 气阀（control/operate 全，af 仅 LED）──
        bool OpenLedWait();
        bool CloseLedWait();
        bool OpenIntakeValveWait();
        bool CloseIntakeValveWait();
        bool OpenExhaustValveWait();
        bool CloseExhaustValveWait();
        bool HouseAerationWait();          // 舱室补气
        bool HouseVentWait();              // 舱室排气
        bool BufferBottleAerationWait();   // 缓冲瓶补气
        /// <summary>自动气体交换开/关（对应 operate AutoWait）。</summary>
        bool AutoAirSwapWait(bool on);

        // ── 直通底层 ComBin（迁移期过渡：调试/采集若需要 ComBin 上 HAL 接口未覆盖的方法可暂取裸实例）──
        /// <summary>桥接对象：返回内部包装的具体 ComBin（object 以避免 HAL 接口耦合具体类型）。
        /// 仅供迁移期老调用方过渡使用，新代码应只用本接口方法。</summary>
        object RawComBin { get; }
    }

    /// <summary>仓门状态（对应 control State 枚举的 未知/打开/关闭 子集）。</summary>
    public enum DoorState { 未知, 打开, 关闭 }
}