Skip to main content


1. Intro#

StallGuard is a feature that detects when the motor is about to stall and signal an interrupt to immediatly stop the motor in its current position.

It works by monitoring the back EMF from the stepper motor. When this value reaches a threshold that you set, it will make the DIAG pin go high. The DIAG pin is connected to an interrupt on the ESP32. When the rising edge is detected by the ESP32, it will immediately stop the motor.

While it is a very powerful feature, it requires near perfect values to be set correctly. In addition, changes in temperature may affect your device, causing it to expand or contract, thus affecting StallGuard as well. In extremem temperature changes, you may need to adjust the StallGuard values quite often.

It is recommended that you never rely on StallGuard, but instead use it only as a backup. Using proper positioning and limit switches is recommended over relying on StallGuard to work properly every time.

2. Tuning#

StallGuard requires near-perfect value to work, thus it requires you to properly tune the values.

StallGuard is a combination of the following parameters:

1. Current
2. Velocity
3. Acceleration
4. TCOOLTHRS setting
5. SGTHRS setting

1. Current:#

The current you are using will determine the amount of back EMF created, so first set your current to a level you want. A high current will make the motor louder and stronger. A low current will do the opposite.

IMPORTANT: Always use the least amount of current needed to make the motor move. This is good for safety reasons, it makes StallGuard more reliable, and runs the motor and driver much cooler, thus extending their lives.

2. Velocity:#

Next, set the velocity. How fast do you want it to go.

3. Acceleration:#

Next, set the acceleration. StallGuard is not reliable at very low speeds, so a very long and slow acceleration will not be good with StallGuard. Try to accelerate as fast as you can based on your project. Just know during the acceleration phase, StallGuard may not work right awat, so can you risk having it not work until it gets to its operating velocity?

For example, in my window opener, I cannot risk StallGuard not working. If the window is locked when trying to open the window, damage may occur if StallGuard does not immediately detect the locked window. So I need to accelerate it as quickly as possible to reach its operating velocity. So take some time to get your acceleration right.

4. TCOOLTHRS setting:#

Now we can set the TCOOLTHRS value. It is on page 26 of the datasheet.

This is the velocity threshold at which point stallGuard will activate. StallGuard is not reliable at low speeds so we need to shut it off until a certain speed is reached. It will always trigger the stall pin when starting up in the first few milisecond, even when there is no stall.

So we need to set the correct velocity value at which point to turn StallGuard on, but this can be very difficult to do because the value is quite hard to figure out.

Fortunately I’ve spent a lot of time figuring this out, and created a formula to figure it out.

TCOOLS = (3089838.00pow(float(VELOCITY),-1.00161534))1.5;

Simply plug in your VELOCITY value into the formula, and it will give you the threshold value.

5. SGTHRS setting#

Finally, we need to set the SGTHRS value which is the main value to set. It is a value from 0 - 255 as seen on page 55 of the datsheet.

A value of 0 will turn StallGuard off completely. The higher you go, the more sensitive it will be to tripping.

My workflow for setting stallguard:#

  1. First I set StallGaurd value to 0 to turn it off.
  2. Then I figure out the minimum current to set. I need to have just enough current to move whatever needs to be moved, but not any more. If the current is too high, StallGuard will require a lot of force to trip, so don’t set the current any higher than the application calls for. Set it at near zero and slowly inscrease it until your object begins to move.
  3. Then I figure out what velocity I want and set that.
  4. Then I figure out what acceleration I want, trying to use the fastest I can for the application
  5. Then I set the TCOOLTHRS value based on the formula above. In fact, I have it coded into the sketch so it automatically sets when I set the velocity.
  6. Then I start at SGTHRS value 0 and start moving the motor and applying pressure to it with my fingers. I slowly increase this number until it stalls. Just keep running the motor, applying pressure, and increasing the value.

Remember: A higher SGTHRS value gives a higher sensitivity. A higher value makes StallGuard more sensitive and requires less torque to indicate a stall.