Trinamic drivers have 2 basic modes. SteathChop is the super quiet mode and CoolStep is a mode where the driver can dynamically increase the current when the motor is under load. Since CoolStep can determine the load, in many cases it can sense when the motor is about to stall or has already stalled. For further reading, Trinamic has an app note about StallGuard.
It does this by measuring the ratio of energy sent to the motor and energy returned. As the load on a motor increases, less energy is returned. When the returned energy falls to a certain point, the driver will indicate a stall. Since there are many sources of power loss, like wiring and motor design, the driver allows you to set the level where the stall is indicated.
Each machine needs to be tuned for motor size/current, speeds, mass, etc. It is a slow and time consuming process. The firmware can only help a little because this is purely a driver features.
The method does not work at very low and very high speeds. You must test your system to determine a good speed to for stall detection to avoid missed stalls or false indications.
The driver chips output a signal on pin associated with the StallGuard state. This pin must be wired to the ESP32. Some controllers do this directly on the PCB. Some may require the use of a jumper or physical wire. This is treated exactly like a mechanical switch by FluidNC. Please read about limits switch setup in other areas of this wiki for help with that.
At best it is accurate to about 1-2 full steps. Most basic switches will be far more accurate. The accuracy may be fine for X and Y on a 3D printer or pen plotter, but probably not for a router or laser engraver.
Setting it up can be a long and frustrating process. Please do not expect a lot of help and support with it. It is not something that is easy to help with remotely.
Here are the config file setting that apply to Stallguard homing. You still need all the other settings, but these specifically apply to this mode.
homing:
feed_mm_per_min: 200.000
seek_mm_per_min: 200.000
motor0:
limit_neg_pin: gpio.4:high
tmc_2209:
stallguard: 15
stallguard_debug: false
homing_mode: StallGuard
In most cases the circuit on the stepper driver is an open drain that closes to ground. This means you define the the switch pin as active low (:low). You also need a pull up resistor somewhere. If your controller has pull up resistors that will be fine. You can also add the ESP32 internal pullup with :pu on the pins that support it.
limit_neg_pin: gpio.33:low:pu
Check the state of the limit switches with no motion with the ? status request command. No limit swithces should be reporting. If they are, change the active state with pin attributes.
Turn on the display of StallGuard data with $/axes/x/motor0/tmc_2209/stallguard_debug=true. This will cause StallGuard data to be output to the USB/Serial port. It must use the serial port for best speed and timing of the data. The data will look like this. These are 4 readings directly before a stall was detected. Note: Only use this reporting when tuning. Turn off the reporting when running normal gcode.
Sometimes the exact reporting text and style changes with the release version, but generally the basic information is the same.
[MSG:INFO: X Axis Stallguard 0 SG_Val:784 Rate:200.000 mm/min SG_Setting:6]
[MSG:INFO: X Axis Stallguard 0 SG_Val:784 Rate:200.000 mm/min SG_Setting:6]
[MSG:INFO: X Axis Stallguard 0 SG_Val:553 Rate:200.000 mm/min SG_Setting:6]
[MSG:INFO: X Axis Stallguard 0 SG_Val:403 Rate:200.000 mm/min SG_Setting:6]
[MSG:INFO: X Axis Stallguard 0 SG_Val:403 Rate:200.000 mm/min SG_Setting:6]
[MSG:INFO: X Axis Stallguard 0 SG_Val:403 Rate:200.000 mm/min SG_Setting:6]
[MSG:INFO: X Axis Stallguard 1 SG_Val:0 Rate:200.000 mm/min SG_Setting:6]
This is what the values mean...
Home using $HX. Add a load to the motor close to stalling it. Watch the values.
You want SG_Val: to drop to 0.
Try different speeds and $/axes/x/motor0/tmc_2209/stallguard values.
Lower values = $/axes/x/motor0/tmc_2209/stallguard lower make it more sensitive.
Try adjusting $/axes/x/motor0/tmc_2209/stallguard up and down until you get a the best sensitivity without false triggers. Record your result.
Try different homing speed values with the same process.
If the second touch, after pull off, is not triggering try using a larger value of feed_scaler:.
Use the best combination of values you find.
If the first phase of a homing sequence is a pull off move, FluidNC thinks the switch is already active at the time you commanded the homing sequence. For StallGuard this should never happen. It should always report the non active state until it is blocked from moving. Your active state attribute could be wrong.
It the first (seek) cycle works, but the second (feed) cycle fails, try increasing the homing/feed_scaler:. This will cause it to move a little further in that phase. Sometimes it takes a few skipped step to register a stall.