max22200_types.hpp

Go to the documentation of this file.

 
#pragma once
#include "max22200_registers.hpp"
#include <array>
#include <cstdint>
 
namespace max22200 {
 
// ============================================================================
// Enumerations
// ============================================================================
 
enum class DriveMode : uint8_t {
  CDR = 0, 
  VDR = 1  
};
 
enum class SideMode : uint8_t {
  LOW_SIDE  = 0, 
  HIGH_SIDE = 1  
};
 
enum class ChannelMode : uint8_t {
  INDEPENDENT = 0, 
  PARALLEL    = 1, 
  HBRIDGE     = 2  
};
 
enum class ChopFreq : uint8_t {
  FMAIN_DIV4 = 0, 
  FMAIN_DIV3 = 1, 
  FMAIN_DIV2 = 2, 
  FMAIN      = 3  
};
 
inline uint32_t getChopFreqKhz(bool master_clock_80khz, ChopFreq cf) {
  switch (cf) {
    case ChopFreq::FMAIN_DIV4: return master_clock_80khz ? 20u : 25u;
    case ChopFreq::FMAIN_DIV3: return master_clock_80khz ? 26u : 33u;
    case ChopFreq::FMAIN_DIV2: return master_clock_80khz ? 40u : 50u;
    case ChopFreq::FMAIN:      return master_clock_80khz ? 80u : 100u;
    default:                   return 25u;
  }
}
 
inline float getChopFreqKhzExact(bool master_clock_80khz, ChopFreq cf) {
  const float fmain_khz = master_clock_80khz ? 80.0f : 100.0f;
  switch (cf) {
    case ChopFreq::FMAIN_DIV4: return fmain_khz / 4.0f;
    case ChopFreq::FMAIN_DIV3: return fmain_khz / 3.0f;
    case ChopFreq::FMAIN_DIV2: return fmain_khz / 2.0f;
    case ChopFreq::FMAIN:      return fmain_khz;
    default:                   return fmain_khz / 4.0f;
  }
}
 
inline uint8_t currentMaToRaw(uint32_t full_scale_current_ma, uint32_t ma) {
  if (full_scale_current_ma == 0) return 0;
  if (ma >= full_scale_current_ma) return 127;
  uint32_t raw = (ma * 127u + full_scale_current_ma / 2u) / full_scale_current_ma;
  return raw > 127u ? 127u : static_cast<uint8_t>(raw);
}
 
inline uint8_t dutyPercentToRaw(float percent) {
  if (!(percent > 0.0f)) return 0;  // also catches NaN
  if (percent >= 100.0f) return 100;
  const uint32_t raw = static_cast<uint32_t>(percent + 0.5f);
  return raw > 100u ? 100u : static_cast<uint8_t>(raw);
}
 
inline float dutyRawToPercent(uint8_t raw) {
  return raw >= 100u ? 100.0f : static_cast<float>(raw);
}
 
inline uint8_t hitTimeMsToRaw(float ms, bool master_clock_80khz, ChopFreq cf) {
  uint32_t fchop_khz = getChopFreqKhz(master_clock_80khz, cf);
  if (ms < 0.0f || ms >= 1000000.0f) return 255;
  if (ms == 0.0f) return 0;
  float fchop_hz = static_cast<float>(fchop_khz) * 1000.0f;
  uint32_t raw = static_cast<uint32_t>((ms / 1000.0f) * fchop_hz / 40.0f + 0.5f);
  if (raw > 254u) return 255;
  if (raw == 0u) return 1;
  return static_cast<uint8_t>(raw);
}
 
inline float getMaxHitTimeMs(bool master_clock_80khz, ChopFreq cf) {
  const uint32_t fchop_khz = getChopFreqKhz(master_clock_80khz, cf);
  const float fchop_hz = static_cast<float>(fchop_khz) * 1000.0f;
  return (254.0f * 40.0f / fchop_hz) * 1000.0f;
}
 
enum class FaultType : uint8_t {
  OCP   = 0, 
  HHF   = 1, 
  OLF   = 2, 
  DPM   = 3, 
  OVT   = 4, 
  UVM   = 5, 
  COMER = 6  
};
 
inline const char *FaultTypeToStr(FaultType ft) {
  switch (ft) {
    case FaultType::OCP:   return "Overcurrent";
    case FaultType::HHF:   return "HIT not reached";
    case FaultType::OLF:   return "Open-load";
    case FaultType::DPM:   return "Plunger movement";
    case FaultType::OVT:   return "Overtemperature";
    case FaultType::UVM:   return "Undervoltage";
    case FaultType::COMER: return "Communication error";
    default:               return "Unknown fault";
  }
}
 
// ============================================================================
// Structures
// ============================================================================
 
struct ChannelConfig {
  // ── User Units (Primary Storage) ──────────────────────────────────────────
  // CDR: setpoint in mA. VDR: setpoint in duty % (0–100). Use accessors for intent-revealing names.
 
  float    hit_setpoint;   
  float    hold_setpoint;  
  float    hit_time_ms;    
 
  // ── Register Fields (Direct Mapping) ─────────────────────────────────────
  bool     half_full_scale;        
  bool     trigger_from_pin;       
  DriveMode drive_mode;            
  SideMode  side_mode;             
  ChopFreq  chop_freq;             
  bool      slew_rate_control_enabled;   
  bool      open_load_detection_enabled; 
  bool      plunger_movement_detection_enabled; 
  bool      hit_current_check_enabled;   
 
  ChannelConfig()
      : hit_setpoint(0.0f), hold_setpoint(0.0f), hit_time_ms(0.0f),
        half_full_scale(false), trigger_from_pin(false),
        drive_mode(DriveMode::CDR), side_mode(SideMode::LOW_SIDE),
        chop_freq(ChopFreq::FMAIN_DIV4), slew_rate_control_enabled(false),
        open_load_detection_enabled(false), plunger_movement_detection_enabled(false),
        hit_current_check_enabled(false) {}
 
  static ChannelConfig makeSolenoidCdr(float hit_ma, float hold_ma, float hit_time_ms) {
    ChannelConfig c;
    c.drive_mode = DriveMode::CDR;
    c.side_mode = SideMode::LOW_SIDE;
    c.hit_setpoint = hit_ma;
    c.hold_setpoint = hold_ma;
    c.hit_time_ms = hit_time_ms;
    c.chop_freq = ChopFreq::FMAIN_DIV4;
    return c;
  }
 
  static ChannelConfig makeSolenoidVdr(float hit_pct, float hold_pct, float hit_time_ms) {
    ChannelConfig c;
    c.drive_mode = DriveMode::VDR;
    c.side_mode = SideMode::LOW_SIDE;
    c.hit_setpoint = hit_pct;
    c.hold_setpoint = hold_pct;
    c.hit_time_ms = hit_time_ms;
    c.chop_freq = ChopFreq::FMAIN_DIV4;
    return c;
  }
 
  // ── Mode-aware accessors (same storage; use for clear intent at call site) ─
  void set_hit_ma(float ma) { hit_setpoint = ma; }
  void set_hold_ma(float ma) { hold_setpoint = ma; }
  void set_hit_duty_percent(float pct) { hit_setpoint = pct; }
  void set_hold_duty_percent(float pct) { hold_setpoint = pct; }
  float hit_ma() const { return hit_setpoint; }
  float hold_ma() const { return hold_setpoint; }
  float hit_duty_percent() const { return hit_setpoint; }
  float hold_duty_percent() const { return hold_setpoint; }
 
  uint32_t toRegister(uint32_t board_ifs_ma = 0, bool master_clock_80khz = false) const {
    // Effective IFS for CDR: HFS=1 halves the scale (datasheet KFS 7.5k vs 15k)
    const uint32_t ifs_ma = (drive_mode == DriveMode::CDR && half_full_scale && board_ifs_ma >= 2u)
                                ? (board_ifs_ma / 2u)
                                : board_ifs_ma;
 
    // Convert hit_setpoint to raw 7-bit
    uint8_t hit_raw;
    if (drive_mode == DriveMode::CDR) {
      // CDR: hit_setpoint is in mA (relative to effective IFS for this channel)
      if (ifs_ma == 0) {
        hit_raw = 0;  // Invalid IFS
      } else if (hit_setpoint >= static_cast<float>(ifs_ma)) {
        hit_raw = 127;
      } else {
        uint32_t ma = static_cast<uint32_t>(hit_setpoint + 0.5f);
        hit_raw = currentMaToRaw(ifs_ma, ma);
      }
    } else {
      // VDR: hit_setpoint is duty percent (0-100)
      hit_raw = dutyPercentToRaw(hit_setpoint);
    }
 
    // Convert hold_setpoint to raw 7-bit
    uint8_t hold_raw;
    if (drive_mode == DriveMode::CDR) {
      // CDR: hold_setpoint is in mA
      if (ifs_ma == 0) {
        hold_raw = 0;
      } else if (hold_setpoint >= static_cast<float>(ifs_ma)) {
        hold_raw = 127;
      } else {
        uint32_t ma = static_cast<uint32_t>(hold_setpoint + 0.5f);
        hold_raw = currentMaToRaw(ifs_ma, ma);
      }
    } else {
      // VDR: hold_setpoint is duty percent (0-100)
      hold_raw = dutyPercentToRaw(hold_setpoint);
    }
 
    // Convert hit_time_ms to raw 8-bit (master_clock_80khz from parameter, not stored on config)
    uint8_t hit_time_raw = hitTimeMsToRaw(hit_time_ms, master_clock_80khz, chop_freq);
 
    // Build register value
    uint32_t val = 0;
    if (half_full_scale) val |= CfgChReg::HFS_BIT;
    val |= (static_cast<uint32_t>(hold_raw & 0x7F) << CfgChReg::HOLD_SHIFT);
    if (trigger_from_pin) val |= CfgChReg::TRGNSPI_BIT;
    val |= (static_cast<uint32_t>(hit_raw & 0x7F) << CfgChReg::HIT_SHIFT);
    val |= (static_cast<uint32_t>(hit_time_raw) << CfgChReg::HITT_SHIFT);
    if (drive_mode == DriveMode::VDR) val |= CfgChReg::VDRNCDR_BIT;
    if (side_mode == SideMode::HIGH_SIDE) val |= CfgChReg::HSNLS_BIT;
    val |= (static_cast<uint32_t>(chop_freq) << CfgChReg::FREQ_CFG_SHIFT);
    if (slew_rate_control_enabled) val |= CfgChReg::SRC_BIT;
    if (open_load_detection_enabled) val |= CfgChReg::OL_EN_BIT;
    if (plunger_movement_detection_enabled) val |= CfgChReg::DPM_EN_BIT;
    if (hit_current_check_enabled) val |= CfgChReg::HHF_EN_BIT;
    return val;
  }
 
  void fromRegister(uint32_t val, uint32_t board_ifs_ma, bool master_clock_80khz_param) {
    // Parse register fields
    half_full_scale = (val & CfgChReg::HFS_BIT) != 0;
    uint8_t hold_raw = static_cast<uint8_t>((val >> CfgChReg::HOLD_SHIFT) & 0x7F);
    trigger_from_pin = (val & CfgChReg::TRGNSPI_BIT) != 0;
    uint8_t hit_raw  = static_cast<uint8_t>((val >> CfgChReg::HIT_SHIFT) & 0x7F);
    uint8_t hit_time_raw = static_cast<uint8_t>((val >> CfgChReg::HITT_SHIFT) & 0xFF);
    drive_mode = (val & CfgChReg::VDRNCDR_BIT) ? DriveMode::VDR : DriveMode::CDR;
    side_mode  = (val & CfgChReg::HSNLS_BIT) ? SideMode::HIGH_SIDE : SideMode::LOW_SIDE;
    chop_freq  = static_cast<ChopFreq>((val >> CfgChReg::FREQ_CFG_SHIFT) & 0x03);
    slew_rate_control_enabled = (val & CfgChReg::SRC_BIT) != 0;
    open_load_detection_enabled = (val & CfgChReg::OL_EN_BIT) != 0;
    plunger_movement_detection_enabled = (val & CfgChReg::DPM_EN_BIT) != 0;
    hit_current_check_enabled = (val & CfgChReg::HHF_EN_BIT) != 0;
 
    // Convert raw → user units (master_clock_80khz_param used for hit_time only; not stored on config)
    if (drive_mode == DriveMode::CDR) {
      // CDR: raw → mA (use effective IFS when HFS=1)
      const uint32_t effective_ifs = half_full_scale && board_ifs_ma >= 2u
                                         ? (board_ifs_ma / 2u)
                                         : board_ifs_ma;
      if (effective_ifs > 0) {
        hit_setpoint = (static_cast<float>(hit_raw) / 127.0f) * static_cast<float>(effective_ifs);
        hold_setpoint = (static_cast<float>(hold_raw) / 127.0f) * static_cast<float>(effective_ifs);
      } else {
        hit_setpoint = 0.0f;
        hold_setpoint = 0.0f;
      }
    } else {
      // VDR: the field is the duty cycle in percent (datasheet Table 3); 100 and above is 100 %
      hit_setpoint = dutyRawToPercent(hit_raw);
      hold_setpoint = dutyRawToPercent(hold_raw);
    }
 
    // Convert hit_time raw → ms
    if (hit_time_raw == 0) {
      hit_time_ms = 0.0f;
    } else if (hit_time_raw == 255) {
      hit_time_ms = -1.0f;  // Continuous (infinite)
    } else {
      uint32_t fchop_khz = getChopFreqKhz(master_clock_80khz_param, chop_freq);
      float fchop_hz = static_cast<float>(fchop_khz) * 1000.0f;
      hit_time_ms = (static_cast<float>(hit_time_raw) * 40.0f / fchop_hz) * 1000.0f;
    }
  }
 
  // ── Inline probe helpers (human-readable, compiler can optimize away) ─────
 
  bool isCdr() const { return drive_mode == DriveMode::CDR; }
  bool isVdr() const { return drive_mode == DriveMode::VDR; }
  bool isLowSide() const { return side_mode == SideMode::LOW_SIDE; }
  bool isHighSide() const { return side_mode == SideMode::HIGH_SIDE; }
  bool hasHitTime() const { return hit_time_ms > 0.0f; }
  bool isContinuousHit() const { return hit_time_ms < 0.0f || hit_time_ms >= 1000000.0f; }
  bool isTriggeredBySpi() const { return !trigger_from_pin; }
  bool isTriggeredByPin() const { return trigger_from_pin; }
  bool isHalfFullScale() const { return half_full_scale; }
  bool isSlewRateControlEnabled() const { return slew_rate_control_enabled; }
  bool isOpenLoadDetectionEnabled() const { return open_load_detection_enabled; }
  bool isPlungerMovementDetectionEnabled() const { return plunger_movement_detection_enabled; }
  bool isHitCurrentCheckEnabled() const { return hit_current_check_enabled; }
  ChopFreq getChopFreq() const { return chop_freq; }
};
 
struct StatusConfig {
  // Byte 3 (bits 31:24)
  uint8_t channels_on_mask;  
 
  // Byte 2 (bits 23:16) — fault masks (1=masked, 0=signaled on FAULT pin)
  bool overtemperature_masked;       
  bool overcurrent_masked;           
  bool open_load_fault_masked;       
  bool hit_not_reached_masked;       
  bool plunger_movement_fault_masked;
  bool communication_error_masked;   
  bool undervoltage_masked;          
  bool master_clock_80khz;           
 
  // Byte 1 (bits 15:8) — channel-pair mode
  ChannelMode channel_pair_mode_76;  
  ChannelMode channel_pair_mode_54;  
  ChannelMode channel_pair_mode_32;  
  ChannelMode channel_pair_mode_10;  
 
  // Byte 0 (bits 7:0) — fault flags (read-only) + ACTIVE
  bool active;                      
 
  // Read-only fault flags (populated on read, cleared by reading STATUS or FAULT register)
  bool overtemperature;             
  bool overcurrent;                  
  bool open_load_fault;              
  bool hit_not_reached;              
  bool plunger_movement_fault;       
  bool communication_error;          
  bool undervoltage;                 
 
  StatusConfig()
      : channels_on_mask(0), overtemperature_masked(false), overcurrent_masked(false),
        open_load_fault_masked(false), hit_not_reached_masked(false),
        plunger_movement_fault_masked(false), communication_error_masked(true),
        undervoltage_masked(false), master_clock_80khz(false),
        channel_pair_mode_76(ChannelMode::INDEPENDENT), channel_pair_mode_54(ChannelMode::INDEPENDENT),
        channel_pair_mode_32(ChannelMode::INDEPENDENT), channel_pair_mode_10(ChannelMode::INDEPENDENT),
        active(false), overtemperature(false), overcurrent(false), open_load_fault(false),
        hit_not_reached(false), plunger_movement_fault(false), communication_error(false),
        undervoltage(false) {}
 
  uint32_t toRegister() const {
    uint32_t val = 0;
    val |= (static_cast<uint32_t>(channels_on_mask) << StatusReg::ONCH_SHIFT);
    if (overtemperature_masked)  val |= StatusReg::M_OVT_BIT;
    if (overcurrent_masked)      val |= StatusReg::M_OCP_BIT;
    if (open_load_fault_masked)  val |= StatusReg::M_OLF_BIT;
    if (hit_not_reached_masked) val |= StatusReg::M_HHF_BIT;
    if (plunger_movement_fault_masked) val |= StatusReg::M_DPM_BIT;
    if (communication_error_masked) val |= StatusReg::M_COMF_BIT;
    if (undervoltage_masked)     val |= StatusReg::M_UVM_BIT;
    if (master_clock_80khz)      val |= StatusReg::FREQM_BIT;
    val |= (static_cast<uint32_t>(channel_pair_mode_76) << StatusReg::CM76_SHIFT);
    val |= (static_cast<uint32_t>(channel_pair_mode_54) << StatusReg::CM54_SHIFT);
    val |= (static_cast<uint32_t>(channel_pair_mode_32) << StatusReg::CM32_SHIFT);
    val |= (static_cast<uint32_t>(channel_pair_mode_10) << StatusReg::CM10_SHIFT);
    if (active) val |= StatusReg::ACTIVE_BIT;
    return val;
  }
 
  void fromRegister(uint32_t val) {
    channels_on_mask = static_cast<uint8_t>((val >> StatusReg::ONCH_SHIFT) & 0xFF);
    overtemperature_masked = (val & StatusReg::M_OVT_BIT) != 0;
    overcurrent_masked     = (val & StatusReg::M_OCP_BIT) != 0;
    open_load_fault_masked = (val & StatusReg::M_OLF_BIT) != 0;
    hit_not_reached_masked = (val & StatusReg::M_HHF_BIT) != 0;
    plunger_movement_fault_masked = (val & StatusReg::M_DPM_BIT) != 0;
    communication_error_masked = (val & StatusReg::M_COMF_BIT) != 0;
    undervoltage_masked    = (val & StatusReg::M_UVM_BIT) != 0;
    master_clock_80khz     = (val & StatusReg::FREQM_BIT) != 0;
    channel_pair_mode_76   = static_cast<ChannelMode>((val >> StatusReg::CM76_SHIFT) & 0x03);
    channel_pair_mode_54   = static_cast<ChannelMode>((val >> StatusReg::CM54_SHIFT) & 0x03);
    channel_pair_mode_32   = static_cast<ChannelMode>((val >> StatusReg::CM32_SHIFT) & 0x03);
    channel_pair_mode_10   = static_cast<ChannelMode>((val >> StatusReg::CM10_SHIFT) & 0x03);
    overtemperature = (val & StatusReg::OVT_BIT) != 0;
    overcurrent     = (val & StatusReg::OCP_BIT) != 0;
    open_load_fault = (val & StatusReg::OLF_BIT) != 0;
    hit_not_reached = (val & StatusReg::HHF_BIT) != 0;
    plunger_movement_fault = (val & StatusReg::DPM_BIT) != 0;
    communication_error   = (val & StatusReg::COMER_BIT) != 0;
    undervoltage   = (val & StatusReg::UVM_BIT) != 0;
    active = (val & StatusReg::ACTIVE_BIT) != 0;
  }
 
  bool hasFault() const {
    return overtemperature || overcurrent || open_load_fault || hit_not_reached
        || plunger_movement_fault || communication_error || undervoltage;
  }
 
  // ── Inline probe helpers ─────────────────────────────────────────────────
 
  bool hasOvertemperature() const { return overtemperature; }
  bool hasOvercurrent() const { return overcurrent; }
  bool hasOpenLoadFault() const { return open_load_fault; }
  bool hasHitNotReached() const { return hit_not_reached; }
  bool hasPlungerMovementFault() const { return plunger_movement_fault; }
  bool hasCommunicationError() const { return communication_error; }
  bool hasUndervoltage() const { return undervoltage; }
  bool isActive() const { return active; }
  bool isChannelOn(uint8_t ch) const {
    return ch < 8u && (channels_on_mask & (1u << ch)) != 0u;
  }
  uint8_t channelCountOn() const {
    uint8_t n = 0;
    for (uint8_t i = 0; i < 8; i++) {
      if (channels_on_mask & (1u << i)) n++;
    }
    return n;
  }
 
  bool isOvertemperatureMasked() const { return overtemperature_masked; }
  bool isOvercurrentMasked() const { return overcurrent_masked; }
  bool isOpenLoadFaultMasked() const { return open_load_fault_masked; }
  bool isHitNotReachedMasked() const { return hit_not_reached_masked; }
  bool isPlungerMovementFaultMasked() const { return plunger_movement_fault_masked; }
  bool isCommunicationErrorMasked() const { return communication_error_masked; }
  bool isUndervoltageMasked() const { return undervoltage_masked; }
 
  bool is80KHzBase() const { return master_clock_80khz; }
  bool is100KHzBase() const { return !master_clock_80khz; }
 
  ChannelMode getChannelPairMode76() const { return channel_pair_mode_76; }
  ChannelMode getChannelPairMode54() const { return channel_pair_mode_54; }
  ChannelMode getChannelPairMode32() const { return channel_pair_mode_32; }
  ChannelMode getChannelPairMode10() const { return channel_pair_mode_10; }
  uint8_t getChannelsOnMask() const { return channels_on_mask; }
};
 
struct FaultStatus {
  uint8_t overcurrent_channel_mask;            
  uint8_t hit_not_reached_channel_mask;       
  uint8_t open_load_fault_channel_mask;       
  uint8_t plunger_movement_fault_channel_mask; 
 
  FaultStatus() : overcurrent_channel_mask(0), hit_not_reached_channel_mask(0),
                  open_load_fault_channel_mask(0), plunger_movement_fault_channel_mask(0) {}
 
  void fromRegister(uint32_t val) {
    overcurrent_channel_mask            = static_cast<uint8_t>((val >> FaultReg::OCP_SHIFT) & 0xFF);
    hit_not_reached_channel_mask        = static_cast<uint8_t>((val >> FaultReg::HHF_SHIFT) & 0xFF);
    open_load_fault_channel_mask        = static_cast<uint8_t>((val >> FaultReg::OLF_SHIFT) & 0xFF);
    plunger_movement_fault_channel_mask = static_cast<uint8_t>((val >> FaultReg::DPM_SHIFT) & 0xFF);
  }
 
  bool hasFault() const {
    return (overcurrent_channel_mask | hit_not_reached_channel_mask
         | open_load_fault_channel_mask | plunger_movement_fault_channel_mask) != 0;
  }
 
  uint8_t getFaultCount() const {
    uint8_t count = 0;
    for (uint8_t i = 0; i < 8; i++) {
      if (overcurrent_channel_mask & (1u << i)) count++;
      if (hit_not_reached_channel_mask & (1u << i)) count++;
      if (open_load_fault_channel_mask & (1u << i)) count++;
      if (plunger_movement_fault_channel_mask & (1u << i)) count++;
    }
    return count;
  }
 
  // ── Inline probe helpers (human-readable, compiler can optimize away) ─────
 
  bool hasOvercurrent() const { return overcurrent_channel_mask != 0; }
  bool hasHitNotReached() const { return hit_not_reached_channel_mask != 0; }
  bool hasOpenLoadFault() const { return open_load_fault_channel_mask != 0; }
  bool hasPlungerMovementFault() const { return plunger_movement_fault_channel_mask != 0; }
  bool hasFaultOnChannel(uint8_t ch) const {
    return ch < NUM_CHANNELS_ && ((overcurrent_channel_mask | hit_not_reached_channel_mask
         | open_load_fault_channel_mask | plunger_movement_fault_channel_mask) & (1u << ch)) != 0u;
  }
  bool hasOvercurrentOnChannel(uint8_t ch) const {
    return ch < NUM_CHANNELS_ && (overcurrent_channel_mask & (1u << ch)) != 0u;
  }
  bool hasHitNotReachedOnChannel(uint8_t ch) const {
    return ch < NUM_CHANNELS_ && (hit_not_reached_channel_mask & (1u << ch)) != 0u;
  }
  bool hasOpenLoadFaultOnChannel(uint8_t ch) const {
    return ch < NUM_CHANNELS_ && (open_load_fault_channel_mask & (1u << ch)) != 0u;
  }
  bool hasPlungerMovementFaultOnChannel(uint8_t ch) const {
    return ch < NUM_CHANNELS_ && (plunger_movement_fault_channel_mask & (1u << ch)) != 0u;
  }
  uint8_t channelsWithAnyFault() const {
    return overcurrent_channel_mask | hit_not_reached_channel_mask
         | open_load_fault_channel_mask | plunger_movement_fault_channel_mask;
  }
};
 
struct DpmConfig {
  uint8_t plunger_movement_start_current;   
  uint8_t plunger_movement_debounce_time;   
  uint8_t plunger_movement_current_threshold; 
 
  DpmConfig() : plunger_movement_start_current(0), plunger_movement_debounce_time(0),
                plunger_movement_current_threshold(0) {}
 
  uint32_t toRegister() const {
    return (static_cast<uint32_t>(plunger_movement_start_current & 0x7Fu) << CfgDpmReg::DPM_ISTART_SHIFT) |
           (static_cast<uint32_t>(plunger_movement_debounce_time & 0x0Fu) << CfgDpmReg::DPM_TDEB_SHIFT) |
           (static_cast<uint32_t>(plunger_movement_current_threshold & 0x0Fu) << CfgDpmReg::DPM_IPTH_SHIFT);
  }
 
  void fromRegister(uint32_t val) {
    plunger_movement_start_current   = static_cast<uint8_t>((val >> CfgDpmReg::DPM_ISTART_SHIFT) & 0x7F);
    plunger_movement_debounce_time   = static_cast<uint8_t>((val >> CfgDpmReg::DPM_TDEB_SHIFT) & 0x0F);
    plunger_movement_current_threshold = static_cast<uint8_t>((val >> CfgDpmReg::DPM_IPTH_SHIFT) & 0x0F);
  }
 
  uint8_t getPlungerMovementStartCurrent() const { return plunger_movement_start_current; }
  uint8_t getPlungerMovementDebounceTime() const { return plunger_movement_debounce_time; }
  uint8_t getPlungerMovementCurrentThreshold() const { return plunger_movement_current_threshold; }
};
 
enum class FullBridgeState : uint8_t {
  HiZ     = 0, 
  Forward = 1, 
  Reverse = 2, 
  Brake   = 3  
};
 
enum class DriverStatus : uint8_t {
  OK = 0,               
  INITIALIZATION_ERROR, 
  COMMUNICATION_ERROR,  
  INVALID_PARAMETER,    
  HARDWARE_FAULT,       
  TIMEOUT               
};
 
inline const char *DriverStatusToStr(DriverStatus s) {
  switch (s) {
    case DriverStatus::OK:
      return "OK";
    case DriverStatus::INITIALIZATION_ERROR:
      return "INITIALIZATION_ERROR";
    case DriverStatus::COMMUNICATION_ERROR:
      return "COMMUNICATION_ERROR";
    case DriverStatus::INVALID_PARAMETER:
      return "INVALID_PARAMETER";
    case DriverStatus::HARDWARE_FAULT:
      return "HARDWARE_FAULT";
    case DriverStatus::TIMEOUT:
      return "TIMEOUT";
    default:
      return "UNKNOWN";
  }
}
 
enum class ChannelState : uint8_t {
  DISABLED = 0, 
  ENABLED,      
  HIT_PHASE,    
  HOLD_PHASE,   
  FAULT         
};
 
using ChannelConfigArray = std::array<ChannelConfig, NUM_CHANNELS_>;
 
using FaultCallback = void (*)(uint8_t channel, FaultType fault_type,
                               void *user_data);
 
using StateChangeCallback = void (*)(uint8_t channel, ChannelState old_state,
                                     ChannelState new_state, void *user_data);
 
struct BoardConfig {
  uint32_t full_scale_current_ma; 
  uint32_t max_current_ma;      
  uint8_t  max_duty_percent;    
 
  BoardConfig() : full_scale_current_ma(1000), max_current_ma(0), max_duty_percent(0) {}
 
  BoardConfig(float rref_kohm, bool hfs)
      : full_scale_current_ma(0), max_current_ma(0), max_duty_percent(0) {
    const float kfs = hfs ? 7.5f : 15.0f;  // KFS in kΩ
    full_scale_current_ma = static_cast<uint32_t>((kfs * 1000.0f) / rref_kohm + 0.5f);
  }
 
  bool hasMaxCurrentLimit() const { return max_current_ma > 0u; }
  bool hasMaxDutyLimit() const { return max_duty_percent > 0u; }
  bool hasIfsConfigured() const { return full_scale_current_ma > 0u; }
  uint32_t getFullScaleCurrentMa() const { return full_scale_current_ma; }
  uint32_t getMaxCurrentLimitMa() const { return max_current_ma; }
  uint8_t getMaxDutyLimitPercent() const { return max_duty_percent; }
};
 
struct DutyLimits {
  uint8_t min_percent;  
  uint8_t max_percent;  
 
  DutyLimits() : min_percent(4), max_percent(96) {}
 
  uint8_t getMinPercent() const { return min_percent; }
  uint8_t getMaxPercent() const { return max_percent; }
  bool inRange(float percent) const {
    return percent >= static_cast<float>(min_percent) && percent <= static_cast<float>(max_percent);
  }
  float clamp(float percent) const {
    if (percent <= static_cast<float>(min_percent)) return static_cast<float>(min_percent);
    if (percent >= static_cast<float>(max_percent)) return static_cast<float>(max_percent);
    return percent;
  }
};
 
struct DriverStatistics {
  uint32_t total_transfers;  
  uint32_t failed_transfers; 
  uint32_t fault_events;     
  uint32_t state_changes;    
  uint32_t uptime_ms;        
 
  DriverStatistics()
      : total_transfers(0), failed_transfers(0), fault_events(0),
        state_changes(0), uptime_ms(0) {}
 
  float getSuccessRate() const {
    if (total_transfers == 0) return 100.0f;
    return ((float)(total_transfers - failed_transfers) / total_transfers) * 100.0f;
  }
 
  bool hasFailures() const { return failed_transfers != 0u; }
  bool isHealthy() const { return failed_transfers == 0u; }
  uint32_t getTotalTransfers() const { return total_transfers; }
  uint32_t getFailedTransfers() const { return failed_transfers; }
  uint32_t getFaultEvents() const { return fault_events; }
  uint32_t getStateChanges() const { return state_changes; }
  uint32_t getUptimeMs() const { return uptime_ms; }
};
 
} // namespace max22200