TMC9660.hpp

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <cstdint>
#include <cstdlib>
#include <span>
#include <variant>
#include <vector>
 
#include "TMC9660Bootloader.hpp"
#include "TMC9660CommInterface.hpp"
#include "parameter_mode/tmc9660_param_mode_tmcl.hpp"
 
class TMC9660 {
public:
  TMC9660(TMC9660CommInterface &comm, uint8_t address = 0,
          const tmc9660::BootloaderConfig *bootCfg = nullptr) noexcept;
 
  ~TMC9660() noexcept;
 
  [[nodiscard]] TMC9660CommInterface &comm() noexcept {
    return comm_;
  }
 
  //***************************************************************************
  //**                  BOOTLOADER INITIALIZATION                          **//
  //***************************************************************************
 
  enum class BootloaderInitResult { Success, NoConfig, Failure };
 
  TMC9660::BootloaderInitResult
  bootloaderInit(const tmc9660::BootloaderConfig *cfg = nullptr) noexcept;
 
  //***************************************************************************
  //**               CORE PARAMETER ACCESS METHODS                         **//
  //***************************************************************************
 
  [[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;
 
  //***************************************************************************
  //**                  SUBSYSTEM: Motor Configuration                     **//
  //***************************************************************************
 
  struct MotorConfig {
    bool setType(tmc9660::tmcl::MotorType type, uint8_t polePairs = 1) noexcept;
 
    bool setDirection(tmc9660::tmcl::MotorDirection direction) noexcept;
 
    bool setPWMFrequency(uint32_t frequencyHz) noexcept;
 
    bool setCommutationMode(tmc9660::tmcl::CommutationMode mode) noexcept;
 
    bool setOutputVoltageLimit(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;
 
  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 scalingFactor) noexcept;
 
    bool getScalingFactor(uint16_t &scalingFactor) 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 &isCalibrated) 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 lowSide,
                           tmc9660::tmcl::PwmOutputPolarity highSide) noexcept;
 
    bool configureBreakBeforeMakeTiming(uint8_t lowSideUVW, uint8_t highSideUVW, uint8_t lowSideY2,
                                        uint8_t highSideY2) noexcept;
 
    bool enableAdaptiveDriveTime(bool enableUVW, bool enableY2) noexcept;
 
    bool configureDriveTimes(uint8_t sinkTimeUVW, uint8_t sourceTimeUVW, uint8_t sinkTimeY2,
                             uint8_t sourceTimeY2) noexcept;
 
    bool configureCurrentLimits(tmc9660::tmcl::GateCurrentSink sinkCurrentUVW,
                                tmc9660::tmcl::GateCurrentSource sourceCurrentUVW,
                                tmc9660::tmcl::GateCurrentSink sinkCurrentY2,
                                tmc9660::tmcl::GateCurrentSource sourceCurrentY2) noexcept;
 
    bool configureBootstrapCurrentLimit(tmc9660::tmcl::BootstrapCurrentLimit limit) noexcept;
 
    bool configureUndervoltageProtection(tmc9660::tmcl::UndervoltageLevel supplyLevel,
                                         tmc9660::tmcl::UndervoltageEnable enableVdrv,
                                         tmc9660::tmcl::UndervoltageEnable enableBstUVW,
                                         tmc9660::tmcl::UndervoltageEnable enableBstY2) noexcept;
 
    bool enableOvercurrentProtection(tmc9660::tmcl::OvercurrentEnable enableUVWLowSide,
                                     tmc9660::tmcl::OvercurrentEnable enableUVWHighSide,
                                     tmc9660::tmcl::OvercurrentEnable enableY2LowSide,
                                     tmc9660::tmcl::OvercurrentEnable enableY2HighSide) noexcept;
 
    bool setOvercurrentThresholds(tmc9660::tmcl::OvercurrentThreshold uvwLowSideThreshold,
                                  tmc9660::tmcl::OvercurrentThreshold uvwHighSideThreshold,
                                  tmc9660::tmcl::OvercurrentThreshold y2LowSideThreshold,
                                  tmc9660::tmcl::OvercurrentThreshold y2HighSideThreshold) noexcept;
 
    bool setOvercurrentBlanking(tmc9660::tmcl::OvercurrentTiming uvwLowSideTime,
                                tmc9660::tmcl::OvercurrentTiming uvwHighSideTime,
                                tmc9660::tmcl::OvercurrentTiming y2LowSideTime,
                                tmc9660::tmcl::OvercurrentTiming y2HighSideTime) noexcept;
 
    bool setOvercurrentDeglitch(tmc9660::tmcl::OvercurrentTiming uvwLowSideTime,
                                tmc9660::tmcl::OvercurrentTiming uvwHighSideTime,
                                tmc9660::tmcl::OvercurrentTiming y2LowSideTime,
                                tmc9660::tmcl::OvercurrentTiming y2HighSideTime) noexcept;
 
    bool enableVdsMonitoringLow(tmc9660::tmcl::VdsUsage uvwEnable,
                                tmc9660::tmcl::VdsUsage y2Enable) noexcept;
 
    bool configureVgsShortProtectionUVW(tmc9660::tmcl::VgsShortEnable enableLowSideOn,
                                        tmc9660::tmcl::VgsShortEnable enableLowSideOff,
                                        tmc9660::tmcl::VgsShortEnable enableHighSideOn,
                                        tmc9660::tmcl::VgsShortEnable enableHighSideOff) noexcept;
 
    bool configureVgsShortProtectionY2(tmc9660::tmcl::VgsShortEnable enableLowSideOn,
                                       tmc9660::tmcl::VgsShortEnable enableLowSideOff,
                                       tmc9660::tmcl::VgsShortEnable enableHighSideOn,
                                       tmc9660::tmcl::VgsShortEnable enableHighSideOff) noexcept;
 
    bool setVgsShortBlankingTime(tmc9660::tmcl::VgsBlankingTime uvwTime,
                                 tmc9660::tmcl::VgsBlankingTime y2Time) noexcept;
 
    bool setVgsShortDeglitchTime(tmc9660::tmcl::VgsDeglitchTime uvwTime,
                                 tmc9660::tmcl::VgsDeglitchTime y2Time) noexcept;
 
    bool setRetryBehavior(tmc9660::tmcl::GdrvRetryBehaviour retryBehavior) noexcept;
 
    bool setDriveFaultBehavior(tmc9660::tmcl::DriveFaultBehaviour faultBehavior) noexcept;
 
    bool setFaultHandlerRetries(uint8_t retries) 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 getHallPhiE(int16_t &phiE) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
    //  ABN encoders (ABN1, ABN2)
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
    bool
    configureABNEncoder(uint32_t countsPerRev,
                        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 &phiE) 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 countsPerRev,
        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 cmdSize, uint16_t csSettleTimeNs,
                             uint8_t csIdleTimeUs) noexcept;
 
    bool configureSPIEncoderDataFormat(
        uint32_t positionMask, 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 initMethod,
                                           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 &shiftFactor) noexcept;
 
    // –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
  private:
    friend class TMC9660;
    explicit FeedbackSense(TMC9660 &parent) noexcept : driver(parent) {}
    TMC9660 &driver;
  } feedbackSense{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: FOC Control                              **//
  //***************************************************************************
 
  struct FOCControl {
    //-------------------------------------------------------------------------
    // 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 pNorm,
                                 tmc9660::tmcl::CurrentPiNormalization iNorm) 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;
 
    //-------------------------------------------------------------------------
    // Velocity control (123–139)
    //-------------------------------------------------------------------------
    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 pNorm,
                                  tmc9660::tmcl::VelocityPiNorm iNorm) 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 maxError, bool softStop = true) noexcept;
    bool getStopOnVelocityDeviation(uint32_t &maxError, bool &softStop) noexcept;
 
    bool setVelocityLoopDownsampling(uint8_t divider) noexcept;
    bool getVelocityLoopDownsampling(uint8_t &divider) noexcept;
 
    bool setVelocityReachedThreshold(uint32_t threshold) noexcept;
    bool getVelocityReachedThreshold(uint32_t &threshold) noexcept;
 
    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;
 
    //-------------------------------------------------------------------------
    // Position control (142–157)
    //-------------------------------------------------------------------------
    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 pNorm,
                                  tmc9660::tmcl::VelocityPiNorm iNorm) noexcept;
 
    bool getPositionPiIntegrator(int32_t &integrator) noexcept;
    bool getPositionPiError(int32_t &error) noexcept;
 
    bool setStopOnPositionDeviation(uint32_t maxError, bool softStop = true) noexcept;
    bool getStopOnPositionDeviation(uint32_t &maxError, bool &softStop) 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;
 
    //-------------------------------------------------------------------------
    // 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;
 
    //-------------------------------------------------------------------------
    // 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;
 
    //-------------------------------------------------------------------------
    // Additional FOC telemetry and tuning parameters (305–334)
    //-------------------------------------------------------------------------
 
    // 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;
 
    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 setFieldWeakeningI(uint16_t milliamps) noexcept;
    bool getFieldWeakeningI(uint16_t &milliamps) noexcept;
    bool setFieldWeakeningVoltageThreshold(uint16_t voltage) noexcept;
    bool getFieldWeakeningVoltageThreshold(uint16_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 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 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 getTorqueFluxCombinedTargetValues(uint32_t &value) noexcept;
    bool getTorqueFluxCombinedActualValues(uint32_t &value) noexcept;
    bool getVoltageDqCombinedActualValues(uint32_t &value) noexcept;
    bool getIntegratedActualTorqueValue(uint32_t &value) noexcept;
    bool getIntegratedActualVelocityValue(uint32_t &value) noexcept;
 
  private:
    friend class TMC9660;
    explicit FOCControl(TMC9660 &parent) noexcept : driver(parent) {}
    TMC9660 &driver;
  } focControl{*this};
 
  //***************************************************************************
  //**                  SUBSYSTEM: Motion Ramp                             **//
  //***************************************************************************
 
  struct Ramp {
    bool enable(bool on) noexcept;
 
    bool setAcceleration(uint32_t a1, uint32_t a2, uint32_t aMax) noexcept;
 
    bool setDeceleration(uint32_t d1, uint32_t d2, uint32_t dMax) noexcept;
 
    bool setVelocities(uint32_t vStart, uint32_t vStop, uint32_t v1, uint32_t v2,
                       uint32_t vMax) noexcept;
 
    bool setTiming(uint16_t tVmaxCycles, uint16_t tZeroWaitCycles) noexcept;
 
    bool enableFeedForward(bool enableVelFF, bool enableAccelFF, uint16_t accelFFGain,
                           tmc9660::tmcl::AccelerationFFShift accelFFShift) noexcept;
 
    bool setDirectVelocityMode(bool enable) noexcept;
 
    bool getRampVelocity(int32_t &velocity) noexcept;
 
    bool getRampPosition(int32_t &position) 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 eRPM) noexcept;
 
    bool enableVelocityFeedForward(bool enableVelFF) 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;
 
  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 maxVelError, uint32_t maxPosError,
        bool softStop = true) noexcept; 
 
    bool
    configureReferenceSwitches(uint8_t mask, bool invertL, bool invertR, bool invertH,
                               bool swapLR) noexcept; 
 
    bool getAndClearLatchedPosition(int32_t &pos) noexcept; 
 
  private:
    friend class TMC9660;
    explicit StopEvents(TMC9660 &parent) noexcept : driver(parent) {}
    TMC9660 &driver;
  } stopEvents{*this};
 
  //===========================================================================
  //==                  SUBSYSTEM: Protection                               ==//
  //===========================================================================
 
  struct Protection {
    bool configureVoltage(uint16_t overVoltThreshold, uint16_t underVoltThreshold) noexcept;
 
    bool configureTemperature(float warningDegC, float shutdownDegC) 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;
 
  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> &scriptData) 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 sampleCount) noexcept;
 
    bool startCapture() noexcept;
 
    bool readData(uint32_t index, uint32_t &data) noexcept;
 
    bool getStatus(bool &isRunning) 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;
 
  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;
 
  private:
    friend class TMC9660;
    explicit Power(TMC9660 &parent) noexcept : driver(parent) {}
    TMC9660 &driver;
  } power{*this};
 
  //==================================================
  // PRIVATE MEMBERS
  //==================================================
private:
  TMC9660CommInterface &comm_;            
  uint8_t address_;                       
  tmc9660::TMC9660Bootloader 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
};