The formula
For a belt-driven axis, one motor revolution moves the belt by one belt pitch for every tooth on the pulley:
belt travel per revolution = belt pitch × pulley teeth
steps per mm = (full steps per revolution × microstepping) ÷ (belt pitch × pulley teeth)
A 1.8° motor has 360 ÷ 1.8 = 200 full steps per revolution, a 0.9° motor has 400. For a standard setup (1.8° motor, 1/16 microstepping, GT2 2 mm belt, 20-tooth pulley) that is 200 × 16 ÷ 40 = 80 steps/mm.
Klipper does not use steps per mm. Its rotation_distance is the distance the axis moves per motor revolution, which for a belt is simply pitch × teeth (2 × 20 = 40). Klipper takes the microstepping separately through the microsteps setting, so changing microstepping does not change rotation_distance.
How to use the result
- Find your motor angle (1.8° unless the motor says 0.9°).
- Enter the microstepping your firmware or driver actually uses.
- Enter belt pitch and the motor pulley's tooth count. Count teeth by eye or check the pulley listing.
- Marlin: send the M92 line, or set
DEFAULT_AXIS_STEPS_PER_UNITin Configuration.h. UseM500to save when EEPROM is enabled. Klipper: set rotation_distance and microsteps in the stepper section and restart. - Verify: command a long move (for example 100 mm), measure it, and scale the value by intended ÷ actual distance.
Things to watch
- This is for direct belt drives. Geared or lead-screw axes need a different formula (a gear ratio, or the screw lead).
- Idler pulleys don't matter; only the pulley on the motor shaft sets the ratio.
- With interpolating drivers (e.g. TMC at 256 internal), the steps per mm still follows the microstepping you configure in firmware.
- Higher steps/mm does not mean a more accurate printer; belt stretch, backlash and frame rigidity matter far more than step resolution.
Frequently asked questions
How many steps per mm for a GT2 belt with a 20-tooth pulley?
With a 1.8° motor and 1/16 microstepping it is 80 steps/mm. With 1/32 microstepping it is 160 steps/mm. The Klipper rotation_distance is 40 in both cases.
What is the Klipper rotation_distance for a belt?
Belt pitch multiplied by the number of teeth on the motor pulley. For GT2 (2 mm) and a 20-tooth pulley that is 40 mm.
Do I need to change steps per mm if I change microstepping?
In Marlin, yes: steps per mm scales with microstepping, so doubling it doubles the value (unless your driver configuration handles it for you). In Klipper you only change the microsteps setting; rotation_distance stays the same.
Why is my axis moving the wrong distance?
Check the motor step angle, the pulley tooth count and the microstepping the driver is really set to. Then measure a long move and correct the value by the ratio of intended to actual distance.