tmc51x0::StealthChopConfig Struct Reference

StealthChop configuration structure. More...

#include <tmc51x0_types.hpp>

Public Member Functions
	StealthChopConfig ()=default
	Default constructor.
	StealthChopConfig (uint8_t pwm_frequency, uint8_t pwm_offset=30, uint8_t pwm_gradient=0, uint8_t regulation_speed=4, uint8_t jerk_reduction=12)
	Helper constructor for automatic tuning mode.
	StealthChopConfig (StealthChopPwmFreq pwm_frequency, StealthChopRegulationSpeed regulation_speed=StealthChopRegulationSpeed::MODERATE, StealthChopJerkReduction jerk_reduction=StealthChopJerkReduction::MODERATE, uint8_t pwm_offset=30, uint8_t pwm_gradient=0)
	Helper constructor using enums (most intuitive)
	StealthChopConfig (uint8_t pwm_frequency, uint8_t pwm_offset, uint8_t pwm_gradient)
	Helper constructor for manual mode.

Public Attributes
uint8_t	pwm_ofs {30}
	PWM amplitude offset.
uint8_t	pwm_grad {0}
	PWM amplitude gradient.
uint8_t	pwm_freq {1}
	PWM frequency selection.
bool	pwm_autoscale {true}
	Enable automatic current scaling.
bool	pwm_autograd {true}
	Enable automatic gradient adaptation.
uint8_t	pwm_reg {4}
	Regulation speed.
uint8_t	pwm_lim {12}
	Mode switching jerk reduction.
PWMFreewheel	freewheel {PWMFreewheel::NORMAL}
	Freewheeling mode when I_HOLD=0.
float	velocity_threshold {0.0F}
	StealthChop velocity threshold (TPWMTHRS)
Unit	velocity_threshold_unit {Unit::Steps}
	Unit for velocity threshold.

Detailed Description

StealthChop configuration structure.

User-friendly configuration for StealthChop2 voltage PWM mode operation. StealthChop provides extremely quiet, noiseless operation for stepper motors, making it ideal for indoor or home use applications.

StealthChop2 features automatic tuning (AT) that adapts operating parameters to the motor automatically. Two tuning phases are required:

• AT#1: Motor in standstill with nominal run current (≤130ms)
• AT#2: Motor moving at medium velocity (60-300 RPM typical, 8+ fullsteps)

Note

StealthChop requires motor to be at standstill when first enabled.

Keep motor stopped for at least 128 chopper periods after enabling StealthChop.

StealthChop and StallGuard2 are mutually exclusive (StallGuard2 requires SpreadCycle).

Lower current limit applies: IRUN ≥ 8 and current must exceed I_LOWER_LIMIT.

Open load detection should be performed in SpreadCycle before enabling StealthChop.

Motor stall during StealthChop can cause overcurrent - tune low-side overcurrent detection.

See also

Datasheet section 7: StealthChop™

Constructor & Destructor Documentation

StealthChopConfig() [1/4]

tmc51x0::StealthChopConfig::StealthChopConfig ( )

default

Default constructor.

Initializes with recommended default values for automatic tuning mode:

• pwm_ofs: 30 (typical starting value, normal mode)
• pwm_grad: 0 (let automatic tuning determine)
• pwm_freq: 1 (~35kHz @ 12MHz, recommended)
• pwm_autoscale: true (automatic current scaling)
• pwm_autograd: true (automatic gradient adaptation)
• pwm_reg: 4 (balanced regulation, 2 increments per half wave)
• pwm_lim: 12 (balanced jerk reduction)
• freewheel: NORMAL (normal operation)
• velocity_threshold: 0.0 (disabled, always use SpreadCycle)

StealthChopConfig() [2/4]

tmc51x0::StealthChopConfig::StealthChopConfig ( uint8_t pwm_frequency, uint8_t pwm_offset = 30, uint8_t pwm_gradient = 0, uint8_t regulation_speed = 4, uint8_t jerk_reduction = 12 )

inline

Helper constructor for automatic tuning mode.

Creates a StealthChop configuration optimized for automatic tuning.

Parameters

pwm_frequency	PWM frequency (StealthChopPwmFreq enum or 0-3)
pwm_offset	Initial PWM offset (0=special mode, 1-255=normal, 30=typical)
pwm_gradient	Initial PWM gradient (0-255, 0=auto)
regulation_speed	Regulation speed (StealthChopRegulationSpeed enum or 1-15, 4=balanced)
jerk_reduction	Jerk reduction (StealthChopJerkReduction enum or 0-15, 12=balanced)

StealthChopConfig() [3/4]

tmc51x0::StealthChopConfig::StealthChopConfig ( StealthChopPwmFreq pwm_frequency, StealthChopRegulationSpeed regulation_speed = StealthChopRegulationSpeed::MODERATE, StealthChopJerkReduction jerk_reduction = StealthChopJerkReduction::MODERATE, uint8_t pwm_offset = 30, uint8_t pwm_gradient = 0 )

inline

Helper constructor using enums (most intuitive)

Creates a StealthChop configuration using intuitive enums.

Parameters

pwm_frequency	PWM frequency enum
regulation_speed	Regulation speed enum
jerk_reduction	Jerk reduction enum
pwm_offset	Initial PWM offset (0=special mode, 1-255=normal, 30=typical)
pwm_gradient	Initial PWM gradient (0-255, 0=auto)

StealthChopConfig() [4/4]

tmc51x0::StealthChopConfig::StealthChopConfig ( uint8_t pwm_frequency, uint8_t pwm_offset, uint8_t pwm_gradient )

inline

Helper constructor for manual mode.

Creates a StealthChop configuration for manual (non-automatic) mode. Requires well-known motor and operating conditions.

Parameters

pwm_frequency	PWM frequency (StealthChopPwmFreq enum or 0-3)
pwm_offset	PWM offset (calculated: 374 * R_COIL * I_COIL / V_M)
pwm_gradient	PWM gradient (calculated from back EMF constant)

Member Data Documentation

freewheel

PWMFreewheel tmc51x0::StealthChopConfig::freewheel {PWMFreewheel::NORMAL}

Freewheeling mode when I_HOLD=0.

Standstill option when motor current setting is zero. Only available with StealthChop enabled.

Options:

• NORMAL: Normal operation (coast when ihold=0)
• ENABLED: Freewheeling (low resistance, easy to move)
• SHORT_LS: Coil short via low-side drivers (passive brake)
• SHORT_HS: Coil short via high-side drivers (passive brake)

Note

Freewheeling makes motor easy to move.

Coil short options realize passive braking (energy efficient).

Enabled after TPOWERDOWN and IHOLDDELAY delay. Freewheeling mode when I_HOLD=0

pwm_autograd

bool tmc51x0::StealthChopConfig::pwm_autograd {true}

Enable automatic gradient adaptation.

Enables automatic tuning of PWM_GRAD_AUTO during AT#2 phase.

• true (recommended): Automatic gradient tuning
  • Driver optimizes PWM_GRAD_AUTO during AT#2
  • Adapts to motor characteristics automatically
• false: Use PWM_GRAD from register
  • Use pre-determined PWM_GRAD value
  • Reduces amplitude jitter
  • Requires manual tuning

Note

Set to false if you have pre-determined PWM_GRAD and want to reduce jitter. Enable automatic gradient adaptation (recommended)

pwm_autoscale

bool tmc51x0::StealthChopConfig::pwm_autoscale {true}

Enable automatic current scaling.

Enables automatic current regulation using current measurement feedback.

• true (recommended): Automatic scaling with current regulator
  • Adapts to motor heating, supply voltage changes
  • Responds to motor stall and load changes
  • Requires current measurement (sense resistors)
• false: Feed-forward velocity-controlled mode
  • Very stable amplitude
  • Does not react to supply voltage changes or motor stall
  • Does not require current measurement
  • Only for well-known motor and operating conditions

Note

Recommended: Use automatic mode (true) unless current regulation is not satisfying.

Non-automatic mode requires careful programming and well-known conditions. Enable automatic current scaling (recommended)

pwm_freq

uint8_t tmc51x0::StealthChopConfig::pwm_freq {1}

PWM frequency selection.

Chopper frequency selection for StealthChop operation. Lower frequencies reduce current ripple but may limit high-velocity performance. Higher frequencies improve high-velocity performance but increase power dissipation.

Can be specified as:

• uint8_t (0-3): Raw register value
• StealthChopPwmFreq enum: More intuitive (recommended)

Recommended: PWM_FREQ_1 (~35kHz @ 12MHz clock) for most applications Use lowest setting giving good results.

Note

Actual frequency depends on clock frequency (f_CLK).

Lower blank time (TBL) allows lower current limit.

During AT#1, driver may reduce frequency if current cannot be reached. PWM frequency (0-3 or StealthChopPwmFreq enum, 1=recommended)

pwm_grad

uint8_t tmc51x0::StealthChopConfig::pwm_grad {0}

PWM amplitude gradient.

Velocity-dependent factor to compensate for back EMF. Used as initialization value for automatic tuning (PWM_GRAD_AUTO).

Range: 0-255

• Typical: 0 (default) - let automatic tuning determine

Calculation (for manual mode, pwm_autoscale=0): PWM_GRAD = C_BEMF * 2π * f_CLK * 1.46 / (V_M * MSPR)

Note

With automatic tuning (pwm_autograd=1), this is used as initial value.

After AT#2, actual value is stored in PWM_GRAD_AUTO (read via GetPwmAuto()). PWM amplitude gradient (0-255, velocity compensation)

pwm_lim

uint8_t tmc51x0::StealthChopConfig::pwm_lim {12}

Mode switching jerk reduction.

Controls current jerk reduction when switching from SpreadCycle to StealthChop. Limits PWM_SCALE_AUTO when switching back from SpreadCycle to StealthChop.

Can be specified as:

• uint8_t (0-15): Raw register value (upper 4 bits of 8-bit amplitude limit)
  • Lower values: Lower current jerk (smoother switching)
  • Higher values: Higher current jerk (faster switching)
  • Default: 12 (recommended, balanced)
• StealthChopJerkReduction enum: More intuitive (recommended)

Note

Reduce value if experiencing current spikes during mode switching.

Only affects switching from SpreadCycle to StealthChop.

Does not limit PWM_GRAD or PWM_GRAD_AUTO offset. Jerk reduction (0-15 or StealthChopJerkReduction enum, 12=balanced)

pwm_ofs

uint8_t tmc51x0::StealthChopConfig::pwm_ofs {30}

PWM amplitude offset.

Initial value for PWM amplitude (offset) for velocity-based scaling. Used as initialization value for automatic tuning (PWM_OFS_AUTO).

Range: 0-255

• 0: Special mode - Disables scaling down motor current below lower measurement threshold. Prevents motor going out of regulation but also prevents power down below regulation limit. Use only when power supply voltage can vary up and down by factor of 2 or more.
• 1-255: Normal mode - Allows automatic scaling to low PWM duty cycles even below regulation threshold. Enables low standstill current settings based on IHOLD_IRUN register.
• Typical: 30 (default) for most motors

Calculation (for manual mode, pwm_autoscale=0): PWM_OFS = 374 * R_COIL * I_COIL / V_M

Note

With automatic tuning (pwm_autoscale=1), this is used as initial value.

After AT#1, actual value is stored in PWM_OFS_AUTO (read via GetPwmAuto()).

PWM_OFS = 0 should only be used under certain conditions (see above). PWM amplitude offset (0=special mode, 1-255=normal, 30=typical)

pwm_reg

uint8_t tmc51x0::StealthChopConfig::pwm_reg {4}

Regulation speed.

Controls how fast the PWM amplitude regulation loop adapts to changes. Specifies maximum PWM amplitude change per half wave when using automatic scaling.

Can be specified as:

• uint8_t (1-15): Raw register value
  • 1: 0.5 increments per half wave (slowest, most stable)
  • 2: 1 increment per half wave
  • 4: 2 increments per half wave (default, balanced)
  • 8: 4 increments per half wave
  • 15: 7.5 increments per half wave (fastest, may be less stable)
• StealthChopRegulationSpeed enum: More intuitive (recommended)

Lower values: Stable, soft regulation (slower response) Higher values: Faster adaptation (may be less stable)

Note

Should be as small as possible for stability, but large enough for quick reaction.

Higher acceleration during AT#2 requires higher regulation speed.

Optimize for fastest required acceleration/deceleration ramp. Regulation speed (1-15 or StealthChopRegulationSpeed enum, 4=balanced)

velocity_threshold

float tmc51x0::StealthChopConfig::velocity_threshold {0.0F}

StealthChop velocity threshold (TPWMTHRS)

Velocity threshold below which StealthChop is active. Above this threshold, driver switches to SpreadCycle mode.

Range: 0.0 to maximum velocity (in steps/s or unit specified by velocity_threshold_unit)

• 0.0: StealthChop disabled (always use SpreadCycle)
• >0.0: StealthChop active below threshold, SpreadCycle above threshold

Note

Unit is specified by velocity_threshold_unit field.

Automatically converted to TSTEP format (TPWMTHRS register) during initialization.

Typical values: 100-1000 steps/s depending on motor and application.

Set to 0.0 to disable StealthChop velocity threshold (always use SpreadCycle). StealthChop velocity threshold (0 = disabled, always SpreadCycle)

velocity_threshold_unit

Unit tmc51x0::StealthChopConfig::velocity_threshold_unit {Unit::Steps}

Unit for velocity threshold.

Specifies the unit used for velocity_threshold field. Unit for velocity threshold

---

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

• tmc51x0_types.hpp