tmc51x0.hpp

Go to the documentation of this file.

 
#pragma once
#include <cstdint>
#include <string>
 
#include "tmc51x0_comm_interface.hpp"
#include "registers/tmc51x0_registers.hpp"
#include "tmc51x0_result.hpp"
#include "tmc51x0_types.hpp"
#include "tmc51x0_version.h"
 
namespace tmc51x0 {
 
template <typename CommType> class TMC51x0 {
public:
  //================================================================================
  // @name Core Initialization and Management
  // @{
  //================================================================================
 
  explicit TMC51x0(CommType &comm, uint8_t daisy_chain_position = 0,
                   uint8_t uart_node_address = 0) noexcept
      : comm_(comm), daisy_chain_position_(daisy_chain_position),
        uart_node_address_(uart_node_address & 0xFF) {}
 
  ~TMC51x0() noexcept {
    // Disable motor on destruction
    if (initialized_) {
      motorControl.Disable();
    }
  }
 
  [[nodiscard]] CommType &GetComm() noexcept { return comm_; }
 
  Result<void> Initialize(const DriverConfig &config = DriverConfig(),
                          bool verbose = true) noexcept;
 
  struct HardResetOptions {
    uint32_t power_off_ms{20};         
    uint32_t power_on_settle_ms{20};   
    bool reinitialize{true};           
    bool prefer_power_cycle{true};     
    bool uart_assume_accessible_at_0{true}; 
    bool verbose{true};                
  };
 
  Result<void> HardReset(const HardResetOptions &opts = HardResetOptions()) noexcept;
 
  [[nodiscard]] DriverConfig GetDriverConfig() const noexcept {
    return driver_config_;
  }
 
  [[nodiscard]] DriverConfig GetDriverConfig(bool &initialized) const noexcept {
    initialized = initialized_;
    return driver_config_;
  }
 
  // NOTE: Heap-heavy string diagnostics are intentionally only available when
  // debug logging is enabled. For embedded targets, prefer LogConfigSummary()
  // and friends (which can be compiled out).
#ifndef TMC51X0_DISABLE_DEBUG_LOGGING
  [[nodiscard]] std::string GetDriverConfigString() const noexcept;
#endif // TMC51X0_DISABLE_DEBUG_LOGGING
 
#ifndef TMC51X0_DISABLE_DEBUG_LOGGING
  void LogConfigSummary(const DriverConfig &cfg, const char *tag = "TMC5160",
                        LogLevel lvl = LogLevel::Info) noexcept;
 
  void LogDerivedInitSummary(const char *tag = "TMC5160",
                             LogLevel lvl = LogLevel::Info) noexcept;
 
  void LogLiveStatusReport(const char *tag = "TMC5160",
                           LogLevel lvl = LogLevel::Info) noexcept;
#endif // TMC51X0_DISABLE_DEBUG_LOGGING
 
  struct MotorCurrentDebugInfo {
    bool initialized{false};          
    uint32_t f_clk_hz{0};             
    MotorSpec motor_spec{};           
    uint8_t calculated_irun{0};       
    uint8_t calculated_ihold{0};      
    uint16_t calculated_global_scaler{0}; 
    uint16_t cached_global_scaler{0}; 
    uint32_t cached_ihold_irun{0};    
  };
 
  [[nodiscard]] MotorCurrentDebugInfo GetMotorCurrentDebugInfo() const noexcept;
 
  // @}
 
  //================================================================================
  // @name Subsystem Interfaces
  // @{
  //================================================================================
 
  //================================================================================
  //================================================================================
  //                                    RAMP CONTROL STRUCT
  //================================================================================
  //================================================================================
 
  struct RampControl {
    explicit RampControl(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> SetRampMode(RampMode mode) noexcept;
 
    Result<RampMode> GetRampMode() noexcept;
 
    Result<bool> IsPositionReached() noexcept;
 
    Result<bool> IsVelocityReached() noexcept;
 
    Result<bool> IsStandstill() noexcept;
 
    Result<void> SetTargetPosition(float value, Unit unit) noexcept;
 
    Result<void> MoveRelative(float offset, Unit unit) noexcept;
 
    Result<float> GetCurrentPosition(Unit unit) noexcept;
 
    Result<float> GetTargetPosition(Unit unit) noexcept;
 
    Result<int32_t> GetCurrentPositionMicrosteps() noexcept;
 
    Result<int32_t> GetTargetPositionMicrosteps() noexcept;
 
    Result<void> SetCurrentPosition(float value, Unit unit,
                                    bool update_encoder = false) noexcept;
 
    Result<void> SetMaxSpeed(float value, Unit unit) noexcept;
 
    Result<void> SetAcceleration(float value, Unit unit) noexcept;
 
    Result<void> SetAccelerations(float accel_val, float decel_val,
                                  Unit unit) noexcept;
 
    Result<void> SetDeceleration(float value, Unit unit) noexcept;
 
    Result<void> SetRampSpeeds(float start_speed, float stop_speed,
                               float transition_speed, Unit unit) noexcept;
 
    Result<float> GetCurrentSpeed(Unit unit) noexcept;
 
    Result<bool> IsTargetReached() noexcept;
 
    Result<bool> IsTargetVelocityReached() noexcept;
 
    Result<void> Stop() noexcept;
 
    Result<void> SetPowerDownDelay(uint8_t tpowerdown) noexcept;
 
    Result<void> SetPowerDownDelayMs(float delay_ms) noexcept;
 
    Result<void> SetZeroWaitTime(uint16_t tzerowait) noexcept;
 
    Result<void> SetZeroWaitTimeMs(float delay_ms) noexcept;
 
    Result<void> ConfigureRamp(const RampConfig &config) noexcept;
 
    Result<void> SetFirstAcceleration(float a1, Unit unit) noexcept;
 
    Result<void> SetFinalDeceleration(float d1, Unit unit) noexcept;
 
  private:
    TMC51x0 &driver_; 
 
    // Internal helper methods (used by unit-aware public methods)
    Result<void> SetTargetPosition(int32_t position) noexcept;
    Result<void> SetCurrentPosition(int32_t position,
                                    bool update_encoder = false) noexcept;
  } rampControl{*this};
 
  //================================================================================
  //================================================================================
  //                                    SWITCHES STRUCT
  //================================================================================
  //================================================================================
  struct Switches {
    explicit Switches(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> ConfigureReferenceSwitch(const ReferenceSwitchConfig &config) noexcept;
 
    Result<ReferenceSwitchConfig> GetReferenceSwitchConfig() noexcept;
 
    Result<void> SetLeftSwitchActiveLevel(ReferenceSwitchActiveLevel active_level) noexcept;
 
    Result<void> SetRightSwitchActiveLevel(ReferenceSwitchActiveLevel active_level) noexcept;
 
    Result<void> SetLeftSwitchStopEnable(bool enable) noexcept;
 
    Result<void> SetRightSwitchStopEnable(bool enable) noexcept;
 
    Result<void> SetLeftSwitchLatchMode(ReferenceLatchMode latch_mode) noexcept;
 
    Result<void> SetRightSwitchLatchMode(ReferenceLatchMode latch_mode) noexcept;
 
    Result<void> SetStopMode(ReferenceStopMode stop_mode) noexcept;
 
    Result<bool> GetReferenceSwitchStatus(bool &right_active,
                                          bool &left_enabled,
                                          bool &right_enabled) noexcept;
 
    Result<float> GetLatchedPosition(Unit unit) noexcept;
 
  private:
    TMC51x0 &driver_;
  } switches{*this};
 
  //================================================================================
  //================================================================================
  //                                    EVENTS STRUCT
  //================================================================================
  //================================================================================
  struct Events {
    explicit Events(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> SetXCompare(float position, Unit unit) noexcept;
 
    Result<float> GetXCompare(Unit unit) const noexcept;
 
    Result<void> ClearRampStatus(uint32_t bits_to_clear) noexcept;
 
  private:
    TMC51x0 &driver_;
  } events{*this};
 
  //================================================================================
  //================================================================================
  //                                    MOTOR CONTROL STRUCT
  //================================================================================
  //================================================================================
 
  struct MotorControl {
    explicit MotorControl(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> Enable() noexcept;
 
    Result<void> Disable() noexcept;
 
    Result<void> SetCurrent(uint8_t irun, uint8_t ihold) noexcept;
 
    Result<void> ConfigureChopper(const ChopperConfig &config) noexcept;
 
    Result<void> SetMicrostepResolution(
        MicrostepResolution mres,
        const MicrostepChangeOptions &opts = MicrostepChangeOptions{}) noexcept;
 
    Result<void> ConfigureStealthChop(const StealthChopConfig &config) noexcept;
 
    Result<void> ConfigureMotorCurrent(const MotorSpec &motor_spec) noexcept;
 
    Result<void> SetGlobalScaler(uint16_t scaler) noexcept;
 
    Result<GlobalConfig> GetGlobalConfig() noexcept;
 
    Result<void> ConfigureCoolStep(const CoolStepConfig &config) noexcept;
 
    Result<void> ConfigureDcStep(const DcStepConfig &config) noexcept;
 
    Result<void> SetMicrostepLookupTable(uint8_t index,
                                         uint32_t value) noexcept;
 
    Result<void> SetMicrostepLookupTableSegmentation(
        uint8_t width_sel_0, uint8_t width_sel_1, uint8_t width_sel_2,
        uint8_t width_sel_3, uint8_t lut_seg_start1, uint8_t lut_seg_start2,
        uint8_t lut_seg_start3) noexcept;
 
    Result<void> SetMicrostepLookupTableStart(uint16_t start_current) noexcept;
 
    Result<void> ConfigureMicrostepLutPreset(MicrostepLutPreset preset) noexcept;
 
    Result<void> ConfigureMicrostepLutCustom(
        const uint32_t lut[8], uint8_t w0, uint8_t w1, uint8_t w2, uint8_t w3,
        uint8_t x1, uint8_t x2, uint8_t x3, uint8_t start_sin,
        uint8_t start_sin90) noexcept;
 
    Result<void> SetupMotorFromSpec(
        const MotorSpec &motor_spec,
        const MechanicalSystem *mechanical_system = nullptr) noexcept;
 
    Result<void> ConfigureGlobalConfig(const GlobalConfig &config) noexcept;
 
    Result<void> SetStealthChopEnabled(bool enabled) noexcept;
 
    Result<ChopperConfig> GetChopperConfig() noexcept;
 
    Result<bool> IsEnabled() noexcept;
 
    Result<bool> IsStealthChopEnabled() noexcept;
 
    Result<bool> IsStealthChopCalibrated() noexcept;
 
    Result<Diag0Config> GetDiag0Config() noexcept;
 
    Result<void> SetDiag0Config(const Diag0Config &config) noexcept;
 
    Result<Diag1Config> GetDiag1Config() noexcept;
 
    Result<void> SetDiag1Config(const Diag1Config &config) noexcept;
 
    Result<void> SetCoilCurrents(int16_t coil_a, int16_t coil_b) noexcept;
 
    Result<void> SetIholdDelayMs(float total_delay_ms) noexcept;
 
  private:
    TMC51x0 &driver_; 
  } motorControl{*this};
 
  //================================================================================
  //================================================================================
  //                                    THRESHOLDS STRUCT
  //================================================================================
  //================================================================================
  struct Thresholds {
    explicit Thresholds(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> SetStealthChopVelocityThreshold(float value, Unit unit) noexcept;
 
    Result<float> GetStealthChopVelocityThreshold(Unit unit) const noexcept;
 
    Result<void> SetTcoolthrs(float threshold, Unit unit) noexcept;
 
    Result<float> GetTcoolthrs(Unit unit) const noexcept;
 
    Result<void> SetHighSpeedThreshold(float value, Unit unit) noexcept;
 
    Result<void> SetDcStepVelocityThreshold(float value, Unit unit) noexcept;
 
    Result<float> GetDcStepVelocityThreshold(Unit unit) const noexcept;
 
    uint32_t GetVdcminRegisterValue() const noexcept;
 
    Result<void> SetModeChangeSpeeds(float pwm_thrs, float cool_thrs,
                                     float high_thrs, Unit unit) noexcept;
 
    uint32_t GetTpwmthrsRegisterValue() const noexcept;
 
    uint32_t GetTcoolthrsRegisterValue() const noexcept;
 
    uint32_t GetThighRegisterValue() const noexcept;
 
    //==========================================================================
    // StealthChop/SpreadCycle Transition Hysteresis
    //==========================================================================
 
    Result<void> SetModeHysteresis(float lower_speed, float upper_speed,
                                   Unit unit) noexcept;
 
    Result<void> UpdateModeHysteresis() noexcept;
 
    Result<void> DisableModeHysteresis() noexcept;
 
    bool IsModeHysteresisEnabled() const noexcept;
 
  private:
    TMC51x0 &driver_;
    
    // Hysteresis state tracking (internal units: TSTEP register values)
    // Note: TSTEP is inverse of velocity (lower TSTEP = higher speed)
    uint32_t hysteresis_to_spreadcycle_tstep_{0};  // Switch to SpreadCycle when TSTEP < this (higher velocity)
    uint32_t hysteresis_to_stealthchop_tstep_{0};  // Switch to StealthChop when TSTEP > this (lower velocity)
    bool hysteresis_enabled_{false};
  } thresholds{*this};
 
  //================================================================================
  //================================================================================
  //                                    POWER STAGE STRUCT
  //================================================================================
  //================================================================================
  struct PowerStage {
    explicit PowerStage(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> ConfigurePowerStage(const PowerStageParameters &config) noexcept;
 
    Result<void> ConfigureShortProtection(const PowerStageParameters &config) noexcept;
 
    Result<void> SetShortProtectionLevels(uint8_t s2vs_level, uint8_t s2g_level,
                                          uint8_t shortfilter,
                                          uint8_t shortdelay) noexcept;
 
  private:
    TMC51x0 &driver_;
  } powerStage{*this};
 
  //================================================================================
  //================================================================================
  //                                    COMMUNICATION STRUCT
  //================================================================================
  //================================================================================
 
  struct Communication {
    explicit Communication(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> SetClkFreq(uint32_t frequency_hz) noexcept {
      return driver_.comm_.SetClkFreq(frequency_hz);
    }
 
    Result<void> SetClkFreq(const ExternalClockConfig &config) noexcept;
 
    Result<void> ConfigureUartNodeAddress(uint8_t node_address,
                                          uint8_t send_delay = 0) noexcept;
 
    void SetDaisyChainPosition(uint8_t position) noexcept {
      driver_.daisy_chain_position_ = position;
    }
 
    [[nodiscard]] uint8_t GetDaisyChainPosition() const noexcept {
      return driver_.daisy_chain_position_;
    }
 
    void SetUartNodeAddress(uint8_t address) noexcept {
      driver_.uart_node_address_ =
          address & 0xFF; // Address range is 0-254 (8-bit)
    }
 
    [[nodiscard]] uint8_t GetUartNodeAddress() const noexcept {
      return driver_.uart_node_address_;
    }
 
  private:
    TMC51x0 &driver_; 
  } communication{*this};
 
  //================================================================================
  //================================================================================
  //                                    IO / PINS STRUCT
  //================================================================================
  //================================================================================
  struct Io {
    explicit Io(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> SetOperatingMode(ChipCommMode mode) noexcept;
 
    Result<ChipCommMode> GetOperatingMode() const noexcept;
 
    Result<InputStatus> ReadInputStatus() noexcept;
 
    Result<uint8_t> ReadIcVersion() noexcept;
 
    Result<uint32_t> ReadGpioPins() noexcept;
 
    Result<void> SetSdoCfg0Polarity(bool polarity) noexcept;
 
  private:
    TMC51x0 &driver_;
  } io{*this};
 
  //================================================================================
  //================================================================================
  //                                    ENCODER STRUCT
  //================================================================================
  //================================================================================
 
  struct Encoder {
    explicit Encoder(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void> Configure(const EncoderConfig &config) noexcept;
 
    Result<EncoderConfig> GetEncoderConfig() noexcept;
 
    Result<void>
    SetNChannelActiveLevel(ReferenceSwitchActiveLevel active_level) noexcept;
 
    Result<void>
    SetNChannelSensitivity(EncoderNSensitivity sensitivity) noexcept;
 
    Result<void> SetClearMode(EncoderClearMode clear_mode) noexcept;
 
    Result<void> SetPrescalerMode(EncoderPrescalerMode prescaler_mode) noexcept;
 
    Result<void> SetLatchXactualEnabled(bool enable) noexcept;
 
    Result<bool> IsLatchXactualEnabled() noexcept;
 
    Result<int32_t> GetPosition() noexcept;
 
    Result<void> SetResolution(int32_t motor_steps, int32_t enc_resolution,
                               bool inverted = false) noexcept;
 
    Result<void> SetAllowedDeviation(int32_t steps) noexcept;
 
    Result<bool> IsNEventDetected() noexcept;
 
    Result<void> ClearNEventFlag() noexcept;
 
    Result<int32_t> GetLatchedPosition() noexcept;
 
    //==========================================================================
    // Encoder Deviation Detection
    //==========================================================================
 
    Result<bool> IsDeviationWarning() noexcept;
 
    Result<void> ClearDeviationWarning() noexcept;
 
  private:
    TMC51x0 &driver_; 
  } encoder{*this};
 
  //================================================================================
  //================================================================================
  //                                    STATUS STRUCT
  //================================================================================
  //================================================================================
 
  struct Status {
    explicit Status(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    DriverStatus GetStatus() noexcept;
 
    Result<bool> GetGlobalStatus(bool &drv_err, bool &uv_cp) noexcept;
 
    Result<void> ClearGlobalStatus(bool clear_reset = true,
                                   bool clear_drv_err = true,
                                   bool clear_uv_cp = true) noexcept;
 
    Result<uint32_t> GetDriverStatusRegister() noexcept;
 
    Result<bool> IsOpenLoadA() noexcept;
 
    Result<bool> IsOpenLoadB() noexcept;
 
    Result<bool> CheckOpenLoad(bool &phase_a, bool &phase_b) noexcept;
 
    //==========================================================================
    // Temperature Status (DRV_STATUS bits 25-26)
    //==========================================================================
 
    Result<bool> IsOvertemperature() noexcept;
 
    Result<bool> IsOvertempWarning() noexcept;
 
    Result<void> GetTemperatureStatus(bool &overtemp, bool &prewarning) noexcept;
 
    //==========================================================================
    // Chopper Mode Status (DRV_STATUS bits 14-15)
    //==========================================================================
 
    Result<bool> IsStealthChopActive() noexcept;
 
    Result<bool> IsFullstepActive() noexcept;
 
    //==========================================================================
    // Current Status (DRV_STATUS bits 16-20)
    //==========================================================================
 
    Result<uint8_t> GetActualCurrentScale() noexcept;
 
    //==========================================================================
    // Short Circuit Status (DRV_STATUS bits 12-13, 27-28)
    //==========================================================================
 
    Result<void> IsShortToSupply(bool &phase_a, bool &phase_b) noexcept;
 
    Result<void> IsShortToGround(bool &phase_a, bool &phase_b) noexcept;
 
    Result<void> GetShortCircuitStatus(bool &s2vs_a, bool &s2vs_b,
                                       bool &s2g_a, bool &s2g_b) noexcept;
 
    Result<uint32_t> GetRampStatusRegister() noexcept;
 
    Result<uint32_t> GetLostSteps() noexcept;
 
    Result<uint32_t> GetTimeBetweenMicrosteps() noexcept;
 
    Result<uint16_t> GetMicrostepCounter() noexcept;
 
    Result<int16_t> GetMicrostepCurrent(int16_t &phase_b) noexcept;
 
    Result<uint8_t> GetPwmScale(int16_t &pwm_scale_auto) noexcept;
 
    Result<uint8_t> GetPwmAuto(uint8_t &pwm_grad_auto) noexcept;
 
    Result<uint8_t> ReadFactoryConfig() noexcept;
 
    Result<uint8_t> ReadOtpConfig(bool &otp_s2_level, bool &otp_bbm,
                                  bool &otp_tbl) noexcept;
 
    Result<uint8_t> GetUartTransmissionCount() noexcept;
 
    Result<uint8_t> ReadOffsetCalibration(uint8_t &phase_b) noexcept;
 
    Result<void> VerifySetup() noexcept;
 
    uint8_t GetChipVersion() const noexcept { return driver_.chip_version_; }
 
    //==========================================================================
    // OTP Programming (One-Time Programmable Memory)
    //==========================================================================
 
    Result<void> ProgramOtpBit(uint8_t byte_index, uint8_t bit_index,
                               bool confirm_permanent) noexcept;
 
    Result<void> ProgramOtpFclktrim(uint8_t fclktrim,
                                    bool confirm_permanent) noexcept;
 
    Result<void> ProgramOtpS2Level(bool high_level,
                                   bool confirm_permanent) noexcept;
 
    Result<void> ProgramOtpBbm(bool short_bbm,
                               bool confirm_permanent) noexcept;
 
    Result<void> ProgramOtpTbl(bool short_tbl,
                               bool confirm_permanent) noexcept;
 
  private:
    TMC51x0 &driver_; 
  } status{*this};
 
  //================================================================================
  //================================================================================
  //                                    STALLGUARD STRUCT
  //================================================================================
  //================================================================================
  struct StallGuard {
    explicit StallGuard(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<uint16_t> GetStallGuard() noexcept;
 
    Result<uint16_t> GetStallGuardResult() noexcept;
 
    Result<void> ConfigureStallGuard(const StallGuardConfig &config) noexcept;
 
    Result<void> EnableStopOnStall(bool enable) noexcept;
 
    Result<bool> IsStopOnStallEnabled() noexcept;
 
    Result<void> SetSoftStop(bool enable) noexcept;
 
    Result<bool> IsSoftStopEnabled() noexcept;
 
    Result<void> ClearStallFlag() noexcept;
 
    Result<bool> IsStallDetected() noexcept;
 
  private:
    TMC51x0 &driver_;
  } stallGuard{*this};
 
  //================================================================================
  //================================================================================
  //                                    TUNING STRUCT
  //================================================================================
  //================================================================================
 
  struct Tuning {
    explicit Tuning(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    Result<void>
    TuneStallGuard(float target_velocity, StallGuardTuningResult &result,
                   int8_t min_sgt = -20, int8_t max_sgt = 20,
                   float acceleration = 5.0F, float min_velocity = 0.0F,
                   float max_velocity = 0.0F,
                   Unit velocity_unit = Unit::RPM,
                   Unit acceleration_unit = Unit::RevPerSec) noexcept;
 
    Result<void>
    AutoTuneStallGuard(float target_velocity, StallGuardTuningResult &result,
                       int8_t min_sgt = -20, int8_t max_sgt = 20,
                       float acceleration = 5.0F, float min_velocity = 0.0F,
                       float max_velocity = 0.0F,
                       Unit velocity_unit = Unit::RPM,
                       Unit acceleration_unit = Unit::RevPerSec,
                       float current_reduction_factor = 0.3F) noexcept;
 
  private:
    TMC51x0 &driver_; 
  } tuning{*this};
 
  //================================================================================
  //================================================================================
  //                                    HOMING STRUCT
  //================================================================================
  //================================================================================
 
  struct Homing {
    explicit Homing(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    // Bounds finding helpers
    enum class BoundsMethod { StallGuard, Encoder, Switch };
    enum class HomePlacement { None, AtMin, AtMax, AtCenter, AtOffsetFromMin };
 
    struct BoundsResult {
      bool success{false};
      bool bounded{false};    
      bool cancelled{false};
      float min_bound{0.0F};  
      float max_bound{0.0F};  
    };
 
    using CancelCallback = bool (*)();
 
    struct HomeConfig {
      HomePlacement mode{HomePlacement::AtCenter};
      float offset{0.0F};         
      Unit offset_unit{Unit::Deg};
    };
 
    struct BoundsOptions {
      // Units
      Unit speed_unit{Unit::RPM};
      Unit position_unit{Unit::Deg};
      Unit accel_unit{Unit::RevPerSec}; 
 
      // Motion behavior
      float search_speed{0.0F};    
      float search_span{360.0F};   
      float backoff_distance{5.0F};
      uint32_t timeout_ms{30000};  
      bool search_positive_first{true}; 
      bool preflight_clear_active_switch{true}; 
 
      // Optional accel/decel override (applies to bounds finding and homing moves that configure positioning ramps).
      // If 0, the routines use the cached driver acceleration/deceleration, or a conservative default.
      float search_accel{0.0F}; 
      float search_decel{0.0F}; 
 
      // StallGuard-only (ignored for Encoder/Switch)
      float current_reduction_factor{0.3F};   
      uint16_t current_reduction_target_mA{0};
      const StallGuardConfig* stallguard_override{nullptr}; 
    };
 
    Result<void> PerformSensorlessHoming(bool direction, const BoundsOptions& opt,
                                         int32_t &final_position,
                                         CancelCallback should_cancel = nullptr) noexcept;
 
    Result<void> PerformSwitchHoming(bool direction, const BoundsOptions& opt,
                                     int32_t &final_position,
                                     bool use_left_switch,
                                     CancelCallback should_cancel = nullptr) noexcept;
 
    Result<void> PerformEncoderIndexHoming(bool direction, const BoundsOptions& opt,
                                           int32_t &final_position,
                                     CancelCallback should_cancel = nullptr) noexcept;
 
    Result<BoundsResult>
    FindBoundsStallGuard(const BoundsOptions& opt, const HomeConfig& home = {},
                         CancelCallback should_cancel = nullptr) noexcept;
 
    Result<BoundsResult>
    FindBoundsEncoder(const BoundsOptions& opt, const HomeConfig& home = {},
                      CancelCallback should_cancel = nullptr) noexcept;
 
    Result<BoundsResult>
    FindBoundsSwitch(const BoundsOptions& opt, const HomeConfig& home = {},
                     CancelCallback should_cancel = nullptr) noexcept;
 
    Result<BoundsResult>
    FindBounds(BoundsMethod method, const BoundsOptions& opt, const HomeConfig& home = {},
               CancelCallback should_cancel = nullptr) noexcept;
 
  private:
    TMC51x0 &driver_;
    HomingSettingsCache cache_{};
 
    Result<void> CacheCurrentSettings() noexcept;
    Result<void> RestoreCachedSettings() noexcept;
    Result<void>
    EnsureSpreadCycleForStallGuard() noexcept; // Disable StealthChop if needed
 
    Result<void> ApplyHomePlacement(BoundsResult& out, float raw_min, float raw_max,
                                    const HomeConfig& home, const BoundsOptions& opt) noexcept;
  } homing{*this};
 
  //================================================================================
  //================================================================================
  //                                    PRINTER STRUCT
  //================================================================================
  //================================================================================
 
  struct Printer {
    explicit Printer(TMC51x0 &driver) noexcept : driver_(driver) {}
 
    void PrintGconf() noexcept;
 
    void PrintGstat() noexcept;
 
    void PrintRampStat() noexcept;
 
    void PrintDrvStatus() noexcept;
 
    void PrintChopconf() noexcept;
 
    void PrintPwmconf() noexcept;
 
    void PrintPwmScale() noexcept;
 
    void PrintSwMode() noexcept;
 
    void PrintIoin() noexcept;
 
    void PrintAll() noexcept;
 
  private:
    TMC51x0 &driver_;
 
    void PrintRegisterField(const char *name, uint32_t value,
                            const char *format = "0x%08X") noexcept;
  } printer{*this};
 
  struct UartConfig {
    TMC51x0 *driver_; 
 
    explicit UartConfig(TMC51x0 *driver) noexcept : driver_(driver) {}
 
    Result<void> ConfigureUartNodeAddress(uint8_t node_address,
                                          uint8_t send_delay) noexcept;
  } uartConfig{this};
 
  // @}
 
protected:
  [[nodiscard]] uint8_t GetCommAddress() const noexcept {
    return (comm_.GetMode() == CommMode::UART) ? uart_node_address_
                                               : daisy_chain_position_;
  }
 
  Result<void> Reset() noexcept;
 
public:
  [[nodiscard]] bool IsInitialized() const noexcept { return initialized_; }
 
  // ===========================================================================
  // Driver Version (public: the documented way to log the library version)
  // ===========================================================================
 
  static constexpr const char* GetDriverVersion() noexcept {
    return HF_TMC51X0_VERSION_STRING;
  }
 
  static constexpr uint8_t GetDriverVersionMajor() noexcept {
    return HF_TMC51X0_VERSION_MAJOR;
  }
 
  static constexpr uint8_t GetDriverVersionMinor() noexcept {
    return HF_TMC51X0_VERSION_MINOR;
  }
 
  static constexpr uint8_t GetDriverVersionPatch() noexcept {
    return HF_TMC51X0_VERSION_PATCH;
  }
 
private:
  Result<bool> IsInternalRampMode() noexcept;
 
  Result<void> RequireInternalRampMode() noexcept;
 
  CommType &comm_; 
  uint32_t f_clk_{ClockFreq::DEFAULT_F_CLK}; 
  uint8_t daisy_chain_position_; 
  uint8_t uart_node_address_;    
  uint8_t send_delay_{
      0}; 
  bool initialized_{false};                    
  uint8_t chip_version_{ChipVersion::TMC5160}; 
 
  // Physical configuration for unit conversions
  MotorSpec motor_spec_;
  MechanicalSystem mechanical_system_;
 
  // Driver configuration (updated on all runtime changes)
  // Represents the current runtime state, updated whenever any Configure*
  // method is called
  DriverConfig driver_config_;
 
  // Calculated motor current settings (stored internally, not in MotorSpec)
  uint16_t calculated_global_scaler_{0};
  uint8_t calculated_irun_{0};
  uint8_t calculated_ihold_{0};
  uint16_t current_microsteps_{256};
 
  // Write-only register tracking (for easy access to current values)
  // These registers cannot be read back, so we track them locally
  struct WriteOnlyRegisters {
    uint32_t x_compare{0};     
    uint32_t short_conf{0};    
    uint32_t drv_conf{0};      
    uint16_t global_scaler{0}; 
    uint32_t ihold_irun{0};    
    uint8_t tpowerdown{0};     
    uint32_t tpwmthrs{0};      
    uint32_t tcoolthrs{0};     
    uint32_t thigh{0};         
    uint32_t vstart{0};        
    uint32_t a1{0};            
    uint32_t v1{0};            
    uint32_t amax{0};          
    uint32_t vmax{0};          
    uint32_t dmax{0};          
    uint32_t d1{0};            
    uint32_t vstop{0};         
    uint32_t tzerowait{0};     
    uint32_t vdcmin{0};        
    uint32_t enc_const{0};     
    uint32_t enc_deviation{0}; 
    uint32_t coolconf{0};      
    uint32_t dcctrl{0};        
    uint32_t pwmconf{0};       
    uint32_t nodeconf{0};      
  } write_only_regs_;
 
  [[nodiscard]] float convertSpeedToSteps(float value,
                                          Unit unit) const noexcept;
 
  [[nodiscard]] float convertAccelerationToSteps(float value,
                                                 Unit unit) const noexcept;
 
  [[nodiscard]] bool IsUnitConvertible(Unit unit) const noexcept;
 
  [[nodiscard]] float convertPositionToSteps(float value,
                                             Unit unit) const noexcept;
 
  [[nodiscard]] float convertStepsToUnit(int32_t steps,
                                         Unit unit) const noexcept;
 
  [[nodiscard]] float convertSpeedToUnit(float steps_per_sec,
                                         Unit unit) const noexcept;
 
  [[nodiscard]] int32_t speedToInternal(float speed_hz) const noexcept;
 
  [[nodiscard]] float speedFromInternal(int32_t speed_internal) const noexcept;
 
  [[nodiscard]] int32_t accelToInternal(float accel_hz) const noexcept;
 
  [[nodiscard]] float accelFromInternal(int32_t accel_internal) const noexcept;
 
  [[nodiscard]] int32_t thresholdSpeedToTstep(float speed_hz) const noexcept;
};
 
// Public API: Get driver version string
inline const char* GetDriverVersion() noexcept {
  return HF_TMC51X0_VERSION_STRING;
}
 
} // namespace tmc51x0
 
// Include template implementation
#ifndef TMC51X0_COMPILING_SRC
#define TMC51X0_HEADER_INCLUDED
// NOLINTNEXTLINE(bugprone-suspicious-include) - Intentional: template
// implementation file
#include "tmc51x0.ipp"  // src/ in the source tree, next to this header once installed
#undef TMC51X0_HEADER_INCLUDED
#endif