HC_APTBS/Services/ICanService.cs

using System;
using System.Collections.Generic;
using HC_APTBS.Models;
using Peak.Can.Basic;
using TPCANHandle = System.UInt16;

namespace HC_APTBS.Services
{
    /// <summary>
    /// Abstracts CAN bus communication for the test bench.
    /// The implementation (<see cref="HC_APTBS.Infrastructure.Pcan.PcanAdapter"/>) wraps
    /// the PEAK PCAN-Basic native API.
    /// </summary>
    public interface ICanService
    {
        // ── Events ────────────────────────────────────────────────────────────────

        /// <summary>
        /// Raised on the CAN read background thread whenever the bus status changes.
        /// <c>message</c> is the short status text; <c>isOk</c> is true when status == PCAN_ERROR_OK.
        /// </summary>
        event Action<string, bool>? StatusChanged;

        /// <summary>
        /// Raised when the bench controller starts or stops sending CAN frames.
        /// <c>alive</c> is true when frames are being received, false after a timeout.
        /// </summary>
        event Action<bool>? BenchLivenessChanged;

        /// <summary>
        /// Raised when the pump ECU starts or stops sending CAN frames.
        /// <c>alive</c> is true when frames are being received, false after a timeout.
        /// </summary>
        event Action<bool>? PumpLivenessChanged;

        // ── Properties ────────────────────────────────────────────────────────────

        /// <summary>Most recent PCAN status code.</summary>
        TPCANStatus CurrentStatus { get; }

        /// <summary>True when the CAN read thread is running and the channel is open.</summary>
        bool IsConnected { get; }

        /// <summary>
        /// True when pump-ECU frames have been received within the last liveness window.
        /// Mirrors the last value broadcast via <see cref="PumpLivenessChanged"/>.
        /// Used by pump-selection flows (e.g. immobilizer unlock) to avoid reading stale
        /// zero-initialised parameter values before the pump has actually started
        /// transmitting on the bus.
        /// </summary>
        bool IsPumpAlive { get; }

        /// <summary>
        /// The PCAN channel handle that will be used on the next <see cref="Connect"/> call.
        /// Defaults to the channel supplied at construction.
        /// Throws <see cref="System.InvalidOperationException"/> when set while <see cref="IsConnected"/> is true.
        /// </summary>
        TPCANHandle SelectedChannel { get; set; }

        // ── Discovery ─────────────────────────────────────────────────────────────

        /// <summary>
        /// Enumerates PCAN USB channels that are physically attached to the system.
        /// Returns an empty list if no adapters are connected or if the PCAN-Basic DLL
        /// is unavailable. Never throws.
        /// </summary>
        System.Collections.Generic.IReadOnlyList<AttachedPcanChannel> EnumerateAttachedChannels();

        // ── Lifecycle ─────────────────────────────────────────────────────────────

        /// <summary>
        /// Opens the PCAN channel, performs OEM legitimation, and starts the receive thread.
        /// </summary>
        /// <returns>True on success; false if the hardware is unavailable or legitimation fails.</returns>
        bool Connect();

        /// <summary>Stops the receive thread and releases the PCAN channel.</summary>
        void Disconnect();

        /// <summary>
        /// Sends a baudrate-change command to the bench firmware, then re-initialises the
        /// PCAN channel at the new baudrate.
        /// </summary>
        /// <param name="newBaudrate">Target baudrate.</param>
        /// <param name="baudrateMessageId">CAN message ID carrying the baudrate-change command.</param>
        void SwitchBaudrate(TPCANBaudrate newBaudrate, uint baudrateMessageId);

        // ── Parameter map ─────────────────────────────────────────────────────────

        /// <summary>Replaces the entire parameter map with the supplied dictionary.</summary>
        void SetParameters(Dictionary<uint, List<CanBusParameter>> parameters);

        /// <summary>Adds entries to the parameter map without removing existing ones.</summary>
        void AddParameters(Dictionary<uint, List<CanBusParameter>> parameters);

        /// <summary>Removes entries whose keys match the supplied dictionary.</summary>
        void RemoveParameters(Dictionary<uint, List<CanBusParameter>> parameters);

        /// <summary>
        /// Registers CAN message IDs that belong to the bench controller.
        /// Frames with these IDs drive <see cref="BenchLivenessChanged"/>.
        /// </summary>
        void RegisterBenchMessageIds(IReadOnlyCollection<uint> ids);

        /// <summary>
        /// Registers CAN message IDs that belong to the pump ECU.
        /// Frames with these IDs drive <see cref="PumpLivenessChanged"/>.
        /// </summary>
        void RegisterPumpMessageIds(IReadOnlyCollection<uint> ids);

        // ── Transmit ──────────────────────────────────────────────────────────────

        /// <summary>
        /// Packs all parameters registered for <paramref name="messageId"/> into a standard
        /// CAN frame (applying the calibration transfer function) and transmits it.
        /// </summary>
        void SendMessageById(uint messageId);

        /// <summary>
        /// Transmits a raw 8-byte CAN standard frame without any parameter lookup.
        /// </summary>
        /// <param name="messageId">CAN message identifier.</param>
        /// <param name="data">Exactly 8 bytes of payload data.</param>
        void SendRawMessage(uint messageId, byte[] data);
    }
}