Klipper Sensorless Homing: TMC2209 Wiring and Threshold Calibration

The Sensing Principle: How StallGuard Replaces Microswitches

When a stepper motor turns, it generates a back-electromotive force (back-EMF) proportional to its velocity. Trinamic’s StallGuard4 technology, integrated into drivers like the TMC2209, continuously measures this back-EMF to calculate the mechanical load on the motor shaft. Under normal printing conditions, the load remains relatively constant, dictated by the mass of the print head and the friction of the linear rails.

When the printer carriage hits a hard physical endstop, the motor stalls, velocity drops to zero, and the back-EMF signature changes abruptly. The driver's internal comparator detects this massive shift in electrical load and immediately pulls the DIAG pin high. This sends a digital interrupt signal to the Klipper MCU, which halts the stepper pulses and registers the axis as homed, entirely eliminating the need for physical microswitches or optical sensors.

Wiring and Pinout: Routing the DIAG Signal

To use sensorless homing, you must physically route the driver's DIAG pin to your mainboard's endstop input. On modern 32-bit control boards like the BigTreeTech SKR 3 or Octopus V1.1, this usually requires installing a physical jumper on the board to bridge the DIAG pad to the endstop signal trace. Without this jumper, the driver detects the stall, but the MCU never receives the interrupt.

Signal Math and Klipper Configuration

A common misconception is that sensorless homing provides an analog distance measurement. It does not. The output is strictly a digital logic signal (a boolean 0V or 3.3V/5V interrupt). You do not read this with an ADC. The 'raw reading' in this context is the stallguard threshold integer you configure in Klipper, which the driver's internal comparator uses to trigger that digital output.

For the TMC2209, the raw threshold value ranges from 0 to 255. The mathematical mapping from raw configuration to physical unit (a stall event) operates on a simple comparator logic inside the silicon:

Physical_Stall_Event = (Measured_Load_Value > Configured_Threshold) ? 1 : 0

In Klipper, this is defined in the [tmc2209 stepper_x] section. You are not scaling a voltage; you are tuning the sensitivity of the internal comparator. A higher number makes the driver less sensitive (requiring a harder physical crash to trigger), while a lower number makes it more sensitive (triggering on minor friction spikes).

[tmc2209 stepper_x]
uart_pin: PA3
run_current: 0.800
stealthchop_threshold: 0
diag_pin: ^PG5      # ^ enables internal pull-up, matching active-HIGH
stallguard: 75      # The raw threshold integer (0-255)
driver_SGT: 1       # Note: SGT is for TMC2130/5160; use stallguard for 2209

Calibration: Dialing in the StallGuard Threshold

Because every printer has different mass, belt tension, and rail friction, you cannot copy-paste a threshold value from the internet. You must calibrate the stallguard integer to your specific mechanical system. According to the official Klipper TMC configuration documentation, this requires an iterative testing process.

1. Establish Baseline: Set stallguard: 75 and homing_speed: 20 in your [stepper_x] config. Restart Klipper.
2. Test Mid-Air: Command G28 X while the carriage is in the middle of the rail. It should move toward the endstop and hit the frame.
3. Evaluate the Crash:
   • If the carriage hits the frame and the motor keeps grinding (stall not detected), the threshold is too high. Decrease stallguard by 5 (e.g., to 70) and repeat.
   • If the carriage stops abruptly before hitting the frame (false trigger), the threshold is too low. Increase stallguard by 5 (e.g., to 80) and repeat.
4. Verify Repeatability: Once it homes reliably, run G28 X ten times. If it occasionally stops mid-air, increase the threshold by 2 points to add a safety margin.

Common Interference Sources and Troubleshooting

Sensorless homing is highly susceptible to mechanical and electrical noise. If your calibration fails or homing is inconsistent, check these specific interference sources before blaming the driver:

• Insufficient Homing Speed: StallGuard4 requires a minimum back-EMF to function. If your homing_speed is below 10 mm/s, the driver cannot generate a reliable load measurement. Set homing speed between 15 and 30 mm/s.
• Loose Grub Screws: A loose pulley grub screw absorbs the kinetic energy of the stall, dampening the back-EMF spike. The driver won't see the stall. Ensure both grub screws on the X and Y motor pulleys are tight, with one seated directly against the flat of the D-shaft.
• Belt Tension Extremes: Over-tightened belts create massive baseline friction, forcing you to lower the threshold so much that normal printing vibrations cause false triggers. Under-tightened belts absorb the stall impact. Tune belt tension to a low, resonant hum when plucked.
• UART Noise: While the DIAG pin is a hardware line, the threshold value is written via UART. If your UART wiring is long and unshielded, electromagnetic interference from the stepper coils can corrupt the configuration register. Keep UART traces short and ensure proper grounding.
• Z-Axis Binding (For CoreXY): On CoreXY kinematics, the X and Y motors work together to move the X axis. If the Z-axis lead screws are binding, the extra load can mask the X-axis stall event. Ensure your Z-axis is perfectly lubricated and free of binding.

Decision Tree: Choosing Your Driver and Homing Parameters

Not all Trinamic drivers handle sensorless homing equally. The Voron Design community documentation heavily favors specific configurations based on the driver's internal architecture. Use this decision path to lock in your exact hardware and configuration values.