tmc51x0::TMC51x0< CommType >::Tuning Struct Reference

Tuning subsystem for automatic parameter optimization. More...

#include <tmc51x0.hpp>

Collaboration diagram for tmc51x0::TMC51x0< CommType >::Tuning:

Public Member Functions
	Tuning (TMC51x0 &driver) noexcept
	Construct tuning subsystem.
Result< void >	TuneStallGuard (float target_velocity, StallGuardTuningResult &result, int8_t min_sgt=-20, int8_t max_sgt=20, float acceleration=5.0F, float min_velocity=0.0F, float max_velocity=0.0F, Unit velocity_unit=Unit::RPM, Unit acceleration_unit=Unit::RevPerSec) noexcept
	Automatically tune StallGuard threshold (SGT) with comprehensive velocity range analysis.
Result< void >	AutoTuneStallGuard (float target_velocity, StallGuardTuningResult &result, int8_t min_sgt=-20, int8_t max_sgt=20, float acceleration=5.0F, float min_velocity=0.0F, float max_velocity=0.0F, Unit velocity_unit=Unit::RPM, Unit acceleration_unit=Unit::RevPerSec, float current_reduction_factor=0.3F) noexcept
	Comprehensive automatic StallGuard tuning with current reduction and optional encoder verification.

Private Attributes
TMC51x0 &	driver_
	Reference to parent driver instance.

Detailed Description

template<typename CommType>
struct tmc51x0::TMC51x0< CommType >::Tuning

Tuning subsystem for automatic parameter optimization.

Provides methods for automatically tuning driver parameters such as StallGuard2 threshold (SGT) for optimal performance.

Constructor & Destructor Documentation

Tuning()

template<typename CommType >

tmc51x0::TMC51x0< CommType >::Tuning::Tuning ( TMC51x0 & driver )

inlineexplicitnoexcept

Construct tuning subsystem.

Parameters

driver

Reference to parent TMC51x0 driver instance

Member Function Documentation

AutoTuneStallGuard()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Tuning::AutoTuneStallGuard ( float target_velocity, StallGuardTuningResult & result, int8_t min_sgt = -20, int8_t max_sgt = 20, float acceleration = 5.0F, float min_velocity = 0.0F, float max_velocity = 0.0F, Unit velocity_unit = Unit::RPM, Unit acceleration_unit = Unit::RevPerSec, float current_reduction_factor = 0.3F )

noexcept

Comprehensive automatic StallGuard tuning with current reduction and optional encoder verification.

Parameters

target_velocity	Target velocity for tuning (most important - optimal SGT is determined here)
result	Reference to store comprehensive tuning results
min_sgt	Minimum SGT to try (default: -20, range: -64 to +63)
max_sgt	Maximum SGT to try (default: +20, range: -64 to +63)
acceleration	Acceleration/deceleration in rev/s² (default: 5.0)
min_velocity	Minimum velocity to verify tuning at (0 = disabled)
max_velocity	Maximum velocity to verify tuning at (0 = disabled)
velocity_unit	Unit for velocity parameters (default: RPM)
acceleration_unit	Unit for acceleration parameter (default: RevPerSec, RPM is not valid for acceleration)
current_reduction_factor	Current reduction factor as percentage (0.0-1.0, where 0.3 = 30% of current motor current). Default: 0.3 (30%) per Duet3D best practices for stall detection. Set to 0 to disable.

Returns

Result<void> indicating success or error

This is an enhanced version of TuneStallGuard that implements comprehensive automatic tuning following Trinamic application note AN-002 guidelines and industry best practices:

Key Features:

• Current Reduction: Reduces motor current for safer tuning and improved StallGuard sensitivity using percentage-based reduction. Current is automatically restored after tuning.
• Comprehensive Preparation: Disables interfering features (CoolStep, StallGuard filter, stop-on-stall) during tuning, then restores them afterward.
• Systematic SGT Scanning: Searches for optimal SGT value that provides SG_RESULT in the ideal range (100-500) at no-load, ensuring reliable stall detection.
• Velocity Range Validation: Tests optimal SGT at min/max velocities to determine actual operating range.
• Optional Encoder Verification: If encoder is available, can verify stall detection accuracy (requires external implementation).

Tuning Process:

1. Save current motor settings (IRUN, IHOLD, GLOBAL_SCALER, CoolStep config)
2. Apply current reduction if specified (percentage-based) - reduces current for safer tuning and improved StallGuard sensitivity
3. Disable CoolStep (SGMIN=0) to prevent current modulation during tuning
4. Disable StallGuard filter (SFILT=0) for immediate response during calibration
5. Disable stop-on-stall to allow manual observation during tuning
6. Find optimal SGT at target velocity (primary goal)
7. Verify optimal SGT works at min/max velocities (if specified)
8. Restore all saved settings

Current Reduction: If current_reduction_factor > 0, reduces current to (current_motor_current * current_reduction_factor). Example: 0.3 = 30% of current motor current. The function uses the driver's current calculation functions to determine the appropriate IRUN and GLOBAL_SCALER values. The current is constrained to ensure the motor can still move (minimum IRUN=8 for StealthChop compatibility).

Note

Target velocity is the most important parameter - optimal SGT is determined here first

If current_reduction_factor is 0, the motor current is not changed

Current reduction is applied by recalculating IRUN/GLOBAL_SCALER from the reduced current

All settings (current, CoolStep, filter) are automatically restored after tuning

This function takes several seconds to complete (typically 5-30 seconds depending on SGT range)

For best results, ensure the motor is unloaded during tuning

See also

TuneStallGuard() for a simpler version without current reduction handling

TuneStallGuard()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Tuning::TuneStallGuard ( float target_velocity, StallGuardTuningResult & result, int8_t min_sgt = -20, int8_t max_sgt = 20, float acceleration = 5.0F, float min_velocity = 0.0F, float max_velocity = 0.0F, Unit velocity_unit = Unit::RPM, Unit acceleration_unit = Unit::RevPerSec )

noexcept

Automatically tune StallGuard threshold (SGT) with comprehensive velocity range analysis.

Parameters

target_velocity	Target velocity for tuning (most important - optimal SGT is determined here)
result	Reference to store comprehensive tuning results
min_sgt	Minimum SGT to try (default: -20, range: -64 to +63)
max_sgt	Maximum SGT to try (default: +20, range: -64 to +63)
acceleration	Acceleration/deceleration in rev/s² (default: 5.0)
min_velocity	Minimum velocity to verify tuning at (0 = disabled, used to determine SGT range)
max_velocity	Maximum velocity to verify tuning at (0 = disabled, used to determine SGT range)
velocity_unit	Unit for velocity parameters (default: RPM)
acceleration_unit	Unit for acceleration parameter (default: RevPerSec, RPM is not valid for acceleration)

Returns

Result<void> indicating success or error

Implements a comprehensive automatic tuning algorithm that prioritizes target velocity:

1. Finds optimal SGT at target_velocity (primary goal - most important)
2. Verifies optimal SGT works at min_velocity and max_velocity (if specified)
3. If min/max velocities don't work with optimal SGT, finds what velocities DO work
4. Reports all findings in the result structure

The algorithm ensures:

• Target velocity gets the best possible SGT value (highest priority)
• Min/max velocities are tested to determine the usable SGT range
• If requested velocities aren't achievable, actual achievable velocities are reported

Note

Target velocity is the most important parameter - optimal SGT is determined here first

Min and max velocities are used to determine the range of SGT values that work

If min/max velocities are not possible, actual_min_velocity and actual_max_velocity in the result struct contain the velocities that DO work with the optimal SGT

Member Data Documentation

driver_

template<typename CommType >

TMC51x0& tmc51x0::TMC51x0< CommType >::Tuning::driver_

private

Reference to parent driver instance.

---

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

• tmc51x0.hpp