tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig Struct Reference

Configuration structure for velocity control auto-configuration. More...

#include <tmc9660.hpp>

Public Attributes
tmc9660::tmcl::VelocitySensorSelection	sensorSelection
	Velocity feedback sensor selection (required)
std::optional< uint16_t >	velocityP
	Velocity P gain [0-32767] (optional, default: 800).
std::optional< uint16_t >	velocityI
	Velocity I gain [0-32767] (optional, default: 1).
tmc9660::tmcl::VelocityPiNorm	pNormalization
tmc9660::tmcl::VelocityPiNorm	iNormalization
std::optional< uint16_t >	velocityScalingFactor
	Velocity scaling factor [1-2047] (optional).
std::optional< uint32_t >	encoderCountsPerRev
	Encoder counts per mechanical revolution (CPR) for auto-calculating velocity scaling.
std::optional< uint8_t >	motor_polePairs
	Motor pole pairs (optional, used for auto-calculating velocity scaling).
std::optional< uint32_t >	pwmFrequency_Hz
	PWM frequency in Hz (optional, used for velocity meter threshold calculation).
uint8_t	loopDownsampling = 5
	Velocity loop downsampling factor [0-127] (default: 5).
uint32_t	velocityReachedThreshold = 1000
	Velocity reached threshold (default: 1000)
std::optional< uint32_t >	stopOnDeviationMaxError
bool	stopOnDeviationSoftStop
	Use soft stop (ramp down) for deviation stop (default: true)
std::optional< uint32_t >	meterSwitchThreshold
	Velocity meter switch threshold (optional, auto-calculated if not provided).
uint16_t	meterHysteresis = 500
	Velocity meter hysteresis (default: 500)
int32_t	velocityOffset = 0
	Velocity offset [-200000 to 200000] (default: 0)
std::optional< bool >	enableVelocityBiquadFilter
	Enable/disable biquad filter on actual velocity feedback.
std::optional< int32_t >	velocityBiquadACoeff1
	Velocity biquad filter coefficients (optional, only used if enableVelocityBiquadFilter is explicitly set).
std::optional< int32_t >	velocityBiquadACoeff2
std::optional< int32_t >	velocityBiquadBCoeff0
std::optional< int32_t >	velocityBiquadBCoeff1
std::optional< int32_t >	velocityBiquadBCoeff2

Detailed Description

template<typename CommType>
struct tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig

Configuration structure for velocity control auto-configuration.

Member Data Documentation

enableVelocityBiquadFilter

template<typename CommType >

std::optional<bool> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::enableVelocityBiquadFilter

Enable/disable biquad filter on actual velocity feedback.

The velocity biquad filter filters the measured velocity before it's used as input to the velocity controller. This filter is enabled by default in hardware because measured velocity is usually quite noisy.

When enabled, you can optionally provide filter coefficients below. If coefficients are not provided, the filter uses default coefficient values optimized for typical velocity measurement noise reduction.

Default: Enabled (filter is on by default for noise reduction). Most users should leave this enabled unless they have specific requirements. Enable/disable biquad filter on actual velocity (optional, default: enabled in hardware)

encoderCountsPerRev

template<typename CommType >

std::optional<uint32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::encoderCountsPerRev

Encoder counts per mechanical revolution (CPR) for auto-calculating velocity scaling.

Required for ABN1_ENCODER, ABN2_ENCODER, or SPI_ENCODER sensor types. For SAME_AS_COMMUTATION or DIGITAL_HALL, this is calculated from motor_polePairs.

If not provided and sensor type requires it, scaling factor defaults to 1. Encoder CPR (optional, required for encoder-based sensors if velocityScalingFactor not provided)

iNormalization

template<typename CommType >

tmc9660::tmcl::VelocityPiNorm tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::iNormalization

Initial value:

=
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT

I-term normalization (default: SHIFT_16_BIT)

loopDownsampling

template<typename CommType >

uint8_t tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::loopDownsampling = 5

Velocity loop downsampling factor [0-127] (default: 5).

Clock Distribution: The velocity control loop frequency is derived from the PWM frequency:

• Velocity loop frequency = PWM frequency / (loop_downsampling + 1)
• Example: 25kHz PWM, downsampling=5 → velocity loop runs at 25kHz/6 = 4.17kHz

Effect on PI Gains: Lower loop frequencies (higher downsampling) require proportionally higher PI gains to maintain the same response. The integrator speed depends on both the PWM frequency and this downsampling factor.

Typical Values:

• 0-2: Fast response (high-frequency velocity control)
• 3-5: Standard (good balance, default: 5)
• 6-10: Slower response (for heavy loads or stability)
• >10: Very slow (rarely needed) Velocity loop downsampling factor [0-127] (default: 5)

meterHysteresis

template<typename CommType >

uint16_t tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::meterHysteresis = 500

Velocity meter hysteresis (default: 500)

meterSwitchThreshold

template<typename CommType >

std::optional<uint32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::meterSwitchThreshold

Velocity meter switch threshold (optional, auto-calculated if not provided).

Threshold for switching from period-based to frequency-based velocity measurement. The optimal switchover point is calculated to minimize measurement noise.

Auto-calculation: If not provided, the threshold is calculated using:

• encoderCountsPerRev (or derived from sensor type and motor_polePairs)
• pwmFrequency_Hz and loop_downsampling (to calculate velocity loop frequency)
• Formulas:
  • v_PerLim_RPM = 0.9 × (40MHz) / (CPR × 60 × 53)
  • v_COP_RPM = 60 × (f_Velo + sqrt(f_Velo² + f_Velo × 40MHz × 8)) / (4 × CPR)
  • v_THR_RPM = min(v_COP_RPM, v_PerLim_RPM)
  • threshold = v_THR_RPM × k_RPM (where k_RPM is the velocity scaling factor)

Note: If auto-calculation is not possible (missing parameters), default value (2000) is used. Velocity meter switch threshold (optional, auto-calculated if not provided)

motor_polePairs

template<typename CommType >

std::optional<uint8_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::motor_polePairs

Motor pole pairs (optional, used for auto-calculating velocity scaling).

Required for SAME_AS_COMMUTATION or DIGITAL_HALL sensor types. If not provided, the value is read from MotorConfig (MOTOR_POLE_PAIRS parameter). For encoder-based sensors, this is not used. Motor pole pairs (optional, read from MotorConfig if not provided)

pNormalization

template<typename CommType >

tmc9660::tmcl::VelocityPiNorm tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::pNormalization

Initial value:

=
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT

P-term normalization (default: SHIFT_16_BIT)

pwmFrequency_Hz

template<typename CommType >

std::optional<uint32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::pwmFrequency_Hz

PWM frequency in Hz (optional, used for velocity meter threshold calculation).

If not provided, the value is read from MotorConfig (MOTOR_PWM_FREQUENCY parameter). Used to calculate velocity loop frequency for meter switch threshold. PWM frequency in Hz (optional, read from MotorConfig if not provided)

sensorSelection

template<typename CommType >

tmc9660::tmcl::VelocitySensorSelection tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::sensorSelection

Velocity feedback sensor selection (required)

stopOnDeviationMaxError

template<typename CommType >

std::optional<uint32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::stopOnDeviationMaxError

Max allowed velocity deviation for stop condition (optional, disabled if not provided)

stopOnDeviationSoftStop

template<typename CommType >

bool tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::stopOnDeviationSoftStop

Initial value:

=
          true

Use soft stop (ramp down) for deviation stop (default: true)

velocityBiquadACoeff1

template<typename CommType >

std::optional<int32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityBiquadACoeff1

Velocity biquad filter coefficients (optional, only used if enableVelocityBiquadFilter is explicitly set).

These coefficients define the biquad filter difference equation: Y(n) = X(n)*b0 + X(n-1)*b1 + X(n-2)*b2 - Y(n-1)*a1 - Y(n-2)*a2

Coefficient Format: All coefficients are 24-bit values in Q4.20 fixed-point format:

• 4 integer bits (range: -8 to +7)
• 20 fractional bits (resolution: 1/1048576)
• To convert a floating-point value to Q4.20: coeff = (float_value * 1048576.0f)
• Example: 1.0 → 1048576, 0.5 → 524288, -0.25 → -262144

Default Values (if not provided): The hardware uses optimized default coefficients for velocity noise reduction:

• ACOEFF_1 = 1849195
• ACOEFF_2 = 15961938
• BCOEFF_0 = 3665
• BCOEFF_1 = 7329
• BCOEFF_2 = 3665

Note: For most applications, leave these unset to use the optimized hardware defaults. Only override if you have specific filtering requirements. Velocity biquad A coefficient 1 (a1) in Q4.20 format (optional, default: 1849195)

velocityBiquadACoeff2

template<typename CommType >

std::optional<int32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityBiquadACoeff2

Velocity biquad A coefficient 2 (a2) in Q4.20 format (optional, default: 15961938)

velocityBiquadBCoeff0

template<typename CommType >

std::optional<int32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityBiquadBCoeff0

Velocity biquad B coefficient 0 (b0) in Q4.20 format (optional, default: 3665)

velocityBiquadBCoeff1

template<typename CommType >

std::optional<int32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityBiquadBCoeff1

Velocity biquad B coefficient 1 (b1) in Q4.20 format (optional, default: 7329)

velocityBiquadBCoeff2

template<typename CommType >

std::optional<int32_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityBiquadBCoeff2

Velocity biquad B coefficient 2 (b2) in Q4.20 format (optional, default: 3665)

velocityI

template<typename CommType >

std::optional<uint16_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityI

Velocity I gain [0-32767] (optional, default: 1).

Direct I gain for the velocity PI controller. Higher values = better steady-state accuracy but potentially more overshoot. Typical range: 1-10. Velocity I gain [0-32767] (optional, default: 1)

velocityOffset

template<typename CommType >

int32_t tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityOffset = 0

Velocity offset [-200000 to 200000] (default: 0)

velocityP

template<typename CommType >

std::optional<uint16_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityP

Velocity P gain [0-32767] (optional, default: 800).

Direct P gain for the velocity PI controller. Higher values = faster response but potentially less stable. Typical range: 400-1600 for most applications. Velocity P gain [0-32767] (optional, default: 800)

velocityReachedThreshold

template<typename CommType >

uint32_t tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityReachedThreshold = 1000

Velocity reached threshold (default: 1000)

velocityScalingFactor

template<typename CommType >

std::optional<uint16_t> tmc9660::TMC9660< CommType >::VelocityControl::VelocityConfig::velocityScalingFactor

Velocity scaling factor [1-2047] (optional).

This factor converts internal velocity units to real-world RPM. Formula: v_RPM = v_internal / k_RPM, where k_RPM = VELOCITY_SCALING_FACTOR

Auto-calculation: If not provided, the scaling factor is automatically calculated from:

• encoderCountsPerRev (or derived from sensor type and motor_polePairs)
• motor_polePairs (for SAME_AS_COMMUTATION or DIGITAL_HALL sensors)
• Formula: k_RPM = (CPR × 2^24) / (40MHz × 60)

CPR calculation by sensor type:

• SAME_AS_COMMUTATION: CPR = 2^16 × motor_polePairs
• DIGITAL_HALL: CPR = 6 × motor_polePairs
• ABN1_ENCODER, ABN2_ENCODER, SPI_ENCODER: CPR = encoderCountsPerRev (from datasheet)

Note: It's recommended to leave this at default (1) and handle scaling externally for better resolution. Internal scaling reduces resolution. Velocity scaling factor [1-2047] (optional, auto-calculated if not provided)

---

The documentation for this struct was generated from the following file:

• tmc9660.hpp