docs: Rename Sensorless_homing.md to TMC_Drivers.md and extend

Add additional information on configuring and using TMC drivers.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

4 files changed, 136 insertions, 53 deletions

diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md
index 8ebb511c..7259d998 100644
--- a/docs/Config_Reference.md
+++ b/docs/Config_Reference.md
@@ -2585,6 +2585,10 @@ pins:
 
 # TMC stepper driver configuration
 
+Configuration of Trinamic stepper motor drivers in UART/SPI mode.
+Additional information is in the [TMC Drivers guide](TMC_Drivers.md)
+and in the [command reference](G-Codes.md#tmc-stepper-drivers).
+
 ## [tmc2130]
 
 Configure a TMC2130 stepper motor driver via SPI bus. To use this
@@ -2652,8 +2656,7 @@ run_current:
 #   pin which may be used as the stepper's endstop_pin. Doing this
 #   enables "sensorless homing". (Be sure to also set driver_SGT to an
 #   appropriate sensitivity value.) The default is to not enable
-#   sensorless homing. See docs/Sensorless_Homing.md for details on
-#   how to configure this.
+#   sensorless homing.
 ```
 
 ## [tmc2208]
@@ -2918,8 +2921,7 @@ run_current:
 #   pin which may be used as the stepper's endstop_pin. Doing this
 #   enables "sensorless homing". (Be sure to also set driver_SGT to an
 #   appropriate sensitivity value.) The default is to not enable
-#   sensorless homing. See docs/Sensorless_Homing.md for details on
-#   how to configure this.
+#   sensorless homing.
 ```
 
 # Run-time stepper motor current configuration
diff --git a/docs/G-Codes.md b/docs/G-Codes.md
index 0b0ad713..772815fc 100644
--- a/docs/G-Codes.md
+++ b/docs/G-Codes.md
@@ -474,7 +474,7 @@ enabled:
   carriage. It is typically invoked from the activate_gcode and
   deactivate_gcode fields in a multiple extruder configuration.
 
-## TMC2130, TMC2660, TMC2208, TMC2209 and TMC5160
+## TMC stepper drivers
 
 The following commands are available when any of the
 [tmcXXXX config sections](Config_Reference.md#tmc-stepper-driver-configuration)
@@ -486,14 +486,14 @@ are enabled:
   turned off then back on.
 - `SET_TMC_CURRENT STEPPER=<name> CURRENT=<amps> HOLDCURRENT=<amps>`:
   This will adjust the run and hold currents of the TMC driver.
-  HOLDCURRENT is applicable only to the tmc2130, tmc2208, tmc2209 and tmc5160.
-- `SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value>`: This will
-  alter the value of the specified register field of the TMC driver.
-  This command is intended for low-level diagnostics and debugging only because
-  changing the fields during run-time can lead to undesired and potentially
-  dangerous behavior of your printer. Permanent changes should be made using
-  the printer configuration file instead. No sanity checks are performed for the
-  given values.
+  (HOLDCURRENT is not applicable to tmc2660 drivers.)
+- `SET_TMC_FIELD STEPPER=<name> FIELD=<field> VALUE=<value>`: This
+  will alter the value of the specified register field of the TMC
+  driver. This command is intended for low-level diagnostics and
+  debugging only because changing the fields during run-time can lead
+  to undesired and potentially dangerous behavior of your printer.
+  Permanent changes should be made using the printer configuration
+  file instead. No sanity checks are performed for the given values.
 
 ## Endstop adjustments by stepper phase
 
diff --git a/docs/Overview.md b/docs/Overview.md
index b67b3e6f..abe1a3b1 100644
--- a/docs/Overview.md
+++ b/docs/Overview.md
@@ -42,8 +42,8 @@ communication with the Klipper developers.
 - [Slicers](Slicers.md): Configure "slicer" software for Klipper.
 - [Command Templates](Command_Templates.md): G-Code macros and
   conditional evaluation.
-- [Sensorless homing](Sensorless_Homing.md): Configuring tmc2130
-  sensorless homing.
+- [TMC Drivers](TMC_Drivers.md): Using Trinamic stepper motor drivers
+  with Klipper.
 - [Skew correction](skew_correction.md): Adjustments for axes not
   perfectly square.
 - [G-Codes](G-Codes.md): Information on commands supported by Klipper.
diff --git a/docs/Sensorless_Homing.md b/docs/TMC_Drivers.md
index 68d3d3bb..2cd9069d 100644
--- a/docs/Sensorless_Homing.md
+++ b/docs/TMC_Drivers.md
@@ -1,3 +1,26 @@
+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
@@ -35,7 +58,7 @@ 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 dependant on the
+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).
 
@@ -53,7 +76,7 @@ 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
-simailar to the other TMCs with StallGuard:
+similar to the other TMCs with StallGuard:
 
 ```
 [tmc2130 stepper_x]
@@ -67,7 +90,7 @@ 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 threshhold when the driver
+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
@@ -124,40 +147,6 @@ 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.
 
-## Testing of SPI/UART communication
-
-Now that the stepper driver is configured, let's make sure that
-Klipper can communicate with the TMC2130 by sending the following
-extended G-Code command to the printer:
-
-```
-DUMP_TMC stepper=stepper_x
-```
-
-This command tells Klipper to read a few registers via SPI from the
-TMC2130. If everything works correctly, the output should look similar
-to this (in OctoPrint terminal tab):
-
-```
-Send: DUMP_TMC stepper=stepper_x
-Recv: // GCONF:          00000004
-Recv: // GSTAT:          00000001
-Recv: // IOIN:           11000078
-Recv: // TSTEP:          000fffff
-Recv: // XDIRECT:        00000000
-Recv: // MSCNT:          00000010
-Recv: // MSCURACT:       00f60018
-Recv: // CHOPCONF:       15008384
-Recv: // DRV_STATUS:     800d0000
-Recv: // PWM_SCALE:      00000000
-Recv: // LOST_STEPS:     00000000
-```
-
-The actual register values might differ based the configuration of
-your TMC2130. If the register values are all `ffffffff` or look
-otherwise bogus (for example, `LOST_STEPS` should be always `00000000`
-here) make sure that the SPI is wired and configured correctly.
-
 ## Homing and Tuning
 
 Let's try the first sensorless homing now. It will likely not work as
@@ -184,7 +173,7 @@ 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 interger between `-64` and `63`. The
+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
@@ -199,3 +188,95 @@ 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 pin settings.
+
+## 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.