StallGuard Tuning : autotune stallguard sensitivity

[narno2202]

Description

This updated pull request supersedes #28455 after a huge refactoring. This PR adds STALLGUARD_TUNING option in Configuration_adv.h, enabling automatic tuning of TMC stallguard thresholds for X/Y sensorless homing in Marlin.
Both StallGuard2 and StallGuard4 drivers are supported for Cartesian and CoreXY printers. For axis with 2 stepper drivers or a CoreXY printer, StallGuard version must be the same or in case of a mismatch, one driver must be a TMC2240.
STALLGUARD_TUNING offers separate tuning results for standard motion and FT_MOTION when both are enabled.

STALLGUARD_TUNING adds:

• a new G-Code M921 for tuning X or Y axis: M921 X or M921 Yand M921 S0 or M921 S1 to save from Fixed Time Motion tuning or Standard motion tuning
• if menu is enabled, a menu entry under TMC settings for launching the autotuning routine and saving the tuned values
• EDITABLE_HOMING_CURRENT must be enabled if you want to save the used tuning current

The tuning routine reports:

• proposed sensitivity values for FT_MOTION
• proposed sensitivity values for standard motion
• success/failure status for each tuning pass

Remeber that the results are only valid for the current and the speed used in the tuning routine.

If both FT_MOTION and standard motion are enabled, the system runs:

1. FT_MOTION tuning first
2. standard motion tuning second

Common flow

SGTHRS is the threshold value (sensitivity), SG_RESULT represents "the motor load".

• The tuning routine temporarily sets motor current to 50% of configured standard current (X_CURRENT, Y_CURRENT) with a minimum of 400 mA to optimize back-EMF behavior.
• Tuning routine uses HOMING_FEEDRATE_MM_M/ 60 for velocity and the same value for motion distance
• Stallguard is enabled on the relevant stepper drivers and the axis is moved until a valid threshold is found or a tuning failure.
• After tuning, the drivers are restored to their default state.

StallGuard2 tuning

• Movements are always one forward and one backward move
• Starts with SGTHRS = 0 for a free move:
• Samples SG_RESULT in a histogram while moving then computes the median of the SG_RESULT sample.
• Adjusts SGTHRS progressively until SG_RESULT is in the target window of 80..120

The range 80-120 matches StallGuard2 datasheet behavior where SG_RESULT indicates proximity to stall. SGTHRS is tuned automatically for the printer motion systems: standard motion and/or FT_MOTION. As the 2 values should be in the good range, either one or another can be chosen.

StallGuard4 tuning

• Movements are always one forward and one backward move
• Starts with SGTHRS = 0 for a free move:
• Samples SG_RESULT in a histogram while moving then computes the median of the SG_RESULT sample.
• Sets initial SGTHRS to one sixth of the median SG_RESULT to avoid false triggers during acceleration
• Enables endstops
• Then repeat: increase SGTHRS, do a move, check the endstop. Stop when the endstop is triggered (the endstop is triggered during the acceleration phase)

For StallGuard4, SG_RESULT is tested against SGTHRS * 2 to detect a stall: SG_RESULT < 2 * SGTHRS. If both standard motion and FT_MOTION are present, the preferred final SGTHRS is the lowest value.

Tested with TMC2226 stepper drivers (equivalent to TMC2209, StallGuard4), 1 driver on X, 2 drivers on Y. Tuning done with standard and FTM motion system. The refactoring improves reliability and repeatability as zombie values are eliminated. The returned values for the 2 motion systems were different but not enough to have a sensorless homing failure.

Please test the function for SG2, SG4 and CoreXY, the menu. Waiting for feedback and suggestions

Requirements

Both SENSORLESS_HOMING and STALLGUARD_TUNING enabled, Sanitycheck.h will do the rest.

Benefits

• Automates sensorless homing threshold calibration for TMC stallguard drivers
• Supports both StallGuard2 and StallGuard4 variants
• Reduces manual threshold trial-and-error
• Provides consistent behavior for machines using both standard and FT motion systems

Configurations

Related Issues