klipper-dgus/docs/TMC_Drivers.md

This document provides information on using Trinamic stepper motor
drivers in SPI/UART mode on Klipper.

Klipper can also use Trinamic drivers in their "standalone mode".
However, when the drivers are in this mode, no special Klipper
configuration is needed and the advanced Klipper features discussed in
this document are not available.

In addition to this document, be sure to review the [TMC driver config
reference](Config_Reference.md#tmc-stepper-driver-configuration).

# Enabling "Stealthchop" mode

By default, Klipper places the TMC drivers in "spreadcycle" mode. If
the driver supports "stealthchop" then it can be enabled by adding
`stealthchop_threshold: 999999` to the TMC config section.

It is recommended to always use "spreadcycle" mode (by not specifying
`stealthchop_threshold`) or to always use "stealthchop" mode (by
setting `stealthchop_threshold` to 999999). Unfortunately, the drivers
often produce poor and confusing results if the mode changes while the
motor is at a non-zero velocity.

# Sensorless Homing

Sensorless homing allows to home an axis without the need for a
physical limit switch. Instead, the carriage on the axis is moved into
the mechanical limit making the stepper motor lose steps. The stepper
driver senses the lost steps and indicates this to the controlling MCU
(Klipper) by toggling a pin. This information can be used by Klipper
as end stop for the axis.

This guide covers the setup of sensorless homing for the X axis of
your (cartesian) printer. However, it works the same with all other
axes (that require an end stop). You should configure and tune it for
one axis at a time.

## Prerequisites

A few prerequisites are needed to use sensorless homing:

1. StallGuard capable TMCxxxx stepper driver
2. SPI / UART interface of the TMCxxxx wired to MCU (stand-alone mode
   does not work)
3. DIAG1/DIAG pin of TMCxxxx connected to the MCU

## Limitations

Be sure that your mechanical components are able to handle the load of
the carriage bumping into the limit of the axis repeatedly. Especially
spindles (on the Z axis) might generate a lot of force. Homing a Z
axis by bumping the nozzle into the printing surface might not be a
good idea.

Further, sensorless homing might not be accurate enough for your
printer. While homing X and Y axes on a cartesian machine can work
well, homing the Z axis is generally not accurate enough and results
in inconsistent first layer height. Homing a delta printer sensorless
is not advisable due to missing accuracy.

Further, the stall detection of the stepper driver is dependent on the
mechanical load on the motor, the motor current and the motor
temperature (coil resistance).

Sensorless homing works best at medium motor speeds. For very slow
speeds (less than 10 RPM) the motor does not generate significant back
EMF and the TMC cannot reliably detect motor stalls. Further, at very
high speeds, the back EMF of the motor approaches the supply voltage
of the motor, so the TMC cannot detect stalls anymore. It is advised
to have a look in the datasheet of your specific TMCs. There you can
also find more details on limitations of this setup.

## Configuration

To enable sensorless homing add a section to configure the TMC stepper
driver to your `printer.cfg`.

In this guide we'll be using a TMC2130. The configuration however is
similar to the other TMCs with StallGuard:

```
[tmc2130 stepper_x]
cs_pin:        # chip select pin of the SPI interface
microsteps:    # number of microsteps per full step of the motor
run_current:   # value in amps
diag1_pin: !   # pin on the MCU where DIAG1 is connected (active low)
driver_SGT:    # tuning value for sensorless homing
```

The above snippet configures a TMC2130 for the stepper on the X axis.
Make sure to fill in the missing values based on your configuration.

The `driver_SGT` value describes the threshold when the driver
reports a stall. Values have to be in between -64 (most sensitive) and
64 (least sensitive). On some TMCs like the TMC2209 this value doesn't
exist in this form as the behavior is different to the TMC2130. In the
case of the TMC2209 the threshold is defined by the `driver_SGTHRS`
value in the config and go from 0 (least sensitive) to 255 (most
sensitive). Have a look at the datasheet of your specific TMC to avoid
mistakes.

If you have a CoreXY machine, you can configure one stepper driver for
X and the other for Y homing as you would on a cartesian printer. Be
aware that Klipper needs both `DIAG1` pins connected to the MCU. It is
not sufficient to use only one signal from one of the stepper drivers
(as it is possible on e.g. Marlin).

The `diag1_pin` of the TMC2130 is configured as open-collector pin.
This means, the stepper driver pulls the pin low to indicate a stalled
motor (active low) and the pin must be inverted by adding a `!` in
front of the pin name. Further, you need a pull-up resistor on the
connection. If your PCB has no external pull-up, you can enable the
internal pull-up of your MCU by adding a `^` in front of the pin name.
The resulting line might look like this:

```
diag1_pin: ^!PA1  # DIAG1 connected to PA1, internal pull-up is enabled, signal is active low
```

By configuring the `diag1_pin`, Klipper allows you to use a special
virtual end stop for the axis. You can use this instead of a physical
end stop pin by changing the `endstop_pin` of the corresponding axis:

```
[stepper_x]
...
endstop_pin: tmc2130_stepper_x:virtual_endstop  # use the virtual end stop generated by the [tmc2130 stepper_x] section of this config file
...
homing_retract_dist: 0
...
```

The name of the virtual end stop pin is derived from the name of the
TMC2130 section. The `homing_retract_dist` setting should be set to
zero to disable the second homing move as a second pass is not needed,
and attempts to do so are error prone.

The TMC2130 and TMC5160 have both a `diag0_pin` and `diag1_pin` in
most known hardware the `diag1_pin` is appropriate. In order for
klipper to correctly configure the driver for sensorless homing, the
correct configuration property name `diag0_pin` or `diag1_pin` must be
used. Which is used is determined by which driver pin is connected to
the MCU pin.

ATTENTION: This guide only mentions the mandatory parameters and the
ones needed to set up sensorless homing. There are many other options
to configure on a TMC2130, make sure to take a look at [config
reference](Config_Reference.md#tmc2130) for all the available options.

## Homing and Tuning

Let's try the first sensorless homing now. It will likely not work as
intended. There are three possible outcomes of this experiment:

1. The axis stops moving before hitting the mechanical limit or does
   not move at all
2. The axis homes correctly (which is unlikely at this point)
3. The axis bumps into the mechanical limit and keeps moving while
   making horrible noise

If the third outcome happens to you, disable the stepper (by cutting
the power or issuing a `M112` emergency stop).

Ok, now that you know what can happen, let's try it out. Put the
carriage somewhere in the middle of the X axis. Home the X axis by
sending the following G-Code command to Klipper and observe the
outcome:

```
G28 X
```

If the axis stopped early (first outcome), the stepper driver detected
a motor stall even though there was none. To trigger stall detection
at a higher load, increase the value of `driver_SGT` (for example from
0 to 5). The values can be any integer between `-64` and `63`. The
higher the value, the later it triggers stall detection.

If your axis did not stop (third outcome), the stepper driver was not
able to detect the stall, because the load on the motor still seemed
reasonable to the driver. To trigger stall detection at a lighter
load, decrease the value of `driver_SGT`.

Even if your axis homed correctly, it might be worth to try a few
different values for `driver_SGT`. If you think that it bumps too hard
into the mechanical limit, try to decrease the value by 1 or 2.

At this point, your axis should be able to home based on the stall
detection of the TMC2130. Congratulations! You can now proceed with
the next axis of your printer.

# Querying and diagnosing driver settings

The `[DUMP_TMC command](G-Codes.md#tmc-stepper-drivers) is a useful
tool when configuring and diagnosing the drivers. It will report all
fields configured by Klipper as well as all fields that can be queried
from the driver.

All of the reported fields are defined in the Trinamic datasheet for
each driver. These datasheets can be found on the [Trinamic
website](https://www.trinamic.com/). Obtain and review the Trinamic
datasheet for the driver to interpret the results of DUMP_TMC.

# Configuring driver_XXX settings

Klipper supports configuring many low-level driver fields using
`driver_XXX` settings. The [TMC driver config
reference](Config_Reference.md#tmc-stepper-driver-configuration) has
the full list of fields available for each type of driver.

In addition, almost all fields can be modified at run-time using the
[SET_TMC_FIELD command](G-Codes.md#tmc-stepper-drivers).

Each of these fields is defined in the Trinamic datasheet for each
driver. These datasheets can be found on the [Trinamic
website](https://www.trinamic.com/).

Note that the Trinamic datasheets sometime use wording that can
confuse a high-level setting (such as "hysteresis end") with a
low-level field value (eg, "HEND"). In Klipper, `driver_XXX` and
SET_TMC_FIELD always set the low-level field value that is actually
written to the driver. So, for example, if the Trinamic datasheet
states that a value of 3 must be written to the HEND field to obtain a
"hysteresis end" of 0, then set `driver_HEND=3` to obtain the
high-level value of 0.

# Common Questions

## Can I use stealthchop mode on an extruder with pressure advance?

Many people successfully use "stealthchop" mode with Klipper's
pressure advance. Klipper implements [smooth pressure
advance](Kinematics.md#pressure-advance) which does not introduce any
instantaneous velocity changes.

However, "stealthchop" mode may produce lower motor torque and/or
produce higher motor heat. It may or may not be an adequate mode for
your particular printer.

## I keep getting "Unable to read tmc uart 'stepper_x' register IFCNT" errors?

This occurs when Klipper is unable to communicate with a tmc2208 or
tmc2209 driver.

Make sure that the motor power is enabled, as the stepper motor driver
generally needs motor power before it can communicate with the
micro-controller.

Otherwise, this error is typically the result of incorrect UART pin
wiring or an incorrect Klipper configuration of the UART pin settings.

## I keep getting "Unable to write tmc spi 'stepper_x' register ..." errors?

This occurs when Klipper is unable to communicate with a tmc2130 or
tmc5160 driver.

Make sure that the motor power is enabled, as the stepper motor driver
generally needs motor power before it can communicate with the
micro-controller.

Otherwise, this error is typically the result of incorrect SPI wiring,
an incorrect Klipper configuration of the SPI settings, or an
incomplete configuration of devices on an SPI bus.

Note that if the driver is on a shared SPI bus with multiple devices
then be sure to fully configure every device on that shared SPI bus in
Klipper. If a device on a shared SPI bus is not configured, then it
may incorrectly respond to commands not intended for it and corrupt
the communication to the intended device. If there is a device on a
shared SPI bus that can not be configured in Klipper, then use a
[static_digital_output config
section](Config_Reference.md#static_digital_output) to set the CS pin
of the unused device high (so that it will not attempt to use the SPI
bus). The board's schematic is often a useful reference for finding
which devices are on an SPI bus and their associated pins.

## Why did I get a "TMC reports error: ..." error?

This type of error indicates the TMC driver detected a problem and has
disabled itself. That is, the driver stopped holding its position and
ignored movement commands. If Klipper detects that an active driver
has disabled itself, it will transition the printer into a "shutdown"
state.

Some common errors and tips for diagnosing them:

**TMC reports error: ... ot=1(OvertempError!)"**: This indicates the
motor driver disabled itself because it became too hot. Typical
solutions are to decrease the stepper motor current, increase cooling
on the stepper motor driver, and/or increase cooling on the stepper
motor.

**TMC reports error: ... ShortToGND** OR **LowSideShort**: This
indicates the driver has disabled itself because it detected very high
current passing through the driver. This may indicate a loose or
shorted wire to the stepper motor or within the stepper motor itself.

**TMC reports error: ... reset=1(Reset)** OR **CS_ACTUAL=0(Reset?)**
OR **SE=0(Reset?)**: This indicates that the driver has reset itself
mid-print. This may be due to voltage or wiring issues.

**TMC reports error: ... uv_cp=1(Undervoltage!)**: This indicates the
driver has detected a low-voltage event and has disabled itself. This
may be due to wiring or power supply issues.

It's also possible that a **TMC reports error** shutdown occurs due to
SPI errors that prevent communication with the driver (on tmc2130,
tmc5160, or tmc2660). If this occurs, it's common for the reported
driver status to show `00000000` or `ffffffff` - for example: `TMC
reports error: DRV_STATUS: ffffffff ...` OR `TMC reports error:
READRSP@RDSEL2: 00000000 ...`. Such a failure may be due to an SPI
wiring problem or may be due to a self-reset or failure of the TMC
driver.

## How do I tune spreadcycle/coolstep/etc. mode on my drivers?

The [Trinamic website](https://www.trinamic.com/) has guides on
configuring the drivers. These guides are often technical, low-level,
and may require specialized hardware. Regardless, they are the best
source of information.