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>

1 files changed, 0 insertions, 201 deletions

diff --git a/docs/Sensorless_Homing.md b/docs/Sensorless_Homing.md
deleted file mode 100644
index 68d3d3bb..00000000
--- a/docs/Sensorless_Homing.md
+++ /dev/null
@@ -1,201 +0,0 @@
-# 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 dependant 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
-simailar 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 threshhold 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.
-
-## 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
-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 interger 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.