StallGuard Tuning

StallGuard Tuning

StallGuard is the TMC2209's sensorless load measurement: it senses how hard the motor is working from the motor's back-EMF, with no extra sensors. Tuned well, it stops the motor the moment it hits an obstacle — that's what makes these boards safe for curtains, windows, and anything that could pinch or jam, and it's how products like the Ropener home against a hard stop without limit switches.

For the deep theory, see the TMC2209 datasheet and the Trinamic book.

The three knobs

All three live in the web UI (see Web UI Reference):

• SG_RESULT (read-only, Diagnostics) — the live load reading. High when spinning freely, drops toward zero as load increases. A stall is declared when SG_RESULT < 2 × SGTHRS.
• SGTHRS — the stall threshold, 0–255. Higher = more sensitive (triggers earlier / with lighter resistance).
• TCOOLTHRS — a speed gate. StallGuard readings are meaningless at very low speeds, so stall detection is only armed when the motor moves faster than this threshold. This is compared against TSTEP (time between microsteps — lower TSTEP = faster): detection is armed while TSTEP < TCOOLTHRS.

When a stall fires, the firmware stops the motor and zeroes the position counter, and logs Stall detected.

Tuning procedure

1. Set your working speed and current first (Motion Tuning → Speed, StallGuard → IRUN). StallGuard readings change with both — retune if you later change either.
2. Run the motor under normal load (actually driving your mechanism, not free-spinning on the bench) and watch SG_RESULT in Diagnostics for a while. Note the typical value — call it SG_normal.
3. Set SGTHRS ≈ SG_normal / 4. Since a stall triggers at SG_RESULT < 2 × SGTHRS, this puts the trigger point at half your normal-load reading — enough margin to avoid false trips, sensitive enough to catch a real jam. Example: SG_RESULT sits around 200 under load → set SGTHRS ≈ 50.
4. Test a real stall. Let the mechanism hit its hard stop (or grab the shaft with a gloved hand). The motor should stop within a fraction of a second. Too slow / doesn't trigger → raise SGTHRS. Trips during normal moves → lower SGTHRS.
5. Check the speed gate. Watch TSTEP at your working speed and make sure TCOOLTHRS is above that TSTEP value so detection is armed while moving, but detection stays off during slow ramps. If stalls fire during acceleration, raise acceleration (shorter time at low speed) or adjust TCOOLTHRS.

Rules of thumb

• StallGuard needs speed. Below roughly a couple of revolutions per second the signal gets unreliable — don't expect stall detection during very slow moves; that's what the TCOOLTHRS gate is for.
• More current = duller feel. At high IRUN the motor powers through light obstacles before StallGuard sees them. For pinch-safety, use the lowest IRUN that reliably moves your load.
• Retune when anything changes. Speed, current, supply voltage, mechanism friction, even temperature shift the SG_RESULT baseline.
• VAL3101: the AS5600 encoder complements StallGuard — the encoder detects missed steps and gives absolute position even when moving too slowly for StallGuard. Use StallGuard for pinch-safety, the encoder for position truth (see the encoder section).