tmc51x0_types.hpp

Go to the documentation of this file.

 
#pragma once
#include <cstdint>
#include "registers/tmc51x0_registers.hpp"
 
namespace tmc51x0 {
 
namespace ClockFreq {
constexpr uint32_t DEFAULT_F_CLK = 12000000U; 
constexpr uint32_t MIN_F_CLK = 8000000U;      
constexpr uint32_t MAX_F_CLK = 16000000U;     
} // namespace ClockFreq
 
namespace ChipVersion {
constexpr uint8_t TMC5130 = 0x11; 
constexpr uint8_t TMC5160 = 0x30; 
} // namespace ChipVersion
 
namespace RegisterConstants {
constexpr float TPOWERDOWN_DIVISOR = 262144.0F;  
constexpr float MS_PER_SEC = 1e3F;              
constexpr float US_PER_SEC = 1e6F;           
constexpr float NS_PER_SEC = 1e9F;        
constexpr float ENC_DECIMAL_MULTIPLIER = 1e4F; 
constexpr uint32_t ENC_BINARY_MULTIPLIER = 65536U; 
} // namespace RegisterConstants
 
namespace MathConstants {
constexpr float PI = 3.14159265359F;        
constexpr float TWO_PI = 2.0F * PI;        
constexpr float DEGREES_PER_REV = 360.0F;  
} // namespace MathConstants
 
 
//===============================================================================================================
//===============================================================================================================
//                                    ENUMERATIONS
//===============================================================================================================
//===============================================================================================================
 
enum class ChipCommMode : uint8_t {
  SPI_INTERNAL_RAMP =
      0, 
  SPI_EXTERNAL_STEPDIR = 1, 
  UART_INTERNAL_RAMP =
      2, 
  STANDALONE_EXTERNAL_STEPDIR =
      3 
};
 
enum class MotorDirection : uint8_t {
  NORMAL = 0, 
  INVERSE = 1 
};
 
inline constexpr const char* ToString(MotorDirection d) noexcept {
  switch (d) {
  case MotorDirection::NORMAL:
    return "NORMAL";
  case MotorDirection::INVERSE:
    return "INVERSE";
  default:
    return "Unknown";
  }
}
 
enum class MotorType : uint8_t {
  STEPPER = 0,         
  DC_MOTOR_SINGLE = 1, 
  DC_MOTOR_DUAL = 2,   
  SOLENOID_SINGLE = 3, 
  SOLENOID_DUAL = 4    
};
 
inline constexpr const char* ToString(MotorType t) noexcept {
  switch (t) {
  case MotorType::STEPPER:
    return "STEPPER";
  case MotorType::DC_MOTOR_SINGLE:
    return "DC_MOTOR_SINGLE";
  case MotorType::DC_MOTOR_DUAL:
    return "DC_MOTOR_DUAL";
  case MotorType::SOLENOID_SINGLE:
    return "SOLENOID_SINGLE";
  case MotorType::SOLENOID_DUAL:
    return "SOLENOID_DUAL";
  default:
    return "Unknown";
  }
}
 
enum class Unit : uint8_t {
  Steps,     
  Rad,       
  Deg,       
  Mm,        
  RPM,       
  RevPerSec  
};
 
inline constexpr const char* ToString(Unit u) noexcept {
  switch (u) {
  case Unit::Steps:
    return "Steps";
  case Unit::Rad:
    return "Rad";
  case Unit::Deg:
    return "Deg";
  case Unit::Mm:
    return "Mm";
  case Unit::RPM:
    return "RPM";
  case Unit::RevPerSec:
    return "RevPerSec";
  default:
    return "Unknown";
  }
}
 
enum class DriverStatus : uint8_t {
  OK,        
  CP_UV,     
  S2VSA,     
  S2VSB,     
  S2GA,      
  S2GB,      
  OT,        
  OTHER_ERR, 
  OTPW       
};
 
//===============================================================================================================
//===============================================================================================================
//                                    RESPONSE STRUCTURES
//===============================================================================================================
//===============================================================================================================
 
struct InputStatus {
  bool refl_step{false};      
  bool refr_dir{false};       
  bool encb_dcen_cfg4{false}; 
  bool enca_dcin_cfg5{false}; 
  bool drv_enn{false};        
  bool enc_n_dco_cfg6{false}; 
  bool sd_mode{false};        
  bool swcomp_in{false};      
  uint8_t version{0};         
};
 
//===============================================================================================================
//===============================================================================================================
//                        HIGHER LEVEL - MECHANICAL SYSTEM CONFIGURATION STRUCTURES
//===============================================================================================================
//===============================================================================================================
 
enum class MechanicalSystemType : uint8_t {
  DirectDrive, 
  LeadScrew,   
  BeltDrive,   
  Gearbox      
};
 
inline constexpr const char* ToString(MechanicalSystemType type) noexcept {
  switch (type) {
  case MechanicalSystemType::DirectDrive:
    return "DirectDrive";
  case MechanicalSystemType::LeadScrew:
    return "LeadScrew";
  case MechanicalSystemType::BeltDrive:
    return "BeltDrive";
  case MechanicalSystemType::Gearbox:
    return "Gearbox";
  default:
    return "Unknown";
  }
}
 
struct MechanicalSystem {
  MechanicalSystemType system_type{MechanicalSystemType::DirectDrive}; 
  float lead_screw_pitch_mm{0.0F};                                     
  uint16_t belt_pulley_teeth{0}; 
  float belt_pitch_mm{0.0F};     
  float gear_ratio{1.0F};        
 
  MechanicalSystem() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                    MOTOR SPECIFICATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
struct MotorSpec {
  // Motor type (for documentation and configuration purposes)
  MotorType motor_type{MotorType::STEPPER}; 
 
  // Motor electrical specifications
  uint16_t steps_per_rev{200};         
  uint16_t rated_current_ma{1500};     
  uint32_t winding_resistance_mohm{3}; 
  float winding_inductance_mh{0.0F}; 
 
  // Desired current settings (used for calculation, not stored as register values)
  uint16_t run_current_ma{0};  
  uint16_t hold_current_ma{0}; 
 
  // Driver hardware configuration (required for automatic current calculation)
  uint32_t sense_resistor_mohm{50};  
  uint32_t supply_voltage_mv{24000}; 
 
  float scaler_adjustment_percent{0.0F};
 
  float irun_adjustment_percent{0.0F};
 
  float ihold_adjustment_percent{0.0F};
 
  float iholddelay_ms{100.0F}; 
 
  MotorSpec() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                              GATE DRIVER - POWER STAGE CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class SenseFilterTime : uint8_t {
  T100ns = 0, 
  T200ns = 1, 
  T300ns = 2, 
  T400ns = 3  
};
 
enum class OverTempProtection : uint8_t {
  Temp150C = 0, 
  Temp143C = 1, 
  Temp136C = 2, 
  Temp120C = 3  
};
 
struct PowerStageParameters {
  float mosfet_miller_charge_nc{10.0F};
 
  uint32_t bbm_time_ns{100};
 
  SenseFilterTime sense_filter{SenseFilterTime::T100ns};
 
  OverTempProtection over_temp_protection{OverTempProtection::Temp150C};
 
  uint16_t s2vs_voltage_mv{0};
 
  uint16_t s2g_voltage_mv{0};
 
  uint8_t shortfilter{1};
 
  uint8_t short_detection_delay_us_x10{0};
 
  PowerStageParameters() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                               CHOPPER CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class ChopperMode : bool {
  SPREAD_CYCLE = false, 
  CLASSIC = true        
};
 
inline constexpr const char* ToString(ChopperMode m) noexcept {
  return (m == ChopperMode::SPREAD_CYCLE) ? "SPREAD_CYCLE" : "CLASSIC";
}
 
enum class ChopperBlankTime : uint8_t {
  TBL_16CLK = 0, 
  TBL_24CLK = 1, 
  TBL_36CLK = 2, 
  TBL_54CLK = 3  
};
 
enum class MicrostepResolution : uint8_t {
  MRES_256 = 0, 
  MRES_128 = 1, 
  MRES_64 = 2,  
  MRES_32 = 3,  
  MRES_16 = 4,  
  MRES_8 = 5,   
  MRES_4 = 6,   
  MRES_2 = 7,   
  FULLSTEP = 8  
};
 
inline constexpr const char* ToString(MicrostepResolution mres) noexcept {
  switch (mres) {
  case MicrostepResolution::MRES_256:
    return "MRES_256";
  case MicrostepResolution::MRES_128:
    return "MRES_128";
  case MicrostepResolution::MRES_64:
    return "MRES_64";
  case MicrostepResolution::MRES_32:
    return "MRES_32";
  case MicrostepResolution::MRES_16:
    return "MRES_16";
  case MicrostepResolution::MRES_8:
    return "MRES_8";
  case MicrostepResolution::MRES_4:
    return "MRES_4";
  case MicrostepResolution::MRES_2:
    return "MRES_2";
  case MicrostepResolution::FULLSTEP:
    return "FULLSTEP";
  default:
    return "Unknown";
  }
}
 
inline constexpr uint16_t MicrostepsPerFullStep(MicrostepResolution mres) noexcept {
  const uint8_t enc = static_cast<uint8_t>(mres);
  const uint8_t clamped = (enc > 8U) ? 8U : enc;
  return static_cast<uint16_t>(256U >> clamped);
}
 
enum class MicrostepLutPreset : uint8_t {
  DEFAULT_SINE = 0,
 
  PURE_SINE = 1
};
 
inline constexpr const char* ToString(MicrostepLutPreset preset) noexcept {
  switch (preset) {
  case MicrostepLutPreset::DEFAULT_SINE:
    return "DEFAULT_SINE";
  case MicrostepLutPreset::PURE_SINE:
    return "PURE_SINE";
  default:
    return "Unknown";
  }
}
 
struct MicrostepChangeOptions {
  bool preserve_physical_units{true};
 
  bool require_standstill{true};
 
  bool rescale_encoder{true};
};
 
struct ChopperConfig {
  ChopperMode mode{ChopperMode::SPREAD_CYCLE}; 
 
  uint8_t toff{5}; 
 
  uint8_t tbl{2}; 
 
  uint8_t hstrt{4}; 
 
  uint8_t hend{0}; 
 
  uint8_t tfd{0}; 
 
  bool disfdcc{false}; 
 
  uint8_t tpfd{0}; 
 
  MicrostepResolution mres{MicrostepResolution::MRES_256}; 
 
  bool intpol{true}; 
 
  bool dedge{false}; 
 
  bool vhighfs{false}; 
 
  bool vhighchm{false}; 
 
  bool diss2g{false}; 
 
  bool diss2vs{false}; 
 
  ChopperConfig() = default;
 
  ChopperConfig(uint8_t off_time, uint8_t blank_time = 2, uint8_t hysteresis_start = 4, uint8_t hysteresis_end = 0,
                MicrostepResolution microstep_res = MicrostepResolution::MRES_256)
      : toff(off_time), tbl(blank_time), hstrt(hysteresis_start), hend(hysteresis_end), mres(microstep_res) {}
 
  ChopperConfig(uint8_t off_time, uint8_t fast_decay_time, uint8_t sine_offset, uint8_t blank_time = 2,
                bool disable_comparator = false, MicrostepResolution microstep_res = MicrostepResolution::MRES_16)
      : mode(ChopperMode::CLASSIC), toff(off_time), tbl(blank_time), hstrt(0) // Not used in Classic mode
        ,
        hend(sine_offset) // Used as OFFSET in Classic mode
        ,
        tfd(fast_decay_time), disfdcc(disable_comparator), mres(microstep_res) {}
};
 
//===============================================================================================================
//===============================================================================================================
//                                 STEALTHCHOP CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class StealthChopPwmFreq : uint8_t {
  PWM_FREQ_0 = 0, 
  PWM_FREQ_1 = 1, 
  PWM_FREQ_2 = 2, 
  PWM_FREQ_3 = 3  
};
 
enum class StealthChopRegulationSpeed : uint8_t {
  VERY_SLOW = 1, 
  SLOW = 2,      
  MODERATE = 4,  
  FAST = 8,      
  VERY_FAST = 15 
};
 
enum class StealthChopJerkReduction : uint8_t {
  MAXIMUM = 8,   
  HIGH = 10,     
  MODERATE = 12, 
  LOW = 14,      
  MINIMUM = 15   
};
 
struct StealthChopConfig {
  uint8_t pwm_ofs{30}; 
 
  uint8_t pwm_grad{0}; 
 
  uint8_t pwm_freq{1}; 
 
  bool pwm_autoscale{true}; 
 
  bool pwm_autograd{true}; 
 
  uint8_t pwm_reg{4}; 
 
  uint8_t pwm_lim{12}; 
 
  PWMFreewheel freewheel{PWMFreewheel::NORMAL}; 
 
  float velocity_threshold{0.0F}; 
 
  Unit velocity_threshold_unit{Unit::Steps}; 
 
  StealthChopConfig() = default;
 
  StealthChopConfig(uint8_t pwm_frequency, uint8_t pwm_offset = 30, uint8_t pwm_gradient = 0,
                    uint8_t regulation_speed = 4, uint8_t jerk_reduction = 12)
      : pwm_ofs(pwm_offset), pwm_grad(pwm_gradient), pwm_freq(pwm_frequency), pwm_reg(regulation_speed),
        pwm_lim(jerk_reduction) {}
 
  StealthChopConfig(StealthChopPwmFreq pwm_frequency,
                    StealthChopRegulationSpeed regulation_speed = StealthChopRegulationSpeed::MODERATE,
                    StealthChopJerkReduction jerk_reduction = StealthChopJerkReduction::MODERATE,
                    uint8_t pwm_offset = 30, uint8_t pwm_gradient = 0)
      : pwm_ofs(pwm_offset), pwm_grad(pwm_gradient), pwm_freq(static_cast<uint8_t>(pwm_frequency)),
        pwm_reg(static_cast<uint8_t>(regulation_speed)), pwm_lim(static_cast<uint8_t>(jerk_reduction)) {}
 
  StealthChopConfig(uint8_t pwm_frequency, uint8_t pwm_offset, uint8_t pwm_gradient)
      : pwm_ofs(pwm_offset), pwm_grad(pwm_gradient), pwm_freq(pwm_frequency), pwm_autoscale(false), // Manual mode
        pwm_autograd(false)                                                                           // Manual mode
  {}
};
 
//===============================================================================================================
//===============================================================================================================
//                                 STALLGUARD CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class StallGuardSensitivity : int8_t {
  VERY_HIGH = -32, 
  HIGH = -16,      
  MODERATE = 0,    
  LOW = 16,        
  VERY_LOW = 32    
};
 
struct StallGuardConfig {
  int8_t threshold{0}; 
 
  bool enable_filter{false}; 
 
  float min_velocity{0.0F}; 
 
  float max_velocity{0.0F}; 
 
  Unit velocity_unit{Unit::Steps}; 
 
  bool stop_on_stall{false}; 
 
  StallGuardConfig() = default;
 
  StallGuardConfig(int8_t sgt_threshold, bool enable_filt = false, float min_vel = 0.0F, float max_vel = 0.0F,
                   Unit vel_unit = Unit::RevPerSec, bool stop_on_stall = false)
      : threshold(sgt_threshold), enable_filter(enable_filt), min_velocity(min_vel), max_velocity(max_vel),
        velocity_unit(vel_unit), stop_on_stall(stop_on_stall) {}
 
  StallGuardConfig(StallGuardSensitivity sensitivity, bool enable_filt = false, float min_vel = 0.0F,
                   float max_vel = 0.0F, Unit vel_unit = Unit::Steps, bool stop_on_stall = false)
      : threshold(static_cast<int8_t>(sensitivity)), enable_filter(enable_filt), min_velocity(min_vel),
        max_velocity(max_vel), velocity_unit(vel_unit), stop_on_stall(stop_on_stall) {}
};
 
struct StallGuardTuningResult {
  int8_t optimal_sgt{0}; 
 
  bool tuning_success{false}; 
 
  int8_t min_velocity_sgt{0}; 
 
  bool min_velocity_success{false}; 
 
  int8_t max_velocity_sgt{0}; 
 
  bool max_velocity_success{false}; 
 
  float actual_min_velocity{0.0F}; 
 
  float actual_max_velocity{0.0F}; 
 
  uint16_t target_velocity_sg_result{0}; 
 
  uint16_t min_velocity_sg_result{0}; 
 
  uint16_t max_velocity_sg_result{0}; 
 
  StallGuardTuningResult() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                          SELF-DESCRIBING VALUE TYPES WITH UNITS
//===============================================================================================================
//===============================================================================================================
 
struct VelocityValue {
    float value{0.0f};        
    Unit unit{Unit::Steps};   
    
    VelocityValue() = default;
    
    constexpr VelocityValue(float v, Unit u) noexcept : value(v), unit(u) {}
    
    // Factory methods for common units
    static constexpr VelocityValue FromSteps(float v) noexcept { return {v, Unit::Steps}; }
    static constexpr VelocityValue FromRPM(float v) noexcept { return {v, Unit::RPM}; }
    static constexpr VelocityValue FromRevPerSec(float v) noexcept { return {v, Unit::RevPerSec}; }
    static constexpr VelocityValue FromRad(float v) noexcept { return {v, Unit::Rad}; }
    static constexpr VelocityValue FromDeg(float v) noexcept { return {v, Unit::Deg}; }
    static constexpr VelocityValue FromMm(float v) noexcept { return {v, Unit::Mm}; }
};
 
struct AccelerationValue {
    float value{0.0f};        
    Unit unit{Unit::Steps};   
    
    AccelerationValue() = default;
    
    constexpr AccelerationValue(float v, Unit u) noexcept : value(v), unit(u) {}
    
    // Factory methods for common units
    static constexpr AccelerationValue FromSteps(float v) noexcept { return {v, Unit::Steps}; }
    static constexpr AccelerationValue FromRevPerSec(float v) noexcept { return {v, Unit::RevPerSec}; }
    static constexpr AccelerationValue FromRad(float v) noexcept { return {v, Unit::Rad}; }
    static constexpr AccelerationValue FromDeg(float v) noexcept { return {v, Unit::Deg}; }
    static constexpr AccelerationValue FromMm(float v) noexcept { return {v, Unit::Mm}; }
};
 
//===============================================================================================================
//===============================================================================================================
//                                 RAMP CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
struct RampConfig {
  // Velocity parameters (self-describing with explicit units)
  VelocityValue vstart{0.0f, Unit::Steps};  
  VelocityValue vstop{10.0f, Unit::Steps};  
  VelocityValue vmax{0.0f, Unit::Steps};    
  VelocityValue v1{0.0f, Unit::Steps};      
 
  // Acceleration parameters (self-describing with explicit units)
  AccelerationValue amax{0.0f, Unit::Steps};   
  AccelerationValue a1{0.0f, Unit::Steps};     
  AccelerationValue dmax{0.0f, Unit::Steps};   
  AccelerationValue d1{100.0f, Unit::Steps};   
 
  // Timing parameters (in milliseconds, automatically converted to register values)
  float tpowerdown_ms{437.0F}; 
 
  float tzerowait_ms{
      0.0F}; 
 
  RampConfig() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                 COOLSTEP CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class CoolStepIncrementStep : uint8_t {
  STEP_1 = 0, 
  STEP_2 = 1, 
  STEP_4 = 2, 
  STEP_8 = 3  
};
 
enum class CoolStepDecrementSpeed : uint8_t {
  EVERY_32 = 0, 
  EVERY_8 = 1,  
  EVERY_2 = 2,  
  EVERY_1 = 3   
};
 
enum class CoolStepMinCurrent : uint8_t {
  HALF_IRUN = 0,   
  QUARTER_IRUN = 1 
};
 
struct CoolStepConfig {
  uint16_t lower_threshold_sg{0}; 
 
  uint16_t upper_threshold_sg{0}; 
 
  // Step size configuration (using enums for clarity)
  CoolStepIncrementStep increment_step{CoolStepIncrementStep::STEP_2};     
  CoolStepDecrementSpeed decrement_speed{CoolStepDecrementSpeed::EVERY_8}; 
 
  // Minimum current configuration
  CoolStepMinCurrent min_current{CoolStepMinCurrent::HALF_IRUN}; 
 
  // Filter configuration
  bool enable_filter{false}; 
 
  // Velocity thresholds (with unit support)
  float min_velocity{0.0F}; 
 
  float max_velocity{0.0F}; 
 
  Unit velocity_unit{Unit::Steps}; 
 
  CoolStepConfig() = default;
 
  CoolStepConfig(uint16_t lower_sg, uint16_t upper_sg, float min_vel, float max_vel, Unit vel_unit = Unit::RevPerSec)
      : lower_threshold_sg(lower_sg), upper_threshold_sg(upper_sg), min_velocity(min_vel), max_velocity(max_vel),
        velocity_unit(vel_unit) {}
};
 
//===============================================================================================================
//===============================================================================================================
//                                 DCSTEP CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class DcStepStallSensitivity : uint8_t {
  DISABLED = 0, 
  LOW = 1,      
  MODERATE = 2, 
  HIGH = 3      
};
 
struct DcStepConfig {
  float min_velocity{0.0F}; 
 
  Unit velocity_unit{Unit::Steps}; 
 
  float pwm_on_time_us{0.0F}; 
 
  DcStepStallSensitivity stall_sensitivity{DcStepStallSensitivity::MODERATE}; 
 
  bool stop_on_stall{false}; 
 
  DcStepConfig() = default;
 
  DcStepConfig(float min_vel, Unit vel_unit = Unit::RevPerSec, float pwm_time_us = 0.0F,
               DcStepStallSensitivity sensitivity = DcStepStallSensitivity::MODERATE)
      : min_velocity(min_vel), velocity_unit(vel_unit), pwm_on_time_us(pwm_time_us), stall_sensitivity(sensitivity) {}
};
 
//===============================================================================================================
//===============================================================================================================
//                            REFERENCE SWITCHES CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class ReferenceSwitchActiveLevel : uint8_t {
  ACTIVE_LOW, 
  ACTIVE_HIGH 
};
 
inline constexpr const char* ToString(ReferenceSwitchActiveLevel a) noexcept {
  switch (a) {
  case ReferenceSwitchActiveLevel::ACTIVE_LOW:
    return "ACTIVE_LOW";
  case ReferenceSwitchActiveLevel::ACTIVE_HIGH:
    return "ACTIVE_HIGH";
  default:
    return "Unknown";
  }
}
 
enum class ReferenceLatchMode : uint8_t {
  DISABLED,      
  ACTIVE_EDGE,   
  INACTIVE_EDGE, 
  BOTH_EDGES     
};
 
inline constexpr const char* ToString(ReferenceLatchMode m) noexcept {
  switch (m) {
  case ReferenceLatchMode::DISABLED:
    return "DISABLED";
  case ReferenceLatchMode::ACTIVE_EDGE:
    return "ACTIVE_EDGE";
  case ReferenceLatchMode::INACTIVE_EDGE:
    return "INACTIVE_EDGE";
  case ReferenceLatchMode::BOTH_EDGES:
    return "BOTH_EDGES";
  default:
    return "Unknown";
  }
}
 
enum class ReferenceStopMode : uint8_t {
  HARD_STOP, 
  SOFT_STOP  
};
 
inline constexpr const char* ToString(ReferenceStopMode m) noexcept {
  switch (m) {
  case ReferenceStopMode::HARD_STOP:
    return "HARD_STOP";
  case ReferenceStopMode::SOFT_STOP:
    return "SOFT_STOP";
  default:
    return "Unknown";
  }
}
 
struct ReferenceSwitchConfig {
  // Switch active level configuration (determines polarity)
  // Active level must always be specified (ACTIVE_LOW or ACTIVE_HIGH)
  // Use stop_enable to control whether switch stops the motor (allows real-time enable/disable)
  ReferenceSwitchActiveLevel left_switch_active{
      ReferenceSwitchActiveLevel::ACTIVE_LOW}; 
  ReferenceSwitchActiveLevel right_switch_active{
      ReferenceSwitchActiveLevel::ACTIVE_LOW}; 
 
  // Motor stop enable configuration (independent of active level)
  // Allows enabling/disabling motor stop in real-time while keeping polarity configured
  bool left_switch_stop_enable{
      false}; 
  bool right_switch_stop_enable{
      false}; 
 
  // Stop configuration
  ReferenceStopMode stop_mode{
      ReferenceStopMode::SOFT_STOP}; 
  bool swap_left_right{false};       
 
  // Position latching configuration
  ReferenceLatchMode latch_left{ReferenceLatchMode::DISABLED};  
  ReferenceLatchMode latch_right{ReferenceLatchMode::DISABLED}; 
  bool en_latch_encoder{false}; 
 
  ReferenceSwitchConfig() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                ENCODER FEEDBACK CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
enum class EncoderNSensitivity : uint8_t {
  ACTIVE_LEVEL, 
  RISING_EDGE,  
  FALLING_EDGE, 
  BOTH_EDGES    
};
 
inline constexpr const char* ToString(EncoderNSensitivity s) noexcept {
  switch (s) {
  case EncoderNSensitivity::ACTIVE_LEVEL:
    return "ACTIVE_LEVEL";
  case EncoderNSensitivity::RISING_EDGE:
    return "RISING_EDGE";
  case EncoderNSensitivity::FALLING_EDGE:
    return "FALLING_EDGE";
  case EncoderNSensitivity::BOTH_EDGES:
    return "BOTH_EDGES";
  default:
    return "Unknown";
  }
}
 
enum class EncoderClearMode : uint8_t {
  DISABLED,  
  ONCE,      
  CONTINUOUS 
};
 
inline constexpr const char* ToString(EncoderClearMode m) noexcept {
  switch (m) {
  case EncoderClearMode::DISABLED:
    return "DISABLED";
  case EncoderClearMode::ONCE:
    return "ONCE";
  case EncoderClearMode::CONTINUOUS:
    return "CONTINUOUS";
  default:
    return "Unknown";
  }
}
 
enum class EncoderPrescalerMode : uint8_t {
  BINARY, 
  DECIMAL 
};
 
inline constexpr const char* ToString(EncoderPrescalerMode m) noexcept {
  switch (m) {
  case EncoderPrescalerMode::BINARY:
    return "BINARY";
  case EncoderPrescalerMode::DECIMAL:
    return "DECIMAL";
  default:
    return "Unknown";
  }
}
 
struct EncoderConfig {
  // N channel configuration (shares ReferenceSwitchActiveLevel enum)
  // Note: Default initialization done in constructor since enum is forward-declared
  ReferenceSwitchActiveLevel n_channel_active{
      ReferenceSwitchActiveLevel::
          ACTIVE_LOW}; 
 
  // A/B polarity requirements for N channel validation
  bool require_a_high{false};    
  bool require_b_high{false};    
  bool ignore_ab_polarity{true}; 
 
  // N channel event detection
  EncoderNSensitivity n_sensitivity{
      EncoderNSensitivity::ACTIVE_LEVEL}; 
 
  // Clear/latch mode
  EncoderClearMode clear_mode{EncoderClearMode::DISABLED}; 
 
  // Additional encoder features
  bool clear_enc_x_on_event{false};   
  bool latch_xactual_with_enc{false}; 
 
  // Prescaler mode
  EncoderPrescalerMode prescaler_mode{
      EncoderPrescalerMode::BINARY}; 
 
  int32_t allowed_deviation_steps{
      0}; 
 
  uint16_t pulses_per_rev{0}; 
 
  bool invert_direction{false}; 
 
  EncoderConfig() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                DIAGNOSTIC PIN CONFIGURATION STRUCTURES
//===============================================================================================================
//===============================================================================================================
 
struct Diag0Config {
  bool error{false}; 
  bool otpw{false};  
  bool stall_step{
      false}; 
  bool pushpull{false}; 
 
  Diag0Config() = default;
};
 
struct Diag1Config {
  bool stall_dir{false};     
  bool index{false};         
  bool onstate{false};       
  bool steps_skipped{false}; 
  bool pushpull{false};      
 
  Diag1Config() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                EXTERNAL CLOCK CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
struct ExternalClockConfig {
  uint32_t frequency_hz{0}; 
 
  ExternalClockConfig() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                UART CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
struct UartConfig {
  uint8_t node_address{0}; 
 
  uint8_t send_delay{0}; 
 
  UartConfig() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                GLOBAL CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
struct GlobalConfig {
  bool recalibrate{false}; 
  bool en_short_standstill_timeout{
      false}; 
 
  bool en_stealthchop_mode{true};        
  bool en_stealthchop_step_filter{true}; 
 
  bool invert_direction{false}; 
 
  Diag0Config diag0; 
  Diag1Config diag1; 
 
  bool en_small_step_frequency_hysteresis{
      false}; 
  bool enca_dcin_sequencer_stop{false}; 
  bool direct_mode{false};              
 
  GlobalConfig() = default;
};
 
//===============================================================================================================
//===============================================================================================================
//                                DRIVER CONFIGURATION STRUCTURE
//===============================================================================================================
//===============================================================================================================
 
struct DriverConfig {
  MotorSpec motor_spec{};             
  PowerStageParameters power_stage{}; 
  MechanicalSystem mechanical{}; 
 
  MotorDirection direction{MotorDirection::NORMAL}; 
  ChopperConfig chopper{};                          
  StealthChopConfig stealthchop{};                  
  GlobalConfig global_config{};                     
  RampConfig ramp_config{};                         
 
  // Clock configuration
  ExternalClockConfig
      external_clk_config{}; 
 
  // Advanced feature configurations (defaults are safe/disabled)
  StallGuardConfig stallguard{}; 
  CoolStepConfig coolstep{};     
  DcStepConfig dcstep{};         
 
  // Sensor configurations (defaults are safe/disabled)
  // These are typically set by test rig/platform configuration helpers
  // Defaults are safe: switches don't stop motor, encoder clear mode is disabled
  ReferenceSwitchConfig
      reference_switch_config{};  
  EncoderConfig encoder_config{}; 
 
  // UART communication configuration (only used in UART mode)
  UartConfig uart_config{}; 
 
  DriverConfig() noexcept {}
};
 
struct HomingSettingsCache {
    // StealthChop state (must be disabled for StallGuard)
    bool cached_stealthchop_enabled = false;
    bool stealthchop_was_modified = false;
    
    // SW_MODE register (modified by both homing methods)
    SW_MODE_Register cached_sw_mode{};  // Full register value before homing
    bool sw_mode_was_modified = false;
    
    // Ramp settings (modified by both homing methods)
    RampMode cached_ramp_mode = RampMode::POSITIONING;
    float cached_max_speed = 0.0f;
    float cached_acceleration = 0.0f;
    float cached_deceleration = 0.0f;
    float cached_vstart = 0.0f;
    float cached_vstop = 0.0f;
    float cached_v1 = 0.0f;
    bool ramp_settings_were_modified = false;
    
    bool is_valid = false;  // True if cache has been populated
};
 
} // namespace tmc51x0