tmc9660.hpp

Go to the documentation of this file.

 
#pragma once
#include <array>
#include <cmath>
#include <cstdint>
#include <cstdlib>
#include <limits>
#include <memory>
#include <optional>
#include <span>
#include <variant>
#include <vector>
 
#include "tmc9660_comm_interface.hpp"
#include "tmc9660_version.h"
#include "bootloader/tmc9660_bootloader.hpp"
#include "parameter_mode/tmc9660_param_mode_tmcl.hpp"
 
namespace tmc9660 {
 
template <typename CommType>
class TMC9660 {
public:
  //================================================================================
  // @name Core Initialization and Management
  // @{
  //================================================================================
 
  TMC9660(CommType& comm, uint8_t address = 0,
          const tmc9660::BootloaderConfig* bootCfg = nullptr) noexcept;
 
  ~TMC9660() noexcept;
 
  [[nodiscard]] CommType& comm() noexcept {
    return comm_;
  }
 
  //============================================================================
  // @name GPIO Helpers (driver-owned control)
  // @{
  //============================================================================
 
  [[nodiscard]] bool GpioSet(TMC9660CtrlPin pin, GpioSignal signal) noexcept;
  [[nodiscard]] bool GpioRead(TMC9660CtrlPin pin, GpioSignal& signal) noexcept;
  [[nodiscard]] bool GpioSetActive(TMC9660CtrlPin pin) noexcept;
  [[nodiscard]] bool GpioSetInactive(TMC9660CtrlPin pin) noexcept;
 
  // @}
 
  // @}
 
  //================================================================================
  // @name Bootloader Management
  // @{
  //================================================================================
 
  enum class BootloaderInitResult {
    Success,  
    NoConfig, 
    Failure   
  };
 
  TMC9660::BootloaderInitResult bootloaderInit(const tmc9660::BootloaderConfig* cfg = nullptr,
                                               bool performReset = true,
                                               bool retrieveBootloaderInfo = false,
                                               bool failOnVerifyError = true) noexcept;
 
  tmc9660::TMC9660Bootloader<CommType>* getBootloader() noexcept {
    return bootloader_.get();
  }
 
  bool enterBootloaderMode() noexcept {
    // Boot command with magic values per datasheet: TYPE=0x81, MOTOR/BANK=0x92, VALUE=0xA3B4C5D6
    return sendCommand(tmc9660::tmcl::Op::Boot, 0x81, 0x92, 0xA3B4C5D6, nullptr);
  }
 
  // @}
 
  //================================================================================
  // @name Core Parameter Access
  // @{
  //================================================================================
 
  [[nodiscard]] bool writeParameter(tmc9660::tmcl::Parameters id, uint32_t value,
                                    uint8_t motorIndex = 0) noexcept;
 
  [[nodiscard]] bool readParameter(tmc9660::tmcl::Parameters id, uint32_t& value,
                                   uint8_t motorIndex = 0) noexcept;
 
  // Variant type for global parameter banks (can be index or any bank enum)
  using GlobalParamBankVariant =
      std::variant<uint8_t, tmc9660::tmcl::GlobalParamBank0, tmc9660::tmcl::GlobalParamBank2,
                   tmc9660::tmcl::GlobalParamBank3>;
 
  [[nodiscard]] bool writeGlobalParameter(GlobalParamBankVariant id, uint8_t bank,
                                          uint32_t value) noexcept;
 
  [[nodiscard]] bool readGlobalParameter(GlobalParamBankVariant id, uint8_t bank,
                                         uint32_t& value) noexcept;
 
  bool sendCommand(tmc9660::tmcl::Op opcode, uint16_t type = 0, uint8_t motor = 0,
                   uint32_t value = 0, uint32_t* reply = nullptr) noexcept;
 
  // @}
 
  //================================================================================
  // @name Subsystem Interfaces
  // @{
  //================================================================================
 
  struct MotorConfig {
    bool setType(tmc9660::tmcl::MotorType type, uint8_t polePairs = 1) noexcept;
 
    bool setDirection(tmc9660::tmcl::MotorDirection direction) noexcept;
 
    bool setPWMFrequency(uint32_t frequency_hz) noexcept;
 
    bool setCommutationMode(tmc9660::tmcl::CommutationMode mode) noexcept;
 
    bool setOutputVoltageLimit(uint16_t limit) noexcept;
 
    bool getOutputVoltageLimit(uint16_t& limit) noexcept;
 
    bool setMaxTorqueCurrent(uint16_t milliamps) noexcept;
 
    bool setMaxFluxCurrent(uint16_t milliamps) noexcept;
 
    bool setPWMSwitchingScheme(tmc9660::tmcl::PwmSwitchingScheme scheme) noexcept;
 
    bool setIdleMotorPWMBehavior(
        tmc9660::tmcl::IdleMotorPwmBehavior pwmOffWhenIdle =
            tmc9660::tmcl::IdleMotorPwmBehavior::PWM_OFF_WHEN_MOTOR_IDLE) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct MotorProfile {
      // Required parameters
      tmc9660::tmcl::MotorType motorType; 
      uint8_t polePairs;        
      uint32_t pwmFrequency_Hz; 
      float maxPhaseCurrent_A;  
 
      // Optional parameters with defaults
      tmc9660::tmcl::MotorDirection direction =
          tmc9660::tmcl::MotorDirection::FORWARD; 
      tmc9660::tmcl::PwmSwitchingScheme pwmSwitchingScheme =
          tmc9660::tmcl::PwmSwitchingScheme::SVPWM; 
      float maxFluxCurrent_A =
          std::numeric_limits<float>::quiet_NaN(); 
      uint16_t outputVoltageLimit =
          8000; 
      tmc9660::tmcl::IdleMotorPwmBehavior idlePwmBehavior =
          tmc9660::tmcl::IdleMotorPwmBehavior::PWM_OFF_WHEN_MOTOR_IDLE; 
      std::optional<tmc9660::tmcl::CommutationMode>
          commutationMode; 
    };
 
    bool configureAuto(const MotorProfile& profile) noexcept;
 
  private:
    friend class TMC9660;
    explicit MotorConfig(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } motorConfig{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Current Measurement                      **//
  //***************************************************************************
 
  struct CurrentSensing {
 
    bool setShuntType(tmc9660::tmcl::AdcShuntType shuntType) noexcept;
 
    bool getShuntType(tmc9660::tmcl::AdcShuntType& shuntType) noexcept;
 
    bool readRaw(int16_t& adc0, int16_t& adc1, int16_t& adc2, int16_t& adc3) noexcept;
 
    bool setCSAGain(tmc9660::tmcl::CsaGain gain012, tmc9660::tmcl::CsaGain gain3) noexcept;
 
    bool getCSAGain(tmc9660::tmcl::CsaGain& gain012, tmc9660::tmcl::CsaGain& gain3) noexcept;
 
    bool setCSAFilter(tmc9660::tmcl::CsaFilter filter012,
                      tmc9660::tmcl::CsaFilter filter3) noexcept;
 
    bool getCSAFilter(tmc9660::tmcl::CsaFilter& filter012,
                      tmc9660::tmcl::CsaFilter& filter3) noexcept;
 
    bool setScalingFactor(uint16_t scaling_factor) noexcept;
 
    bool getScalingFactor(uint16_t& scaling_factor) noexcept;
 
    bool setPhaseAdcMapping(tmc9660::tmcl::AdcMapping ux1, tmc9660::tmcl::AdcMapping vx2,
                            tmc9660::tmcl::AdcMapping wy1, tmc9660::tmcl::AdcMapping y2) noexcept;
 
    bool getPhaseAdcMapping(tmc9660::tmcl::AdcMapping& ux1, tmc9660::tmcl::AdcMapping& vx2,
                            tmc9660::tmcl::AdcMapping& wy1, tmc9660::tmcl::AdcMapping& y2) noexcept;
 
    bool setScalingFactors(uint16_t scale0, uint16_t scale1, uint16_t scale2,
                           uint16_t scale3) noexcept;
 
    bool getScalingFactors(uint16_t& scale0, uint16_t& scale1, uint16_t& scale2,
                           uint16_t& scale3) noexcept;
 
    bool setInversion(tmc9660::tmcl::AdcInversion inv0, tmc9660::tmcl::AdcInversion inv1,
                      tmc9660::tmcl::AdcInversion inv2, tmc9660::tmcl::AdcInversion inv3) noexcept;
 
    bool getInversion(tmc9660::tmcl::AdcInversion& inv0, tmc9660::tmcl::AdcInversion& inv1,
                      tmc9660::tmcl::AdcInversion& inv2,
                      tmc9660::tmcl::AdcInversion& inv3) noexcept;
 
    bool setOffsets(int16_t offset0, int16_t offset1, int16_t offset2, int16_t offset3) noexcept;
 
    bool getOffsets(int16_t& offset0, int16_t& offset1, int16_t& offset2,
                    int16_t& offset3) noexcept;
 
    bool readScaledAndOffset(int16_t& adc0, int16_t& adc1, int16_t& adc2, int16_t& adc3) noexcept;
 
    bool calibrateOffsets(bool waitForCompletion = false, uint32_t timeoutMs = 1000) noexcept;
 
    bool getCalibrationStatus(bool& is_calibrated) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
    struct AutoConfig {
      // Required parameters
      float shuntResistance_mOhm; 
      float expectedPeakCurrent_A; 
      tmc9660::tmcl::MotorType motorType; 
 
      // Optional parameters with defaults
      bool usePeakScaling =
          true; 
      tmc9660::tmcl::AdcShuntType shuntType =
          tmc9660::tmcl::AdcShuntType::BOTTOM_SHUNTS; 
      tmc9660::tmcl::CsaFilter csaFilter =
          tmc9660::tmcl::CsaFilter::T_1_0_MICROSEC; 
 
      // Per-ADC actual shunt resistances (for automatic ADC_Ix_SCALE compensation)
      // If NaN or <= 0, uses nominal value (no compensation)
      float actualShuntR_adc0_mOhm =
          std::numeric_limits<float>::quiet_NaN(); 
      float actualShuntR_adc1_mOhm =
          std::numeric_limits<float>::quiet_NaN(); 
      float actualShuntR_adc2_mOhm =
          std::numeric_limits<float>::quiet_NaN(); 
      float actualShuntR_adc3_mOhm =
          std::numeric_limits<float>::quiet_NaN(); 
 
      // Per-phase ADC mapping (which ADC channel maps to which motor phase)
      // If not set (std::nullopt), uses defaults: U->I0, V->I1, W->I2, Y2->I3
      std::optional<tmc9660::tmcl::AdcMapping>
          phaseU_adcMapping; 
      std::optional<tmc9660::tmcl::AdcMapping>
          phaseV_adcMapping; 
      std::optional<tmc9660::tmcl::AdcMapping>
          phaseW_adcMapping; 
      std::optional<tmc9660::tmcl::AdcMapping>
          phaseY2_adcMapping; 
 
      // Per-ADC inversion settings
      // If not set (std::nullopt), uses Table 24 defaults based on motor type:
      //   DC:      ADC_I0=INVERTED, ADC_I1=NOT_INVERTED
      //   BLDC:    ADC_I0=INVERTED, ADC_I1=INVERTED, ADC_I2=INVERTED
      //   Stepper: ADC_I0=INVERTED, ADC_I1=NOT_INVERTED, ADC_I2=INVERTED, ADC_I3=NOT_INVERTED
      std::optional<tmc9660::tmcl::AdcInversion>
          adc0_inverted; 
      std::optional<tmc9660::tmcl::AdcInversion>
          adc1_inverted; 
      std::optional<tmc9660::tmcl::AdcInversion>
          adc2_inverted; 
      std::optional<tmc9660::tmcl::AdcInversion>
          adc3_inverted; 
 
      // Auto-calibration settings
      bool autoCalibrate =
          false; 
      uint32_t calibrationTimeoutMs =
          2000; 
    };
 
    bool configureAuto(const AutoConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit CurrentSensing(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } currentSensing{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Gate Driver                              **//
  //***************************************************************************
 
  struct GateDriver {
    bool setOutputPolarity(tmc9660::tmcl::PwmOutputPolarity low_side,
                           tmc9660::tmcl::PwmOutputPolarity high_side) noexcept;
 
    bool configureBreakBeforeMakeTiming(uint8_t low_side_uvw, uint8_t high_side_uvw, uint8_t low_side_y2,
                                        uint8_t high_side_y2) noexcept;
 
    bool configureBreakBeforeMakeTiming_ns(float lowSideUVW_ns, float highSideUVW_ns,
                                           float lowSideY2_ns, float highSideY2_ns) noexcept;
 
    bool enableAdaptiveDriveTime(bool enable_uvw, bool enable_y2) noexcept;
 
    bool configureDriveTimes(uint8_t sink_time_uvw, uint8_t source_time_uvw, uint8_t sink_time_y2,
                             uint8_t source_time_y2) noexcept;
 
    bool configureDriveTimes_ns(float sinkTimeUVW_ns, float sourceTimeUVW_ns, float sinkTimeY2_ns,
                                float sourceTimeY2_ns) noexcept;
 
    bool configureCurrentLimits(tmc9660::tmcl::GateCurrentSink sink_current_uvw,
                                tmc9660::tmcl::GateCurrentSource source_current_uvw,
                                tmc9660::tmcl::GateCurrentSink sink_current_y2,
                                tmc9660::tmcl::GateCurrentSource source_current_y2) noexcept;
 
    bool configureBootstrapCurrentLimit(tmc9660::tmcl::BootstrapCurrentLimit limit) noexcept;
 
    bool configureUndervoltageProtection(tmc9660::tmcl::UndervoltageLevel supplyLevel,
                                         tmc9660::tmcl::UndervoltageEnable enable_vdrv,
                                         tmc9660::tmcl::UndervoltageEnable enable_bst_uvw,
                                         tmc9660::tmcl::UndervoltageEnable enable_bst_y2) noexcept;
 
    bool enableOvercurrentProtection(tmc9660::tmcl::OvercurrentEnable enable_uvw_low_side,
                                     tmc9660::tmcl::OvercurrentEnable enable_uvw_high_side,
                                     tmc9660::tmcl::OvercurrentEnable enable_y2_low_side,
                                     tmc9660::tmcl::OvercurrentEnable enable_y2_high_side) noexcept;
 
    bool setOvercurrentThresholds(tmc9660::tmcl::OvercurrentThreshold uvw_low_side_threshold,
                                  tmc9660::tmcl::OvercurrentThreshold uvw_high_side_threshold,
                                  tmc9660::tmcl::OvercurrentThreshold y2LowSideThreshold,
                                  tmc9660::tmcl::OvercurrentThreshold y2HighSideThreshold) noexcept;
 
    bool setOvercurrentBlanking(tmc9660::tmcl::OvercurrentTiming uvw_low_side_time,
                                tmc9660::tmcl::OvercurrentTiming uvw_high_side_time,
                                tmc9660::tmcl::OvercurrentTiming y2LowSideTime,
                                tmc9660::tmcl::OvercurrentTiming y2HighSideTime) noexcept;
 
    bool setOvercurrentDeglitch(tmc9660::tmcl::OvercurrentTiming uvw_low_side_time,
                                tmc9660::tmcl::OvercurrentTiming uvw_high_side_time,
                                tmc9660::tmcl::OvercurrentTiming y2LowSideTime,
                                tmc9660::tmcl::OvercurrentTiming y2HighSideTime) noexcept;
 
    bool enableVdsMonitoringLow(tmc9660::tmcl::VdsUsage uvw_enable,
                                tmc9660::tmcl::VdsUsage y2Enable) noexcept;
 
    bool configureVgsShortProtectionUVW(tmc9660::tmcl::VgsShortEnable enable_low_side_on,
                                        tmc9660::tmcl::VgsShortEnable enable_low_side_off,
                                        tmc9660::tmcl::VgsShortEnable enable_high_side_on,
                                        tmc9660::tmcl::VgsShortEnable enable_high_side_off) noexcept;
 
    bool configureVgsShortProtectionY2(tmc9660::tmcl::VgsShortEnable enable_low_side_on,
                                       tmc9660::tmcl::VgsShortEnable enable_low_side_off,
                                       tmc9660::tmcl::VgsShortEnable enable_high_side_on,
                                       tmc9660::tmcl::VgsShortEnable enable_high_side_off) noexcept;
 
    bool setVgsShortBlankingTime(tmc9660::tmcl::VgsBlankingTime uvw_time,
                                 tmc9660::tmcl::VgsBlankingTime y2Time) noexcept;
 
    bool setVgsShortDeglitchTime(tmc9660::tmcl::VgsDeglitchTime uvw_time,
                                 tmc9660::tmcl::VgsDeglitchTime y2Time) noexcept;
 
    bool setRetryBehavior(tmc9660::tmcl::GdrvRetryBehaviour retry_behavior) noexcept;
 
    bool setDriveFaultBehavior(tmc9660::tmcl::DriveFaultBehaviour fault_behavior) noexcept;
 
    bool setFaultHandlerRetries(uint8_t retries) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct PowerStageProfile {
      // Required parameters
      float mosfet_RdsOn_mOhm; 
      float mosfet_gateCharge_nC; 
      float shuntResistance_mOhm; 
      float busVoltage_V;         
      float pwmFrequency_Hz;      
      float expectedPeakCurrent_A; 
 
      // Optional parameters with defaults
      float motorInductance_uH =
          std::numeric_limits<float>::quiet_NaN(); 
 
      // Safety margin multipliers (optional, with conservative defaults)
      float overcurrentMargin =
          1.5f; 
      float blankingMargin = 1.2f; 
 
      // Fault handling behavior (optional, with safe defaults)
      tmc9660::tmcl::GdrvRetryBehaviour retryBehaviour =
          tmc9660::tmcl::GdrvRetryBehaviour::OPEN_CIRCUIT; 
      tmc9660::tmcl::DriveFaultBehaviour faultBehaviour =
          tmc9660::tmcl::DriveFaultBehaviour::OPEN_CIRCUIT; 
      uint8_t faultHandlerRetries =
          5; 
 
      // Gate driver timing overrides (optional, for advanced tuning)
      std::optional<float>
          targetTurnOnTime_ns; 
      std::optional<float>
          targetTurnOffTime_ns; 
 
      // Gate driver interface configuration (optional, with safe defaults)
      tmc9660::tmcl::PwmOutputPolarity pwmLowPolarity =
          tmc9660::tmcl::PwmOutputPolarity::ACTIVE_HIGH; 
      tmc9660::tmcl::PwmOutputPolarity pwmHighPolarity =
          tmc9660::tmcl::PwmOutputPolarity::ACTIVE_HIGH; 
 
      // Undervoltage protection configuration (optional, with safe defaults)
      tmc9660::tmcl::UndervoltageLevel supplyLevel =
          tmc9660::tmcl::UndervoltageLevel::DISABLED; 
    };
 
    bool configurePowerStageProtection(const PowerStageProfile& profile) noexcept;
 
  private:
    friend class TMC9660;
    explicit GateDriver(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } gateDriver{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Feedback Sensors                        **//
  //***************************************************************************
 
  struct FeedbackSense {
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
    //  HALL sensors (digital Hall)
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
    bool configureHall(
        tmc9660::tmcl::HallSectorOffset sectorOffset = tmc9660::tmcl::HallSectorOffset::DEG_0,
        tmc9660::tmcl::Direction inverted = tmc9660::tmcl::Direction::NOT_INVERTED,
        tmc9660::tmcl::EnableDisable enableExtrapolation = tmc9660::tmcl::EnableDisable::DISABLED,
        uint8_t filterLength = 0) noexcept;
 
    bool setHallPositionOffsets(int16_t offset0 = 0, int16_t offset60 = 10922,
                                int16_t offset120 = 21845, int16_t offset180 = -32768,
                                int16_t offset240 = -21846, int16_t offset300 = -10923,
                                int16_t globalOffset = 0) noexcept;
 
    bool setHallPositionOffsetsDegrees(float offset0Deg = 0.0f, float offset60Deg = 60.0f,
                                       float offset120Deg = 120.0f, float offset180Deg = 180.0f,
                                       float offset240Deg = 240.0f, float offset300Deg = 300.0f,
                                       float globalOffsetDeg = 0.0f) noexcept;
 
    bool setHallPositionOffsetsRadians(float offset0Rad = 0.0f, float offset60Rad = 1.04719755f,
                                       float offset120Rad = 2.09439510f,
                                       float offset180Rad = 3.14159265f,
                                       float offset240Rad = 4.18879020f,
                                       float offset300Rad = 5.23598775f,
                                       float globalOffsetRad = 0.0f) noexcept;
 
    static int16_t degreesToHallOffset(float degrees) noexcept;
 
    static int16_t radiansToHallOffset(float radians) noexcept;
 
    bool getHallPhiE(int16_t& phi_e) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
    //  ABN encoders (ABN1, ABN2)
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
    bool configureABNEncoder(
        uint32_t counts_per_rev,
        tmc9660::tmcl::Direction inverted = tmc9660::tmcl::Direction::NOT_INVERTED,
        tmc9660::tmcl::EnableDisable nChannelInverted =
            tmc9660::tmcl::EnableDisable::DISABLED) noexcept;
 
    bool configureABNInitialization(
        tmc9660::tmcl::AbnInitMethod initMethod =
            tmc9660::tmcl::AbnInitMethod::FORCED_PHI_E_ZERO_WITH_ACTIVE_SWING,
        uint16_t initDelay = 1000, int32_t initVelocity = 5, int16_t nChannelOffset = 0) noexcept;
 
    bool getABNInitializationState(tmc9660::tmcl::AbnInitState& state) noexcept;
 
    bool getABNPhiE(int16_t& phi_e) noexcept;
 
    bool getABNRawValue(uint32_t& value) noexcept;
 
    bool configureABNNChannel(tmc9660::tmcl::AbnNChannelFiltering filterMode =
                                  tmc9660::tmcl::AbnNChannelFiltering::FILTERING_OFF,
                              tmc9660::tmcl::EnableDisable clearOnNextNull =
                                  tmc9660::tmcl::EnableDisable::DISABLED) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
    bool configureSecondaryABNEncoder(
        uint32_t counts_per_rev,
        tmc9660::tmcl::Direction inverted = tmc9660::tmcl::Direction::NOT_INVERTED,
        uint8_t gearRatio = 1) noexcept;
 
    // ABN-2 (secondary encoder) getters
    bool getSecondaryABNCountsPerRev(uint32_t& counts) noexcept;
 
    bool getSecondaryABNDirection(tmc9660::tmcl::Direction& dir) noexcept;
 
    bool getSecondaryABNGearRatio(uint8_t& ratio) noexcept;
 
    bool setSecondaryABNEncoderEnabled(bool enable) noexcept;
 
    bool getSecondaryABNEncoderValue(uint32_t& value) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
    //  SPI encoder timing & frame size
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
    bool configureSPIEncoder(uint8_t cmd_size, uint16_t cs_settle_time_ns,
                             uint8_t cs_idle_time_us) noexcept;
 
    bool configureSPIEncoderDataFormat(
        uint32_t position_mask, uint8_t positionShift = 0,
        tmc9660::tmcl::Direction invertDirection = tmc9660::tmcl::Direction::NOT_INVERTED) noexcept;
 
    bool setSPIEncoderRequestData(const uint8_t* requestData, uint8_t size) noexcept;
 
    bool configureSPIEncoderInitialization(tmc9660::tmcl::SpiInitMethod init_method,
                                           int16_t offset = 0) noexcept;
 
    bool setSPIEncoderLUTCorrection(tmc9660::tmcl::EnableDisable enable,
                                    int8_t shiftFactor = 0) noexcept;
 
    bool uploadSPIEncoderLUTEntry(uint8_t index, int8_t value) noexcept;
 
    // SPI encoder timing & frame size
    bool getSPIEncoderCSSettleDelay(uint16_t& timeNs) noexcept;
 
    bool getSPIEncoderCSIdleDelay(uint8_t& timeUs) noexcept;
 
    bool getSPIEncoderMainCmdSize(uint8_t& size) noexcept;
 
    bool getSPIEncoderSecondaryCmdSize(uint8_t& size) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
    //  SPI encoder data & status
    bool getSPIEncoderPositionMask(uint32_t& mask) noexcept;
 
    bool getSPIEncoderPositionShift(uint8_t& shift) noexcept;
 
    bool getSPIEncoderPositionValue(uint32_t& value) noexcept;
 
    bool getSPIEncoderCommutationAngle(int16_t& angle) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
    //  SPI encoder initialization & offset
    bool getSPIEncoderInitialization(tmc9660::tmcl::SpiInitMethod& method,
                                     int16_t& offset) noexcept;
 
    bool getSPIEncoderDirection(tmc9660::tmcl::Direction& dir) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
    //  SPI LUT
    bool getSPIEncoderLUTAddress(uint8_t& address) noexcept;
 
    bool getSPIEncoderLUTData(int8_t& data) noexcept;
 
    bool getSPIEncoderLUTShiftFactor(int8_t& shift_factor) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct HallConfig {
      // Required parameters
      tmc9660::tmcl::HallSectorOffset sectorOffset =
          tmc9660::tmcl::HallSectorOffset::DEG_0; 
 
      // Optional parameters with defaults
      tmc9660::tmcl::Direction direction =
          tmc9660::tmcl::Direction::NOT_INVERTED; 
      tmc9660::tmcl::EnableDisable extrapolation =
          tmc9660::tmcl::EnableDisable::DISABLED; 
      uint8_t filterLength =
          0; 
 
      // Position offsets (optional, use NaN to skip)
      std::optional<float>
          offset0Deg; 
      std::optional<float>
          offset60Deg; 
      std::optional<float>
          offset120Deg; 
      std::optional<float>
          offset180Deg; 
      std::optional<float>
          offset240Deg; 
      std::optional<float>
          offset300Deg; 
      std::optional<float> globalOffsetDeg; 
    };
 
    struct AbnConfig {
      // Required parameters
      uint32_t countsPerRev; 
 
      // Optional parameters with defaults
      tmc9660::tmcl::Direction direction =
          tmc9660::tmcl::Direction::NOT_INVERTED; 
      tmc9660::tmcl::EnableDisable nChannelInverted =
          tmc9660::tmcl::EnableDisable::DISABLED; 
 
      // Initialization parameters (optional)
      tmc9660::tmcl::AbnInitMethod initMethod = tmc9660::tmcl::AbnInitMethod::
          FORCED_PHI_E_ZERO_WITH_ACTIVE_SWING; 
      uint16_t initDelay = 1000;  
      int32_t initVelocity = 5;   
      int16_t nChannelOffset = 0; 
 
      // N-channel filtering (optional)
      tmc9660::tmcl::AbnNChannelFiltering nChannelFiltering =
          tmc9660::tmcl::AbnNChannelFiltering::FILTERING_OFF; 
      tmc9660::tmcl::EnableDisable clearOnNextNull =
          tmc9660::tmcl::EnableDisable::DISABLED; 
    };
 
    struct Abn2Config {
      // Required parameters
      uint32_t countsPerRev; 
 
      // Optional parameters with defaults
      tmc9660::tmcl::Direction direction =
          tmc9660::tmcl::Direction::NOT_INVERTED; 
      uint8_t gearRatio =
          1; 
      bool enable = true; 
    };
 
    struct SpiEncoderConfig {
      // Required parameters
      uint8_t cmdSize;       
      uint32_t positionMask; 
 
      // Optional parameters with defaults
      uint16_t csSettleTimeNs = 0; 
      uint8_t csIdleTimeUs = 0;    
      uint8_t positionShift = 0;   
      tmc9660::tmcl::Direction direction =
          tmc9660::tmcl::Direction::NOT_INVERTED; 
 
      // Initialization parameters (optional)
      tmc9660::tmcl::SpiInitMethod initMethod = tmc9660::tmcl::SpiInitMethod::
          FORCED_PHI_E_ZERO_WITH_ACTIVE_SWING; 
      int16_t offset = 0; 
 
      // Request data for continuous transfer (optional)
      std::optional<std::array<uint8_t, 16>>
          requestData; 
 
      // LUT correction (optional)
      tmc9660::tmcl::EnableDisable lutCorrection =
          tmc9660::tmcl::EnableDisable::DISABLED; 
      int8_t lutShiftFactor = 0;                  
    };
 
    bool configureAuto(const HallConfig& config) noexcept;
 
    bool configureAuto(const AbnConfig& config) noexcept;
 
    bool configureAuto(const Abn2Config& config) noexcept;
 
    bool configureAuto(const SpiEncoderConfig& config) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
  private:
    friend class TMC9660;
    explicit FeedbackSense(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } feedbackSense{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Torque/Flux Control (FOC)                **//
  //***************************************************************************
 
  struct TorqueFluxControl {
    //-------------------------------------------------------------------------
    // Torque / Flux control (104–120)
    //-------------------------------------------------------------------------
    bool stop() noexcept;
 
    bool setTargetTorque(int16_t milliamps) noexcept;
    bool getActualTorque(int16_t& milliamps) noexcept;
 
    bool setTargetFlux(int16_t milliamps) noexcept;
    bool getActualFlux(int32_t& milliamps) noexcept;
 
    bool setTorqueOffset(int16_t milliamps) noexcept;
    bool getTorqueOffset(int16_t& milliamps) noexcept;
 
    bool setFluxOffset(int16_t milliamps) noexcept;
    bool getFluxOffset(int16_t& milliamps) noexcept;
 
    bool setCurrentLoopGains(uint16_t p, uint16_t i, bool separate = false, uint16_t fluxP = 0,
                             uint16_t fluxI = 0) noexcept;
    bool setTorqueFluxPiSeparation(tmc9660::tmcl::TorqueFluxPiSeparation sep) noexcept;
 
    bool setCurrentNormalization(tmc9660::tmcl::CurrentPiNormalization p_norm,
                                 tmc9660::tmcl::CurrentPiNormalization i_norm) noexcept;
 
    bool getTorquePiError(int32_t& error) noexcept;
    bool getFluxPiError(int32_t& error) noexcept;
    bool getTorquePiIntegrator(int32_t& integrator) noexcept;
    bool getFluxPiIntegrator(int32_t& integrator) noexcept;
 
    //-------------------------------------------------------------------------
    // Open‐loop support (45–47)
    //-------------------------------------------------------------------------
    bool getOpenloopAngle(int16_t& angle) noexcept;
 
    bool setOpenloopCurrent(uint16_t milliamps) noexcept;
    bool getOpenloopCurrent(uint16_t& milliamps) noexcept;
 
    bool setOpenloopVoltage(uint16_t voltage) noexcept;
    bool getOpenloopVoltage(uint16_t& voltage) noexcept;
 
    //-------------------------------------------------------------------------
    // Field-weakening (308, 310)
    //-------------------------------------------------------------------------
    bool setFieldWeakeningI(uint16_t milliamps) noexcept;
    bool getFieldWeakeningI(uint16_t& milliamps) noexcept;
 
    bool setFieldWeakeningVoltageThreshold(uint16_t voltage) noexcept;
    bool getFieldWeakeningVoltageThreshold(uint16_t& voltage) noexcept;
 
    bool setTargetTorqueBiquadFilterEnable(bool enable) noexcept;
    bool getTargetTorqueBiquadFilterEnable(bool& enable) noexcept;
 
    bool setTargetTorqueBiquadFilterACoeff1(int32_t coeff) noexcept;
    bool getTargetTorqueBiquadFilterACoeff1(int32_t& coeff) noexcept;
 
    bool setTargetTorqueBiquadFilterACoeff2(int32_t coeff) noexcept;
    bool getTargetTorqueBiquadFilterACoeff2(int32_t& coeff) noexcept;
 
    bool setTargetTorqueBiquadFilterBCoeff0(int32_t coeff) noexcept;
    bool getTargetTorqueBiquadFilterBCoeff0(int32_t& coeff) noexcept;
 
    bool setTargetTorqueBiquadFilterBCoeff1(int32_t coeff) noexcept;
    bool getTargetTorqueBiquadFilterBCoeff1(int32_t& coeff) noexcept;
 
    bool setTargetTorqueBiquadFilterBCoeff2(int32_t coeff) noexcept;
    bool getTargetTorqueBiquadFilterBCoeff2(int32_t& coeff) noexcept;
 
    bool getFocVoltageUx(int16_t& voltage) noexcept;
    bool getFocVoltageWy(int16_t& voltage) noexcept;
    bool getFocVoltageV(int16_t& voltage) noexcept;
    bool getFocVoltageUq(int16_t& voltage) noexcept;
 
    bool getFocCurrentUx(int16_t& milliamps) noexcept;
    bool getFocCurrentV(int16_t& milliamps) noexcept;
    bool getFocCurrentWy(int16_t& milliamps) noexcept;
    bool getFocCurrentIq(int16_t& milliamps) noexcept;
 
    bool getTorqueFluxCombinedTargetValues(uint32_t& value) noexcept;
    bool getTorqueFluxCombinedActualValues(uint32_t& value) noexcept;
    bool getVoltageDqCombinedActualValues(uint32_t& value) noexcept;
    bool getIntegratedActualTorqueValue(uint32_t& value) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct TorqueFluxConfig {
      // ========================================================================
      // PI Controller Configuration
      // ========================================================================
 
      std::optional<uint16_t>
          torqueP; 
      std::optional<uint16_t>
          torqueI; 
 
      bool separateTorqueFluxLoops =
          false; 
 
      std::optional<uint16_t>
          fluxP; 
      std::optional<uint16_t>
          fluxI; 
 
      std::optional<tmc9660::tmcl::CurrentPiNormalization>
          pNormalization; 
      std::optional<tmc9660::tmcl::CurrentPiNormalization>
          iNormalization; 
 
      // ========================================================================
      // Field Weakening Configuration
      // ========================================================================
 
      bool enableFieldWeakening = false; 
 
      float fieldWeakeningVoltageThresholdPercent =
          0.85f; 
 
      uint16_t fieldWeakeningI = 100; 
 
      // ========================================================================
      // Advanced Configuration (Optional)
      // ========================================================================
 
      int16_t torqueOffset_mA = 0; 
      int16_t fluxOffset_mA = 0;   
 
      bool enableTorqueBiquadFilter =
          false; 
 
      std::optional<int32_t> biquadACoeff1; 
      std::optional<int32_t> biquadACoeff2; 
      std::optional<int32_t>
          biquadBCoeff0; 
      std::optional<int32_t> biquadBCoeff1; 
      std::optional<int32_t> biquadBCoeff2; 
    };
 
    bool configureAuto(const TorqueFluxConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit TorqueFluxControl(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } torqueFluxControl{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Velocity Control                           **//
  //***************************************************************************
 
  struct VelocityControl {
    //-------------------------------------------------------------------------
    // Velocity control (123–139)
    //-------------------------------------------------------------------------
    bool stop() noexcept;
 
    bool setVelocitySensor(tmc9660::tmcl::VelocitySensorSelection sel) noexcept;
    bool getVelocitySensor(tmc9660::tmcl::VelocitySensorSelection& sel) noexcept;
 
    bool setTargetVelocity(int32_t velocity) noexcept;
    bool getActualVelocity(int32_t& velocity) noexcept;
 
    bool setVelocityOffset(int32_t offset) noexcept;
    bool getVelocityOffset(int32_t& offset) noexcept;
 
    bool setVelocityLoopGains(uint16_t p, uint16_t i) noexcept;
    bool setVelocityNormalization(tmc9660::tmcl::VelocityPiNorm p_norm,
                                  tmc9660::tmcl::VelocityPiNorm i_norm) noexcept;
 
    bool getVelocityPiIntegrator(int32_t& integrator) noexcept;
    bool getVelocityPiError(int32_t& error) noexcept;
 
    bool setVelocityScalingFactor(uint16_t factor) noexcept;
    bool getVelocityScalingFactor(uint16_t& factor) noexcept;
 
    bool setStopOnVelocityDeviation(uint32_t max_error, bool softStop = true) noexcept;
    bool getStopOnVelocityDeviation(uint32_t& max_error, bool& soft_stop) noexcept;
 
    bool setVelocityLoopDownsampling(uint8_t divider) noexcept;
    bool getVelocityLoopDownsampling(uint8_t& divider) noexcept;
 
    // Note: VELOCITY_REACHED_THRESHOLD is not a configurable parameter in TMC9660.
    // The VELOCITY_REACHED flag is set when both actual and target velocity are below
    // an internal threshold. Parameter 134 is STOP_ON_VELOCITY_DEVIATION, not
    // VELOCITY_REACHED_THRESHOLD.
 
    bool setVelocityMeterSwitchThreshold(uint32_t threshold) noexcept;
    bool getVelocityMeterSwitchThreshold(uint32_t& threshold) noexcept;
 
    bool setVelocityMeterSwitchHysteresis(uint16_t hysteresis) noexcept;
    bool getVelocityMeterSwitchHysteresis(uint16_t& hysteresis) noexcept;
 
    bool getVelocityMeterMode(tmc9660::tmcl::VelocityMeterMode& mode) noexcept;
 
    bool setActualVelocityBiquadFilterEnable(bool enable) noexcept;
    bool getActualVelocityBiquadFilterEnable(bool& enable) noexcept;
    bool setActualVelocityBiquadFilterACoeff1(int32_t coeff) noexcept;
    bool getActualVelocityBiquadFilterACoeff1(int32_t& coeff) noexcept;
    bool setActualVelocityBiquadFilterACoeff2(int32_t coeff) noexcept;
    bool getActualVelocityBiquadFilterACoeff2(int32_t& coeff) noexcept;
    bool setActualVelocityBiquadFilterBCoeff0(int32_t coeff) noexcept;
    bool getActualVelocityBiquadFilterBCoeff0(int32_t& coeff) noexcept;
    bool setActualVelocityBiquadFilterBCoeff1(int32_t coeff) noexcept;
    bool getActualVelocityBiquadFilterBCoeff1(int32_t& coeff) noexcept;
    bool setActualVelocityBiquadFilterBCoeff2(int32_t coeff) noexcept;
    bool getActualVelocityBiquadFilterBCoeff2(int32_t& coeff) noexcept;
 
    bool getIntegratedActualVelocityValue(uint32_t& value) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct VelocityConfig {
      // Required parameters
      tmc9660::tmcl::VelocitySensorSelection
          sensorSelection; 
 
      // Optional parameters with defaults
      std::optional<uint16_t> velocityP; 
 
      std::optional<uint16_t> velocityI; 
 
      tmc9660::tmcl::VelocityPiNorm pNormalization =
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT; 
      tmc9660::tmcl::VelocityPiNorm iNormalization =
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT; 
 
      // Velocity scaling (optional, can be auto-calculated from encoder CPR and motor parameters)
      std::optional<uint16_t>
          velocityScalingFactor; 
 
      std::optional<uint32_t>
          encoderCountsPerRev; 
 
      std::optional<uint8_t>
          motor_polePairs; 
 
      std::optional<uint32_t> pwmFrequency_Hz; 
 
      // Velocity loop downsampling (optional)
      uint8_t loopDownsampling = 5; 
 
      // Velocity reached threshold (optional)
      uint32_t velocityReachedThreshold = 1000; 
 
      // Stop on deviation (optional)
      std::optional<uint32_t>
          stopOnDeviationMaxError; 
      bool stopOnDeviationSoftStop =
          true; 
 
      // Velocity meter (optional, can be auto-calculated for optimal performance)
      std::optional<uint32_t> meterSwitchThreshold; 
      uint16_t meterHysteresis = 500;               
 
      // Velocity offset (optional)
      int32_t velocityOffset = 0; 
 
      // Biquad filter (optional)
      std::optional<bool>
          enableVelocityBiquadFilter; 
 
      std::optional<int32_t> velocityBiquadACoeff1; 
      std::optional<int32_t> velocityBiquadACoeff2; 
      std::optional<int32_t> velocityBiquadBCoeff0; 
      std::optional<int32_t> velocityBiquadBCoeff1; 
      std::optional<int32_t> velocityBiquadBCoeff2; 
    };
 
    bool configureAuto(const VelocityConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit VelocityControl(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } velocityControl{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Position Control                          **//
  //***************************************************************************
 
  struct PositionControl {
    //-------------------------------------------------------------------------
    // Position control (142–157)
    //-------------------------------------------------------------------------
    bool stop() noexcept;
 
    bool setPositionSensor(tmc9660::tmcl::PositionSensorSelection sel) noexcept;
    bool getPositionSensor(tmc9660::tmcl::PositionSensorSelection& sel) noexcept;
 
    bool setTargetPosition(int32_t position) noexcept;
    bool getActualPosition(int32_t& position) noexcept;
 
    bool setPositionScalingFactor(uint16_t factor) noexcept;
    bool getPositionScalingFactor(uint16_t& factor) noexcept;
 
    bool setPositionLoopGains(uint16_t p, uint16_t i) noexcept;
    bool setPositionNormalization(tmc9660::tmcl::VelocityPiNorm p_norm,
                                  tmc9660::tmcl::VelocityPiNorm i_norm) noexcept;
 
    bool getPositionPiIntegrator(int32_t& integrator) noexcept;
    bool getPositionPiError(int32_t& error) noexcept;
 
    bool setStopOnPositionDeviation(uint32_t max_error, bool softStop = true) noexcept;
    bool getStopOnPositionDeviation(uint32_t& max_error, bool& soft_stop) noexcept;
 
    bool setPositionLoopDownsampling(uint8_t divider) noexcept;
    bool getPositionLoopDownsampling(uint8_t& divider) noexcept;
 
    bool setPositionLimitLow(int32_t limit) noexcept;
    bool getPositionLimitLow(int32_t& limit) noexcept;
 
    bool setPositionLimitHigh(int32_t limit) noexcept;
    bool getPositionLimitHigh(int32_t& limit) noexcept;
 
    bool setPositionReachedThreshold(uint32_t threshold) noexcept;
    bool getPositionReachedThreshold(uint32_t& threshold) noexcept;
 
    //-------------------------------------------------------------------------
    // Ref switch & stop-event (161–170)
    //-------------------------------------------------------------------------
    bool setReferenceSwitchEnable(tmc9660::tmcl::ReferenceSwitchEnable enable) noexcept;
    bool getReferenceSwitchEnable(tmc9660::tmcl::ReferenceSwitchEnable& enable) noexcept;
 
    bool setReferenceSwitchPolaritySwap(tmc9660::tmcl::ReferenceSwitchPolaritySwap config) noexcept;
    bool getReferenceSwitchPolaritySwap(
        tmc9660::tmcl::ReferenceSwitchPolaritySwap& config) noexcept;
 
    bool setReferenceSwitchLatchSettings(
        tmc9660::tmcl::ReferenceSwitchLatchSettings setting) noexcept;
    bool getReferenceSwitchLatchSettings(
        tmc9660::tmcl::ReferenceSwitchLatchSettings& setting) noexcept;
 
    bool setEventStopSettings(tmc9660::tmcl::EventStopSettings settings) noexcept;
    bool getEventStopSettings(tmc9660::tmcl::EventStopSettings& settings) noexcept;
 
    bool setReferenceSwitchSearchMode(tmc9660::tmcl::ReferenceSwitchSearchMode mode) noexcept;
    bool getReferenceSwitchSearchMode(tmc9660::tmcl::ReferenceSwitchSearchMode& mode) noexcept;
 
    bool setReferenceSwitchSearchSpeed(int32_t speed) noexcept;
    bool getReferenceSwitchSearchSpeed(int32_t& speed) noexcept;
 
    bool setReferenceSwitchSpeed(int32_t speed) noexcept;
    bool getReferenceSwitchSpeed(int32_t& speed) noexcept;
 
    bool getRightLimitSwitchPosition(int32_t& position) noexcept;
 
    bool getHomeSwitchPosition(int32_t& position) noexcept;
 
    bool getLastReferencePosition(int32_t& position) noexcept;
 
    // Raw inputs for ABN, hall, reference switches, driver enabled,
    // hall filtered and ABN2 or Step/Dir (Parameter 304: MCC_INPUTS_RAW)
    bool getMccInputsRaw(uint16_t& inputs) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct PositionConfig {
      // Required parameters
      tmc9660::tmcl::PositionSensorSelection
          sensorSelection; 
 
      // Optional parameters with defaults
      std::optional<uint16_t> positionP; 
 
      std::optional<uint16_t> positionI; 
 
      tmc9660::tmcl::VelocityPiNorm pNormalization =
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT; 
      tmc9660::tmcl::VelocityPiNorm iNormalization =
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT; 
 
      // Position scaling (optional, can be auto-calculated from encoder CPR)
      std::optional<uint16_t>
          positionScalingFactor; 
      std::optional<uint32_t>
          encoderCountsPerRev; 
 
      // Position loop downsampling (optional)
      uint8_t loopDownsampling = 1; 
 
      // Position limits (optional)
      std::optional<int32_t>
          positionLimitLow; 
      std::optional<int32_t>
          positionLimitHigh; 
 
      // Position reached threshold (optional)
      uint32_t positionReachedThreshold = 100; 
 
      // Stop on deviation (optional)
      std::optional<uint32_t>
          stopOnDeviationMaxError; 
      bool stopOnDeviationSoftStop =
          true; 
    };
 
    bool configureAuto(const PositionConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit PositionControl(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } positionControl{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Motion Ramp                             **//
  //***************************************************************************
 
  struct Ramp {
    bool enable(bool on) noexcept;
 
    bool setAcceleration(uint32_t a1, uint32_t a2, uint32_t a_max) noexcept;
 
    bool setDeceleration(uint32_t d1, uint32_t d2, uint32_t d_max) noexcept;
 
    bool setVelocities(uint32_t v_start, uint32_t v_stop, uint32_t v1, uint32_t v2,
                       uint32_t v_max) noexcept;
 
    bool setTiming(uint16_t t_vmax_cycles, uint16_t t_zero_wait_cycles) noexcept;
 
    bool enableFeedForward(bool enable_vel_ff, bool enable_accel_ff, uint16_t accel_ff_gain,
                           tmc9660::tmcl::AccelerationFFShift accel_ff_shift) noexcept;
 
    bool setDirectVelocityMode(bool enable) noexcept;
 
    bool getRampVelocity(int32_t& velocity) noexcept;
 
    bool getRampPosition(int32_t& position) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct RampConfig {
      // Required parameters
      uint32_t maxVelocity = 134217727; 
 
      // Optional parameters with defaults
      std::optional<uint32_t>
          maxAcceleration; 
 
      std::optional<uint32_t>
          acceleration1; 
 
      std::optional<uint32_t>
          acceleration2; 
 
      std::optional<uint32_t>
          maxDeceleration; 
 
      std::optional<uint32_t>
          deceleration1; 
 
      std::optional<uint32_t>
          deceleration2; 
 
      std::optional<uint32_t>
          velocityThreshold1; 
 
      std::optional<uint32_t>
          velocityThreshold2; 
 
      std::optional<uint32_t>
          startVelocity; 
 
      std::optional<uint32_t>
          stopVelocity; 
 
      std::optional<uint16_t> timeAtVmax; 
 
      std::optional<uint16_t> timeZeroWait; 
 
      std::optional<bool> enableRamp; 
 
      std::optional<bool>
          enableDirectVelocityMode; 
 
      std::optional<bool>
          enableVelocityFeedForward; 
 
      std::optional<bool> enableAccelerationFeedForward; 
 
      std::optional<uint16_t>
          accelerationFeedForwardGain; 
 
      std::optional<tmc9660::tmcl::AccelerationFFShift>
          accelerationFeedForwardShift; 
    };
 
    bool configureAuto(const RampConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit Ramp(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } ramp{*this};
 
  //***************************************************************************
  //**              SUBSYSTEM: Step/Dir Input Extrapolation                **//
  //***************************************************************************
 
  struct StepDir {
 
    bool setMicrostepResolution(tmc9660::tmcl::StepDirStepDividerShift µSteps) noexcept;
 
    bool enableInterface(bool on) noexcept;
 
    bool enableExtrapolation(bool enable) noexcept;
 
    bool setSignalTimeout(uint16_t timeout_ms) noexcept;
 
    bool setMaxExtrapolationVelocity(uint32_t e_rpm) noexcept;
 
    bool enableVelocityFeedForward(bool enable_vel_ff) noexcept;
 
  private:
    friend class TMC9660;
    explicit StepDir(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } stepDir{*this};
 
  //***********************************************************************
  //**                    SUBSYSTEM: Reference Search                   **//
  //***********************************************************************
 
  struct ReferenceSearch {
    bool start() noexcept;
    bool stop() noexcept;
    bool getStatus(tmc9660::tmcl::ReferenceSearchStatus& status) noexcept;
 
  private:
    friend class TMC9660;
    explicit ReferenceSearch(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } referenceSearch{*this};
 
  //***************************************************************************
  //**                      SUBSYSTEM: Brake Chopper                       **//
  //***************************************************************************
 
  struct Brake {
    bool enableChopper(bool enable) noexcept;
 
    bool setVoltageLimit(float voltage) noexcept;
 
    bool setHysteresis(float voltage) noexcept;
 
    bool release() noexcept;
 
    bool engage() noexcept;
 
    bool setReleasingDutyCycle(uint8_t percent) noexcept;
 
    bool setHoldingDutyCycle(uint8_t percent) noexcept;
 
    bool setReleasingDuration(uint16_t milliseconds) noexcept;
 
    bool invertOutput(bool invert) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct BrakeConfig {
      // Brake chopper configuration (optional)
      std::optional<bool> enableChopper; 
 
      std::optional<float> chopperVoltageThreshold_V; 
 
      std::optional<float>
          chopperHysteresis_V; 
 
      // Mechanical brake configuration (optional)
      std::optional<uint8_t>
          releasingDutyCycle; 
 
      std::optional<uint8_t>
          holdingDutyCycle; 
 
      std::optional<uint16_t>
          releasingDuration_ms; 
 
      std::optional<bool> invertOutput; 
    };
 
    bool configureAuto(const BrakeConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit Brake(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } brake{*this};
 
  //***************************************************************************
  //**                   SUBSYSTEM: I²t Overload Protection                **//
  //***************************************************************************
 
  struct IIT {
    bool configure(uint16_t timeConstant1_ms, float continuousCurrent1_A, uint16_t timeConstant2_ms,
                   float continuousCurrent2_A) noexcept;
 
    bool resetIntegralState() noexcept;
 
    bool setThermalWindingTimeConstant1(uint16_t ms) noexcept;
    bool getThermalWindingTimeConstant1(uint16_t& ms) noexcept;
 
    bool setLimit1(uint32_t limit) noexcept;
    bool getLimit1(uint32_t& limit) noexcept;
 
    bool setThermalWindingTimeConstant2(uint16_t ms) noexcept;
    bool getThermalWindingTimeConstant2(uint16_t& ms) noexcept;
 
    bool setLimit2(uint32_t limit) noexcept;
    bool getLimit2(uint32_t& limit) noexcept;
 
    bool getActualTotalMotorCurrent(uint32_t& current, uint8_t motorIndex = 0) noexcept;
 
    bool getSum1(uint32_t& sum) noexcept;
 
    bool getSum2(uint32_t& sum) noexcept;
 
  private:
    friend class TMC9660;
    explicit IIT(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } iit{*this};
 
  //===========================================================================
  //==                  SUBSYSTEM: Telemetry & Status                       ==//
  //===========================================================================
 
  struct Telemetry {
    bool getGeneralStatusFlags(uint32_t& flags) noexcept;
 
    float getSupplyVoltage() noexcept;
 
    float getChipTemperature() noexcept;
 
    int16_t getMotorCurrent() noexcept;
 
    int32_t getActualVelocity() noexcept;
 
    int32_t getActualPosition() noexcept;
 
    bool getGeneralErrorFlags(uint32_t& flags) noexcept;
 
    bool getGateDriverErrorFlags(uint32_t& flags) noexcept;
 
    bool clearGeneralErrorFlags(uint32_t mask) noexcept;
 
    bool clearGateDriverErrorFlags(uint32_t mask) noexcept;
 
    bool getADCStatusFlags(uint32_t& flags) noexcept;
 
    bool clearADCStatusFlags(uint32_t mask) noexcept;
 
    uint16_t getExternalTemperature() noexcept;
 
  private:
    friend class TMC9660;
    explicit Telemetry(TMC9660& parent) noexcept;
    TMC9660& driver;
  } telemetry{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Stop / Event                            **//
  //***************************************************************************
 
  struct StopEvents {
    bool enableDeviationStop(
        uint32_t max_vel_error, uint32_t max_pos_error,
        bool softStop = true) noexcept; 
 
    bool configureReferenceSwitches(
        uint8_t mask, bool invert_l, bool invert_r, bool invert_h,
        bool swap_lr) noexcept; 
 
    bool getAndClearLatchedPosition(int32_t& pos) noexcept; 
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct StopEventsConfig {
      // Deviation stop (optional)
      std::optional<uint32_t> maxVelocityDeviation; 
 
      std::optional<uint32_t> maxPositionDeviation; 
 
      std::optional<bool>
          deviationSoftStop; 
 
      // Reference switches (optional)
      std::optional<uint8_t>
          referenceSwitchMask; 
 
      std::optional<bool> invertLeftSwitch; 
 
      std::optional<bool> invertRightSwitch; 
 
      std::optional<bool> invertHomeSwitch; 
 
      std::optional<bool> swapLeftRight; 
    };
 
    bool configureAuto(const StopEventsConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit StopEvents(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } stopEvents{*this};
 
  //===========================================================================
  //==                  SUBSYSTEM: Protection                               ==//
  //===========================================================================
 
  struct Protection {
    bool configureVoltage(uint16_t over_volt_threshold, uint16_t under_volt_threshold) noexcept;
 
    bool configureTemperature(float warning_deg_c, float shutdown_deg_c) noexcept;
 
    bool setOvercurrentEnabled(bool enabled) noexcept;
 
    bool configureI2t(uint16_t timeConstant1_ms, float continuousCurrent1_A,
                      uint16_t timeConstant2_ms, float continuousCurrent2_A) noexcept;
 
    bool resetI2tState() noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct ProtectionConfig {
      // Voltage protection (optional, with defaults)
      std::optional<float>
          overvoltageThreshold_V; 
 
      std::optional<float>
          undervoltageThreshold_V; 
 
      // Temperature protection (optional, with defaults)
      std::optional<float>
          temperatureWarning_C; 
 
      std::optional<float> temperatureShutdown_C; 
 
      // Overcurrent protection (optional, with default)
      std::optional<bool>
          enableOvercurrent; 
 
      // I²t thermal protection (optional, with defaults)
      std::optional<uint16_t>
          i2tTimeConstant1_ms; 
 
      std::optional<float> i2tContinuousCurrent1_A; 
 
      std::optional<uint16_t>
          i2tTimeConstant2_ms; 
 
      std::optional<float> i2tContinuousCurrent2_A; 
    };
 
    bool configureAuto(const ProtectionConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit Protection(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } protection{*this};
 
  //===========================================================================
  //==                  SUBSYSTEM: Script                                   ==//
  //===========================================================================
 
  struct Script {
    bool upload(const std::vector<uint32_t>& script_data) noexcept;
 
    bool start(uint16_t address = 0) noexcept;
 
    bool stop() noexcept;
 
    bool step() noexcept;
 
    bool reset() noexcept;
 
    bool getStatus(uint32_t& status) noexcept;
 
    bool readMemory(uint16_t address, uint32_t& value) noexcept;
 
    bool addBreakpoint(uint16_t address) noexcept;
 
    bool removeBreakpoint(uint16_t address) noexcept;
 
    bool clearBreakpoints() noexcept;
 
    bool getMaxBreakpointCount(uint32_t& count) noexcept;
 
  private:
    friend class TMC9660;
    explicit Script(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } script{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: RamDebug                                **//
  //***************************************************************************
  struct RamDebug {
    bool init(uint32_t sample_count) noexcept;
 
    bool startCapture() noexcept;
 
    bool readData(uint32_t index, uint32_t& data) noexcept;
 
    bool getStatus(bool& is_running) noexcept;
 
  private:
    friend class TMC9660;
    explicit RamDebug(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } ramDebug{*this};
 
  //===========================================================================
  //**                SUBSYSTEM: FLASH STORAGE                             ==//
  //===========================================================================
 
  struct NvmStorage {
    bool storeToFlash() noexcept;
 
    bool recallFromFlash() noexcept;
 
    bool eraseFlashBank(uint8_t n) noexcept;
 
  private:
    friend class TMC9660;
    explicit NvmStorage(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } nvmStorage{*this};
 
  //===========================================================================
  //==                SUBSYSTEM: Heartbeat (Watchdog)                       ==//
  //===========================================================================
 
  struct Heartbeat {
    bool configure(tmc9660::tmcl::HeartbeatMonitoringConfig mode, uint32_t timeout_ms) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct HeartbeatConfig {
      std::optional<bool> enable; 
 
      std::optional<uint32_t> timeoutMs; 
    };
 
    bool configureAuto(const HeartbeatConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit Heartbeat(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } heartbeat{*this};
 
  //***************************************************************************
  //**                   SUBSYSTEM: Global Parameter Access                **//
  //***************************************************************************
  struct Globals {
    bool writeBank0(tmc9660::tmcl::GlobalParamBank0 param, uint32_t value) noexcept;
 
    bool readBank0(tmc9660::tmcl::GlobalParamBank0 param, uint32_t& value) noexcept;
 
    bool writeBank2(tmc9660::tmcl::GlobalParamBank2 param, int32_t value) noexcept;
 
    bool readBank2(tmc9660::tmcl::GlobalParamBank2 param, int32_t& value) noexcept;
 
    bool writeBank3(tmc9660::tmcl::GlobalParamBank3 param, uint32_t value) noexcept;
 
    bool readBank3(tmc9660::tmcl::GlobalParamBank3 param, uint32_t& value) noexcept;
 
    // High level helpers --------------------------------------------------
    bool setSerialAddress(uint8_t address) noexcept;
 
    bool getSerialAddress(uint8_t& address) noexcept;
 
    bool setHostAddress(uint8_t address) noexcept;
 
    bool getHostAddress(uint8_t& address) noexcept;
 
    bool configureHeartbeat(tmc9660::tmcl::HeartbeatMonitoringConfig iface,
                            uint32_t timeout_ms) noexcept;
 
    bool getHeartbeat(tmc9660::tmcl::HeartbeatMonitoringConfig& iface,
                      uint32_t& timeout_ms) noexcept;
 
    bool setIODirectionMask(uint32_t mask) noexcept;
 
    bool getIODirectionMask(uint32_t& mask) noexcept;
 
    bool setPullEnableMask(uint32_t mask) noexcept;
 
    bool getPullEnableMask(uint32_t& mask) noexcept;
 
    bool setPullDirectionMask(uint32_t mask) noexcept;
 
    bool getPullDirectionMask(uint32_t& mask) noexcept;
 
    bool setAutoStart(bool enable) noexcept;
 
    bool getAutoStart(bool& enable) noexcept;
 
    bool setClearUserVariables(bool clear) noexcept;
 
    bool getClearUserVariables(bool& clear) noexcept;
 
    bool setUserVariable(uint8_t index, int32_t value) noexcept;
 
    bool getUserVariable(uint8_t index, int32_t& value) noexcept;
 
    bool setTimerPeriod(uint8_t timer, uint32_t period_ms) noexcept;
 
    bool getTimerPeriod(uint8_t timer, uint32_t& period_ms) noexcept;
 
    bool setInputTrigger(uint8_t index, tmc9660::tmcl::TriggerTransition transition) noexcept;
 
    bool getInputTrigger(uint8_t index, tmc9660::tmcl::TriggerTransition& transition) noexcept;
 
  private:
    friend class TMC9660;
    explicit Globals(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } globals{*this};
 
  //***************************************************************************
  //**        SUBSYSTEM: General-purpose GPIO (Digital/Analog I/O)          **//
  //***************************************************************************
 
  struct GPIO {
    bool setMode(uint8_t pin, bool output, bool pullEnable = false, bool pullUp = true) noexcept;
 
    bool writePin(uint8_t pin, bool value) noexcept;
 
    bool readDigital(uint8_t pin, bool& value) noexcept;
 
    bool readAnalog(uint8_t pin, uint16_t& value) noexcept;
 
  private:
    friend class TMC9660;
    explicit GPIO(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } gpio{*this};
 
  //***************************************************************************
  //**               SUBSYSTEM: Power Management                          **//
  //***************************************************************************
 
  struct Power {
    bool enableWakePin(bool enable) noexcept;
 
    bool enterPowerDown(tmc9660::tmcl::PowerDownTimeout period) noexcept;
 
    //-------------------------------------------------------------------------
    // Auto-Configuration
    //-------------------------------------------------------------------------
 
    struct PowerConfig {
      std::optional<bool> enableWakePin; 
 
      std::optional<tmc9660::tmcl::PowerDownTimeout>
          powerDownTimeout; 
    };
 
    bool configureAuto(const PowerConfig& config) noexcept;
 
  private:
    friend class TMC9660;
    explicit Power(TMC9660& parent) noexcept : driver(parent) {}
    TMC9660& driver;
  } power{*this};
 
  // ===========================================================================
  // Driver Version
  // ===========================================================================
 
  static constexpr const char* GetDriverVersion() noexcept {
    return HF_TMC9660_VERSION_STRING;
  }
 
  static constexpr uint8_t GetDriverVersionMajor() noexcept {
    return HF_TMC9660_VERSION_MAJOR;
  }
 
  static constexpr uint8_t GetDriverVersionMinor() noexcept {
    return HF_TMC9660_VERSION_MINOR;
  }
 
  static constexpr uint8_t GetDriverVersionPatch() noexcept {
    return HF_TMC9660_VERSION_PATCH;
  }
 
  //==================================================
  // PRIVATE MEMBERS
  //==================================================
private:
  CommType& comm_; 
  uint8_t address_;            
  std::unique_ptr<tmc9660::TMC9660Bootloader<CommType>> bootloader_; 
  const tmc9660::BootloaderConfig* bootCfg_;
 
#ifdef TMC_API_EXTERNAL_CRC_TABLE
  extern const uint8_t tmcCRCTable_Poly7Reflected[256];
#else
  const uint8_t tmcCRCTable_Poly7Reflected[256] = {
      0x00, 0x91, 0xE3, 0x72, 0x07, 0x96, 0xE4, 0x75, 0x0E, 0x9F, 0xED, 0x7C, 0x09, 0x98, 0xEA,
      0x7B, 0x1C, 0x8D, 0xFF, 0x6E, 0x1B, 0x8A, 0xF8, 0x69, 0x12, 0x83, 0xF1, 0x60, 0x15, 0x84,
      0xF6, 0x67, 0x38, 0xA9, 0xDB, 0x4A, 0x3F, 0xAE, 0xDC, 0x4D, 0x36, 0xA7, 0xD5, 0x44, 0x31,
      0xA0, 0xD2, 0x43, 0x24, 0xB5, 0xC7, 0x56, 0x23, 0xB2, 0xC0, 0x51, 0x2A, 0xBB, 0xC9, 0x58,
      0x2D, 0xBC, 0xCE, 0x5F, 0x70, 0xE1, 0x93, 0x02, 0x77, 0xE6, 0x94, 0x05, 0x7E, 0xEF, 0x9D,
      0x0C, 0x79, 0xE8, 0x9A, 0x0B, 0x6C, 0xFD, 0x8F, 0x1E, 0x6B, 0xFA, 0x88, 0x19, 0x62, 0xF3,
      0x81, 0x10, 0x65, 0xF4, 0x86, 0x17, 0x48, 0xD9, 0xAB, 0x3A, 0x4F, 0xDE, 0xAC, 0x3D, 0x46,
      0xD7, 0xA5, 0x34, 0x41, 0xD0, 0xA2, 0x33, 0x54, 0xC5, 0xB7, 0x26, 0x53, 0xC2, 0xB0, 0x21,
      0x5A, 0xCB, 0xB9, 0x28, 0x5D, 0xCC, 0xBE, 0x2F, 0xE0, 0x71, 0x03, 0x92, 0xE7, 0x76, 0x04,
      0x95, 0xEE, 0x7F, 0x0D, 0x9C, 0xE9, 0x78, 0x0A, 0x9B, 0xFC, 0x6D, 0x1F, 0x8E, 0xFB, 0x6A,
      0x18, 0x89, 0xF2, 0x63, 0x11, 0x80, 0xF5, 0x64, 0x16, 0x87, 0xD8, 0x49, 0x3B, 0xAA, 0xDF,
      0x4E, 0x3C, 0xAD, 0xD6, 0x47, 0x35, 0xA4, 0xD1, 0x40, 0x32, 0xA3, 0xC4, 0x55, 0x27, 0xB6,
      0xC3, 0x52, 0x20, 0xB1, 0xCA, 0x5B, 0x29, 0xB8, 0xCD, 0x5C, 0x2E, 0xBF, 0x90, 0x01, 0x73,
      0xE2, 0x97, 0x06, 0x74, 0xE5, 0x9E, 0x0F, 0x7D, 0xEC, 0x99, 0x08, 0x7A, 0xEB, 0x8C, 0x1D,
      0x6F, 0xFE, 0x8B, 0x1A, 0x68, 0xF9, 0x82, 0x13, 0x61, 0xF0, 0x85, 0x14, 0x66, 0xF7, 0xA8,
      0x39, 0x4B, 0xDA, 0xAF, 0x3E, 0x4C, 0xDD, 0xA6, 0x37, 0x45, 0xD4, 0xA1, 0x30, 0x42, 0xD3,
      0xB4, 0x25, 0x57, 0xC6, 0xB3, 0x22, 0x50, 0xC1, 0xBA, 0x2B, 0x59, 0xC8, 0xBD, 0x2C, 0x5E,
      0xCF,
  };
#endif
};
 
// Include template implementation
#define TMC9660_HEADER_INCLUDED
// NOLINTNEXTLINE(bugprone-suspicious-include) - Intentional: template implementation file
#include "../src/tmc9660.ipp"
#undef TMC9660_HEADER_INCLUDED
 
inline const char* GetDriverVersion() noexcept {
  return HF_TMC9660_VERSION_STRING;
}
 
} // namespace tmc9660